CLI reference

Global options

These options can be used with any subcommand.

Accession types

sracha accepts three types of accessions:

Study and BioProject accessions are automatically resolved to their constituent run accessions via the NCBI EUtils API.

Accession lists

The get, fetch, and info commands accept --accession-list to read accessions from a file (one per line). Blank lines and lines starting with # are skipped. This can be combined with positional arguments.

1
2
3
4
5

# From a file
sracha get --accession-list SRR_Acc_List.txt

# Mixed: positional + file
sracha get SRR9999999 --accession-list more_accessions.txt

sracha get

Download, convert, and compress SRA data in one shot.

1

sracha get [OPTIONS] [ACCESSION]...

Arguments

Options

Input / output

Sequence output

Compression

Performance

Download behavior

sracha fetch

Download SRA files without conversion. When the run has a .vdbcache companion (split-archive cSRA) it is saved beside the archive as <ACC>.sra.vdbcache; sracha fastq picks it up from there. get downloads the same companion, so both commands report each transfer as downloaded, resumed or cached.

1

sracha fetch [OPTIONS] [ACCESSION]...

Arguments

Options

sracha fastq

Convert SRA files to FASTQ (or FASTA).

1

sracha fastq [OPTIONS] <INPUT>...

Arguments

Options

Sequence output

Compression

Other

sracha info

Show accession metadata, or inspect a local .sra file.

1

sracha info [OPTIONS] [ACCESSION_OR_PATH]...

Arguments

Options

For accessions, displays file sizes, available formats, download mirrors, and quality information. Study and BioProject accessions are resolved to runs first.

For local file paths, opens the KAR archive directly (no network) and prints its table of contents, schema, and metadata. Paths starting with ~/ are expanded to $HOME.

--format tsv and --format csv emit a single header row followed by one record per accession. Columns: accession, archive_type (SRA/cSRA), layout (SINGLE/PAIRED/N-read), nreads, spots, size_bytes, platform, md5, read_lengths (;-separated, e.g. 8;50;16;49) and read_types (;-separated Biological/Technical), read_lengths_source, title, format (normalized or lite; empty for local files), bases (NCBI's reported count, else an estimate) and bases_estimated (true/false). nreads is the number of biological reads. Missing fields are empty strings. Local .sra paths get a row alongside remote accessions; --prefer-ena is ignored with a stderr warning in these formats. read_lengths and read_types come from the archive's own metadata (fetched with small range requests, no download), so technical reads are included. If that fetch fails, read_lengths falls back to an estimate from NCBI RunInfo, shown as ~61bp+62bp in the table, with read_types empty. read_lengths_source is archive or runinfo accordingly.

title is the human-readable name of the run from NCBI's EFetch experiment XML: the sample title when the run has one, otherwise the experiment title (many runs have only the latter). The same fetch adds Title, Study and Design lines to the single-accession view and a Title column to the multi-run table. It is best-effort: if NCBI is slow or unavailable the fields are simply empty and the rest of the output is unaffected. Local .sra paths have no title.

1
2
3

$ sracha info --format tsv SRR28588231.sra
accession   archive_type    layout  nreads  spots   size_bytes  platform    md5 read_lengths    read_types  read_lengths_source title   format  bases   bases_estimated
SRR28588231 SRA PAIRED  2   66220   23395841    ILLUMINA        301;301 B;B archive             

--format json prints a pretty-printed array with one object per accession and every field the other views show. TSV/CSV stay flat; JSON is the superset for scripts, and adds the study title, design description, mirror URL, alternate mirrors and vdbcache size. Unknown scalars are null and empty lists are [] (no empty-string placeholders). The experiment details are nested:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "accession": "SRR18918001",
  "layout": "PAIRED",
  "format": "normalized",
  "read_lengths": [8, 50, 16, 49],
  "read_types": ["T", "B", "T", "B"],
  "read_lengths_source": "archive",
  "title": "scATAC-seq of Drosophila melanogaster: third-instar larval third leg disc",
  "experiment": {
    "experiment_title": "scATAC-seq of Drosophila melanogaster: third-instar larval third leg disc",
    "sample_title": null,
    "study_title": "Single-Cell Atlas of the Drosophila Leg Disc Identifies a Long Non-Coding RNA in Late Development",
    "design_description": "10X Genomics scATAC-seq v.1",
    "library_construction_protocol": null
  }
}

An accession that fails to resolve appears as {"accession": "...", "error": "..."} so one failure does not break the array. Local .sra paths and remote accessions mix in the same array. Fields shown above are abridged; see the full output for accession, path, archive_type, nreads, spots, bases, bases_estimated, size_bytes, platform, md5, source, source_url, alt_mirrors, vdbcache_size, blobs and columns.

