CLI

The curva binary is the server and a set of tools. It comes with pip install curva-ai, or in the Docker image.

Usage: curva <COMMAND>

Commands:
  serve        Run the HTTP API (POST /v1/decide, GET /health, GET /metrics)
  keys         Manage Curva API keys (stored hashed)
  project-key  Give a project its own provider key (read from stdin, encrypted with CURVA_MASTER_KEY)
  spike        Check which models return usable label probabilities
  bench        Run the labeled eval sets and print accuracy, calibration, latency and cost
  map          Answer the same questions for every state in a JSONL file (resumable)
  report       Re-print a saved bench run (and its calibration) without calling any model
  shadow       Replay logged traffic through Curva and compare with your current system (resumable)
  tune         Curva Tune: search models, modes, debias, few-shot examples and plans on a labeled set
  recipe       Ready question packs: `list`, or `show <name>` to print one as a questions object
  mcp          MCP server over stdio with a `decide` tool that forwards to a running Curva server

Options:
  -h, --help     Print help
  -V, --version  Print version

curva serve

Runs the HTTP API. Once any API key exists, every route but /health needs one.

Option	Default	Meaning
--addr <ADDR>	127.0.0.1:7777	Address to listen on
--model <MODEL>	the latest pin’s model	Model used when a request names neither a model nor a config
--cache-size <N>	1000	Decisions remembered per mode; repeats return in about 1 ms at no cost
--db <DB>	curva.db	SQLite file for decisions, feedback, calibrators, audit log and keys
--latest-config <NAME>	the newest	The pinned config curva-latest points to
--no-auth		Allow listening beyond localhost without API keys (only on a trusted private network)
--max-body-mb <MB>	16	Largest request body accepted (inline base64 images count towards it)

curva keys

Manages API keys, stored as hashes. All subcommands take --db <DB> (default curva.db).

curva keys create --name ci [--rpm 600]   # prints the key once
curva keys list
curva keys revoke <ID>

--rpm is the requests per minute allowed for the key (default 600).

curva project-key

Gives a project its own provider key, read from stdin (so it never lands in shell history) and encrypted with CURVA_MASTER_KEY. Takes --db <DB>.

printf %s "$OPENROUTER_KEY" | curva project-key set support
curva project-key remove support

curva map

Answers the same questions for every state in a JSONL file. See Batch files with curva map.

curva map [OPTIONS] --questions <QUESTIONS> --output <OUTPUT> <INPUT>

Option	Meaning
<INPUT>	One JSON state per line
-q, --questions <FILE>	JSON object of questions, as in a /v1/decide request
-o, --output <FILE>	One JSON result per line; rerunning continues after the last line written
--model <MODEL>	A model id, or a comma-separated fallback chain
--council <A,B>	Models that answer together; probabilities are blended
--cascade <A,B>	Models cheapest first; unsure questions go to the next one
--race <A,B>	Models asked at once; the first valid answer wins (one call each)
--escalate-below <P>	Cascade: confidence below which a question is escalated (default 0.8)
--mode <MODE>	auto (default), logprobs or verbal
--no-debias	Skip order debiasing (half the calls; answers keep any position bias)

curva shadow

Replays logged traffic through Curva and compares it with your current system. See Shadow mode.

curva shadow [OPTIONS] --questions <QUESTIONS> --output <OUTPUT> <INPUT>

Option	Meaning
<INPUT>	One {"state": ..., "labels": {"<question>": <answer>}} per line
-q, --questions <FILE>	JSON object of questions, as in a /v1/decide request
-o, --output <FILE>	Curva’s answers, one JSON line per input line; rerunning continues after the last one
--compare <FIELD>	Field of each input line holding the current system’s answers (default labels)
--examples <N>	Disagreements listed per question (default 5)

Plus the same model options as map.

curva tune

Searches models, modes, debiasing, few-shot examples and multi-model plans on a labeled set, and writes the best setup. See Curva Tune.

curva tune [OPTIONS] <SET>

Option	Meaning
<SET>	Name of the set (<dir>/<set>.json)
--dir <DIR>	Directory of eval sets (default evals)
--models <A,B>	Models to try; 2+ also tries a council and cascades
--per-set <N>	Rows used, spread evenly (default: all rows)
--out <FILE>	Where the winning request config is written (default tuned.json)
--yes	Allow more than 200 model calls

curva recipe

Ready question packs. See Recipes.

curva recipe list
curva recipe show support-triage > questions.json

curva mcp

An MCP server over stdio with a decide tool that forwards to a running Curva server. See MCP server.

Option	Meaning
--url <URL>	The Curva server (default http://127.0.0.1:7777)
--api-key <KEY>	Curva API key (default: CURVA_API_KEY)

curva bench

Runs labeled eval sets and prints accuracy, calibration, latency and cost. See Benchmarks.

curva bench [OPTIONS] [SETS]...

Takes the same model options as map (--model, --council, --cascade, --race, --escalate-below, --mode, --no-debias), plus:

Option	Meaning
[SETS]...	Sets to run (default: all)
--per-set <N>	Rows per set (default: all rows)
--dir <DIR>	Directory of eval sets (default evals)
--save <FILE>	Append every scored row to this JSONL file, to re-analyse later with curva report

curva report

Re-prints a saved bench run, including its calibration, without calling any model.

curva report [--dir <DIR>] <FILE>

curva spike

Checks which models return usable label probabilities (log-probabilities over the label tokens).

curva spike [MODELS]...

Without arguments it tests the free models that list logprobs support.