Reference — CLI¶

The knovaryn CLI exposes the same pipeline as the MCP server and the REST control plane: every lifecycle command below delegates to the same Workspace application services those interfaces use, so the CLI can never advertise a step the code does not run. This page's command table is generated from the real Typer command tree (scripts/generate_cli_reference.py); CI fails if the table drifts from the installed app.

Conventions¶

Run via uv run knovaryn <command> (or python -m knovaryn.interfaces.cli).
Lifecycle and reporting commands accept --json for machine-readable output (server, mcp, verify-release, and version are the exceptions).
Commands are exit-code driven: 0 success, non-zero failure (e.g. a blocked publication gate or a failed job exits 1) so they compose in scripts/CI.
State lives under .knovaryn/ by default (SQLite + content-addressed artifacts); override with the standard KNOVARYN_* environment variables — see Configuration.
knovaryn doctor is the first thing to run after install: it reports profile, extras, config provenance, storage health, and provider wiring.

Typical lifecycle¶

$ knovaryn init                                   # create state dir, check config
$ knovaryn project create my-dataset --name "My Dataset"
$ knovaryn source add proj_… ./handbook.md --license CC-BY-4.0
$ knovaryn run --project proj_… --family factual_explanation:1.0 --target 200
$ knovaryn job status job_…
$ knovaryn review ex_… approve --note "verified against page 3"
$ knovaryn dataset validate proj_…
$ knovaryn dataset version proj_… --set 1.0.0
$ knovaryn dataset export proj_… --format openai_chat
$ knovaryn dataset publish proj_… org/dataset-name          # dry-run by default

Command reference¶

Command	Description	Options
`knovaryn backup`	—	`--out, -o`, `--json`
`knovaryn dataset export`	—	`project_id`, `--format`, `--version`, `--out`, `--json`
`knovaryn dataset publish`	—	`project_id`, `repo_id`, `--live`, `--principal`, `--json`
`knovaryn dataset validate`	—	`project_id`, `--limit`, `--json`
`knovaryn dataset version`	—	`project_id`, `--set`, `--json`
`knovaryn demo`	—	`--out, -o`, `--examples`, `--json`
`knovaryn doctor`	—	`--json`
`knovaryn init`	—	`--json`
`knovaryn job list`	—	`--project`, `--limit`, `--json`
`knovaryn job status`	—	`job_id`, `--json`
`knovaryn mcp`	—	`--transport`, `--host`, `--port, -p`, `--database-url`
`knovaryn project create`	—	`slug`, `--name`, `--description`, `--json`
`knovaryn project list`	—	`--limit`, `--json`
`knovaryn repair`	—	`--json`
`knovaryn restore`	—	`--from, -f`, `--json`
`knovaryn review`	—	`example_id`, `decision`, `--note`, `--reviewer`, `--revision`, `--json`
`knovaryn run`	—	`--project, -p`, `--family`, `--target`, `--budget-usd`, `--profile`, `--json`
`knovaryn server`	—	`--host`, `--port, -p`, `--reload`
`knovaryn source add`	—	`project_id`, `path`, `--license`, `--privacy`, `--group`, `--json`
`knovaryn source list`	—	`project_id`, `--limit`, `--json`
`knovaryn verify-release`	—	`path`
`knovaryn version`	—	—
`knovaryn worker`	—	`--id`, `--poll`, `--lease`, `--max-attempts`, `--once`, `--database-url`, `--json`

Notes¶

demo runs fully offline on the fake provider — no credentials, no network.
worker claims leased jobs from the shared queue; multiple workers are safe against Postgres (see deployment profiles).
verify-release checks a release bundle's detached checksum and per-file manifest without trusting the archive's self-report.
Job durability (checkpoint/resume) applies to the worker path; the local run command drives one queued job in-process as a single worker.