CLI reference
Every command's flags, defaults and help text, taken straight from the CLI itself. This page is generated from vcc --help, so it cannot drift from the code.
Running vcc <command> --help in your own terminal shows exactly the same thing.
vcc
text
Usage: vcc [OPTIONS] COMMAND [ARGS]...
vcc — submit predictions to the Virtual Cell Challenge.
Run `vcc version` for version details, or `vcc COMMAND --help` for a
command.
Options:
--json Emit machine-readable JSON instead of human-readable text.
--profile TEXT Named credential profile [env: VCC_PROFILE].
--endpoint TEXT Base URL of the VCC site to talk to [env: VCC_ENDPOINT].
--version Show the vcc version and exit.
-h, --help Show this message and exit.
Commands:
cancel Abandon an in-progress submission, freeing your team's slot.
datasets List and download Virtual Cell Challenge reference data.
login Authenticate with a VCC API token.
logout Remove the stored credential for the active profile.
prep Validate, slim, normalize, and package an .h5ad into a .vcc.
sample Generate a random, valid dummy prediction for testing `vcc...
skill Install the VCC agent skill into your coding agent (Claude...
status Show the status (and scores, once published) of one submission.
submit Upload a prediction and start scoring.
version Print the vcc version.
whoami Show the authenticated account, team, and whether you can...vcc cancel
text
Usage: vcc cancel [OPTIONS] [ENTRY_ID]
Abandon an in-progress submission, freeing your team's slot.
Use this when an upload was interrupted or you started submitting the wrong
file: your team allows one submission in progress at a time, so a stuck
upload otherwise blocks the next `vcc submit` until it either finishes or
ages out.
Cancelling marks the entry failed and clears the interrupted upload so a
fresh `vcc submit` works right away. **It does NOT count against your daily
limit** — only a successfully scored submission does — so abandoning a wrong
file is free.
ENTRY_ID is optional when there is exactly one interrupted upload for this
profile; pass it explicitly to disambiguate, or to cancel an entry started
on another machine.
An UPLOADING submission is always cancellable. One that has moved on to
`launching`/`scoring` can be cancelled only while its scoring job is still
waiting in the queue for a machine — once the job actually starts running it
can't be stopped, and `vcc cancel` will tell you to wait for it.
Options:
-y, --yes Do not prompt for confirmation.
--endpoint TEXT Base URL to query.
--profile TEXT Credential profile to use.
--json Emit machine-readable JSON instead of human-readable text.
-h, --help Show this message and exit.vcc datasets
text
Usage: vcc datasets [OPTIONS] COMMAND [ARGS]...
List and download Virtual Cell Challenge reference data.
Options:
-h, --help Show this message and exit.
Commands:
download Download a dataset by id (see `vcc datasets list`).
list Show which datasets you can download.vcc datasets download
text
Usage: vcc datasets download [OPTIONS] DATASET_ID
Download a dataset by id (see `vcc datasets list`).
Resumes an interrupted download, re-mints the link if it expires mid-
transfer, and verifies the finished file against the checksum the server
advertises.
Options:
-o, --output FILE Write to this exact path instead of <dir>/<filename>.
-d, --dir DIRECTORY Directory to download into [default: $VCC_DATA_DIR or
cwd].
-f, --force Re-download even if the file is already present and
verified.
--endpoint TEXT Base URL to query.
--profile TEXT Credential profile to use.
--json Emit machine-readable JSON instead of human-readable
text.
-h, --help Show this message and exit.vcc datasets list
text
Usage: vcc datasets list [OPTIONS]
Show which datasets you can download.
Options:
--endpoint TEXT Base URL to query.
--profile TEXT Credential profile to use.
--json Emit machine-readable JSON instead of human-readable text.
-h, --help Show this message and exit.vcc login
text
Usage: vcc login [OPTIONS]
Authenticate with a VCC API token.
Tokens are created in the web app on your Credentials page — the CLI cannot
mint one (generating a token there revokes any previous token). Provide it
via --token-stdin, --token, or the VCC_TOKEN environment variable.
Options:
--token TEXT The API token. Visible in your shell history and process
list — prefer --token-stdin.
--token-stdin Read the API token from stdin (one line). Best for piping
from a secret manager.
--endpoint TEXT Base URL to log in against (remembered for this profile).
--store-plaintext If no secure OS keychain exists, save the token to a 0600
file instead of refusing.
--no-store Validate the token but store nothing (use VCC_TOKEN each
run).
--json Emit machine-readable JSON instead of human-readable
text.
-h, --help Show this message and exit.vcc logout
text
Usage: vcc logout [OPTIONS]
Remove the stored credential for the active profile.
Only touches this profile, and cannot revoke the token itself — revoke it in
the web app if it may have leaked.
Options:
--profile TEXT Credential profile to log out of.
--json Emit machine-readable JSON instead of human-readable text.
-h, --help Show this message and exit.vcc prep
text
Usage: vcc prep [OPTIONS] [INPUT.h5ad]
Validate, slim, normalize, and package an .h5ad into a .vcc.
Native reimplementation of `cell-eval prep` — no network calls, no cell-eval
dependency. Catches locally the same errors the server would reject.
Options:
-i, --input PATH Path to the input .h5ad (alternative to the
positional argument).
-g, --genes PATH Headerless CSV of expected gene symbols, in
order.
--perts PATH pert_counts.csv from the controls bundle —
the official perturbation list, checked per
context.
--verify-targets / --no-verify-targets
Check each context predicts exactly its
official perturbations. Needs --perts.
[default: verify-targets]
--check-cell-counts / --no-check-cell-counts
Require each perturbation to have exactly
the official number of cells. [default:
check-cell-counts]
--cells-per-pert INTEGER Cells required per perturbation (the panel's
count). An n_cells column in --perts wins
over it; -1 means no built-in expectation.
[default: 400]
-o, --output PATH Path to write the .vcc [default:
<input>.prep.vcc].
-p, --pert-col TEXT Input column naming perturbations.
[default: target_gene]
-c, --celltype-col TEXT Input column naming cell type (optional).
-n, --ntc-name TEXT Negative-control label expected in the
perturbation column. [default: non-
targeting]
-P, --output-pert-col TEXT Perturbation column name in the output.
[default: target_gene]
-C, --output-celltype-col TEXT Cell-type column name in the output.
[default: celltype]
--context-col TEXT Input column naming the cell context
(A/B/C), as in the control files. [default:
context]
--contexts TEXT Comma-separated contexts the submission must
cover: A,B,C in the validation phase, D,E,F
in the final phase. [default: from the
controls bundle's manifest.json beside
--perts]. Empty disables the check.
-e, --encoding [32|64] Float bit width for X. [default: 32]
--allow-discrete Legacy: with --no-require-counts, keep
integer counts as-is instead of log-
normalizing.
--require-counts / --no-require-counts
Require raw integer counts (2026 scores in
counts space). --no-require-counts restores
log-normalization. [default: require-
counts]
--reject-controls / --allow-controls
Reject submitted control cells (scoring uses
the held-out controls, never yours).
[default: reject-controls]
--expected-gene-dim INTEGER Expected gene dimension; -1 disables the
check. [default: 18533]
--max-cell-dim INTEGER Maximum cell count; -1 disables the cap.
[default: 400000]
--max-nnz INTEGER Maximum nonzero values (density cap); -1
disables the cap. [default: the scoring
hardware's limit]
--max-counts-per-cell INTEGER Maximum per-cell count total (sum over
genes); -1 disables the cap. [default:
1000000]
--dry-run Validate and report what prep would do,
without writing output.
-f, --force Overwrite the output file if it already
exists.
--json Emit machine-readable JSON instead of human-
readable text.
-h, --help Show this message and exit.vcc sample
text
Usage: vcc sample [OPTIONS]
Generate a random, valid dummy prediction for testing `vcc submit`.
Builds synthetic random counts over the given gene list — one cell group per
perturbation — and packages a submittable .vcc (same format as `vcc prep`).
The result is minimal but *complete*: every official perturbation from
`pert_counts.csv`, in every context, with exactly the 400 cells each the
panel uses, so scoring accepts it. The values are noise, so it is for
pipeline testing (upload → scoring), NOT for scoring well.
Both -g and -p come from `vcc datasets download controls` (`controls-final`
in the final phase).
Options:
-g, --genes PATH Headerless CSV of gene symbols (the official VCC
gene list, from `vcc datasets download`).
[required]
-o, --output PATH Where to write the sample [default: sample.vcc, or
sample.h5ad with --h5ad].
-p, --perts PATH pert_counts.csv from the controls bundle — the
official perturbation list. Required: a sample
built from anything else is rejected by scoring.
[required]
--cells-per-pert INTEGER Cells per perturbation [default: 400 with --full,
5 with --no-full]. An n_cells column in --perts
still wins.
--full / --no-full Give each perturbation the official 400 cells.
--no-full makes a small, DELIBERATELY INVALID file
that scoring will reject — upload-path testing
only. [default: full]
--ntc-cells INTEGER Non-targeting control cell count [default:
--cells-per-pert]. Only for the legacy --contexts
'' shape.
--genes-per-cell INTEGER Nonzero genes per cell (controls sparsity and file
size). [default: 300]
--context-col TEXT Context column name to write into the sample.
[default: context]
--contexts TEXT Comma-separated contexts the sample must cover:
A,B,C in the validation phase, D,E,F in the final
phase. [default: from the controls bundle's
manifest.json beside --perts]. Empty disables
contexts.
--max-cell-dim INTEGER Maximum total cells; -1 disables the cap (raise it
for a very large --full sample). [default:
400000]
--seed INTEGER RNG seed. Omitted, each run generates a different
sample (and prints the seed it used); pass that
value back to reproduce one exactly.
--h5ad Write a raw .h5ad instead of packaging a .vcc.
-f, --force Overwrite the output file if it already exists.
--json Emit machine-readable JSON instead of human-
readable text.
-h, --help Show this message and exit.vcc skill
text
Usage: vcc skill [OPTIONS] COMMAND [ARGS]...
Install the VCC agent skill into your coding agent (Claude Code / Codex /
Gemini).
Options:
-h, --help Show this message and exit.
Commands:
install Copy the bundled skill into your agent's skills directory.
path Print where `vcc skill install` would put the skill for an...
uninstall Remove a skill directory previously installed by vcc (leaves...vcc skill install
text
Usage: vcc skill install [OPTIONS]
Copy the bundled skill into your agent's skills directory.
The skill ships inside the CLI but agents don't read skills from Python
packages, so this copies it where the agent looks. Restart your agent
session (or /reload) afterward so it picks up the new skill.
Options:
--agent [auto|claude|codex|gemini|all]
Which agent(s) to install into. 'auto' =
every agent already present on the machine
(falls back to claude if none); 'all' = all
three regardless. [default: auto]
--dir PATH Install into this exact directory instead of
the per-agent default.
--force Overwrite a target directory vcc didn't
create.
--json Emit machine-readable JSON instead of human-
readable text.
-h, --help Show this message and exit.vcc skill path
text
Usage: vcc skill path [OPTIONS]
Print where `vcc skill install` would put the skill for an agent (installs
nothing).
Options:
--agent [claude|codex|gemini] Which agent's skills directory to print.
[default: claude]
--json Emit machine-readable JSON instead of human-
readable text.
-h, --help Show this message and exit.vcc skill uninstall
text
Usage: vcc skill uninstall [OPTIONS]
Remove a skill directory previously installed by vcc (leaves foreign dirs
untouched).
Options:
--agent [auto|claude|codex|gemini|all]
Which agent(s) to remove from. 'auto' =
every agent present on the machine.
[default: auto]
--dir PATH Remove from this exact directory instead of
the per-agent default.
--json Emit machine-readable JSON instead of human-
readable text.
-h, --help Show this message and exit.vcc status
text
Usage: vcc status [OPTIONS] ENTRY_ID
Show the status (and scores, once published) of one submission.
Options:
--wait Block until the submission reaches a terminal state.
--poll-interval FLOAT Seconds between polls with --wait. [default: 5.0]
--wait-timeout FLOAT Give up waiting after N seconds.
--endpoint TEXT Base URL to query.
--profile TEXT Credential profile to use.
--json Emit machine-readable JSON instead of human-readable
text.
-h, --help Show this message and exit.vcc submit
text
Usage: vcc submit [OPTIONS] FILE
Upload a prediction and start scoring.
FILE may be a .vcc (validated and uploaded as-is) or a raw .h5ad, which is
prepped first — pass -g/--genes and --perts (or --no-verify-targets to skip
the perturbation check).
Options:
-m, --model-name TEXT Name for this model on the leaderboard
(required).
-d, --description TEXT Optional description (max 2000 chars).
-g, --genes PATH Gene list, if FILE is a raw .h5ad that needs
prepping.
--perts PATH pert_counts.csv, if FILE is a raw .h5ad —
the official list prep checks targets
against (required by default when prepping;
see --no-verify-targets).
--verify-targets / --no-verify-targets
When prepping a raw .h5ad, check each
context predicts exactly its official
perturbations. Needs --perts. [default:
verify-targets]
--check-cell-counts / --no-check-cell-counts
When prepping a raw .h5ad, require each
perturbation to have exactly the official
number of cells (400). [default: check-
cell-counts]
--contexts TEXT When prepping a raw .h5ad, the contexts it
must cover. [default: what the server is
scoring now: A,B,C in the validation phase,
D,E,F in the final phase]
--wait Block until scoring reaches a terminal
state.
--poll-interval FLOAT Seconds between status polls with --wait.
[default: 5.0]
--wait-timeout FLOAT Give up waiting after N seconds (the
submission keeps running).
--resume TEXT Resume an interrupted upload (optionally
pass its entry id).
--skip-limit-check Skip the daily-allowance pre-check. The
season and minimum-version checks still
apply.
-f, --force Overwrite an existing prep output.
--endpoint TEXT Base URL to submit to.
--profile TEXT Credential profile to use.
--json Emit machine-readable JSON instead of human-
readable text.
-h, --help Show this message and exit.vcc version
text
Usage: vcc version [OPTIONS]
Print the vcc version.
Options:
--json Emit machine-readable JSON instead of human-readable text.
-h, --help Show this message and exit.vcc whoami
text
Usage: vcc whoami [OPTIONS]
Show the authenticated account, team, and whether you can submit.
Options:
--endpoint TEXT Base URL to query (overrides the profile's stored
endpoint).
--profile TEXT Credential profile to inspect.
--json Emit machine-readable JSON instead of human-readable text.
-h, --help Show this message and exit.