CLI Reference

Usage: coralsnake [OPTIONS] COMMAND [ARGS]...

Commands

Command	Description
`prepare`	Extract primary transcript from GTF/GFF file.
`liftover`	Bidirectional BAM liftover (`--direction t2g` default / `g2t`).
`annotate`	Unified site/variant annotation (region + gene/effect).
`group`	Group genes and build consensus sequences.
`metagene`	Metagene profiling across 5’UTR/CDS/3’UTR.
`logo`	Plot a DNA/RNA sequence-logo.
`motif`	Fetch a genomic motif around variant sites.
`coordinate`	Map chromosome names between coordinate systems.

Run coralsnake <command> --help for the full option list of any command.

Mapping is out of scope: coralsnake map was removed. Align reads with bwamem map (plain) or prismalign map (nucleotide-conversion / two-color), then prepare + liftover for the exon-aware steps.

`prepare`

Extract the primary transcript from a GTF/GFF file into a reference transcript FASTA.

coralsnake prepare -g annotation.gtf -f genome.fa -o transcripts.fa \
                   --with-codon --with-genename --filter-biotype protein_coding

Option	Description
`-g, --gtf-file`	GTF file (required).
`-f, --fasta-file`	Reference FASTA.
`-o, --output-file`	Output FASTA (required).
`-s, --seq-file`	Sequence file (requires `--fasta-file`).
`-c, --with-codon`	Include codon info.
`-n, --with-genename`	Include gene name.
`-t, --with-biotype`	Include biotype.
`-x, --with-txpos`	Include transcript position.
`-z, --sanitize`	Sanitize sequence names.
`-U/-u, --seq-upper/--seq-lower`	Case of sequence.
`-l, --line-length`	Output line length (0 = no wrap).

`liftover`

Remap a BAM between transcript and genome coordinates, both directions:

--direction t2g (default) — transcriptome-aligned BAM → genome coordinates.
--direction g2t — genome-aligned BAM → transcript coordinates (the former standalone gbam2tbam command, now fully fused into liftover).

coralsnake liftover -i tx.bam -o genome.bam -a annot.tsv -f faidx.fai --sort
coralsnake liftover -d g2t -i genome.bam -o tx.bam -a annot.tsv --sort

Option	Description
`-d, --direction`	`t2g` (default) or `g2t`.
`-i, --input-bam`	Input BAM (required).
`-o, --output-bam`	Output BAM (required).
`-a, --annotation-file`	Annotation TSV (required).
`-f, --faidx-file`	Reference `.fai` (required for `t2g`).
`-t, --threads`	Threads.
`-s, --sort`	Sort output by coordinate.

`annotate`

The unified site / variant annotation command, with a single output schema. One command serves a bare site (chrom,pos,strand → gene/transcript/position + region) and a full variant (chrom,pos,strand,ref,alt + genome FASTA → codon/AA + effect). A precomputed prepare-style table (--annotation) gives fast table mode.

coralsnake annotate -i sites.tsv -o out.tsv --reference-gtf annotation.gtf -c 1,2,3
coralsnake annotate -i variants.tsv -o effects.tsv \
                    --reference-gtf annotation.gtf \
                    --reference-transcript genome.fa -s -a
coralsnake annotate -i sites.tsv -o out.tsv --annotation prepared_table.tsv

Option	Description
`-i, --input`	Input site/variant file (default `-` = stdin; 1-based positions, like `motif`).
`-o, --output`	Output file (default `-` = stdout).
`-g, --reference-gtf`	Reference GTF (GTF mode).
`--annotation`	Precomputed `prepare` table (fast table mode).
`-f, --reference-transcript`	Genome FASTA (needed for motif/codon/AA).
`-s, --strandness`	Use strand information.
`-n, --npad`	Padding bases for motif (default 10).
`-a, --all-effects`	Output all overlapping effects (not just top).
`-H, --with-header`	Input has a header line.
`-c, --columns`	Chrom,Pos,Strand,Ref,Alt (default `1,2,3,4,5`; Ref/Alt optional).

Output schema: gene_id transcript_id transcript_pos region gene_pos transcript_strand mut_type transcript_motif coding_pos codon_ref aa_pos aa_ref distance2splice. The mut_*/coding columns are filled only when a genome FASTA and ref/alt were supplied. —

`metagene`

Run metagene profiling: the distribution of genomic sites relative to gene regions (5’UTR / CDS / 3’UTR), with optional binned score statistics and a publication-ready profile plot (requires coralsnake[plot]). Use a built-in reference (-r GRCh38) or a custom GTF (-g file.gtf); --list shows the built-in references and --download <name|all> fetches them.

