Command-line interface (`gtars-cli==0.9.0`)

Verified from the published crate and v0.9.0 tagged source on 2026-07-23. The package is gtars-cli; the installed binary is gtars.

Trust, installation, and features

Cargo installation compiles native code and may run transitive build scripts. Review the official crate/source, lock resolution, license, and build environment before:

bash

cargo install gtars-cli --version 0.9.0 --locked
gtars --version
gtars --help

The v0.9.0 GitHub release also publishes platform archives plus .sha256 sidecars. Verify the archive checksum before extraction and do not execute an untrusted binary. The bundled artifact_inspector.py hashes/classifies an artifact without extracting or executing it.

Default CLI features are:

text

scoring uniwig bbcache igd fragsplit overlaprs genomicdist refget

To build a reduced binary:

bash

cargo install gtars-cli --version 0.9.0 --locked \
  --no-default-features --features "overlaprs,genomicdist"

Feature availability controls subcommand availability. There is no 0.9.0 CLI tokenizers feature/subcommand. Do not copy an old --all-features binary's command assumptions into a reduced binary.

Global behavior

bash

gtars --help
gtars --version
gtars <command> --help

Tagged source defines no global --threads, --memory-limit, --buffer-size, --verbose, --quiet, --strict, --continue-on-error, or --log-file options. Concurrency is command-specific.

Before every real command, run the exact installed --help. This reference is pinned to 0.9.0; unversioned web documentation can drift.

`overlaprs`

bash

gtars overlaprs \
  --query query.bed \
  --universe universe.bed \
  --backend bits

Options:

-q/--query PATH (required);
-u/--universe PATH (required);
-e/--backend bits|ailist (handler default: bits);
--streaming is parsed but ignored by the v0.9.0 handler.

Output is BED3 universe-hit coordinates to stdout, one row per overlap. It is not a count table and does not retain query IDs. See overlap.md.

`igd`

Create from a folder of BED files:

bash

gtars igd create \
  --filelist approved-bed-directory \
  --output index-directory \
  --dbname reference_index

Search with a BED/BED.GZ query:

bash

gtars igd search \
  --database index-directory \
  --query query.bed

Current subcommands are create and search, not build, query, or count. The --filelist help text calls the input a path to a list but specifies a folder; validate installed behavior on a synthetic directory before scaling.

`uniwig`

Batch BigWig:

bash

gtars uniwig \
  --file sorted.bed.gz \
  --filetype bed \
  --chromref assembly.chrom.sizes \
  --smoothsize 5 \
  --stepsize 1 \
  --fileheader output/sample_ \
  --outputtype bw \
  --counttype core \
  --threads 4

BAM QC:

bash

gtars uniwig bamqc \
  --input aligned.bam \
  --output bamqc.tsv \
  --threads 1

BED streaming adds --streaming and supports only WIG/bedGraph output. Read coverage.md for all flags, sorting/bounds, BAM behavior, and resource limits.

`consensus`

bash

gtars consensus \
  --beds a.bed b.bed c.bed \
  --min-count 2 \
  --output consensus.bed

--beds requires at least two paths;
--min-count defaults to 1;
output defaults to stdout and is BED4 (chr start end count).

Consensus counts input sets overlapping a reduced union component; it is not per-base support segmentation. See overlap.md.

`ranges`

ranges exposes interval algebra:

text

gtars ranges reduce      --input BED [--output OUT]
gtars ranges trim        --input BED --chrom-sizes SIZES [--output OUT]
gtars ranges promoters   --input BED [--upstream 2000] [--downstream 200] [--output OUT]
gtars ranges setdiff     -a BED_A -b BED_B [--output OUT]
gtars ranges pintersect  -a BED_A -b BED_B [--output OUT]
gtars ranges concat      -a BED_A -b BED_B [--output OUT]
gtars ranges union       -a BED_A -b BED_B [--output OUT]
gtars ranges jaccard     -a BED_A -b BED_B
gtars ranges shift       --input BED --offset N [--output OUT]
gtars ranges flank       --input BED --width N [--start|--both] [--output OUT]
gtars ranges resize      --input BED --width N [--fix start|end|center] [--output OUT]
gtars ranges narrow      --input BED [--start N] [--end N] [--width N] [--output OUT]
gtars ranges disjoin     --input BED [--output OUT]
gtars ranges gaps        --input BED --chrom-sizes SIZES [--output OUT]
gtars ranges intersect   -a BED_A -b BED_B [--output OUT]

Operations without --output write to stdout. promoters is anchored on region starts in core behavior; do not assume strand-aware TSS handling.

`fscoring` fragment counts

File-by-peak matrix:

bash

gtars fscoring "fragments/sample01.fragments.tsv.gz" consensus.bed \
  --mode atac \
  --output counts.csv.gz

Arguments are positional:

text

gtars fscoring <fragments> <consensus> [--mode atac|chip] [--output PATH]

