CLI Reference

The vep binary accepts the Perl VEP command-line interface. Most flags have the same name and behavior; a flag marked “Accepted for VEP compatibility” below is parsed and has no effect on the annotation (the cache flags among them only name the cache path the output header prints), so an existing VEP command line is accepted. The annotation cache is always --json_cache.

# Show all flags
cargo run --release -- --help

# Short form
vep -i input.vcf -o output.txt --offline --json_cache /path/to/json_cache

Input

Output

Output parity

For the golden-corpus flag set (--offline --json_cache <dir> --species homo_sapiens --assembly <assembly> --buffer_size 5000 --no_stats --quiet plus one format flag), the default, --tab, --vcf and --json data rows match Ensembl VEP 116.2 apart from the consequence-term divergences the corpus manifests document; header lines that carry a time, a path, the command line or Perl API component versions match in shape. --vcf also switches on --symbol, --biotype and --numbers, as in VEP, and --json output is unescaped (VEP’s --no_escape behavior; vep-rs has no --no_escape flag). Under --everything, vep-rs also switches on --allele_number and --hgvsg, which VEP’s --everything does not, so the ALLELE_NUM and HGVSg header keys differ there. The formats, the header blocks and the golden-corpus tests are described in output-formats.md.

Parquet output

--output_format=parquet writes a TSV intermediate (one row per (allele × transcript-consequence) tuple) and post-processes it to a Hive-partitioned Parquet directory via a duckdb CLI subprocess. The intermediate is deleted on success unless the hidden --keep_intermediate is given. With -o STDOUT the TSV intermediate is streamed to stdout and no Parquet is written.

Requirements: the duckdb CLI, 1.2 or newer, must be on PATH. Install via brew install duckdb (macOS) or the CLI archive from https://duckdb.org/docs/installation/ (Linux: the duckdb_cli-linux-*.zip release asset). vep-rs checks for it after the FASTA, plugins and variation cache are loaded and before the first variant is read, and fails there if duckdb is missing or too old, so no annotation is spent on a run it cannot finalize.

Schema: five key columns (chrom, pos, end, ref, alt) then exactly the --tab columns in --tab order; pos/end are BIGINT, DISTANCE INTEGER, STRAND TINYINT, everything else VARCHAR with - stored as NULL, except the allele columns (ref, alt, Allele), where - is a real allele (a deletion’s ALT, an insertion’s REF) and is kept.

Writer options (all chosen for the reader): Parquet v2, ZSTD level 9, row groups of 122,880 rows sorted by (chrom, pos, ref, alt), a dictionary and a Bloom filter (0.1% false-positive rate) on every populated column of the flat shape (asserted by the parity tests; a column NULL throughout a row group has neither), the partition column stored inside the files, and the run’s identity (version, assembly, cache, command line, cache source versions) in the footer’s key-value metadata. The dictionary limit equals the row group size, which a flat column’s distinct values can never exceed; a LIST column of the nested shape keeps its dictionary and Bloom filter only while its distinct elements in a row group stay within that limit, so a column whose elements are mostly distinct, such as HGVSc, carries neither. The hidden --parquet_row_group_size N overrides the row group size (rounded up to a multiple of 2,048, DuckDB’s vector size, which the dictionary limit follows so that a row group with a distinct value per row keeps its Bloom filter); it exists so a small input can be written as several row groups under test.

Shape (--parquet_shape):

• nested (default): one row per (record, allele); the per-consequence columns are LIST columns aligned index-wise. Query with UNNEST or list_contains:

  SELECT chrom, pos, ref, alt
  FROM read_parquet('out.parquet/**/*.parquet', hive_partitioning=false)
  WHERE list_contains(Feature, 'ENST00000366667')
    AND list_contains(IMPACT, 'HIGH');
  

• flat: one row per (allele × transcript-consequence) tuple; every column scalar, so predicates push down directly:

  SELECT chrom, pos, ref, alt, Consequence, IMPACT
  FROM read_parquet('out.parquet/**/*.parquet', hive_partitioning=false)
  WHERE Feature = 'ENST00000366667' AND IMPACT = 'HIGH';
  

hive_partitioning=false keeps chrom as the stored VARCHAR; Hive type inference would otherwise read chrom=21 as a number.

Cache / Offline

The environment variable VEP_FASTA_STORAGE selects how the FASTA is held: mmap (default) maps the file, memory reads it into RAM; any other value is an error.

Species / Assembly

Runtime

Output Control

These flags control which annotation fields appear in the output (--coding_only and --no_intergenic are accepted and have no effect). --everything switches on VEP’s --everything set plus --allele_number and --hgvsg.

Allele Frequencies

Filtering / Picking

Plugins

