CLI Reference

eskaks uses subcommands for its two modes of operation:

eskaks <COMMAND> [OPTIONS]
eskaks --list-codes
eskaks --version

Global flags

Flag	Description
--demo	Run a quick demo on the bundled example data (no input files needed) and exit
--list-codes	List available NCBI genetic code tables and exit
--completions <SHELL>	Print a shell completion script and exit (bash, zsh, fish, elvish, powershell)
-v, --verbose	Increase log verbosity: -v shows info, -vv shows debug. Data-quality warnings show by default
-q, --quiet	Silence all logs except errors (also hides the run-confirmation block)
-h, --help	Show help. Per subcommand, flags are grouped into sections (Output / Analysis / Statistics / Filtering / Input) and followed by usage examples
-V, --version	Show version

Run confirmation & logging

Every eskaks fasta / eskaks vcf run ends with a short confirmation block on stderr (sequence/gene counts, model, and the list of files written), so a run is never silent about where its output went. Add --quiet to suppress it.

Diagnostics are printed as clean warning: / error: lines (coloured only when stderr is a terminal). Set RUST_LOG to override the level entirely.

---

eskaks fasta: Pairwise dN/dS

Compute pairwise dN/dS from codon-aligned FASTA sequences.

eskaks fasta <INPUT_FILE> [OPTIONS]

Argument	Description
<INPUT_FILE>	Aligned coding sequences in FASTA format. Use - for stdin.

Flag	Description	Default
-o, --output <PREFIX>	Base name for output files	output
-w, --workers <N>	Number of parallel threads	4
--model <nei\|li>	Substitution model	nei
--format <tsv\|csv\|json>	Output format	tsv
--genetic-code <N>	NCBI translation table number	1
--lineage	Lineage summary mode	off
--group-average	Group average mode	off
--first-letter-lineage	Group by first character of ID	off
--window-size <N>	Sliding window size (codons)	off
--window-step <N>	Window step size	1
--min-codons <N>	Filter sequences with < N valid codons	0
--summary	Print summary statistics to stderr	off
--neutrality	Write a per-pair Nei-Gojobori neutrality test (<output>_pairwise_tests): dN, dS, SEs, Z, p-value (Nei only)	off
--bootstrap <N>	Per-pair 95% bootstrap CIs on dN, dS, dN/dS (<output>_pairwise_bootstrap); resamples codons, works for both models	0
--seed <N>	Seed for reproducible bootstrap resampling	42
--plot	Generate SVG plot(s)	off
--report	Write an interactive HTML report (<output>_report.html): lineage/group scatter with per-group means, or the pairwise dN/dS distribution	off

Examples

# Basic Nei model
eskaks fasta input.fasta

# Li model, 16 threads, CSV output
eskaks fasta input.fasta --model li --workers 16 --format csv -o results

# Vertebrate mitochondrial code, JSON output
eskaks fasta mito.fasta --genetic-code 2 --format json -o mito

# Sliding window with plot
eskaks fasta input.fasta --window-size 100 --window-step 10 --plot -o windows

# From stdin
cat input.fasta | eskaks fasta - --summary -o piped

---

eskaks vcf: pN/pS per gene

Compute pN/pS per gene from a VCF file, reference FASTA, and GFF3 annotation.

eskaks vcf --ref <FASTA> --gff <GFF3> --vcf <VCF> [OPTIONS]

Inputs & output

Flag	Description	Default
--ref <FASTA>	Reference genome in FASTA format	required
--gff <GFF3>	Gene annotation in GFF3 format	required
--vcf <VCF>	VCF file(s), use multiple times for per-sample VCFs	one of --vcf / --vcf-list required
--vcf-list <FILE>	File with one VCF path per line (alternative to repeated --vcf)	one of --vcf / --vcf-list required
-o, --output <PREFIX>	Base name for output files	output
--format <tsv\|csv\|json>	Output format	tsv
--genetic-code <N>	NCBI translation table number	1
--workers <N>	Parallel threads (output is deterministic)	4

Variant filters

