Refget CLI Reference

The refget command-line interface provides tools for working with reference sequences following GA4GH standards. It includes commands for computing sequence collection digests, managing local sequence stores, and interacting with remote seqcol APIs.

Installation

pip install refget

Quick Start

# Compute seqcol digest from a FASTA file
refget fasta digest genome.fa

# Create all index files from a FASTA
refget fasta index genome.fa

# Initialize a local sequence store
refget store init

# Add a FASTA to the store
refget store add genome.fa

# Compare two sequence collections
refget seqcol compare genome1.fa genome2.fa

Command Groups

The CLI is organized into five command groups:

Group	Description
refget config	Configuration management
refget fasta	FASTA file utilities
refget store	RefgetStore operations
refget seqcol	Sequence collection API
refget admin	Admin/database operations

---

Global Options

--version, -v    Show version and exit
--help           Show help message and exit

---

Config Commands

Manage refget configuration stored in ~/.refget/config.toml.

config init

Interactive setup wizard for refget configuration.

refget config init [--force]

Options:

• --force, -f: Overwrite existing configuration

config show

View all configuration or a specific section.

refget config show [SECTION]

Arguments:

• SECTION: Optional section to show (store, seqcol_servers, remote_stores, admin)

config get

Get a specific configuration value.

refget config get KEY

Examples:

refget config get store.path
refget config get admin.postgres_host

config set

Set a configuration value.

refget config set KEY VALUE

Examples:

refget config set store.path /path/to/store
refget config set admin.postgres_host localhost

config path

Show the path to the configuration file.

refget config path

config validate

Validate the configuration file.

refget config validate

config add

Add a server or store to the configuration.

refget config add RESOURCE_TYPE URL [--name NAME]

Arguments:

• RESOURCE_TYPE: One of: seqcol_server, remote_store, or sequence_server
• URL: URL of the server/store to add

Options:

• --name, -n: Optional name for this server/store

Examples:

refget config add seqcol_server https://seqcolapi.databio.org --name databio
refget config add remote_store s3://bucket/store/ --name primary
refget config add sequence_server https://www.ebi.ac.uk/ena/cram/ --name ebi

config remove

Remove a server or store from the configuration.

refget config remove RESOURCE_TYPE NAME

Examples:

refget config remove seqcol_server databio
refget config remove remote_store primary

---

FASTA Commands

Utilities for processing FASTA files and computing seqcol data.

fasta digest

Compute the seqcol digest (top-level) of a FASTA file.

refget fasta digest FILE

Output: JSON with digest and file path

{"digest": "abc123...", "file": "genome.fa"}

fasta seqcol

Compute the full seqcol JSON from a FASTA file.

refget fasta seqcol FILE [-o OUTPUT] [-l LEVEL]

Options:

• --output, -o: Output file path (default: stdout)
• --level, -l: Seqcol level: 1 (digests only) or 2 (full arrays). Default: 2

Example:

refget fasta seqcol genome.fa -o genome.seqcol.json

fasta index

Generate ALL derived files from a FASTA file.

refget fasta index FILE [-o OUTPUT_DIR] [--json]

For genome.fa, creates:

• genome.fa.fai - FASTA index (samtools-compatible)
• genome.seqcol.json - Sequence collection JSON
• genome.chrom.sizes - Chromosome sizes

Options:

• --output-dir, -o: Output directory (default: same as input file)
• --json, -j: Output result as JSON

fasta fai

Compute FAI index from a FASTA file.

refget fasta fai FILE [-o OUTPUT]

Outputs samtools-compatible .fai format (tab-separated).

fasta chrom-sizes

Compute chrom.sizes from a FASTA file.

refget fasta chrom-sizes FILE [-o OUTPUT]

Outputs UCSC-compatible chrom.sizes format (tab-separated name/length).

fasta stats

Display statistics for a FASTA file.

refget fasta stats FILE [--json]

Shows: sequence count, total length, N50, min/max/mean sequence length.

Options:

