A fast terminal-based viewer and command-line toolkit for sequences. View, translate, convert (to FASTA), and combine sequences aligned or not — all from the terminal.
Written in Rust
Author: Vincent Ranwez
- Multi-Format Support: FASTA, PHYLIP, and NEXUS formats with auto-detection
- Color-Coded: Nucleotides and amino acids displayed with distinct background colors
- NT → AA Translation: 33 NCBI genetic codes, handling ambiguity codes (R, Y, N)
- Concatenation & Supermatrix: Combine multiple alignments, fill missing with gaps
- SNP Extraction: Export isolated biallelic SNPs to VCF with flanking distance filter
- Sticky Names: Sequence identifiers remain visible while scrolling
- Vim-style Navigation: h/j/k/l, w/b/e, Ctrl+U/D, search with
/and? - Command-Line Mode: Batch convert, translate, combine — pipe-friendly output
- Large File Support: Tested on alignments larger than 500 MB
# View an alignment interactively
seqtui LOC_01790.nex
# Translate to amino acids
seqtui alignment.fasta -t -o out_AA.fastaIf you find SeqTUI useful, please consider starring the repository.
terminal requirements: SeqTUI requires a terminal that supports ANSI colors and cursor movement (most modern terminals do). By default, SeqTUI uses an ASCII-safe interface for maximum compatibility. Optional Unicode glyphs can be enabled using the --fancy option. While Unicode glyphs provide a nicer visual rendering, they may cause display issues on some terminal configurations, especially on Windows.
SeqTUI has been tested on macOS using WezTerm, including remote use over SSH to Linux systems, and on Windows 11 using Windows Terminal.
macOS note: on first launch, macOS may block the application. In this case, allow it via
System Settings → Privacy & Security, then run it again.
Precompiled binaries are available from the Releases section of the GitHub repository: https://github.com/ranwez-search/SeqTUI/releases
SeqTUI is also distributed as a Rust crate and can be installed (or build from source) using Cargo (https://www.rust-lang.org/tools/install)
install from crate.io (recommanded)
cargo install seqtuirecompiled from source
git clone https://github.com/ranwez-search/SeqTUI.git
cd SeqTUI
cargo install --path .SeqTUI works in two modes:
- Interactive Viewer (default): Opens a full-screen terminal interface
- Command-Line Mode (with
-o): Batch processing for scripts and pipelines
Small test data files are available in the test_data/ directory of the repository.
Use -o to output to a file (or - for stdout) instead of opening the interactive viewer.
Single-line FASTA output makes sequences easy to process with standard Unix tools.
# Convert to single-line FASTA
seqtui sequences.fasta -o sequences_1L.fasta
# Translate to amino acids
seqtui sequences.fasta -t -o sequences_AA.fasta
# Translate with specific genetic code and reading frame
seqtui sequences.fasta -t -g 2 -r 1 -o sequences_AA.fasta# Check for internal stop codons in coding sequences
seqtui sequences.fasta -t -o - | grep "\*."
# Create a small test set (first 10 sequences, 500 bp each)
seqtui large_alignment.nex -o - | head -20 | cut -c1-500 > test_seq.fasta
# Extract subset of sequences by ID
seqtui sequences.nex -o - | grep -A1 -w -f seq_ids.txt > subset.fasta
# Count sequences
seqtui alignment.phy -o - | grep -c "^>"
# Batch translate all files in a directory
for f in *.fasta; do seqtui "$f" -t -o "${f%.fasta}_AA.fasta"; doneConcatenate multiple alignment files by matching sequence IDs:
# Basic concatenation (sequences matched by ID)
seqtui gene1.fasta gene2.fasta gene3.fasta -o concatenated.fasta
# Mix different formats (FASTA, PHYLIP, NEXUS) - auto-detected!
seqtui gene1.fasta gene2.phy gene3.nex -o concatenated.fasta
# Supermatrix: fill missing sequences with gaps
seqtui gene*.fasta -s -o supermatrix.fasta
# Translate all genes and build AA supermatrix
seqtui gene*.fasta -s -t -o supermatrix_AA.fasta
# With partition file for phylogenetic analysis
seqtui examples/LOC* -s -t -p partitions.nex -o supermatrix.fasta
# Creates NEXUS partition file compatible with IQtree:
# #nexus
# begin sets;
# charset LOC_01790 = 1-286;
# charset LOC_11070 = 287-636;
# charset LOC_39310 = 637-951;
# end;
Sequence ID matching with delimiter — when sequence names have prefixes/suffixes:
# Files have: Human_ENS001, Human_LOC789, Mouse_ENS002, Mouse_LOC456...
# Match on species name (first field before "_")
seqtui gene1.fasta gene2.fasta -d "_" -s -o supermatrix.fasta
# Output sequences: Human, Mouse, ... (matched across files)
# Keep multiple fields: Ae_bicornis_contig257 → Ae_bicornis
seqtui gene*.fasta -f 1,2 -d "_" -s -o supermatrix.fastaExtract isolated biallelic SNPs from alignments using a minimum flanking monomorphic distance filter:
# Extract SNPs with at least 300 monomorphic sites on each side
seqtui alignment.fasta -v 300 -o snps.vcf
# Process multiple alignments (each becomes a separate CHROM)
seqtui gene*.fasta -v 100 -o all_snps.vcf
# With sequence ID matching via delimiter
seqtui gene*.fasta -v 100 -d "_" -o snps.vcfVCF output features:
- Reference = first sequence of first file
- Samples sorted alphabetically (reference first)
- Haploid genotypes:
0(ref),1(alt),.(missing) DLandDRin INFO: distance to nearest polymorphic site (for filtering)- Only isolated biallelic SNPs are exported (polymorphic sites reduce DL/DR)
- Sites with gaps are excluded; N/? become missing genotypes
| Option | Long | Description |
|---|---|---|
-o |
--output |
Output file in sorted FASTA (triggers CLI mode). Use - for stdout |
--format |
Force input format (fasta, phylip, nexus). Default: auto-detect | |
--force |
Proceed despite warnings (ID mismatches, suspect sequences) | |
-d |
--delimiter |
Delimiter for splitting sequence IDs (default: _ when -f is used) |
-f |
--fields |
Fields to keep from IDs (1-based, comma-separated). Ex: -f 1,2 |
-s |
--supermatrix |
Fill missing sequences with a character (default: -) |
-p |
--partitions |
Write partition file in NEXUS format (IQtree-compatible) |
-t |
--translate |
Translate nucleotides to amino acids |
-g |
--genetic-code |
Genetic code (1-33, default: 1 = Standard) |
-r |
--reading-frame |
Reading frame (1-3, default: 1) |
-v |
--vcf |
Extract isolated biallelic SNPs to VCF (value = min flanking distance) |
--fancy |
Enable fancy Unicode glyphs in the interactive TUI (may cause issues on some terminals, especially on Windows) |
On Unix-like systems (Linux, macOS), you may prefer to always use the fancy Unicode interface. In this case, you can define a shell alias:
alias seqtui='seqtui --fancy'This keeps the default behavior safe and portable while allowing a richer interface when explicitly requested.
By default, SeqTUI opens a full-screen terminal interface for exploring alignments.
# Launch file browser (no arguments)
seqtui
# View an alignment (format auto-detected from extension)
seqtui sequences.fasta
seqtui alignment.phy
seqtui data.nex
# Force a specific format
seqtui --format nexus myfile.txt
seqtui --format phylip alignment.dat
# Preset translation settings
seqtui sequences.fasta -g 2 -r 1 # Open with genetic code 2 preset| Key | Action |
|---|---|
←↑↓→ |
Move one position |
Shift+←→ |
Half page left/right |
Shift+↑↓ |
Full page up/down |
Home / End |
First / last column |
PgUp / PgDn |
Full page up/down |
| Key | Action |
|---|---|
h / j / k / l |
Move left/down/up/right |
Ctrl+U / Ctrl+D |
Half page up/down |
zH / zL |
Half page left/right |
0 / $ |
First / last column |
g0 / gm / g$ |
First/middle/last visible column |
<num>| |
Go to column (e.g., 50|) |
w / b / e |
Next/previous/end of word |
| Key | Action |
|---|---|
/pattern |
Search forward |
?pattern |
Search backward |
n |
Next match |
N |
Previous match |
| Command | Action |
|---|---|
:q |
Quit |
:h |
Toggle help overlay |
:<number> |
Go to sequence/row |
:e |
Open file browser |
:w file.fa |
Save current view to FASTA |
:asAA |
Translate nucleotides to amino acids |
:asNT |
Switch back to nucleotide view |
:setcode |
Change genetic code and reading frame |
Use :asAA to translate nucleotides to amino acids:
- Choose from 33 NCBI genetic codes
- Select reading frame (+1, +2, +3)
- Use
j/kto browse codes,h/lto change frame - Press
Enterto translate,Escto cancel
Use :asNT to switch back to the nucleotide view.
Use :w filename.fasta to save the current view:
- Saves NT or AA sequences depending on current view mode
- Sequences are written on single lines (convenient for bash processing)
- Example:
:w Loc256_AA.fasta
| Format | Extensions | Features |
|---|---|---|
| FASTA | .fasta, .fa, .fna, .faa, .fas |
Multi-line sequences |
| PHYLIP | .phy, .phylip |
Sequential and interleaved |
| NEXUS | .nex, .nexus, .nxs |
DATA/CHARACTERS blocks, MATCHCHAR support |
The application follows an event-driven MVC architecture. The internal architecture is shown below for developers interested in extending or modifying SeqTUI:
src/
├── main.rs # Entry point and CLI argument parsing
├── lib.rs # Module exports
├── model.rs # Data structures (Sequence, Alignment, Viewport, AppState)
├── formats/ # Multi-format support
│ ├── mod.rs # Format detection and unified parsing
│ ├── fasta.rs # FASTA format parser
│ ├── nexus.rs # NEXUS format parser (token-based)
│ └── phylip.rs # PHYLIP format parser
├── event.rs # Keyboard event handling
├── ui.rs # TUI rendering with ratatui
├── controller.rs # Main application loop
└── genetic_code.rs # Genetic code tables and translation
# Run tests (96 tests covering all formats and SNP extraction functionality)
cargo test
# Run with test data
cargo run -- test_data/alignment.fasta
cargo run -- test_data/LOC_01790.nex
# Build release version
cargo build --release# On Linux or cross-compile
cargo build --release --target x86_64-unknown-linux-gnuSeqTUI was inspired by several great tools:
- Seaview - Multiplatform GUI for molecular phylogeny. I'm a huge fan and it has many more features. SeqTUI was born from needing a quick alignment view when working on HPC clusters via terminal.
- Vim - The navigation philosophy and keybindings
- ratatui - The excellent Rust TUI framework powering this app
- Awesome ratatui - Inspiration from the ecosystem, especially:
SeqTUI handles frameshifts consistently with MACSE
Alternatives to SeqTUI include:
- termal - a terminal alignment viewer with conservation scores
- alen - a simpler terminal alignment viewer
- alv - a terminal alignment viewer to be combined with linux commands
- segul - a powerful phylogenomic tools (no alignment viewer)
MIT