Command-line reference¶
Run ViroSync through Pixi from the repository root:
pixi run virosync -i INPUT -o OUTPUT is a shortcut for
pixi run virosync run -i INPUT -o OUTPUT. CLI values override YAML values only
when you supply them. Use -h or --help on any command.
Global options¶
Global options must occur before the command. The bare -i and -o shortcut
also accepts them before the input option.
| Option | Behavior |
|---|---|
-v, --verbose |
Show diagnostic output. A command-local -v is also available on run and orchestrate setup. |
-q, --quiet |
Hide the banner, progress display, and final summary. Errors remain visible. |
--version |
Print the ViroSync version and exit. |
-h, --help |
Print help and exit. |
Show system information¶
Print the ViroSync and database versions, Python and PyTorch versions, CUDA state, CPU count, and installed memory.
| Option | Behavior |
|---|---|
--config PATH |
Read the database root from this config. Default: config/orchestration.yaml. VIROSYNC_DB_ROOT has priority. |
Run ViroSync¶
Input can be one uncompressed genome FASTA, a directory of FASTA files, or a
text file with one FASTA path per line. A directory scan uses only its top
level and matches the lowercase extensions .fna, .fasta, and .fa.
Relative paths in a list file start at the current working directory.
virosync orchestrate run calls the same command.
Input and execution¶
| Option | Behavior |
|---|---|
-i PATH, --input PATH |
Required input. Accepts an uncompressed .fna, .fasta, or .fa file, a directory, or a list file. The path must exist. |
-o PATH, --output PATH |
Required output root. ViroSync creates one subdirectory per genome. |
--config PATH |
Read orchestration and pipeline defaults from this YAML file. The path must exist. |
--clean-run |
Start again without reusing completed output. Otherwise, resume when the input, settings and saved outputs still match. |
-w N, --workers N |
Run up to N genomes at once. Minimum: 1. The shipped config sets 6. |
--threads-per-worker N |
Set tool threads for each genome. Minimum: 1. Default: compute.threads, or 8 if unset. ViroSync lowers the value to compute.max_threads (48 in the shipped config) divided by the genome limit and prints a warning. |
--max-concurrent-genomes N |
Set the same genome limit as --workers. Minimum: 1. Both values must agree if you supply both. |
-v, --verbose |
Show the effective config and diagnostic logs instead of the progress display. |
Without --clean-run, reuse requires matching run identities and validated
checkpoints and outputs, including the repeat-candidate table. See
Output compatibility and resume
for the required files and schema versions.
Database and tool paths¶
All path overrides in this table must exist.
| Option | Behavior |
|---|---|
--hmm-db PATH |
Override the viral-marker HMM database. |
--hmm-allowlist PATH |
Override the HMM allowlist. |
--marker-faa-db PATH |
Set the marker-protein FASTA build input. This has priority over --marker-faa-dir. |
--marker-faa-dir PATH |
Set the directory of marker-protein FASTA build inputs. |
--marker-db PATH |
Override the prebuilt marker DIAMOND database used for Phase 1 validation. --rebuild-db ignores it. |
--faa-dir PATH |
Set the protein FASTA directory used for a run-local marker database build. |
--gvclass-db PATH |
Override the GVClass database. |
--gvclass PATH |
Set the GVClass install directory and enable batch classification. Default: VIROSYNC_GVCLASS_PATH. The directory must contain an executable gvclass. A tool error omits gvclass_results.tsv, but the core run continues. |
--diamond-db PATH |
Override the Phase 3 phylogenetic DIAMOND database. |
Marker discovery and scoring¶
| Option | Behavior |
|---|---|
--enable-phylogenetic, --disable-phylogenetic |
Enable or disable GVClass and DIAMOND phylogenetic validation. |
--assembly-mode MODE |
Set HMM seed handling to default, fragmented, relaxed, or strict. |
--high-tier-threshold FLOAT |
Set the HIGH confidence cutoff from 0 to 1. Default: config value or 0.7. |
--low-tier-threshold FLOAT |
Set the LOW confidence cutoff from 0 to 1. Default: config value or 0.2. It must be below the HIGH cutoff. |
--hmm-chunk-size N |
Set the number of predicted open reading frames per HMM chunk. Minimum: 1. |
--rebuild-db, --no-rebuild-db |
Force or avoid a run-local marker database build. Forced mode ignores --marker-db and needs an FAA directory plus one marker FASTA source, from CLI or config. Without a prebuilt database, ViroSync must build one even when the flag is off. |
--phase1-initial-window-bp N |
Set the first marker-cluster window and the maximum gap to an independently validated neighbor for novel-marker support, in base pairs. Minimum: 1. Default: 10000. |
--phase1-initial-window-genes N |
Set the first marker-cluster window in genes. Minimum: 1. Default: 5. |
--phase1-min-markers-initial N |
Set the minimum marker count for an initial cluster. Minimum and default: 1. |
--phase1-extension-kb N |
Extend from the outer markers by this many kilobases. Minimum: 0. Default: 5. |
--phase1-merge-distance N |
Merge overlapping regions within this base-pair gap. Minimum: 0. Default: 1000. |
--frameshift-screening, --no-frameshift-screening |
Enable or disable native codon-aware marker rescue. Off by default; uses the standard Pixi environment. |
Compute and optional evidence¶
| Option | Behavior |
|---|---|
--device DEVICE |
Select cpu or cuda. Default: config value or cpu. |
--search-backend diamond |
Select the sequence search backend. diamond is the only accepted value. |
--gpu-id N |
Select a GPU by its zero-based index. |
--skip-masking, --no-skip-masking |
Force masking off or enable TRF plus RepeatMasker. --no-skip-masking needs exactly one execution.masking.repeatmasker_species or repeatmasker_library value. |
--skip-structural, --no-skip-structural |
Skip or run Boltz and Foldseek structural homology. --boltz clears the skip unless you set it explicitly. |
--boltz, --no-boltz |
Enable or disable Boltz and Foldseek. Missing runtime or data disables the layer with a warning. |
--tmvec, --no-tmvec |
Enable or disable TMVec2 BFVD search. An enabled search fails before analysis when its runtime or resources do not pass validation. |
--tmvec-gpu, --no-tmvec-gpu |
Require or do not require TMVec2 on CUDA. --tmvec-gpu also enables TMVec2 and selects CUDA. It cannot be combined with --device cpu or --no-tmvec. |
--interproscan, --no-interproscan |
Enable or disable InterProScan. Missing runtime or data disables the layer with a warning. |
--use-taxonomy-ml, --no-taxonomy-ml |
Enable or disable per-gene ML support for seed-preserving outward extension. |
--taxonomy-ml-model MODEL |
Select logreg, gbdt, or xgboost for that support model. Host stops and seed containment still apply. |
The core direct-repeat assessment runs
by default and has no separate enable flag. It reads unmasked host sequence;
--skip-masking controls preprocessing and does not disable this assessment.
Orchestration commands¶
The orchestration group contains setup, resource verification, system
information, and the run command.
Install resources¶
Install databases and optional analysis resources.
| Option | Behavior |
|---|---|
--config PATH |
Read or update this config. Default: config/orchestration.yaml. |
--db-root PATH |
Install the core databases here. You can also set VIROSYNC_DB_ROOT. |
--core-resource PATH_OR_URL |
Use a different core archive. Supply its version, archive SHA-256 and manifest SHA-256 with the options below. |
--core-version TEXT |
Set the expected core-resource version for a custom source. |
--core-resource-sha256 HEX |
Set the expected SHA-256 for the full core archive. |
--core-manifest-sha256 HEX |
Set the expected SHA-256 for RESOURCE_MANIFEST.json inside the archive. |
--tmvec, --no-tmvec |
Install or skip the configured TMVec2 BFVD resource set. |
--tmvec-url PATH_OR_URL |
Override the configured TMVec2 BFVD bundle. Use it with --tmvec-resource-sha256. |
--tmvec-resource-sha256 HEX |
Set the SHA-256 for a custom TMVec2 BFVD bundle. |
--tmvec-dir PATH |
Install TMVec2 here. Overrides phase3.tmvec_database_dir. If unset, setup chooses a directory beside the core databases. |
--interproscan-url PATH_OR_URL |
Install a user-supplied InterProScan archive. Use it with --interproscan-resource-sha256. |
--interproscan-resource-sha256 HEX |
Set the SHA-256 for the InterProScan archive. |
--interproscan-dir PATH |
Set the InterProScan target. |
--boltz-db-dir PATH |
Record a Foldseek viral-structure database prefix for Boltz. |
--interactive-optional, --no-interactive-optional |
Enable or disable optional-resource prompts. Prompts appear only in an interactive terminal. Default: disabled. |
--force |
Reinstall resources even when the target exists. |
--write-config, --no-write-config |
Enable or disable writes of resolved paths to the config. Default: write. |
-v, --verbose |
Show source, target, config, and validation details. |
Resource commands¶
The resource group contains the verify command.
Verify core resources¶
Check the installed databases.
| Option | Behavior |
|---|---|
--config PATH |
Read the expected version and manifest digest. Default: config/orchestration.yaml. |
--db-root PATH |
Check databases at this path. You can also set VIROSYNC_DB_ROOT. |
--full |
Check file contents as well as names, sizes and version. Takes longer than the default check. |
Show orchestration information¶
Print the orchestration backend, ViroSync version, and input forms. This command has no command-specific options.
Check optional tools¶
Run pixi run -e structural check-structural-runtime with the options below.
| Option | Behavior |
|---|---|
--config PATH |
Read optional-feature paths and states from this config. Default: config/orchestration.yaml. |
--require-tmvec |
Test TMVec2 and its database with a protein query. Runs on CPU unless the config selects CUDA. |
--require-boltz |
Exit with status 1 unless Boltz, Foldseek, the MSA setting, and the Foldseek database pass. |
--require-interproscan |
Exit with status 1 unless an executable interproscan.sh exists in the configured directory. |
--require-all-optional |
Apply all three required checks. |
With no required option, check only tools enabled in the config. A failed required check returns a nonzero exit status. This command does not download models or databases.