> For the complete documentation index, see [llms.txt](https://help.connected.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.connected.illumina.com/annotation/v4.0/software-functionality/command-line-parameters.md). # Command Line Parameters ### General Usage ``` Annotator [options] ``` #### Global Flags | Flag | Description | | ----------------- | ------------------------- | | `--help`, `-h` | Show help for the command | | `--version`, `-v` | Show version information | #### Available Commands | Command | Description | | ------------------ | ----------------------------------------------------------------------------------------- | | `setup` | Setup annotation environment with license and config files (internet connection required) | | `download` | Download data files from the cloud (internet connection required) | | `annotate` | Run annotation on a VCF file | | `list` | Display available data catalogs or data sources for DRAGEN Annotation | | `version-validate` | Validate downloaded data version with the provided config | *** ### setup Configure the annotation environment interactively or non-interactively. The setup wizard guides through four steps: data directory, credentials, catalog selection, and assembly selection. It generates run config files and optionally downloads data. The default mode is interactive. At the end of the interactive session, the equivalent non-interactive command line is provided for convenience. For new users, the interactive mode is highly recommended. #### Interactive Example (Recommended) ``` $ dotnet Annotator.dll setup --------------------------------------------------------------------------- DRAGEN Annotation (c) 2026 Illumina Inc. 4.0.0+ffeb8ce05ca46c9a11b1f44d44debdb707f538d9 --------------------------------------------------------------------------- This assistant will guide you through configuring and downloading annotation data. Available Annotation Sets ------------------------- Basic - Open/public data sources (ClinVar, gnomAD, dbSNP, REVEL, etc.) Requires a MyIllumina API Key (free from https://accounts.login.illumina.com/). Professional - Basic + paid/proprietary sources such as: OMIM, COSMIC, SpliceAI, PrimateAI-3D, PromoterAI Requires a DRAGEN (Serial Number or API key), or Cloud (API Key + Secret pair) credentials. Step 1 of 4: Data Directory --------------------------- This directory will store all downloaded annotation data. Enter data directory path: /data/annotations Step 2 of 4: Credentials ------------------------ Detected credentials (highest priority first): 1. DRAGEN Serial from /data/annotations/license/credentials.json (Professional) [recommended] 2. Enter different credentials Select (1-2) [default 1]: 2 No credentials were found. Let's create one. Select the type of credential you have: 1. Existing Credentials File (credentials.json) 2. Existing Lic Credentials File (dragen_credentials.txt) (Professional) 3. Existing DRAGEN API Key File (dragen_api_key.txt) (Professional) 4. DRAGEN Serial Number (Professional) 5. BYOL License (API Key + Secret) (Professional) 6. DRAGEN API Key (Professional) 7. MyIllumina API Key (Basic) Select (1-7) [default 1]: 4 Enter DRAGEN serial number: Save directory [/data/annotations/license]: Credentials saved to /data/annotations/license/credentials.json Step 3 of 4: Catalog -------------------- Available data catalogs: 1. 20260501 name May 2026 released 2026-05-01 includes basic, germline-tagging, premium, tmb 2. dragen-4.5 name Dragen 4.5 released 2025-01-01 includes germline-tagging, premium, tmb Select (1-2) [default 1]: 1 Step 4 of 4: Assemblies ----------------------- Available assemblies: 1. GRCh37 2. GRCh38 3. All Select (1-3) [default 3]: 3 Configuration Summary --------------------- Data directory: /data/annotations Credentials: DRAGEN Serial from /data/annotations/license/credentials.json Catalog: May 2026: basic, germline-tagging, premium, tmb Assemblies: GRCh37, GRCh38 Generated run configs: GRCh37: /data/annotations/runConfigs/GRCh37.20260501.basic.json /data/annotations/runConfigs/GRCh37.20260501.germline-tagging.json /data/annotations/runConfigs/GRCh37.20260501.premium.json /data/annotations/runConfigs/GRCh37.20260501.tmb.json GRCh38: /data/annotations/runConfigs/GRCh38.20260501.basic.json /data/annotations/runConfigs/GRCh38.20260501.germline-tagging.json /data/annotations/runConfigs/GRCh38.20260501.premium.json /data/annotations/runConfigs/GRCh38.20260501.tmb.json To reproduce this setup non-interactively: dotnet Annotator.dll setup --non-interactive \ --data.directory /data/annotations \ --data.catalog 20260501 \ --data.assemblies GRCh37,GRCh38 Proceed with download? [Y/n]: n Setup cancelled; no data was downloaded. Run configs saved to: /data/annotations/runConfigs Setup report: /data/annotations/logs/setup.20260501.json To download later, run a single command covering all generated configs: dotnet Annotator.dll download \ --config /data/annotations/runConfigs/GRCh37.20260501.basic.json \ --config /data/annotations/runConfigs/GRCh37.20260501.germline-tagging.json \ --config /data/annotations/runConfigs/GRCh37.20260501.premium.json \ --config /data/annotations/runConfigs/GRCh37.20260501.tmb.json \ --config /data/annotations/runConfigs/GRCh38.20260501.basic.json \ --config /data/annotations/runConfigs/GRCh38.20260501.germline-tagging.json \ --config /data/annotations/runConfigs/GRCh38.20260501.premium.json \ --config /data/annotations/runConfigs/GRCh38.20260501.tmb.json ``` #### Non-Interactive Example ```bash Annotator setup --non-interactive \ --data.directory /data/annotations \ --data.catalog 20260501 \ --data.assemblies GRCh37,GRCh38 ``` #### Downloading a Subset of a Catalog If you only need specific annotation sets (e.g. only TMB for GRCh38), pass the corresponding config(s) to the `download` command: ```bash dotnet Annotator.dll download \ --config /data/annotations/runConfigs/GRCh38.20260501.tmb.json ``` Or combine multiple configs to download only what you need: ```bash dotnet Annotator.dll download \ --config /data/annotations/runConfigs/GRCh37.20260501.germline-tagging.json \ --config /data/annotations/runConfigs/GRCh38.20260501.germline-tagging.json ``` #### Help Output ``` USAGE: dotnet Annotator.dll setup [--config ] [options] OPTIONS: --config Path to setup config JSON file --data.directory Data directory path --data.catalog Catalog Id or Name (e.g. "20260501" or "May 2026") --data.assemblies Comma-separated assemblies (e.g. GRCh37,GRCh38) --data.autoDownload true|false Download annotation data after generating run configs. Default: interactive mode prompts, non-interactive does not download. --license.credentialsFile --license.apiKeyFile --license.licCredentialsFile --license.autoDetect true|false Auto-detect credentials from DRAGEN serial, env vars, and default folders (default: true). When false, only explicit --license.* files are used. --license.overwrite true|false Rotate existing credentials.json to .bak and overwrite (default: true). When false, setup fails if credentials.json already exists. --interactive / --non-interactive Force interactive/non-interactive mode --help, -h Show this help message ``` *** ### download Download annotation data files from the cloud. Supports single or multiple configs to download a superset of data versions in one pass. If no `--config` flags are provided, the command auto-discovers all `*.json` files under `/runConfigs/`, optionally filtered by `--data.assembly`. #### Example Using the run configs generated by `setup`: ```bash dotnet Annotator.dll download \ --config /data/annotations/runConfigs/GRCh37.20260501.basic.json \ --config /data/annotations/runConfigs/GRCh37.20260501.germline-tagging.json \ --config /data/annotations/runConfigs/GRCh37.20260501.premium.json \ --config /data/annotations/runConfigs/GRCh37.20260501.tmb.json \ --config /data/annotations/runConfigs/GRCh38.20260501.basic.json \ --config /data/annotations/runConfigs/GRCh38.20260501.germline-tagging.json \ --config /data/annotations/runConfigs/GRCh38.20260501.premium.json \ --config /data/annotations/runConfigs/GRCh38.20260501.tmb.json ``` Or let auto-discovery find all configs in the data directory: ```bash dotnet Annotator.dll download --data.directory /data/annotations ``` #### Help Output ``` USAGE: dotnet Annotator.dll download [--config ]... [options] CONFIGS (one or more): --config Path to a RunConfig JSON file. Repeat to download a superset of versions across multiple configs. If omitted, all *.json under /runConfigs are used (filtered by --data.assembly when provided). COMMON OVERRIDES: --data.directory Override data directory --data.assembly Override assembly (GRCh37, GRCh38) --parallel.workers Number of concurrent downloads --license.credentialsFile Path to credentials JSON file --license.apiKeyFile Path to API key file --license.licCredentialsFile Path to LIC credentials file VERSION SELECTOR OVERRIDES: --data.versionSelector.. Override specific data source version Example: --data.versionSelector.clinvar.SmallVariant 20260201 OTHER: --help, -h Show this help message ``` *** ### annotate Run annotation on a VCF file using a config-first approach. A JSON config file defines the annotation environment and can be overridden on the command line with dotted key paths. #### Example ```bash dotnet Annotator.dll annotate \ --config /data/annotations/runConfigs/GRCh38.20260501.premium.json \ --input.file /data/samples/sample.vcf.gz \ --output.directory /data/annotations/results ``` #### Help Output ``` --------------------------------------------------------------------------- DRAGEN Annotation (c) 2026 Illumina Inc. 4.0.0+ffeb8ce05ca46c9a11b1f44d44debdb707f538d9 --------------------------------------------------------------------------- USAGE: dotnet Annotator.dll annotate --config [options] REQUIRED --config Path to RunConfig JSON file --input.file Path to input VCF file --output.directory Directory for output files DATA OPTIONS: --data.directory Root directory for annotation data files --data.assembly Genome assembly (GRCh37, GRCh38) --data.customStrTsv Path to custom STR TSV file --data.catalog Catalog identifier this data set was sourced from OUTPUT OPTIONS: --output.prefix Output file stem; overrides the stem derived from input.file --output.format Output format: json or vcf LICENSE OPTIONS: --license.credentialsFile Path to license credentials JSON file --license.apiKeyFile Path to API key file --license.licCredentialsFile Path to LIC credentials file --license.throwInvalidLicenseError Throw error on invalid license (default: false) ANNOTATION OPTIONS: --annotationOptions.forceMitochondrialAnnotation Force mitochondrial annotation (default: false) --annotationOptions.useLegacyVids Enable legacy VID support (default: false) --annotationOptions.enableDq Report DQ from VCF samples field (default: false) --annotationOptions.enableBidirectionalFusions Enable bidirectional gene fusions (default: false) --annotationOptions.disableConsequencePrioritization Disable consequence prioritization (default: false) --annotationOptions.enableIntervalSvTypeMatching Enable interval SV type matching (default: true) --annotationOptions.enableMethylationAnnotation Enable methylation annotation (default: false) --annotationOptions.saCutoffLength SV size cutoff for supplementary annotations --annotationOptions.iscnSvCutoffLength SV cutoff for ISCN simple nomenclature LOGGING OPTIONS: --logging.level Log level: debug, info, warning, error, verbose (default: info) PARALLEL OPTIONS: --parallel.workers Number of worker processes (default: CPU count) --parallel.singleWorkerPositionsCountThreshold Position count threshold for single worker mode (default: 500000) VERSION SELECTOR: --data.versionSelector.. Data source version overrides Example: --data.versionSelector.clinvar.smallvariant 20251103 OTHER: --help, -h Show this help message --version, -v Show version information ``` Setup-generated run configs set `parallel.workers` to `2`. If the field is omitted from a RunConfig, the annotate default is the machine's CPU count. *** ### list Display annotation data sources available on the server, or list available data catalogs. #### Usage ``` Annotator list [options] ``` #### Help Output ``` USAGE: dotnet Annotator.dll list [options] MODES: --catalogs List available data catalogs (no --data.assembly required) --data.assembly List data sources for an assembly (GRCh37, GRCh38) DATA OPTIONS: --data.catalog Filter data sources by catalog (Id or Name) --data.directory Local directory (marks locally-available files with (*)) --data.sources Comma-separated data sources to filter LICENSE OPTIONS: --license.credentialsFile Path to credentials JSON file (default: /license/credentials.json) --license.apiKeyFile Path to API key file --license.licCredentialsFile Path to LIC credentials file OTHER: --help, -h Show this help message ``` #### Examples ```bash # List available catalogs (credentials auto-discovered from data directory) Annotator list --catalogs --data.directory /data/annotations # List available catalogs (explicit credentials, e.g. before first download) Annotator list --catalogs --license.credentialsFile /data/annotations/license/credentials.json ``` Output: ``` --------------------------------------------------------------------------- DRAGEN Annotation (c) 2026 Illumina Inc. 4.0.0+738fbe350b24778e7c398ef7fad19e69f5cd33b9 --------------------------------------------------------------------------- Available Catalogs ==================================================================================================== Id | Name | Released | Assemblies | Categories ==================================================================================================== 20260501 | May 2026 | 2026-05-01 | GRCh37, GRCh38 | basic, germline-tagging, premium, tmb dragen-4.5 | Dragen 4.5 | 2025-01-01 | GRCh37, GRCh38 | germline-tagging, premium, tmb ---------------------------------------------------------------------------------------------------- ``` ```bash # List all GRCh38 data sources (with data directory for local file markers) Annotator list --data.assembly GRCh38 --data.directory /data/annotations # List all GRCh38 data sources (explicit credentials, no data directory) Annotator list --data.assembly GRCh38 \ --license.credentialsFile /data/annotations/license/credentials.json # List data sources for a specific catalog Annotator list --data.assembly GRCh38 --data.catalog 20260501 \ --data.directory /data/annotations ``` Output: ``` --------------------------------------------------------------------------- DRAGEN Annotation (c) 2026 Illumina Inc. 4.0.0+738fbe350b24778e7c398ef7fad19e69f5cd33b9 --------------------------------------------------------------------------- Filtering by catalog: May 2026 (20260501) Assembly: GRCh38 ====================================================================================================================================================== Data Source | Annotation Type | Description | Version ====================================================================================================================================================== ABRaOM | SmallVariant | ABRaOM | SABE-WGS-1171_trimmed ------------------------------------------------------------------------------------------------------------------------------------------------------ DANN | Score | DANN | 20200205 ------------------------------------------------------------------------------------------------------------------------------------------------------ DECIPHER | StructuralVariant | DECIPHER | 201509 ------------------------------------------------------------------------------------------------------------------------------------------------------ Ensembl | GeneModels | Ensembl | 112 ------------------------------------------------------------------------------------------------------------------------------------------------------ FusionCatcher | GeneFusion | FusionCatcher | 1.33 ------------------------------------------------------------------------------------------------------------------------------------------------------ GME | SmallVariant | GME | 20160618 ------------------------------------------------------------------------------------------------------------------------------------------------------ GenomeAssembly | GenomeAssembly | GenomeAssembly | GRCh38.p14 ------------------------------------------------------------------------------------------------------------------------------------------------------ Gerp | Score | Gerp | 20110522 ------------------------------------------------------------------------------------------------------------------------------------------------------ HGNC | GeneModels | HGNC | 20240603 ------------------------------------------------------------------------------------------------------------------------------------------------------ MultiZ100Way | Protein | MultiZ100Way | 20171006 ------------------------------------------------------------------------------------------------------------------------------------------------------ PrimateAI | SmallVariant | PrimateAI | 0.2 ------------------------------------------------------------------------------------------------------------------------------------------------------ PromoterAI | SmallVariant | PromoterAI | 1.1 ------------------------------------------------------------------------------------------------------------------------------------------------------ REVEL | SmallVariant | REVEL | 20200205 ------------------------------------------------------------------------------------------------------------------------------------------------------ RefSeq | GeneModels | RefSeq | GCF_000001405.40-RS_2023_10 ------------------------------------------------------------------------------------------------------------------------------------------------------ TOPMed | SmallVariant | TOPMed | freeze_5 ------------------------------------------------------------------------------------------------------------------------------------------------------ UcscCpgIsland | MethylationRegion | UcscCpgIsland | 20221018 ------------------------------------------------------------------------------------------------------------------------------------------------------ alphaMissense | SmallVariant | AlphaMissense | 1.0 ------------------------------------------------------------------------------------------------------------------------------------------------------ clingen | Gene | ClinGen disease validity curations | 20250815 | | ClinGen Dosage Sensitivity Map | 20250815 | StructuralVariant | ClinGen Dosage Sensitivity Map | 20250815 ------------------------------------------------------------------------------------------------------------------------------------------------------ clingen (legacy) | StructuralVariant | ClinGen | 20160414 ------------------------------------------------------------------------------------------------------------------------------------------------------ clinvar | SmallVariant | ClinVar | 20250601_trimmed | StructuralVariant | ClinVar | 20250601 ------------------------------------------------------------------------------------------------------------------------------------------------------ clinvar-preview | SmallVariant | ClinVarPreview | 20250601 | StructuralVariant | ClinVarPreview | 20250601 ------------------------------------------------------------------------------------------------------------------------------------------------------ cosmic | Gene | Cosmic Cancer Gene Census | 102 | GeneFusion | COSMIC gene fusions | 102 | SmallVariant | COSMIC | 102_trimmed ------------------------------------------------------------------------------------------------------------------------------------------------------ dbSNP | SmallVariant | dbSNP | 157 ------------------------------------------------------------------------------------------------------------------------------------------------------ globalAllele | SmallVariant | dbSNP | 151 ------------------------------------------------------------------------------------------------------------------------------------------------------ gnomad | Gene | gnomAD_gene_scores | 4.1 | LowComplexityRegions | gnomAD_LCR | 2.1 | SmallVariant | gnomAD | 4.1_trimmed | StructuralVariant | gnomAD_SV | 4.1 | | gnomAD-cnv | 4.1 ------------------------------------------------------------------------------------------------------------------------------------------------------ gnomad-exome | SmallVariant | gnomAD_exome | 4.1_trimmed ------------------------------------------------------------------------------------------------------------------------------------------------------ mitomap | SmallVariant | MITOMAP | 20200819 | StructuralVariant | MITOMAP_SV | 20200819 ------------------------------------------------------------------------------------------------------------------------------------------------------ omim | Gene | OMIM | 20250815 ------------------------------------------------------------------------------------------------------------------------------------------------------ oneKg | RefMinor | 1000 Genomes Project | Phase 3 v3plus | SmallVariant | 1000 Genomes Project | Phase 3 v3plus_trimmed | StructuralVariant | 1000 Genomes Project (SV) | Phase 3 v5a ------------------------------------------------------------------------------------------------------------------------------------------------------ phylopScore | ConservationScore | phyloP | hg38 | Score | PhyloPPrimate | 1.0 ------------------------------------------------------------------------------------------------------------------------------------------------------ primateAI-3D | SmallVariant | PrimateAI-3D | 1.0 ------------------------------------------------------------------------------------------------------------------------------------------------------ spliceAI | SmallVariant | SpliceAI | 1.3 ------------------------------------------------------------------------------------------------------------------------------------------------------ (*) : available in local directory ``` ```bash # List specific sources filtered by catalog, show which are locally available Annotator list --data.assembly GRCh38 --data.catalog 20260501 \ --data.directory /data/annotations --data.sources clinvar,gnomad # List GRCh37 data sources Annotator list --data.assembly GRCh37 --data.directory /data/annotations ``` *** ### version-validate Validate that all data source versions specified in a config file have corresponding files present on disk. #### Usage ``` Annotator version-validate --config [options] ``` #### Required | Option | Description | | ---------- | --------------------------- | | `--config` | Path to RunConfig JSON file | #### Common Overrides | Option | Description | Default | | ------------------ | -------------------------------------------- | ----------- | | `--data.directory` | Override data directory (must exist on disk) | from config | | `--data.assembly` | Override assembly (GRCh37, GRCh38) | from config | #### Version Selector Overrides | Option | Description | | ---------------------------------------- | ------------------------------------- | | `--data.versionSelector..` | Override specific data source version | #### Validation Rules * The config must contain at least one entry in `data.versionSelector` * The `data.directory` must exist on disk * The `data.assembly` must be a valid assembly name * Every (source, type, version) tuple in the config must have a matching file in the data directory #### Example ```bash Annotator version-validate --config run_config.json # Override data directory for validation Annotator version-validate --config run_config.json --data.directory /mnt/data/annotations ``` *** ### RunConfig JSON Schema The `annotate`, `download`, and `version-validate` commands all use a RunConfig JSON file. Below is the structure: ```json { "schemaVersion": "1.0", "dateGenerated": "2026-01-15T00:00:00Z", "comment": "optional description", "data": { "directory": "/path/to/data", "assembly": "GRCh38", "customStrTsv": null, "catalog": "20260501", "versionSelector": { "clinvar": { "SmallVariant": "20260201", "StructuralVariant": "20260201" }, "gnomad": { "SmallVariant": "4.1.0" } } }, "input": { "file": "/path/to/input.vcf.gz" }, "output": { "directory": "/path/to/output", "prefix": null, "format": "json" }, "license": { "credentialsFile": null, "apiKeyFile": null, "licCredentialsFile": null, "throwInvalidLicenseError": false }, "annotationOptions": { "forceMitochondrialAnnotation": false, "useLegacyVids": false, "enableDq": false, "enableBidirectionalFusions": false, "disableConsequencePrioritization": false, "enableIntervalSvTypeMatching": true, "enableMethylationAnnotation": false, "saCutoffLength": null, "iscnSvCutoffLength": null }, "logging": { "level": "info" }, "parallel": { "workers": 2, "singleWorkerPositionsCountThreshold": 500000 } } ``` #### CLI Overrides Any key in the config can be overridden on the command line using its dotted path: ```bash --data.directory /new/path --output.format vcf --parallel.workers 4 ``` For the `versionSelector` dictionary, use the format: ```bash --data.versionSelector.. ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.connected.illumina.com/annotation/v4.0/software-functionality/command-line-parameters.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.