Shell completion¶

cxg supports tab-completion for filter options like --organism, --tissue, --assay, and more. When you press <TAB> after a filter flag, you'll see valid values you can filter by.

Setup¶

Install shell completions once:

cxg --install-completion

This registers completions with your shell (bash, zsh, fish, or PowerShell). You may need to restart your shell or source its config file for the change to take effect.

To verify the completions are registered:

cxg --show-completion

Usage¶

After setup, press <TAB> to complete filter values:

# See all organisms
cxg list --organism <TAB>

# Prefix matching is case-sensitive
cxg dataset list --tissue br<TAB>    # shows values starting with "br", like "brain" and "breast"

# Output format completions
cxg list --output <TAB>               # shows "table", "json", "tsv"

How it works¶

Completions are sourced from two places:

Local dataset cache (primary): if you've run cxg list or cxg cache refresh before, completions are drawn from your cached datasets. Values are sorted by the number of matching datasets, with counts shown as help text in shells that support it (zsh, fish, PowerShell).
Bundled fallback: if no cache exists yet, completions fall back to a pre-generated list of valid values shipped with the package. These values won't include dataset counts.

Completions never make network calls and never produce errors. If anything goes wrong internally, an empty list is returned silently.

Supported options¶

The following options support tab-completion:

--organism
--tissue
--tissue-type
--assay
--cell-type
--disease
--self-reported-ethnicity
--suspension-type
--schema-version
--output

Shell notes¶

zsh, fish, PowerShell: display both the value and a help string (e.g., dataset count)
bash: displays only the value, help text is not shown
Values containing spaces (e.g., "Homo sapiens") are automatically quoted by the shell