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.

Upgrading

uv tool upgrade vcc-cli          # or: pipx upgrade vcc-cli
pip install --upgrade vcc-cli    # if you installed it with pip
vcc --version                    # shows the installed version
vcc skill install                # only if you use the agent skill: refresh it to match

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      # final phase: controls-final (see below)
unzip -o -j ~/vcc/vcc_2026_controls.zip "*gene_names.csv" "*pert_counts.csv" "*manifest.json" -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, pert_counts.csv and manifest.json (which tells prep the phase's contexts). 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 of the phase, in raw counts, with each cell tagged with its context in a context column: A, B or C in the validation phase, D, E or F in the final phase. 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 — and its own controls. They are a separate download, controls-final, available once the final phase opens. It has the same layout as controls, under its own file name, so the two bundles never overwrite each other:

vcc datasets download controls-final -d ~/vcc-final
unzip -o -j ~/vcc-final/vcc_2026_controls_final.zip "*gene_names.csv" "*pert_counts.csv" "*manifest.json" -d ~/vcc-final
vcc prep final_pred.h5ad -g ~/vcc-final/gene_names.csv --perts ~/vcc-final/pert_counts.csv -o final.vcc

vcc prep reads which contexts to check from the manifest.json in the zip, so keep it next to pert_counts.csv. If it isn't there, pass --contexts D,E,F (or A,B,C in validation). The final perturbation list is not the validation one, so a final prediction checked against the validation pert_counts.csv fails. vcc submit refuses a file prepped with 0.3.0 or newer for the other phase before anything is uploaded, and vcc whoami shows which phase is running. A .vcc made with an older vcc doesn't record its contexts, so it uploads and fails only at scoring: re-prep it with 0.3.0.

The final phase

• You need vcc 0.3.0 or newer to submit in the final phase. Older versions are refused with an upgrade message: run uv tool upgrade vcc-cli (or pipx upgrade vcc-cli).
• Scores are not shown. A final submission is confirmed once it is scored, but no score or rank is shown anywhere (CLI, email or web) until the winners are announced.
• Two final submissions per team per UTC day. Only the last final entry your team makes will be considered for prizes.
• Deadline: vcc whoami prints it in UTC. A submission created before the deadline can finish uploading for up to 30 minutes after it. vcc submit on a raw .h5ad preps it first and creates the submission only after that, so near the deadline run vcc prep ahead of time and submit the .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.

Don't submit a sample in the final phase. It becomes your team's latest final entry and replaces your real one, and it uses one of your two daily submissions.

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.

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.