Flag	Description	Default
--pass-only	Only include FILTER=PASS variants	off
--min-af <FLOAT>	Minimum allele frequency (0.0–1.0)	none
--max-af <FLOAT>	Maximum allele frequency (exclude fixed variants)	none
--min-depth <INT>	Minimum read depth (INFO/DP)	none
--af-weighted	Weight counts by AF (πN/πS instead of pN/pS)	off

Model, test & correction

Flag	Description	Default
--kappa <FLOAT>	ts/tv rate ratio for spectrum-aware site counting	1.0
--min-snps <N>	Drop genes with fewer SNPs from the table, plot, and test	0
--fdr <FLOAT>	Benjamini-Hochberg threshold for significant genes	0.05
--mk	Run the McDonald-Kreitman test (<prefix>_mk.<ext>)	off
--mk-fixed-af <FLOAT>	AF at/above which a variant is "fixed" in the MK test	0.99
--bootstrap <N>	Replicates for a 95% CI on the genome-wide pooled pN/pS	0
--seed <N>	Seed for reproducible bootstrap resampling	42
--genomic-control	Divide each χ² by the inflation factor λ and re-test	off
--exclude-repetitive	Drop PE/PPE/PGRS/IS genes from the pooled estimate and test	off
--codon-scan	Rank codons by their count of distinct nonsynonymous alleles (<prefix>_codons.<ext>). Tests allelic multiplicity, not carrier counts and not a per-codon pN/pS	off
--tree <FILE>	Newick tree over the cohort's samples. Adds independent-origin counting to --codon-scan and --variants, which is what lets a single allele that arose many times independently be seen as convergent (rpoB S450L, rpsL K43R). Tip names must match the VCF's sample names exactly; any mismatch is a hard error. Read the limitations before using the p-values	none
--min-origin-support <N>	Minimum carriers in the clade an origin subtends for that origin to count (requires --tree). The default is load-bearing: at 1, three isolated false calls on top of one real clade allele are enough to fake genome-wide significance	2

Output & reporting

Flag	Description	Default
--variants	Write a per-coding-SNP table (<prefix>_variants.<ext>): position, base and amino-acid change (e.g. S315T), AF, and effect (synonymous/missense/nonsense/stop_loss)	off
--shared-codons	Append Codon_Shared and Codon_Change to that table: true when a sample carrying this ALT also carries another SNP in the same codon, so the row's amino-acid change is the joint (multi-nucleotide) one, plus the codon change itself (CTT>TTA, coding strand). Requires --variants	off
--diversity	Write per-gene πN/πS, Watterson θ and Tajima's D (<prefix>_diversity.<ext>); needs the sample size, so a multi-sample VCF or --vcf-list	off
--summary	Print the pN/pS summary block to stderr	off
--plot	Generate Manhattan / p-value SVG plots	off
--report	Write a self-contained interactive HTML report	off
--divergence <FILE>	Per-gene dN/dS TSV for the report's polymorphism-vs-divergence panel	none

Examples

# Population πN/πS from per-sample VCFs
eskaks vcf --ref H37Rv.fasta --gff H37Rv.gff3 \
  --vcf sample1.vcf --vcf sample2.vcf --vcf sample3.vcf \
  --af-weighted --genetic-code 11 -o mtb_pnps

# Full selection scan with the interactive report
eskaks vcf --ref H37Rv.fasta --gff H37Rv.gff3 --vcf-list samples.txt \
  --genetic-code 11 --kappa 2 --min-snps 5 \
  --mk --bootstrap 1000 --seed 42 --report --plot -o mtb_scan

# Single multi-sample VCF with filters
eskaks vcf --ref ref.fasta --gff ref.gff3 --vcf calls.vcf \
  --pass-only --min-af 0.05 --min-depth 10 -o filtered

# Convergence scan: how many times did each allele arise, on a supplied phylogeny
eskaks vcf --ref H37Rv.fasta --gff H37Rv.gff3 --vcf-list samples.txt \
  --genetic-code 11 --codon-scan --variants --exclude-repetitive \
  --tree samples.nwk -o mtb_origins

---

Exit codes

Code	Meaning
0	Success
1	Error (invalid input, missing file, bad arguments)
2	Argument parsing error (clap)

Environment variables

Variable	Description
RUST_LOG	Set log level: info, warn, debug