• --json, -j: Output as JSON instead of table

fasta validate

Validate a FASTA file format.

refget fasta validate FILE

Returns exit code 0 if valid, non-zero if invalid.

fasta rgsi

Compute .rgsi (RefgetStore sequence index) from a FASTA file.

refget fasta rgsi FILE [-o OUTPUT]

The .rgsi file contains sequence metadata in RefgetStore format.

fasta rgci

Compute .rgci (RefgetStore collection index) from a FASTA file.

refget fasta rgci FILE [-o OUTPUT]

The .rgci file contains collection metadata in RefgetStore format.

---

Store Commands

Manage a local RefgetStore for storing and retrieving sequences. See What is RefgetStore? for the concepts and RefgetStore file format for the on-disk layout. The direct store subcommands are init, add, list, match, get, pull, export, regions, chrom-sizes, stats, remove, crate, explore, and serve, plus the alias and fhr command groups documented below. Most commands accept --path PATH to select a local store (default: from config); where noted, they also accept --remote URL to read directly from a remote store instead.

store init

Initialize a local RefgetStore.

refget store init [--path PATH]

Options:

• --path, -p: Path for the store (default: from config or ~/.refget/store)

store add

Import one or more FASTA files into the local store.

refget store add FASTAS... [--namespace NS ...] [--file-list FILE] [--jobs N] [--force] [--path PATH] [--mode MODE] [--quiet]

Accepts explicit paths, glob patterns, and directories (expanded by gtars), plus a file-of-filenames via --file-list. Creates a sequence collection from each FASTA and stores all of its sequences; identical sequence content is deduplicated across files and collections.

Arguments:

• FASTAS...: FASTA paths, glob patterns, or directories to import (supports .gz). Can be omitted if --file-list supplies the inputs instead.

Options:

• --namespace, -N: Namespace prefix to extract aliases from FASTA headers (repeatable), e.g. -N ucsc -N refseq
• --file-list, -F: File-of-filenames (one path/glob/directory per line)
• --jobs, -j: Concurrent imports (0 = auto, 1 = serial; default 0)
• --force, -f: Overwrite existing collections/sequences
• --path, -p: Store path (default: from config)
• --mode, -m: Storage mode override: encoded (compressed, ~4x smaller, default) or raw (faster access, easier to inspect). Set at add time rather than at init, since mode describes how sequences are encoded and an empty store has no sequences yet.
• --quiet, -q: Suppress progress output

Output: a single explicit path returns one object; multiple inputs (globs, --file-list, or --jobs > 1) return a batch report instead. The batch report's n_* fields are per-run ingest counters -- use them (not store stats) to report what an add run actually did.

Single explicit path:

{"digest": "abc123...", "fasta": "genome.fa", "sequences": 25, "was_new": true}

Multiple inputs:

{
  "results": [
    {"digest": "IhtTMDzhGDWFvmoXdLg4KwcslTzDtPaO", "sequences": 1, "was_new": true},
    {"digest": "kd2A0MKmZCwr9SH8IM5MNYioSUVcVMfD", "sequences": 1, "was_new": true}
  ],
  "count": 2,
  "n_sequences_written": 2,
  "n_sequences_deduped": 0,
  "n_collections_new": 2
}

Examples:

refget store add genome.fa
refget store add 'fastas/*.fa.gz' --jobs 4
refget store add --file-list manifest.txt
refget store add dir1/ dir2/ -N ucsc

store list

Browse collections, the chromosome or contig names within one collection, or the store's global deduplicated sequence records.

refget store list [COLLECTION] [--sequences] [--path PATH] [--remote URL]

Arguments:

• COLLECTION: Optional collection digest or NAMESPACE:ALIAS, such as ucsc:hg38. When provided, the command lists that collection's own sequence names in original FASTA order.

Options:

• --sequences, -s: List globally deduplicated sequence records instead of collections. This cannot be combined with COLLECTION.
• --path, -p: Store path (default: from config)
• --remote, -r: Remote store URL (overrides --path)

