AI written
I'm tired and bad at writing things, help appreciated - file an issue or PR on GitHub.

Command reference

A map of the WGS Extract command line.

The CLI is the best interface for repeatable work: scripts, batch jobs, remote machines, AI-agent workflows, and long-running analyses where exact commands matter.

Global optionsCommand groupsRecipesPixi environmentsBest practices

Global options

Shared options can go before or after the subcommand. --threads and --memory accept auto (the default). Every command exits non-zero on failure (1 failure, 2 usage error, 3 missing tool), so commands can be chained safely in scripts. --json prints a machine-readable result manifest on stdout instead of human text; commands that write files also save it as <output>.manifest.json. Examples write plain wgsextract; see Running the CLI for the launcher that matches your install.

For long jobs, --log-file out/run.log records diagnostics and provenance, --tmp-dir /data/work selects a writable staging volume, and opt-in --keep-awake requests sleep inhibition. --atomic-output protects existing results for supported writers. Memory/disk preflight is advisory; it does not replace existing safety guards.

global-options.sh
wgsextract \
  --input /data/sample.cram \
  --outdir /data/out/sample \
  --ref /refs/hs38.fa \
  --threads auto \
  --memory 2G \
  info --detailed

Command groups

wgsextract --help lists the core commands first, in the order you would usually run them (info, microarray/lineage, extract, realign/align, vcf, vep), then setup and advanced commands. Run wgsextract help --all for one line per command (--json for a machine-readable index with each command's options and, for typed commands, a JSON Schema), wgsextract help <command> for one command's options, examples and output files (--help-all adds the advanced options), wgsextract help topics for concepts such as references, builds and exit codes, or wgsextract help for the full tree. A mistyped command or option gets a "Did you mean" hint, and on a terminal some commands suggest what to run next.

Info and QC

info (build, integrity, read metrics; --csv for machine-readable output), info calculate-coverage (exact breadth via samtools coverage, written to <input>_coverage.tsv; --bins streams depth bands 0 / 1–3 / 4–7 / 8+), info coverage-sample (fast estimate), info chip (which vendor chip revision a microarray raw file is, with a confidence score and the matching --formats template), plus qc fastqc, qc fastp, qc multiqc (one offline report of FastQC, bcftools stats and WGS Extract metrics), qc multiqc-metrics (MultiQC custom content for a pipeline's own report; see pipeline interop), qc vcf, and qc fake-data.

BAM / CRAM

bam identify, bam sort, bam index, bam unindex, bam unsort, bam to-cram, bam to-bam, bam unalign, bam merge, bam to-ubam (unaligned BAM for GATK), plus repair ftdna-bam and repair ftdna-vcf for FTDNA files.

Extraction

extract mito-fasta, extract mito-vcf, extract mt-bam, extract ydna-bam, extract ydna-vcf, extract y-mt-extract, extract unmapped, extract custom, and extract bam-subset. Mito and Y VCFs are called as haploid. Optional ydna-bam --poz selects licensed GRCh37/38 Y intervals; ydna-vcf --ybrowse calls explicitly installed GRCh38 yBrowse sites; unmapped --fastq separates pairs, single-end reads and orphan mates.

Variant workflows

Calling: vcf snp, vcf indel, vcf freebayes, vcf gatk, vcf deepvariant, vcf sv, vcf cnv. Annotation: vcf annotate, vcf chain-annotate, vcf clinvar, vcf gnomad, vcf revel, vcf phylop, vcf cadd, vcf gerp, vcf spliceai, vcf alphamissense, vcf pharmgkb, vcf pharmcat. Also vcf table (one row per variant as TSV or Parquet and SQLite, ready for SQL; see variant table), vcf filter, vcf trio, and vcf to-fasta (personal consensus genome).

References and annotation

ref bootstrap, ref library, ref library-list, ref status, ref download, ref index, ref verify, ref count-ns, ref gene-map, the annotation downloads (ref clinvar, gnomad, revel, phylop, cadd, gerp, spliceai, alphamissense, pharmgkb), explicit ref aadr and ref ybrowse resource setup, and vep download, vep run, vep verify.

ref library-list is a deprecated compatibility alias for ref library --list. For annotation, vep run --assembly GRCh37 also accepts the deprecated --vep-assembly GRCh37; vep download --assembly selects the cache build.

Analysis and alignment

microarray, lineage y-haplogroup, lineage y-str, lineage mt-haplogroup, typing cyp2d6, typing hla, typing str, methylation pileup, sign create, sign verify, align, realign, pet-align, analyze comprehensive, analyze batch-gen, example-genome list/download, benchmark, deps check, and config.

Common CLI recipes

These examples are intentionally small and explicit. Replace paths and references with your own. Output names keep the full input stem, so HG002.chr20.bam produces HG002.chr20_sorted.bam.

recipes.sh
# Identify a BAM/CRAM and inspect metadata
wgsextract --input sample.cram info --detailed

# Sort and index an alignment (sample.bam -> out/sample/sample_sorted.bam)
wgsextract --input sample.bam --outdir out/sample bam sort
wgsextract --input out/sample/sample_sorted.bam bam index

# Convert BAM to CRAM for storage
wgsextract --input sample.bam --ref /refs/hs38.fa bam to-cram

# Generate consumer microarray-style outputs
wgsextract --input sample.bam microarray --formats 23andme_v5,ancestry_v2

# Extract mitochondrial variants and Y-DNA reads
wgsextract --input sample.bam extract mito-vcf
wgsextract --input sample.bam extract ydna-bam

# Call and filter variants
wgsextract --input sample.bam --ref /refs/hs38.fa vcf snp
wgsextract vcf filter --vcf-input calls.vcf.gz --expr 'QUAL>30'

# Show the full command tree
wgsextract help

Pixi environments

Some specialized tools live in dedicated Pixi environments. Install them explicitly with pixi install --locked -e <environment> before use. WGS Extract can route tools such as vep or pbsv through an existing environment, but validates dependencies rather than installing them during a feature. You can also run a whole command inside an installed environment, from the app/ folder or a source checkout.

pacbio

PacBio-aware structural variant workflows using pbmm2, pbsv, and sniffles where available.

pixi run -e pacbio wgsextract vcf sv --pacbio

vep

Ensembl VEP for vep run, vep download, and vep verify. Not available on native Windows.

pixi run -e vep wgsextract vep run

gatk and freebayes

GATK (Python 3.10, Java 17) and FreeBayes live in their own environments. Install the locked environment before calling; neither is downloaded on first use. The Windows installer prepares GATK with its native GKL sidecar. FreeBayes is not supported on native Windows; GATK is gated on Linux ARM64.

cyrius, t1k, and expansionhunter

Gene and repeat typing: typing cyp2d6 (Cyrius), typing hla (T1K), and typing str (ExpansionHunter). Linux x86_64 and macOS, where packaged; not qualified on Linux ARM64. Install once with pixi install --locked -e <environment>; Cyrius is licensed for noncommercial use only.

modkit

methylation pileup tabulates CpG methylation from Nanopore and PacBio MM/ML tags with ONT's modkit. Linux and macOS only; install it with pixi install --locked -e modkit.

dev

Contributor tooling: pytest, ruff, mypy, pre-commit, actionlint. Development tasks select it automatically.

pixi run test
pixi run lint

CLI best practices

Genome jobs are expensive. These habits prevent wasted hours and corrupted assumptions.

Use regions first

Try chrM, chrY, or a small gene region before whole-genome commands.

Keep outputs isolated

Use --outdir per sample or --genome folders to avoid mixing files.

Match builds

Keep BAM/CRAM, FASTA, VCF, gene maps, and annotations on the same reference build.

Log the command

Save exact commands, Pixi environment, reference build, and tool versions for repeatability.