Dylib plugins implement ABI version 1 (vep_plugin_abi_version, vep_plugin_create, vep_plugin_init, vep_plugin_run, vep_plugin_free, vep_plugin_destroy, vep_plugin_name, vep_plugin_version). After the built-in plugins have run, each is called once per transcript consequence with the consequence and the variant as JSON and returns a JSON object whose entries become fields of the default format’s Extra column and of the --json output. The contract has no header symbol, so a dylib field carries no ## description line and no --tab or --vcf column. A run-time failure in a dylib plugin is logged as an error and the batch continues. crates/vep-plugin/examples/echo_plugin.rs is a working example (built as a cdylib) and crates/vep-cli/src/dylib_plugins.rs is the host side.

Transcript Sets

Statistics

Verbosity

Miscellaneous

Compatibility with Perl VEP

What the flag tables above mark “Accepted for VEP compatibility” is the whole list of Perl VEP behaviour vep-rs does not implement; this section gathers it.

Consequence terms never assigned. Six regulatory-feature terms (TFBS_ablation, TFBS_amplification, TF_binding_site_variant, regulatory_region_ablation, regulatory_region_amplification, regulatory_region_variant) need a regulatory-feature cache that is not loaded: --regulatory, alone or through --everything, is accepted and warns that regulatory-feature annotation is not implemented. The root term sequence_variant has no predicate, and Perl VEP’s consequence engine never assigns it either. The other 34 of Perl VEP’s 41 Sequence Ontology terms are assigned.

Input formats. --format takes vcf, ensembl (the tab-delimited default format), hgvs and region (chr:start-end/allele and chr:start-end:strand/allele), or guess. HGVS input is genomic (:g.) only; :c., :n., :p. and :r. notation is rejected as not implemented. The id, spdi and caid formats are not read: Perl VEP resolves all three through its variation database and refuses them in --offline mode.

Refused flags. Three Ensembl VEP 116 flags are declared so that the command line names them, and refused with an error that says what each would do: --regulatory_gff and --extended_promoters belong to regulatory annotation, --custom_suppress_filter to custom annotation; neither is supported.

No database mode. vep-rs is offline-first and never contacts a database; --database, --host, --port, --user and --password do not exist and are rejected as unknown flags. The transcript set is the --json_cache contents (cache-setup.md), so --refseq, --merged and --gencode_basic select nothing.

Accepted without effect. --custom (custom annotation files are not processed); --regulatory; the statistics flags --stats_file, --stats_text and --no_stats (no statistics file is written with or without them); --mirna (the miRNA column is added and always empty); --cache, --offline, --dir, --dir_cache and --cache_version (they locate no cache; see the Cache table); --coding_only and --pick_order. Protein domains are never mapped: the DOMAINS field exists and protein features are read from the cache, but --domains leaves the column empty, and the native cache builder writes no domain features (the Ensembl GFF3 it reads carries none).

Examples

Basic offline annotation

vep -i input.vcf -o output.txt \
    --offline --cache \
    --json_cache /path/to/json_cache \
    --species homo_sapiens --assembly GRCh37

VCF output with common fields

vep -i input.vcf -o annotated.vcf \
    --vcf --offline --cache \
    --json_cache /path/to/json_cache \
    --everything

JSON output

vep -i input.vcf -o output.json \
    --json --offline --cache \
    --json_cache /path/to/json_cache \
    --everything

Clinical plugins

vep -i input.vcf -o output.txt \
    --offline --cache --json_cache /path/to/json_cache \
    --assembly GRCh38 \
    --plugin CADD,snv=/path/to/cadd/whole_genome_SNVs.tsv.gz,indels=/path/to/cadd/gnomad.genomes.r4.0.indel.tsv.gz \
    --plugin REVEL,file=/path/to/revel/revel_scores.tsv.gz \
    --plugin SpliceAI,snv=/path/to/spliceai/spliceai_scores.raw.snv.vcf.gz \
    --everything --force

--assembly is not optional here. CADD and dbscSNV use it to reject a data file built from the other genome; REVEL uses it to select which of its two coordinate columns to read and rejects a copy whose tabix index was built on the other column. Without it those guards are inert and REVEL falls back to the GRCh37 column with a warning, so a GRCh38-indexed file annotates nothing. SpliceAI also accepts indel= and cutoff=; only the openly published GRCh38 SNV file is validated, and the indel files, distributed through Illumina BaseSpace, are unsupported data rather than a rejected parameter (see plugins.md).

Parallel annotation

vep -i large_input.vcf -o output.txt \
    --offline --cache --json_cache /path/to/json_cache \
    --fork 8 --buffer_size 10000

Filtered output (one consequence per allele per gene)

vep -i input.vcf -o output.txt \
    --offline --cache --json_cache /path/to/json_cache \
    --pick_allele_gene --canonical \
    --everything