vcc — Virtual Cell Challenge CLI

Download Challenge data, validate and package your predictions, and submit them to the Virtual Cell Challenge from your terminal — no browser upload required. Works on macOS, Linux and Windows, including headless clusters and remote machines where a browser upload isn't practical.

Validation runs locally, so format problems surface in seconds instead of after a multi-gigabyte upload.

uv tool install vcc-cli      # the installed command is `vcc`

The distribution is named vcc-cli; the command it installs is vcc.

📖 Full documentation — the VCC CLI guide — the complete walkthrough, submission requirements, command reference and troubleshooting. This page is the short version.

Requirements

Python 3.11 or newer, and a Challenge account. Generate an API key at virtualcellchallenge.org/app/credentials — keys are shown once, and generating a new one revokes the old (one active key per account).

Install

With uv (recommended):

uv tool install vcc-cli
vcc --version

Or with pipx:

pipx install vcc-cli

If your shell reports command not found: vcc, it installed but isn't on your PATH: run uv tool update-shell, open a new terminal and retry — don't reinstall. Upgrade later with uv tool upgrade vcc-cli.

Quickstart

# 1. authenticate — pipe the key in, so it never reaches your shell history
echo "$VCC_TOKEN" | vcc login --token-stdin
vcc whoami                     # account, team, and whether you can submit yet

# 2. get the control data, and unpack it
vcc datasets list              # shows sizes before you download
vcc datasets download controls -d ~/vcc
unzip -o -j ~/vcc/vcc_2026_controls.zip "*gene_names.csv" "*pert_counts.csv" -d ~/vcc

# 3. package your prediction
vcc prep ~/path/to/prediction.h5ad \
  -g ~/vcc/gene_names.csv \
  --perts ~/vcc/pert_counts.csv \
  -o ~/vcc/prediction.vcc

# 4. submit, and follow it through scoring
vcc submit ~/vcc/prediction.vcc -m "my model v3" --wait

# 5. or check back later
vcc status ENTRY_ID

vcc datasets download fetches the bundle as a single .zip and does not unpack it, so the unzip step is required before prep can find gene_names.csv and pert_counts.csv. The files sit at the root of the archive.

Prefer an interactive prompt to piping? Plain vcc login prompts for the key with the input hidden. --token-stdin reads one line from standard input and does not prompt.

Downloads and uploads both resume after an interruption and are checksum-verified; re-run the same command to continue. vcc submit --resume continues an interrupted upload rather than creating a second entry.

Interrupted the upload because it was the wrong file? Your team may have only one submission in progress at a time, so run vcc cancel to abandon it and free the slot for a fresh vcc submit. An abandoned or failed submission does not count against your daily limit — only a successfully scored one does — so cancelling a wrong file costs you nothing.

Every command accepts --json for machine-readable output.

Submission format

You submit one .vcc file covering all three cell contexts, in raw counts, with each cell tagged A, B or C in a context column. vcc prep checks the gene set, contexts, perturbation labels, per-perturbation cell counts, raw counts, the per-cell count cap and the no-control-cells rule before packaging, so a format problem surfaces locally rather than after an upload. Add --dry-run to validate without writing a file.

📖 The rules in full: Submission requirements (2026). Read it before your first submission.

Two things that cost people real submissions:

⚠️ Never reorder or reassign the context labels. The label decides which held-out dataset a cell is scored against, so swapping two degrades every metric toward chance and looks like a weak model rather than a bug. vcc prep catches a missing or unknown context, but nothing can detect that A and B were swapped.

⚠️ The final phase uses different labels — D, E, F. --contexts defaults to A,B,C and rejects labels it wasn't told about, so a final submission needs the flag:

vcc prep final_pred.h5ad -g gene_names.csv --perts pert_counts.csv --contexts D,E,F -o final.vcc

Testing the pipeline without a model

# needs the same two files as `prep`, so unzip the bundle first (step 2 above)
vcc sample -g ~/vcc/gene_names.csv -p ~/vcc/pert_counts.csv -o sample.vcc
vcc submit sample.vcc -m "pipeline test"

vcc sample builds a random but structurally valid submission — every perturbation with its official 400 cells — so it passes validation and the scorer accepts it. It scores poorly by design.

Authentication

Tokens are created in the web app, never by the CLI: there is deliberately no vcc token create. The CLI only consumes a token.

Situation	Recommended
Laptop with a working OS keychain	vcc login — hidden prompt, stored in the keychain
Scripted or non-interactive	echo "$VCC_TOKEN" | vcc login --token-stdin
Headless Linux, HPC node, container, CI	export VCC_TOKEN=… — never touches disk
Headless but you want persistence	echo "$VCC_TOKEN" | vcc login --token-stdin --store-plaintext (a 0600 file, warned about)

vcc login refuses to silently write your token in plaintext. If no secure OS keychain is available it says so and requires --store-plaintext to opt in — this is intentional, not a bug. A token supplied through VCC_TOKEN takes precedence and is never persisted.

Piping into --token-stdin is the preferred form for anything scripted: the token never appears in argv or in the process list, and reading it from a variable or a file keeps it out of your shell history. --token-stdin reads a single line from standard input — it does not prompt, so run it with a pipe or a redirect rather than on its own.

Use it from a coding agent

vcc skill install

This copies a bundled skill into your agent's skills directory (Claude Code, Codex, Gemini), so you can ask the agent to drive the workflow — "download the VCC control data and make a submission." Restart the agent session afterwards, and re-run vcc skill install after each CLI upgrade so the skill matches the installed version.

Help

Run vcc --help, or vcc COMMAND --help for any command. Questions and problems: the Virtual Cell Challenge Discord.

License

MIT. Copyright (c) 2026 Arc Research Institute.