CLI reference¶

Command	What it does
`aver init`	Write `aver.yaml` (preset, name, clinical flag, region).
`aver resolve [-o snapshot.json]`	Fingerprint the pipeline (Nextflow or Snakemake); 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.
`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 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 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:
    - sample: HG002                # a registered GIAB code; nothing else is accepted
      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: snakemake-workflows/dna-seq-gatk-variant-calling   # GitHub owner/repo, https Git URL or local path
  revision: v2.1.1
  snakefile: null        # default: Snakefile or workflow/Snakefile, as Snakemake looks for them
  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`).