Metadata-Version: 2.5
Name: vcc-cli
Version: 0.2.2
Summary: Command-line tool for submitting to the Virtual Cell Challenge (VCC).
Project-URL: Homepage, https://virtualcellchallenge.org
Author: Arc Institute
License-Expression: MIT
License-File: LICENSE
Keywords: arc-institute,perturbation,single-cell,vcc,virtual-cell-challenge
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: anndata>=0.10
Requires-Dist: click>=8.1
Requires-Dist: google-crc32c>=1.5
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=24
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: zstandard>=0.22
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# vcc — Virtual Cell Challenge CLI

Download Challenge data, validate and package your predictions, and submit them to the
[Virtual Cell Challenge](https://virtualcellchallenge.org) 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.

```bash
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](https://vcc-cli-wiki.virtualcellchallenge.org/)**
— 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](https://virtualcellchallenge.org/app/credentials) —
keys are shown once, and generating a new one revokes the old (one active key per account).

## Install

With [uv](https://docs.astral.sh/uv/) (recommended):

```bash
uv tool install vcc-cli
vcc --version
```

Or with pipx:

```bash
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

```bash
# 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)](https://vcc-cli-wiki.virtualcellchallenge.org/#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:

```bash
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

```bash
# 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

```bash
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](https://discord.com/invite/f2aWGPXwej).

## License

MIT. Copyright (c) 2026 Arc Research Institute.