Without an argument, the command returns all collections, including sequence counts and registered collection aliases:

{
  "collections": [
    {
      "digest": "abc123...",
      "n_sequences": 455,
      "aliases": [["ucsc", "hg38"]]
    }
  ]
}

With a collection selector, it returns collection identity plus its collection-local names, lengths, and canonical sequence identifiers:

{
  "collection": {
    "digest": "abc123...",
    "n_sequences": 455,
    "aliases": [["ucsc", "hg38"]]
  },
  "sequences": [
    {"name": "chr1", "length": 248956422, "digest": "xyz..."}
  ]
}

Every row -- collection-local names, the global sequence inventory, and match results below -- identifies a sequence by the bare digest field: the sha512t24u value with no SQ. prefix. (The SQ.-prefixed form only appears in the GA4GH-spec sequences array returned by store get, which follows the seqcol Level 2 wire format rather than this CLI's row schema.)

--sequences retains the separate global sequence-store view:

{"sequences": [{"digest": "abc123...", "name": "chr1", "length": 12345}, ...]}

Collection-local names and global sequence records are deliberately different: identical sequence content is stored once globally but may be named chr1, 1, or another label in different collections.

Examples:

# Inventory of collections and aliases
refget store list --path /data/refget

# Chromosomes/contigs for a collection selected by alias or digest
refget store list ucsc:hg38 --path /data/refget
refget store list abc123... --path /data/refget

# Global deduplicated sequence records
refget store list --sequences --path /data/refget

store match

Translate chromosome or contig names between two stored collections by joining their collection-local records on canonical sequence digest. Selectors may be collection digests, collection aliases, or one of each.

refget store match COLLECTION_A COLLECTION_B [--include-unmatched] [--path PATH] [--remote URL]

Arguments:

• COLLECTION_A: First collection digest or NAMESPACE:ALIAS.
• COLLECTION_B: Second collection digest or NAMESPACE:ALIAS.

Options:

• --include-unmatched: Include sequences present in only one collection.
• --path, -p: Store path (default: from config).
• --remote, -r: Remote store URL (overrides --path).

Each matched group contains the shared bare sequence digest (sha512t24u, no SQ. prefix) and length plus every name used for that content in each collection. Name arrays make one-to-many relationships explicit rather than arbitrarily choosing one label.

{
  "collection_a": "digest-a...",
  "collection_b": "digest-b...",
  "matches": [
    {
      "digest": "xyz...",
      "length": 23513712,
      "names_a": ["chr2L"],
      "names_b": ["2L"]
    }
  ]
}

With --include-unmatched, the response also includes a_only and b_only arrays with the same row structure -- each entry has an empty names_a or names_b for the collection that lacks the sequence.

Examples:

# Match two named collections
refget store match ucsc:dm6 flybase:r6.68 --path /data/refget

# Match by digest and retain sequences found on only one side
refget store match digest-a... digest-b... \
  --include-unmatched --path /data/refget

# Match against a remote store without pulling it locally first
refget store match ucsc:dm6 flybase:r6.68 --remote https://example.com/store

store get

Get a collection or sequence by digest.

refget store get DIGEST [--sequence] [--name NAME] [--start N] [--end M] [--path PATH] [--remote URL]

Options:

• --sequence, -s: Get a sequence instead of a collection
• --name, -n: Get sequence by name from a collection (requires collection digest)
• --start: Subsequence start position (0-based)
• --end: Subsequence end position (exclusive)
• --path, -p: Store path (default: from config)
• --remote, -r: Remote store URL (overrides --path)

Output: Full seqcol JSON (default), or raw sequence string with --sequence or --name.

Examples:

# Get collection by digest
refget store get abc123

# Get sequence by digest
refget store get <seq_digest> --sequence

# Get sequence by name from collection
refget store get <coll_digest> --name chr1

# Get subsequence
refget store get <seq_digest> --sequence --start 100 --end 200

# Get from remote store
refget store get abc123 --remote https://example.com/store

Note: Digests with SQ. prefix (e.g., SQ.abc123) are automatically normalized—the prefix is stripped before lookup.

store pull

Pull collections from a remote store into the local store.

refget store pull [DIGEST] [--file FILE] [--remote URL] [--path PATH] [--alias-strategy STRATEGY] [--quiet]

Each requested collection is imported in full: sequences, aliases, and FHR metadata are all materialized into the local on-disk store. There is no lazy pull mode -- for on-demand access to a remote store without copying it locally, open it with --remote on the read commands instead. Before importing, the remote's alias and FHR sidecars are fetched (using --alias-strategy to resolve conflicts) so they travel with the collection.

Arguments:

• DIGEST: Collection digest to pull. Omit when using --file for a batch pull.

Options:

• --file, -f: File containing digests (one per line) for batch pull
• --path, -p: Local store path (default: from config)
• --remote, --server, -r: Remote store URL. If omitted, resolution tries, in order: (1) the local store, (2) configured remote_stores, then (3) configured seqcol_servers (discovered via service-info).
• --alias-strategy: Conflict strategy when fetching alias/FHR sidecars from the remote: keep-ours, keep-theirs, or notify (default: keep-ours)
• --quiet, -q: Suppress progress output

Examples:

refget store pull ABC123 --remote https://example.com/store
refget store pull --file digests.txt --remote https://example.com/store

store export

Export sequences as a FASTA file, in one of four modes.

refget store export [DIGEST] [-o OUTPUT] [--bed BED] [--name NAME] [--seq-digest DIGEST] [--path PATH] [--remote URL] [--line-width N]

Modes (pick one):

• Full collection: DIGEST alone
• Subset by names: DIGEST --name chr1 --name chr2
• Regions from a BED file: DIGEST --bed regions.bed
• Ad-hoc by sequence digest, bypassing collections entirely: --seq-digest SEQ_DIGEST (repeatable). This mode takes sequence digests, not a collection digest, and ignores the DIGEST argument if one is given.

Options:

• --output, -o: Output FASTA file path (default: stdout)
• --bed, -b: BED file for region extraction
• --name, -n: Sequence names to include (repeatable)
• --seq-digest, -S: Export ad-hoc by sequence digest, bypassing collections (repeatable; see modes above)
• --path, -p: Store path (default: from config)
• --remote, -r: Remote store URL (overrides --path)
• --line-width, -w: FASTA line width (default: 80)

Examples:

# Export full collection
refget store export abc123 -o genome.fa

# Export specific chromosomes
refget store export abc123 -o subset.fa --name chr1 --name chr2

# Export regions from BED file
refget store export abc123 -o regions.fa --bed regions.bed

# Export by sequence digest, bypassing collections
refget store export --seq-digest xyz123... --seq-digest xyz456... -o seqs.fa

store regions

Extract BED-file regions from a collection as structured sequence data. Local- and remote-capable.

refget store regions DIGEST --bed BED [--json] [--path PATH] [--remote URL]

Reads a BED file and returns the sequence for each region. By default, emits FASTA-style records with headers >{chrom}:{start}-{end}; --json emits a list of {chrom_name, start, end, sequence} objects instead. Unlike store export --bed, which writes a FASTA file, regions is the structured/JSON-friendly form of the same extraction.

Arguments:

• DIGEST (required): Collection digest to extract regions from

Options:

• --bed, -b (required): BED file of regions to extract
• --json, -j: Output as a JSON list of region records instead of FASTA
• --path, -p: Store path (default: from config)
• --remote, -r: Remote store URL (overrides --path)

Example:

refget store regions abc123 --bed regions.bed
refget store regions abc123 -b regions.bed --json

[{"chrom_name": "chr1", "start": 0, "end": 5, "sequence": "ACGTA"}]

store chrom-sizes

Generate chrom.sizes from a collection digest. Local- and remote-capable.

refget store chrom-sizes DIGEST [-o OUTPUT] [--path PATH] [--remote URL]

Outputs UCSC-compatible chrom.sizes format (tab-separated name/length).

Options:

• --output, -o: Output file path (default: stdout)
• --path, -p: Store path (default: from config)
• --remote, -r: Remote store URL (overrides --path)

store stats

Display store statistics. Local- and remote-capable.

refget store stats [--path PATH] [--remote URL]

Options:

• --path, -p: Store path (default: from config)
• --remote, -r: Remote store URL (overrides --path)

Output: the store's stats dict. All values are emitted as JSON strings, not numbers or booleans:

• n_sequences: total number of sequences (Stub + Full)
• n_sequences_in_memory: number of sequences whose bytes are currently held in RAM (Full). This is a live RAM-residency gauge, not an ingest count -- it reads "0" for a store you just opened, since opening only reads metadata.
• n_collections: total number of collections (Stub + Full)
• n_collections_in_memory: number of collections whose sequence list is currently loaded in RAM. Also a residency gauge; it resets on process start and counts collections merely touched by a read, not collections ingested.
• storage_mode: "Encoded" or "Raw"
• logical_sequence_bytes: the logical encoded size of all sequence payloads, computed from sequence lengths and storage mode at index-write time. It excludes indexes, aliases, FHR sidecars, the manifest, and filesystem overhead, so it approximates but is not the exact on-disk footprint. See RefgetStore file format.

For what a specific add run actually wrote, use that command's own output (n_sequences_written, n_sequences_deduped, n_collections_new) rather than stats, which is a snapshot of current state.

Example output:

{
  "n_sequences": "3",
  "n_sequences_in_memory": "0",
  "n_collections": "2",
  "n_collections_in_memory": "0",
  "storage_mode": "Encoded",
  "logical_sequence_bytes": "25"
}

store remove

Remove a collection from the store.

refget store remove DIGEST [--path PATH]

This removes the collection from the store's index. Associated sequences are not removed, since they may be shared with other collections.

Options:

• --path, -p: Store path (default: from config)

store crate

Generate an RO-Crate metadata file describing the store as a FAIR research object -- structure, provenance, and statistics. Local-only.

refget store crate --name NAME [--path PATH] [--description TEXT] [--author "Name <URL>"] [--license URL] [-o OUTPUT]

Writes ro-crate-metadata.json (or the path given by --output) conforming to the RO-Crate specification. The store's own store crate command is the canonical way to produce this file; see the RO-Crate profile it targets.

Options:

• --path, -p: Store path (default: from config)
• --name, -n (required): Name for the RO-Crate root dataset
• --description, -d: Description of the store
• --author, -a: Author, in "Name <URL>" format, e.g. "Jane Doe <https://orcid.org/...>"
• --license, -l: License URL
• --output, -o: Output path (default: <store-path>/ro-crate-metadata.json)

Example:

refget store crate --path /store --name "My genomes" --author "J Doe <https://orcid.org/0000-0001-1234-5678>"

{"output": "/store/ro-crate-metadata.json", "status": "created", "entities": 14}

store explore

Browse a local RefgetStore in your web browser -- no backend, no internet connection required. Local-only, read-only.

refget store explore [PATH] [--host HOST] [--port N] [--no-browser] [--frontend-dir DIR] [--store-only]

Serves the store's static files and the bundled Store Explorer single-page app from one localhost origin (so no CORS is involved), then opens the Explorer pointed at that store. Only GET/HEAD are served; no write or control operation is exposed -- use store pull/add/alias to modify a store. Unlike most store commands, explore doesn't require gtars; it's pure static file serving, so it also works against read-only CVMFS mounts and air-gapped servers.

Arguments:

• PATH: Local store directory to explore (default: from config)

Options:

• --host: Host/interface to bind (default: 127.0.0.1)
• --port, -P: Port to serve on, auto-increments if busy (default: 8080)
• --no-browser: Do not open a web browser; just print the URLs
• --frontend-dir: Override the Store Explorer SPA build directory
• --store-only: Serve only the store files (skip the SPA), for a self-hosted UI

Examples:

refget store explore /path/to/refget-store
refget store explore --no-browser --port 9000

store serve

Serve a seqcol API backed by a RefgetStore. No database required. See How to serve a RefgetStore concurrently for the full deployment recipe.

refget store serve [--path PATH | --remote URL] [--port N] [--host HOST] [--lazy]

By default the store is fully loaded and converted to a ReadonlyRefgetStore, whose read methods borrow immutably and are safe to share across request threads for concurrent serving. Pass --lazy to skip that load-and-convert step and serve directly from the mutable, lazy-loading store instead -- this avoids loading the whole store into memory up front, but is single-reader-oriented and not recommended for concurrent production serving. explore and serve are not interchangeable: explore is static, read-only browsing with no API; serve runs the actual seqcol HTTP API.

Options:

• --path, -p: Local store path
• --remote, -r: Remote store URL (e.g. s3://bucket/store/)
• --port: Port to serve on (default: 8000)
• --host: Host to bind to; use 0.0.0.0 to expose on your network (default: 127.0.0.1)
• --lazy: Serve from the mutable, lazy-loading store instead of converting to readonly

Examples:

refget store serve --path /path/to/store --port 8000
refget store serve --remote s3://bucket/store/ --port 8000
refget store serve --path /path/to/store --lazy

store alias

Manage sequence and collection aliases -- human-readable namespace:alias names that resolve to a digest. See Names, aliases, and identifiers for the concepts.

refget store alias {add|get|list|rm|load|for} ...

All six actions operate on collection aliases by default; pass --seq to operate on sequence aliases instead. add, rm, and load are local-only writes. get, list, and for are reads that also accept --remote URL.

Action	Usage	Notes
add	refget store alias add NAMESPACE ALIAS DIGEST [--seq] [--path PATH]	Map namespace:alias -> digest
get	refget store alias get NAMESPACE ALIAS [--seq] [--metadata] [--path PATH] [--remote URL]	Resolve to a digest, or full metadata with --metadata
list	refget store alias list [NAMESPACE] [--seq] [--namespaces] [--path PATH] [--remote URL]	Omit NAMESPACE (or pass --namespaces) to list namespaces; give one to list its aliases
rm	refget store alias rm NAMESPACE ALIAS [--seq] [--path PATH]	Remove one alias
load	refget store alias load NAMESPACE FILE [--seq] [--path PATH]	Bulk-load alias<TAB>digest lines from a TSV file into a namespace
for	refget store alias for DIGEST [--seq] [--path PATH] [--remote URL]	Reverse lookup: every (namespace, alias) pair for a digest

Forward-lookup example:

refget store alias add ucsc hg38 abc123...
refget store alias get ucsc hg38

{"namespace": "ucsc", "alias": "hg38", "digest": "abc123...", "kind": "collection"}

Reverse-lookup example:

refget store alias for abc123...

{"digest": "abc123...", "aliases": [["ucsc", "hg38"], ["ncbi", "GRCh38"]]}

store fhr

Manage FHR (FAIR Headers Reference genome) metadata attached to a collection. See Understanding FHR metadata for the field meanings.

refget store fhr {get|set|set-fields|rm|list} ...

get and list are reads that also accept --remote URL. set, set-fields, and rm are local-only writes.

Action	Usage	Notes
get	refget store fhr get DIGEST [--path PATH] [--remote URL]	Show FHR metadata for a collection
set	refget store fhr set DIGEST FILE [--path PATH]	Set FHR metadata from a JSON file, replacing any existing metadata
set-fields	refget store fhr set-fields DIGEST [FIELDS...] [--path PATH]	Set FHR metadata from individual field options (below)
rm	refget store fhr rm DIGEST [--path PATH]	Remove FHR metadata for a collection
list	refget store fhr list [--path PATH] [--remote URL]	List collection digests that have FHR metadata

set-fields accepts these field options; --genome-synonym and --identifier are repeatable, the rest are scalar:

--genome, --version, --masking, --genome-synonym (repeatable), --voucher-specimen, --documentation, --identifier (repeatable), --scholarly-article, --funding

JSON-file example:

refget store fhr set abc123... fhr_metadata.json
refget store fhr get abc123...

Field-based example:

refget store fhr set-fields abc123... --genome "Homo sapiens" --version GRCh38 \
  --genome-synonym hg38 --genome-synonym GRCh38.p14

{"digest": "abc123...", "status": "set"}

---

Seqcol Commands

Work with sequence collections and the seqcol API.

seqcol compare

Compare two sequence collections.

refget seqcol compare A B [--server URL] [--quiet]

Accepts flexible inputs:

• <digest> - Fetches from local store or server
• <file.fa> - Computes seqcol on the fly
• <file.seqcol.json> - Uses local seqcol file

Options:

• --server, -s: Server URL override
• --quiet, -q: Suppress output; use exit code only (0=compatible, 1=incompatible)

Example:

refget seqcol compare genome1.fa genome2.fa
refget seqcol compare abc123 def456 --server https://seqcolapi.databio.org

seqcol digest

Compute the seqcol digest of a file.

refget seqcol digest FILE

Accepts either a FASTA file or a .seqcol.json file.

seqcol validate

Validate a seqcol JSON file.

refget seqcol validate FILE

Checks that the file is valid JSON and conforms to the seqcol schema.

seqcol attributes

List attributes in a seqcol JSON file.

refget seqcol attributes FILE

Shows the attribute names and their array lengths.

seqcol schema

Show the seqcol schema definition.

refget seqcol schema

seqcol servers

List known seqcol servers from configuration.

refget seqcol servers

seqcol show

Get a sequence collection by digest from local store or remote server.

refget seqcol show DIGEST [--level LEVEL] [--server URL]

Resolution order: local store -> configured seqcol_servers -> --server override

Options:

• --level, -l: Seqcol level: 1 (digests only) or 2 (full arrays). Default: 2
• --server, -s: Server URL override

Examples:

refget seqcol show XZlrcEGi6mlopZ2uD8ObHkQB1d0oDwKk
refget seqcol show XZlrcEGi6mlopZ2uD8ObHkQB1d0oDwKk --level 1
refget seqcol show XZlrcEGi6mlopZ2uD8ObHkQB1d0oDwKk --server https://seqcolapi.databio.org

seqcol list

List collections available on the server.

refget seqcol list [--server URL] [--limit N] [--offset N]

Options:

• --server, -s: Server URL override
• --limit, -n: Maximum number of collections to return (default: 100)
• --offset: Offset for pagination (default: 0)

seqcol search

Find collections that share an attribute.

refget seqcol search [--names DIGEST] [--lengths DIGEST] [--sequences DIGEST] [--server URL]

The attribute digest is the digest of an attribute array (e.g., from level 1 output).

Options:

• --names: Names array digest to search for
• --lengths: Lengths array digest to search for
• --sequences: Sequences array digest to search for
• --server, -s: Server URL override

Example workflow:

# Get names digest from level 1
names_digest=$(refget fasta seqcol genome.fa --level 1 | jq -r '.names')

# Search for collections with same names
refget seqcol search --names $names_digest

seqcol attribute

Retrieve the actual array values for an attribute digest.

refget seqcol attribute ATTRIBUTE_NAME DIGEST [--server URL]

Examples:

refget seqcol attribute lengths cGRMZIb3AVgkcAfNv39RN7hnT5Chk7RX
refget seqcol attribute names Fw1r9eRxfOZD98KKrhlYQNEdSRHoVxAG

seqcol info

Get server information and capabilities.

refget seqcol info [--server URL]

Returns service info including supported algorithms and features.

---

Admin Commands

Database administration and bulk loading operations.

admin status

Show admin/database connection status.

refget admin status

Tests the database connection and displays connection info and table statistics.

admin info

Show system info (version, dependencies, etc.).

refget admin info [--json]

admin load

Load seqcol metadata from FASTA or JSON into PostgreSQL.

refget admin load [INPUT_FILE] [--pep PEP] [--pephub PROJECT] [--fa-root PATH] [--name NAME]

Can load from:

• Single FASTA file
• Single .seqcol.json file
• Batch from PEP project file (--pep)
• Batch from PEPhub project (--pephub)

Options:

• --pep: PEP project file for batch loading
• --pephub: PEPhub project (e.g., nsheff/human_fasta_ref)
• --fa-root: Root directory for FASTA files (used with --pep/--pephub)
• --name, -n: Human-readable name for the FASTA

Examples:

refget admin load genome.fa
refget admin load genome.fa --name "Human GRCh38"
refget admin load genome.seqcol.json
refget admin load --pep genomes.yaml --fa-root /data/fasta
refget admin load --pephub nsheff/human_fasta_ref --fa-root /data/fasta

admin register

Upload a FASTA file to S3 and create a DRS record.

refget admin register FASTA --bucket BUCKET [--prefix PREFIX] [--cloud CLOUD] [--region REGION] [--digest DIGEST]

Does NOT load seqcol metadata. Use ingest for combined operation, or run load first.

Required Options:

• --bucket, -b: S3 bucket name for upload

Optional Options:

• --prefix, -p: S3 key prefix (default: none)
• --cloud, -c: Cloud provider (default: aws)
• --region, -r: Cloud region (default: us-east-1)
• --digest, -d: Seqcol digest (if not provided, will be computed from FASTA)

Examples:

refget admin register genome.fa --bucket my-refget-bucket
refget admin register genome.fa -b my-bucket -p fasta/ -c aws -r us-west-2
refget admin register genome.fa -b my-bucket --digest abc123...

admin ingest

Load seqcol metadata AND register FASTA with cloud storage (combined operation).

refget admin ingest [FASTA] --bucket BUCKET [--prefix PREFIX] [--cloud CLOUD] [--region REGION] [--pep PEP] [--pephub PROJECT] [--fa-root PATH] [--name NAME]

Combines load and register in a single operation:

1. Parse FASTA and extract seqcol metadata
2. Store metadata in PostgreSQL
3. Upload FASTA to S3
4. Create DRS record for access

Required Options:

• --bucket, -b: S3 bucket name for upload

Optional Options:

• --prefix, -p: S3 key prefix
• --cloud, -c: Cloud provider (default: aws)
• --region, -r: Cloud region (default: us-east-1)
• --pep: PEP project file for batch ingestion
• --pephub: PEPhub project (e.g., nsheff/human_fasta_ref)
• --fa-root: Root directory for FASTA files (used with --pep/--pephub)
• --name, -n: Human-readable name for the FASTA

Examples:

refget admin ingest genome.fa --bucket my-bucket
refget admin ingest genome.fa -b my-bucket --name "Human GRCh38"
refget admin ingest --pep genomes.yaml --fa-root /data/fasta --bucket my-bucket

---

Environment Variables

Variable	Description
REFGET_CONFIG	Path to configuration file
REFGET_STORE	Path to local RefgetStore
REFGET_STORE_PATH	Alternative for store path
REFGET_DATABASE_URL	PostgreSQL connection URL
POSTGRES_HOST	Database host
POSTGRES_DB	Database name
POSTGRES_USER	Database user
POSTGRES_PASSWORD	Database password

---

Exit Codes

Code	Meaning
0	Success
1	General failure
2	File not found
3	Network error
4	Configuration error

---

Configuration File

The configuration file is located at ~/.refget/config.toml:

[store]
path = "~/.refget/store"

[seqcol_servers]
default = "https://seqcolapi.databio.org"

[admin]
postgres_host = "localhost"
postgres_db = "refget"
postgres_user = "postgres"