CLI reference¶

Command	What it does
`aver init`	Write `aver.yaml` (preset, name, clinical flag, region).
`aver resolve [-o snapshot.json] [--replay dragen-replay.json]`	Fingerprint the pipeline (Nextflow, Snakemake, or DRAGEN from its replay file); print the snapshot hash and any unpinned dependencies.
`aver benchmark [--force]`	Prepare verified reference data, run the pipeline on reference reads, compare with hap.py/vcfeval, print metrics. Nextflow and Snakemake pipelines through a preset; for anything else, run it on the reference reads yourself and use `aver compare`.
`aver compare --query out.vcf.gz --sample HG002`	Compare an existing VCF with the truth set (no pipeline run). The VCF's sample must be the named reference material. `--sample HCC1395` selects the somatic path (SEQC2 pair, som.py).
`aver compare ... --stratification core`	Add per-stratification metrics (GIAB v3.6 core set, or name individual stratifications; repeatable). `benchmark.stratifications: [core]` in `aver.yaml` does the same for `aver benchmark`.
`aver compare ... --snapshot snapshot.json`	Stamp a resolved snapshot's hash into the result and write a push-ready bundle — how DRAGEN and other externally-run pipelines get their metrics onto the platform.
`aver report [--format html\\|pdf\\|json]`	Write a deterministic report bundle from benchmark results.
`aver verify BUNDLE`	Recompute the content hash and every file hash; re-render the HTML. Exit 1 on any mismatch.
`aver diff SNAP_A SNAP_B [--clinical] [--json]`	Structured dependency diff with rule-derived severity.
`aver login [--url URL] [--key-stdin]`	Save an organisation API key (web app: Settings > API keys) to your user config directory, readable only by you.
`aver push [--pipeline ID]`	Upload each result's dependency snapshot and metrics to the platform. Pushing the same result twice records one run. Reads, VCFs and outputs never leave your machine.
`aver push --snapshot snapshot.json`	Upload a dependency snapshot alone, without benchmark results — configuration-drift monitoring for engines without `aver benchmark`, such as DRAGEN.
`aver qc push --run-key KEY --date YYYY-MM-DD [--multiqc\\|--dragen-metrics\\|--metrics\\|--metric]`	Push one run's QC metrics (numbers only) for trending against your laboratory's control limits; reads MultiQC JSON or DRAGEN `*_metrics.csv` files. See Run QC monitoring.
`aver compare ... --sv --build GRCh37`	Benchmark structural variants (≥50bp) against the GIAB SV Tier 1 truth set with truvari. See Structural variants.
`aver pgx compare --sample NA12878 --calls calls.json`	Judge star-allele diplotype calls against the GeT-RM published consensus, gene by gene. See Pharmacogenomics.
`aver logout`	Remove the saved API key.
`aver runner install`	How to install the lab-hosted Runner (a separate binary; see `runner/README.md`).

aver.yaml¶

apiVersion: aver/v1
pipeline:
  name: germline-chr20
  engine: nextflow
  entrypoint: nf-core/sarek        # or a local path
  revision: 3.10.0
  profile: docker
  preset: nf-core/sarek
  clinical: true
  intended_use: Germline SNV and small indel detection …
  target_bed: null                 # panel/exome footprint, recommended
  params: {}                       # pipeline parameters under validation
reference:
  build: GRCh38
  materials:
    # Samples must be registered GIAB codes; nothing else is accepted.
    - sample: HG002
      truth_set: null        # null = the published default (v4.2.1)
benchmark:
  threads: 8
  region: chr20                    # laptop-sized; null = whole genome
  max_cpus: 12
  max_memory_gb: 12
policy:
  snv_recall_delta_pp: -0.5
  indel_recall_delta_pp: -1.0
  precision_delta_pp: -0.5
  reference_change: revalidation_required

Unknown fields are rejected, so a misspelt key never silently falls back to a default.

Snakemake workflows¶

pipeline:
  name: germline-gatk
  engine: snakemake
  # entrypoint: a GitHub owner/repo, an https Git URL or a local path
  entrypoint: snakemake-workflows/dna-seq-gatk-variant-calling
  revision: v2.1.1
  # snakefile defaults to Snakefile or workflow/Snakefile
  snakefile: null
  preset: snakemake-workflows/dna-seq-gatk-variant-calling
  params: {}             # config overrides, as with snakemake --config

aver resolve loads the workflow with a pinned Snakemake (9.27.0, installed on first use into Aver's cache from a hash-locked requirements file; needs uv and git, Linux or WSL). It records every rule's container (by digest), conda environment (file SHA-256 and declared packages), wrapper (with its release) and the workflow config. A conda environment counts as pinned only when every declared package has an exact version (==X or =X=BUILD) or a *.linux-64.pin.txt pin file sits next to it; conda's =X means "any X.*" and is reported as unpinned. A bare aver resolve records no reference genome row for a Snakemake workflow; aver benchmark does, because it supplies the verified reference.

aver benchmark executes a Snakemake preset inside the digest-pinned snakemake/snakemake image — the same 9.27.0 the snapshot records — building each rule's conda environment inside the container, so the host needs Docker only. The dna-seq-gatk-variant-calling preset benchmarks the per-contig genotyped VCF (raw calls, before the workflow's hard filter) and pre-seeds the workflow's reference inputs from Aver's checksummed catalogue, including an empty known-variation VCF, so the workflow never downloads unverified reference data (ADR-012).

Environment¶

Variable	Meaning
`AVER_CACHE`	Cache directory for reference data, derived files, tools and results (default `~/.cache/aver`).
`AVER_API_KEY`	API key for `aver push`; takes precedence over the key saved by `aver login` (use it in CI).
`AVER_API_URL`	Platform API URL (default `https://api.aver.bio`).