sracha validate

Validate SRA file integrity by decoding all records and checking for errors.

1

sracha validate [OPTIONS] <INPUT>...

Arguments

Options

sracha vdb

Inspect the VDB structure of an .sra archive. Pure-Rust replacement for vdb-dump — no C FFI, no subprocess to sra-tools.

1

sracha vdb <SUBCOMMAND> <SOURCE> [OPTIONS]

<SOURCE> is a local .sra path, an https:// URL, or a run accession. Accessions and URLs are read in place over HTTP range requests — the archive is never downloaded. The table of contents is a file prefix and the column indexes are kilobytes, so inspecting a multi-gigabyte run transfers a few hundred KiB:

1
2
3
4
5

# ~1 s and ~256 KiB transferred against a 4.2 GB archive
sracha vdb info SRR18959644

# spot-check read structure without downloading anything
sracha vdb dump SRR18959644 -C READ_LEN,READ_TYPE -R 1,22228622

Pass -v to see how much was transferred. Only inspection works remotely; sracha fastq needs a local file, since decoding touches essentially every byte and would transfer the whole archive anyway.

sracha vdb info

Print summary metadata: schema, platform, table row counts, load timestamp, and formatter / loader / update software events.

1

sracha vdb info <SOURCE> [--json]

sracha vdb tables

List tables in the archive. Only meaningful for Database archives (cSRA / aligned); flat Tables print a note.

1

sracha vdb tables <SOURCE>

sracha vdb columns

List columns in a table.

1

sracha vdb columns <SOURCE> [-T TABLE] [-s]

sracha vdb meta

Dump the metadata tree (schema / stats / LOAD / SOFTWARE nodes).

1

sracha vdb meta <SOURCE> [-T TABLE] [-P PATH] [-d DEPTH] [--db]

sracha vdb schema

Print the embedded schema text.

1

sracha vdb schema <SOURCE>

sracha vdb id-range

Print the first row id and row count for a table/column.

1

sracha vdb id-range <SOURCE> [-T TABLE] [-C COLUMN]

sracha vdb dump

Dump row-level data for the chosen columns. Values are typed by a name-based heuristic (READ as bases, READ_LEN as an array, and so on); unrecognized columns render as hex.

-C READ renders the logical READ column — the 2na basecalls with the ALTREAD ambiguity mask applied — so ambiguous positions show as N and the output matches vdb-dump. Releases before 0.5.0 showed the physical column without the mask, which disagreed with vdb-dump wherever a submitter recorded an ambiguity.

1

sracha vdb dump <SOURCE> [-T TABLE] [-C COLUMNS] [-x COLUMNS] [-R ROWS] [-f FORMAT]

Custom deflines

--seq-defline <TEMPLATE> (available on both sracha get and sracha fastq) replaces the built-in FASTQ/FASTA header with a template, using the same $-variable syntax as fasterq-dump's --seq-defline:

1
2
3
4

# Match a fasterq-dump pipeline that used --seq-defline '@$ac.$si.$ri'
sracha get --seq-defline '@$ac.$si.$ri' --split split-files SRR12345678
#  -> @SRR12345678.1.1
#     @SRR12345678.1.2   (mate 2 of spot 1)

Notes:

• A leading @ (or > for FASTA) is optional — it is stripped, and sracha adds the correct record prefix automatically.
• The + (quality) line mirrors the sequence defline unless --qual-defline <TEMPLATE> is given. It takes the same variables; a leading + is optional and + alone writes a bare + line. Ignored with --fasta.
• When a template is given, the split-spot/interleaved modes do not add their implicit <spot>/<mate> suffix — use $ri in the template to distinguish mates instead.
• $sg (spot-group) is not supported; a template using it is rejected at startup. Reference-compressed (cSRA) archives have no NAME column, so $sn expands to empty there.

Notes on $lg:

• $lg is read from bam-loaded (cSRA) archives, where LINKAGE_GROUP lives in PRIMARY_ALIGNMENT (or SEQUENCE.CMP_LINKAGE_GROUP for unaligned spots). Plain SRA runs have none, so it expands to empty. The column is only read when a template uses $lg.
• To pull a 10x barcode out as its own file: sracha fastq --seq-defline '@$si $lg' SRR30022414.

Coming from sra-tools

How common fasterq-dump / fastq-dump options map to sracha:

sracha-only conveniences with no fasterq-dump equivalent: parallel chunked download, --prefer-ena, --metadata sidecars, --folder-per-accession, --zstd, and direct accession resolution from a study/BioProject.