coralsnake metagene -i sites.tsv.gz -r GRCh38 -H -m 1,2,3 -w 5 \
                    -o out.tsv -s scores.tsv -p plot.png
coralsnake metagene -i sites.bed -g custom.gtf.gz -m 1,2,3,6 -o out.tsv

Option	Description
`-i, --input`	Input file (BED/TSV/CSV).
`-o, --output`	Output score table path.
`-s, --output-score`	Output binned score statistics path.
`-p, --output-figure`	Metagene plot path (`coralsnake[plot]`).
`-r, --reference`	Built-in reference (e.g. `GRCh38`, `GRCm39`).
`-g, --gtf`	Custom GTF/GFF reference.
`--region`	`all` (default) / `5utr` / `cds` / `3utr`.
`-b, --bins`	Number of bins (default 100).
`-H, --with-header`	Input has a header line.
`-S, --separator`	Input separator (default tab).
`-m, --meta-columns`	Coordinate columns (default `1,2,3,6`).
`-w, --weight-columns`	Weight/score columns (1-based).
`-n, --weight-names`	Names for the weight columns.
`--score-transform`	`none` (default) / `log2` / `log10`.
`--normalize`	Normalize scores by transcript length.
`--list`	List built-in references and exit.
`--download`	Download a reference (`<name>` or `all`).

`logo`

Plot a DNA/RNA sequence-logo from a set of motif sequences. The scoring engine is pure numpy; rendering requires matplotlib (pip install "coralsnake[plot]").

coralsnake logo -m ACGT -m ACGG -m CCGT -o logo.png
coralsnake logo -i motifs.tsv -o logo.svg   # one motif per line; seq<TAB>count for weights

Option	Description
`-m, --motifs`	Motif sequences (repeatable / comma-separated).
`-i, --input`	File of motifs, one per line.
`-o, --output`	Output image (e.g. `logo.png`, `logo.svg`) (required).
`-w, --weights`	Comma-separated per-motif weights.
`--t2u/--no-t2u`	Convert T→U (default on).
`--2bit/--no-2bit`	2-bit logo (default on).
`--normed`	Normalize letter heights.

`group`

Group related genes and build consensus sequences.

coralsnake group -f genes.fa -g genes.gtf -o grouped.tsv \
                 --output-consensus consensus.fa --threads 8

Option	Description
`-f, --fasta-file`	FASTA file (required).
`-g, --gtf-file`	GTF file (required).
`-o, --output-file`	Grouped output TSV.
`-c, --output-consensus`	Consensus FASTA output.
`-r, --gene-name-regex`	Gene name regex.
`-b, --gene-biotype-list`	Biotype filter.
`-l, --gene-length-limit`	Max gene length (default 300).
`-s, --cluster-threshold`	Clustering threshold (default 0.1).
`-t, --threads`	Threads.

`motif`

Fetch a genomic motif (reference sequence) around each input site, strand-aware with N-padding at chromosome ends. Migrated from the standalone variant package; the old pyfaidx dependency is gone (uses pysam.FastaFile).

coralsnake motif -i sites.tsv -o motifs.tsv -f genome.fa -n 10 -c 1,2,3 -u -w

Option	Description
`-i, --input`	Input position file (default `-` = stdin).
`-o, --output`	Output file (default `-` = stdout).
`-f, --fasta`	Reference FASTA (required).
`-n, --npad`	Padding bases (default `10`; use `2,3` for L,R).
`-H, --with-header`	Input has a header line.
`-c, --columns`	Site columns Chrom,Pos,Strand (default `1,2,3`).
`-u, --to-upper`	Emit motif in upper case.
`-w, --wrap-site`	Wrap the motif site in `[...]`.

`coordinate`

Map chromosome names between coordinate systems (UCSC ↔ Ensembl). Accepts a custom 2-column mapping file or a built-in preset.

coralsnake coordinate -i in.tsv -o out.tsv -M U2E -c 1 -k

Option	Description
`-i, --input`	Input file (default `-` = stdin).
`-o, --output`	Output file (default `-` = stdout).
`-m, --reference-mapping`	2-col mapping file `chrom<TAB>renamed`.
`-M, --buildin-mapping`	`U2E`, `E2U`, `U2E-hg38`, `E2U-hg38`, `U2E-mm39`, `E2U-mm39`.
`-c, --columns`	Chrom column (default `1`).
`-H, --with-header`	Input has a header line.
`-k, --keep-original`	Keep original chrom as an extra column.