CLI Referenceο
Auto-generated: All command output below is captured live during documentation build from the actual
sirnaforgeCLI.
This reference shows each command with its real --help output and working examples.
Help & Versionο
Main Helpο
Usage: sirnaforge [OPTIONS] COMMAND [ARGS]...
siRNAforge - siRNA design toolkit for gene silencing
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --install-completion Install completion for the current shell. β
β --show-completion Show completion for the current shell, to β
β copy it or customize the installation. β
β --help Show this message and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Commands βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β search Search transcript references and optionally fetch sequences. β
β workflow Run the end-to-end workflow: transcripts β siRNA design β β
β off-target. β
β offtarget Run off-target analysis on pre-designed siRNA candidates. β
β design Design siRNA candidates from a transcript FASTA file. β
β validate Validate a FASTA file and report basic statistics. β
β version Show CLI version and author information. β
β config Print the default design parameter values. β
β cache Inspect and clear the unified reference cache. β
β sequences Manage siRNA sequences and metadata β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Versionο
ββββββββ Version Info ββββββββ
β 𧬠siRNAforge Toolkit β
β Version: 0.4.1 β
β Author: Austin S. Hovland. β
ββββββββββββββββββββββββββββββ
workflowο
Run complete siRNA design from gene query to scored candidates.
Helpο
Usage: sirnaforge workflow [OPTIONS] GENE_QUERY
Run the end-to-end workflow: transcripts β siRNA design β off-target.
This is the main orchestration command. It resolves transcriptome and miRNA
reference policies, designs candidates, and then runs off-target analysis on
the selected top candidates.
ββ Arguments ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β * gene_query TEXT Gene name or ID to analyze [required] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --input-fasta TEXT Local path or β
β remote URI to an β
β input FASTA file β
β (http/https/ftp) β
β --output-dir -o PATH Output directory β
β for all workflow β
β results β
β [default: β
β sirna_workflow_oβ¦ β
β --database -d TEXT Database to β
β search (ensembl, β
β refseq, gencode) β
β [default: β
β ensembl] β
β --design-mode TEXT Design mode: β
β sirna (default) β
β or mirna β
β (miRNA-biogenesiβ¦ β
β [default: sirna] β
β --top-n -n INTEGER RANGE Number of top β
β [x>=1] siRNA candidates β
β to select (also β
β used for β
β off-target β
β analysis) β
β [default: 100] β
β --species TEXT Comma-separated β
β canonical species β
β identifiers. This β
β single parameter β
β drives all β
β off-target β
β analysis: miRNA β
β database lookups β
β (default: 7 β
β species) and β
β transcriptome β
β fetching from β
β Ensembl (default: β
β 4 species). β
β Override specific β
β layers with β
β --mirna-species β
β or β
β --transcriptome-β¦ β
β Supported: human, β
β mouse, macaque, β
β rat, chicken, β
β pig, rhesus β
β [default: β
β chicken,pig,rat,β¦ β
β --mirna-db TEXT miRNA reference β
β database to use β
β for seed analysis β
β [default: β
β mirgenedb] β
β --mirna-species TEXT Override miRNA β
β species β
β identifiers β
β (comma-separatedβ¦ β
β When omitted, β
β automatically β
β maps from β
β --species. Use β
β this for surgical β
β control of miRNA β
β database queries. β
β --transcriptomeβ¦ TEXT Override or β
β extend β
β transcriptome β
β references for β
β off-target β
β analysis. β
β Accepts: local β
β file, HTTP(S) β
β URL, or β
β pre-configured β
β source (e.g., β
β 'ensembl_human_cβ¦ β
β When omitted, β
β automatically β
β fetches Ensembl β
β cDNA for species β
β selected via β
β --species. Custom β
β FASTA files are β
β cached and β
β indexed β
β automatically. β
β Use this to add β
β novel sequences β
β (e.g., synthetic β
β contigs) to the β
β default set. β
β --transcriptomeβ¦ TEXT Filter β
β transcriptome to β
β reduce size and β
β memory β
β requirements. β
β Comma-separated β
β filter names: β
β 'protein_coding' β
β (only β
β protein-coding β
β genes), β
β 'canonical_only' β
β (only canonical β
β isoforms). β
β Example: β
β --transcriptome-β¦ β
β protein_coding,cβ¦ β
β Filtered versions β
β are cached β
β separately with β
β automatic β
β indexing. β
β --offtarget-indβ¦ TEXT Comma-separated β
β overrides for β
β genome indices β
β used in β
β off-target β
β analysis. Format: β
β human:/abs/path/β¦ β
β When provided, β
β overrides β
β cached/default β
β genome β
β references. β
β --gc-min FLOAT RANGE Minimum GC β
β [0.0<=x<=100.0] content β
β percentage β
β [default: 30.0] β
β --gc-max FLOAT RANGE Maximum GC β
β [0.0<=x<=100.0] content β
β percentage β
β [default: 60.0] β
β --length -l INTEGER RANGE siRNA length in β
β [19<=x<=23] nucleotides β
β [default: 21] β
β --modifications -m TEXT Chemical β
β modification β
β pattern β
β (standard_2ome, β
β minimal_terminal, β
β maximal_stabilitβ¦ β
β none) β
β [default: β
β standard_2ome] β
β --overhang TEXT Overhang sequence β
β (dTdT for DNA, UU β
β for RNA) β
β [default: dTdT] β
β --skip-off-targβ¦ Skip off-target β
β analysis (faster) β
β --snp TEXT Variant β
β identifier(s) for β
β SNP β
β targeting/avoidaβ¦ β
β Accepts rsID β
β (rs12345), β
β coordinate β
β (chr17:7577121:Gβ¦ β
β or HGVS β
β (NM_000546.6:c.2β¦ β
β Can be specified β
β multiple times. β
β All variants must β
β be on GRCh38 β
β assembly. β
β --snp-file PATH VCF file β
β containing β
β variants for β
β targeting/avoidaβ¦ β
β Preferably β
β bgzip-compressed β
β with tabix index β
β (.vcf.gz + .tbi) β
β for performance. β
β Variants are β
β filtered by β
β --min-af and β
β --clinvar-filterβ¦ β
β --variant-mode [target|avoid|b How to handle β
β oth] variants in siRNA β
β design: 'avoid' = β
β exclude β
β candidates β
β overlapping β
β variants β
β (default), β
β 'target' = design β
β siRNAs β
β specifically β
β targeting variant β
β alleles, 'both' = β
β generate β
β candidates for β
β both reference β
β and alternate β
β alleles. β
β [default: avoid] β
β --min-af FLOAT RANGE Minimum allele β
β [0.0<=x<=1.0] frequency β
β threshold for β
β variant β
β inclusion. β
β Variants with AF β
β below this value β
β are excluded β
β (default: 0.01 = β
β 1%%). β
β [default: 0.01] β
β --clinvar-filteβ¦ TEXT Comma-separated β
β ClinVar clinical β
β significance β
β levels to β
β include. Default: β
β 'Pathogenic,Likeβ¦ β
β pathogenic'. β
β Other options: β
β 'Benign', 'Likely β
β benign', β
β 'Uncertain β
β significance'. β
β [default: β
β Pathogenic,Likely β
β pathogenic] β
β --variant-assemβ¦ TEXT Reference genome β
β assembly for β
β variants (only β
β GRCh38 supported) β
β [default: GRCh38] β
β --verbose -v Enable verbose β
β output β
β --log-file PATH Path to β
β centralized log β
β file (overrides β
β SIRNAFORGE_LOG_Fβ¦ β
β env) β
β --nextflow-dockβ¦ TEXT Override the β
β Docker image β
β passed to β
β Nextflow β
β (default: β
β ghcr.io/austin-sβ¦ β
β [env var: β
β SIRNAFORGE_NEXTFβ¦ β
β --json-summary --no-json-summβ¦ Write β
β logs/workflow_suβ¦ β
β (disable to skip β
β JSON output) β
β [default: β
β json-summary] β
β --help Show this message β
β and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Note
The workflow command searches for gene transcripts, designs siRNA candidates, scores them using thermodynamic analysis, and outputs ranked results.
Input Sources & Transcriptome Referencesο
siRNAforge accepts complementary inputs when you need to bypass gene search or control the reference used for transcriptome off-target analysis:
--input-fastareplaces the transcript retrieval step. Point it at a local FASTA file, HTTP(S) URL, or FTP location. The positional argument (GENE_QUERY) still names the outputs, while the workflow designs guides from the supplied sequences. When you pass--input-fastawithout--transcriptome-fasta, transcriptome off-target analysis is disabled (design-only mode).--transcriptome-fastaselects the dataset used for transcriptome off-target analysis. It accepts local paths, remote URLs, or presets such asensembl_human_cdnaandensembl_mouse_cdna(seesirnaforge cache --info). Provide this flag to re-enable transcriptome off-target analysis when running from a custom FASTA.--offtarget-indicesoverrides the genome indices used for Nextflow/BWA-MEM2 with explicitspecies:/path/to/index_prefixentries. When present, these drive the set of species processed by the off-target pipeline.
Passing both flags is common: the input FASTA feeds the design engine, while the transcriptome FASTA controls which reference is indexed for the Nextflow stage. Remote resources are cached under ~/.cache/sirnaforge/ and reused automatically.
Rows inside off_target/results/*/analysis.tsv and the aggregated combined_offtargets.tsv include a species column so you can filter hits directly. Aggregated summaries collapse those values into human vs other buckets, exposing hits_per_species, human_hits, and other_species_hits in combined_summary.json plus the workflow console output. The workflow also records the resolved reference decision in logs/workflow_summary.json (reference_summary.transcriptome) so each run documents whether the transcriptome reference was disabled, defaulted, or explicitly provided.
searchο
Search gene databases and retrieve transcript sequences.
Helpο
Usage: sirnaforge search [OPTIONS] QUERY
Search transcript references and optionally fetch sequences.
This command queries Ensembl/RefSeq/Gencode (depending on flags) for a gene
or transcript identifier. When sequences are fetched, it writes them to a
FASTA file and can optionally also emit a canonical-only FASTA.
ββ Arguments ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β * query TEXT Gene ID, gene name, or transcript ID to search for β
β [required] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --output -o PATH Output FASTA file β
β for transcript β
β sequences β
β [default: β
β transcripts.fasta] β
β --database -d TEXT Database to search β
β (ensembl, refseq, β
β gencode) β
β [default: ensembl] β
β --all -a Search all databases β
β --fallback --no-fallback Enable automatic β
β fallback to other β
β databases if access β
β is blocked β
β [default: fallback] β
β --no-sequence Skip sequence β
β retrieval (metadata β
β only) β
β --canonical-only Extract only β
β canonical isoforms β
β --extract-canonical --no-extract-canoniβ¦ Automatically β
β extract canonical β
β isoforms to separate β
β file β
β [default: β
β extract-canonical] β
β --types -t TEXT Comma-separated list β
β of transcript types β
β to include (e.g., β
β protein_coding,lncRβ¦ β
β [default: β
β protein_coding,lncRβ¦ β
β --exclude-types TEXT Comma-separated list β
β of transcript types β
β to exclude β
β [default: β
β nonsense_mediated_dβ¦ β
β --verbose -v Enable verbose β
β output β
β --help Show this message β
β and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
designο
Design siRNA candidates from FASTA sequences.
Helpο
Usage: sirnaforge design [OPTIONS] INPUT_FILE
Design siRNA candidates from a transcript FASTA file.
Outputs a TSV/CSV-like table of candidates, optionally including secondary
structure scoring, off-target checks, and chemical modification annotations.
ββ Arguments ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β * input_file FILE Input FASTA file containing transcript sequences β
β [required] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --output -o PATH Output file for siRNA β
β candidates β
β [default: β
β sirna_results.tsv] β
β --design-mode TEXT Design mode: sirna β
β (default) or mirna β
β (miRNA-biogenesis-awarβ¦ β
β [default: sirna] β
β --length -l INTEGER RANGE siRNA length in β
β [19<=x<=23] nucleotides β
β [default: 21] β
β --top-n -n INTEGER RANGE [x>=1] Number of top-ranked β
β candidates to select β
β for β
β reporting/off-target β
β (all candidates are β
β still generated) β
β [default: 100] β
β --gc-min FLOAT RANGE Minimum GC content β
β [0.0<=x<=100.0] percentage β
β [default: 30.0] β
β --gc-max FLOAT RANGE Maximum GC content β
β [0.0<=x<=100.0] percentage β
β [default: 60.0] β
β --max-poly-runs INTEGER RANGE [x>=1] Maximum consecutive β
β identical nucleotides β
β [default: 3] β
β --genome-index PATH Genome index for β
β off-target analysis β
β --snp-file PATH VCF file with SNPs to β
β avoid β
β --skip-structure Skip secondary β
β structure prediction β
β (faster) β
β --skip-off-targets Skip off-target β
β analysis (faster) β
β --modifications -m TEXT Chemical modification β
β pattern (standard_2ome, β
β minimal_terminal, β
β maximal_stability, β
β none) β
β [default: β
β standard_2ome] β
β --overhang TEXT Overhang sequence (dTdT β
β for DNA, UU for RNA) β
β [default: dTdT] β
β --verbose -v Enable verbose output β
β --help Show this message and β
β exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Example: Design from Sample Dataο
ββββββββββββββββ Configuration ββββββββββββββββ
β 𧬠siRNAforge Toolkit β
β Design Mode: sirna β
β Input: ../examples/sample_transcripts.fasta β
β Output: /tmp/sirna_example.csv β
β Length: 21 nt β
β GC range: 30.0%-60.0% β
β Top candidates: 5 β
β Modifications: standard_2ome β
β Overhang: dTdT β
βββββββββββββββββββββββββββββββββββββββββββββββ
2026-01-11 01:22:45,635 - sirnaforge.models.sirna - INFO - siRNA candidates schema validation passed for 2051 candidates
β Saving results...
π Design Summary
βββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Metric β Value β
βββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Input Sequences β 3 β
β Total Candidates β 2051 β
β Filtered Candidates β 240 β
β Top Candidates β 5 β
β Processing Time β 2.80s β
β Best Score β 85.96553642329138 β
β Tool Versions β {'python': '3.12.12', 'biopython': '1.86', β
β β 'sirnaforge': '0.4.1'} β
βββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π Top Candidates:
βββββββββββββ¬ββββββββββββ¬βββββββββββ¬βββββββββββββ¬βββββββ¬βββββββ¬ββββββββ¬ββββββββ
β ID β Transcriβ¦ β Position β Sequence β GC% β Hits β Hit % β Score β
βββββββββββββΌββββββββββββΌβββββββββββΌβββββββββββββΌβββββββΌβββββββΌββββββββΌββββββββ€
β SIRNAF_Nβ¦ β NM_00204β¦ β 211 β GTGGAATCAβ¦ β 38.1 β 1 β 33.3% β 86.0 β
β SIRNAF_Nβ¦ β NM_00204β¦ β 839 β CACCTTCTTβ¦ β 38.1 β 1 β 33.3% β 86.0 β
β SIRNAF_Nβ¦ β NM_00204β¦ β 1016 β GTAGCCAAAβ¦ β 38.1 β 1 β 33.3% β 86.0 β
β SIRNAF_Nβ¦ β NM_00054β¦ β 198 β GTAGTTTCCβ¦ β 38.1 β 1 β 33.3% β 86.0 β
β SIRNAF_Nβ¦ β NM_00054β¦ β 259 β GACAGCATCβ¦ β 38.1 β 1 β 33.3% β 86.0 β
βββββββββββββ΄ββββββββββββ΄βββββββββββ΄βββββββββββββ΄βββββββ΄βββββββ΄ββββββββ΄ββββββββ
β
Results saved to: /tmp/sirna_example.csv
Output Previewο
id,transcript_id,position,guide_sequence,passenger_sequence,gc_content,asymmetry_score,structure,mfe,paired_fraction,duplex_stability_dg,duplex_stability_score,dg_5p,dg_3p,delta_dg_end,melting_temp_c,off_target_count,guide_pos1_base,pos1_pairing_state,seed_class,supp_13_16_score,seed_7mer_hits,seed_8mer_hits,seed_hits_weighted,off_target_seed_risk_class,transcript_hit_count,transcript_hit_fraction,composite_score,passes_filters,guide_overhang,guide_modifications,passenger_overhang,passenger_modifications,variant_mode,allele_specific,targeted_alleles,overlapped_variants
SIRNAF_NM_002046-7_211_231,NM_002046.7,211,GTGGAATCATATTGGAACATG,CATGTTCCAATATGATTCCAC,38.095238095238095,0.5,.....................,0.0,0.0,-4.099999904632568,0.0,-1.2000000476837158,-1.2000000476837158,0.0,45.19999980926514,0,,,,,,,,,1,0.3333333333333333,85.96553642329138,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,,
SIRNAF_NM_002046-7_839_859,NM_002046.7,839,CACCTTCTTGATGTCATCATA,TATGATGACATCAAGAAGGTG,38.095238095238095,0.5,.....................,0.0,0.0,-12.5,0.21428571428571427,3.700000047683716,3.700000047683716,0.0,62.0,0,,,,,,,,,1,0.3333333333333333,85.96553642329138,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,,
SIRNAF_NM_002046-7_1016_1036,NM_002046.7,1016,GTAGCCAAATTCGTTGTCATA,TATGACAACGAATTTGGCTAC,38.095238095238095,0.5,.....................,0.0,0.0,-2.4000000953674316,0.0,0.6000000238418579,0.6000000238418579,0.0,41.80000019073486,0,,,,,,,,,1,0.3333333333333333,85.96553642329138,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,,
SIRNAF_NM_000546-6_198_218,NM_000546.6,198,GTAGTTTCCATAGGTCTGAAA,TTTCAGACCTATGGAAACTAC,38.095238095238095,0.5,.....................,0.0,0.0,-3.4000000953674316,0.0,0.0,0.0,0.0,43.80000019073486,0,,,,,,,,,1,0.3333333333333333,85.96553642329138,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,,
SIRNAF_NM_000546-6_259_279,NM_000546.6,259,GACAGCATCAAATCATCCATT,AATGGATGATTTGATGCTGTC,38.095238095238095,0.5,.....................,0.0,0.0,-2.299999952316284,0.0,0.800000011920929,0.800000011920929,0.0,41.59999990463257,0,,,,,,,,,1,0.3333333333333333,85.96553642329138,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,,
validateο
Check FASTA file format and content.
Helpο
Usage: sirnaforge validate [OPTIONS] INPUT_FILE
Validate a FASTA file and report basic statistics.
This performs lightweight validation (parseable FASTA, presence of
sequences, and common issues like short/ambiguous sequences).
ββ Arguments ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β * input_file FILE FASTA file to validate [required] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --help Show this message and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Example: Validate Sample Dataο
π FASTA Validation Results
ββββββββββββββββββββββββββββββββ¬ββββββββββββ
β Metric β Value β
ββββββββββββββββββββββββββββββββΌββββββββββββ€
β Total sequences β 3 β
β Total length β 5,117 nt β
β Average length β 1705.7 nt β
β Min length β 1285 nt β
β Max length β 2512 nt β
β Short sequences (<50 nt) β 0 β
β Ambiguous sequences (with N) β 0 β
ββββββββββββββββββββββββββββββββ΄ββββββββββββ
β
FASTA validation complete
configο
Show default configuration parameters.
Default Design Parameters:
Basic Parameters:
siRNA length: 21 nt
Top candidates: 500
Filtering Criteria:
GC content: 35.0% - 60.0%
Max poly runs: 3
Max paired fraction: 0.6
Scoring Weights:
Asymmetry: 0.15
GC content: 0.15
Accessibility: 0.2
Off-target: 0.3
Empirical: 0.2
sequencesο
Manage siRNA sequences and chemical modification metadata.
Helpο
Usage: sirnaforge sequences [OPTIONS] COMMAND [ARGS]...
Manage siRNA sequences and metadata
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --help Show this message and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Commands βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β show Show sequences from a FASTA file in table, JSON, or FASTA β
β format. β
β annotate Merge metadata from a JSON file into FASTA headers. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
cacheο
Manage miRNA database cache for off-target analysis.
Helpο
Usage: sirnaforge cache [OPTIONS]
Inspect and clear the unified reference cache.
This command can display cache statistics and/or delete cached assets for
miRNA databases and transcriptomes.
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --clear Clear all cached databases (miRNA + β
β transcriptomes) β
β --clear-mirna Clear only miRNA databases β
β --clear-transcriptome Clear only transcriptomes β
β --dry-run Show what would be deleted without actually β
β deleting β
β --info Show cache information for all databases β
β --help Show this message and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