fragments is interpreted by FragmentFileGlob; a single explicit local file is safest. Shell globs can expose unintended files, while quoted globs are expanded by the library.
default mode is atac;
default output is fscoring.csv.gz;
atac uses cut-site scoring semantics; chip uses fragment overlap semantics.

Sparse barcode mode:

bash

gtars fscoring sample.fragments.tsv.gz consensus.bed \
  --barcode \
  --output output/sample01

This writes:

text

output/sample01_matrix.mtx.gz
output/sample01_barcodes.tsv.gz
output/sample01_features.tsv.gz

The fragment file must carry valid coordinates and barcodes. Do not expose raw barcodes in logs or reports; cap cells, peaks, nonzeros, memory, and output.

`pb` pseudobulk splitting

The current command name is pb, not fragsplit:

bash

gtars pb sample.fragments.tsv.gz barcode_to_cluster.tsv \
  --output pseudobulk-output

Positional arguments are fragments then mapping; default output is out/. This writes cluster-specific files. Validate mapping uniqueness, unknown barcodes, safe cluster names, output collisions, file-count bounds, and patient split policy first.

`genomicdist`

Minimal call:

bash

gtars genomicdist \
  --bed regions.bed \
  --chrom-sizes assembly.chrom.sizes \
  --bins 250 \
  --output distribution.json

Optional inputs/features:

--gtf GTF for partitions and derived TSS distances;
--tss BED to override GTF-derived TSS;
--signal-matrix TSV;
--fasta FASTA|FAB for GC content;
--dinucl-freq and --dinucl-raw-counts;
--ignore-unk-chroms;
--promoter-upstream, --promoter-downstream;
--compact.

Supplying chromosome sizes makes region-distribution bins comparable across files and enables bounds-related operations. Omitting them derives scale from observed ends and is unsuitable for cross-file comparison.

`prep`

text

gtars prep --gtf genes.gtf.gz [--output genes.gda]
gtars prep --signal-matrix matrix.tsv.gz [--output matrix.bin]
gtars prep --fasta reference.fa [--output reference.fab]

prep serializes local inputs into Gtars-specific binary formats. Treat these artifacts as versioned native data: hash inputs/outputs, record 0.9.0, reject untrusted serialized files, and bound expansion/memory.

`refget`

bash

gtars refget build reference.fa reference-alt.fa.gz \
  --output refget-store \
  --jobs 1

Other options are --file-list/-f, --raw, and --force; --jobs 0 means automatic concurrency. There are no current CLI digest, verify, or remote query subcommands. See refget.md.

`bbcache`

text

gtars bbcache cache-bed       --identifier VALUE [--cache-folder DIR]
gtars bbcache cache-bedset    --identifier VALUE [--cache-folder DIR]
gtars bbcache seek            --identifier VALUE [--cache-folder DIR]
gtars bbcache inspect-bedfiles                 [--cache-folder DIR]
gtars bbcache inspect-bedsets                  [--cache-folder DIR]
gtars bbcache rm              --identifier VALUE [--cache-folder DIR]

Client construction creates cache directories. Cache/download calls can contact BEDbase or arbitrary URL hosts and write SQLite/cache files. rm deletes local content. The tagged source has a likely ID-only download mismatch described in refget.md; do not guess a workaround.

Threading and resource controls

There is no global thread flag:

batch uniwig --threads/-p defaults to 6;
uniwig bamqc --threads/-t defaults to 1; values above 1 need a BAM index;
refget build --jobs/-j defaults to 0 (auto);
other commands expose no documented thread setting.

Set command-specific values explicitly. Also bound input bytes/records/files, glob matches, hit pairs/nonzeros, stdout, memory, temporary disk, cache, and wall time externally.

Safe dry-run planning

bash

python3 -B scripts/execution_plan.py --help
python3 -B scripts/coverage_preflight.py --help

These helpers produce fixed argv templates only. They do not invoke gtars, expand globs, download data, create caches, or write outputs.

Removed stale command forms

Do not use:

text

gtars igd build/query/count
gtars overlaprs overlap/count/filter/subtract
gtars uniwig generate
gtars scoring score/batch
gtars fragsplit split/cluster-split/filter
gtars refget digest/verify
gtars --threads/--memory-limit/--verbose

Command-line interface (`gtars-cli==0.9.0`)

Command-line interface (gtars-cli==0.9.0)

Trust, installation, and features

Global behavior

overlaprs

igd

uniwig

consensus

ranges

fscoring fragment counts

pb pseudobulk splitting

genomicdist

prep

refget

bbcache

Threading and resource controls

Safe dry-run planning

Removed stale command forms

Official sources (accessed 2026-07-23)

Command-line interface (`gtars-cli==0.9.0`)

`overlaprs`

`igd`

`uniwig`

`consensus`

`ranges`

`fscoring` fragment counts

`pb` pseudobulk splitting

`genomicdist`

`prep`

`refget`

`bbcache`