Commands
Every zurdo command, its flags, an example, and the exit codes.
zurdo v1.36.0
Every command of zurdo v1.36.0, one entry each. zurdo <command> --help prints the full detail, and a bare zurdo <prd> is shorthand for zurdo run <prd>.
Common flags
Most commands accept these. They go before or after the subcommand.
| Flag | Effect |
|---|---|
--no-prompt | Never prompt; the resume prompt defaults to Resume (CI-safe) |
--no-color | Strip ANSI colour from stdout |
-v / -q | Diagnostic log at debug / warn |
--log-level <level> | error, warn, info, debug or trace |
--log-format <fmt> | text (default) or json, one object per line on stderr |
--log-file <path> | Also write the diagnostic log to this file |
--repo-root <path> uses that repo root instead of the nearest .git ancestor. init, doctor, reason, state, lumen, pyxis, vela, mcp, skills, self-update, completions and help don't take it.
Before a run
zurdo init
Writes a commented .zurdo/config.toml and installs the bundled skills for the executor.
It detects the languages at the repository root (Cargo.toml, go.mod, package.json, a Python project file, pom.xml, build.gradle(.kts)) and writes one [[coverage.source]] per language. When it finds none, it writes [coverage] with enabled = false and a commented example to start from.
| Flag | Effect |
|---|---|
--force | Overwrite an existing config (asks first on a terminal) |
--sync | Report how far the config has drifted from the current template; when the config has no [coverage] table, print the generated coverage table so you can append it by hand |
--check-models | Probe every effort-map model afterwards; informational, always exits 0 |
--quiet | Drop the one-line summary |
zurdo init
zurdo init --sync # after an upgrade
zurdo doctor
Reports everything that would stop a run, without a PRD, a lock, or any write.
| Flag | Effect |
|---|---|
--skip-probes | Spawn no provider process: no model probes, no vocabulary canary |
--format text|json | Grouped sections (default) or one JSON document |
Blocking findings exit 4; warnings leave the exit code alone. zurdo check-models is deprecated: doctor probes the same rows.
…
providers:
ok executor → anthropic: cli `claude` found on PATH
ok analyzer → anthropic: cli `claude` found on PATH
models:
ok model probes: skipped (--skip-probes) — no provider process spawned
git:
warn .zurdo/ gitignored: not listed in .gitignore
…
lumen:
ok index generation: generation 25 (40 records)
warn vela daemon: not running
doctor: no blocking findings, 2 warningszurdo validate
Checks a PRD's grammar, dependency graph and hint syntax, with no model and no run.
| Flag | Effect |
|---|---|
--strict | Promote nine of the twenty-two warn-lint families to errors (exit 2) |
--format text|json | Prose (default) or a versioned JSON envelope; same exit code |
--authoring-state | Check the PRD as of the commit that added it, against that commit's parent |
--at <rev> | Check against an explicit revision instead |
zurdo validate prd.md --strict
zurdo validate prd.md --authoring-state
zurdo analyze
Runs the static lints plus, with [roles.analyzer], an LLM critique, and executes nothing.
| Flag | Effect |
|---|---|
--static-only | Deterministic checks only: no tokens, no analyzer needed |
--fix | Loop the analyzer over the PRD, writing <prd>.proposed.md |
--max-iterations <n> | Cap the --fix loop |
--no-progress | Print only the final verdict |
zurdo analyze prd.md --static-only
zurdo analyze prd.md --fix --max-iterations 5
zurdo scaffold
Drafts a first-cut PRD from a design document through the analyzer role.
| Flag | Effect |
|---|---|
--out <path> | Where to write the PRD; it and its .trail.md must not exist (required) |
--section <heading> | Draft from one heading's section, matched by exact text |
--max-iterations <n> | Drafting attempts before exit 6 (default 3) |
--no-pre-run | Skip the check that each pre-authored test fails on an assertion first |
The draft opens with the unreviewed-scaffold marker. Review it with the zurdo-prd-author skill before zurdo run; see Your first PRD.
zurdo scaffold docs/design/cache.md --out docs/prds/prd-eviction.md --section "Phase 2 — eviction"
zurdo reason
Inspects or clears the lesson library, and previews which lessons match a PRD's tasks.
| Subcommand | Effect |
|---|---|
status | Lesson count, plus diagnosis blocks per state directory; needs [reason] enabled |
match <prd> | Lessons each task would match; read-only, ungated |
clear [--yes] | Delete the lessons/ directory |
zurdo reason match prd.md
Running
zurdo run
Drives each task through the agent, then checks every criterion itself, in dependency order. Once a task's criteria pass, the coverage gate measures the lines it changed.
zurdo run refuses to start on a config with no [coverage] table (exit 2); zurdo init --sync prints the table generated for your repository. Every other command still accepts such a config.
| Flag | Effect |
|---|---|
--resume | Continue existing state without asking |
--reset | Archive existing state and start fresh |
--max-iterations <n> | Override max_total_iterations; 0 is unlimited |
--skip-model-check | Skip the pre-run model probe |
--no-progress | Print only the final status line |
--quiet-agent | Hide the live agent output (it is still captured) |
--raw-agent | Show the agent's raw output instead of step summaries |
zurdo run prd.md
zurdo run prd.md --no-prompt --resume
zurdo heal
Re-aims a prior run's failing [grep:] and [no-grep:] hints, verifying each proposal before applying it.
| Flag | Effect |
|---|---|
--no-prompt | Write verified heals to <prd>.proposed.md instead of applying them |
It reads prd.json and never runs the executor. It needs [roles.analyzer] and a prior run (exit 3 otherwise).
zurdo heal prd.md
After a run
zurdo review
Shows a run's evidence and signs off [manual] criteria, in a terminal UI or headlessly.
| Flag | Effect |
|---|---|
--no-prompt | Print the unsigned [manual] criteria as JSON; writes nothing, takes no lock |
--sign-off <task>:<n> | Sign criterion n (1-based) of a task, headlessly |
--by <name> | Who signs; required with --sign-off |
--note <text> | Optional note on the sign-off |
Sign-offs append to review-log.jsonl and can't be undone. The evidence view shows a task's Coverage: line (status, percent against threshold, reason, changed build files). See Signing off manual checks.
zurdo review prd.md --no-prompt
zurdo review prd.md --sign-off task-3:1 --by alice --note "checked on staging"
zurdo report
Writes a curated report of a run's state under reports/ and prints it.
| Flag | Effect |
|---|---|
--format json|md | JSON (default, for tools) or Markdown |
Each task section also carries the run's own signals: a flaky: <hint> line for a criterion that got two verdicts on one tree, a | witness | <n> witnessed, <m> unwitnessed | row for a passed task, and a line for each criterion that passed at least ten times faster than its failing pre-flight (duration_anomalies, for a pre-flight of 2000 ms or more). The summary table counts the tasks that passed at pre-flight.
A task the coverage gate reached gets a | coverage | row in Markdown (status, percent against threshold, reason, uncovered lines, build files); the JSON carries its coverage block as recorded.
zurdo report prd.md --format md
zurdo verify
Re-checks every passed task's criteria against the current tree, without running the agent.
| Flag | Effect |
|---|---|
--criteria <file> | Checks one task's criteria lines from a JSON file ({"task": …, "criteria": […]}) against the current directory, with no PRD and no run state. This is the clean room's entry point. Exits 0 when every criterion passes, 5 when one fails, and 2 on a [manual] line or a malformed file |
--format text|json | Prose (default) or a JSON envelope |
zurdo verify prd.md
zurdo verify --criteria criteria.json
zurdo state
Lists the state directories at the repo root, or prints where one PRD's lives.
| Subcommand | Effect |
|---|---|
list | Every .zurdo/<slug>/ with its PRD, last run and status |
where <prd> | The absolute path a PRD resolves to, even before a run |
$ zurdo state list
slug prd_path last_run status
prd-01-public-site-1c06 docs/site-launch/prds/prd-01-public-site.md 2026-10-11T20:44:47Z clean
Indexes and agents
zurdo lumen
Manages Lumen, the structural index behind [symbol:], [references:] and [callers:].
| Subcommand | Effect |
|---|---|
status | Record counts and Vela freshness |
rebuild | Rebuild the index and publish a new generation |
clear [--yes] | Delete .zurdo/lumen/ |
query | One of --name, --outline <file>, --callers, --references; --limit (default 20) |
Every subcommand needs lumen.enabled = true. See Structural verification.
zurdo lumen query --name Config::load
zurdo lumen query --outline src/config.rs --limit 0
zurdo pyxis
Ranks source symbols and Markdown sections against a free-text question.
| Subcommand | Effect |
|---|---|
status | Unit counts and whether the embedding model is installed |
query <text> | One row per hit; --limit (default 20) |
install | Install the pinned embedding model; --from <dir> copies it offline |
Without the model, ranking is lexical; with it, hybrid. status and query need [pyxis] and [lumen] enabled.
zurdo pyxis query "the code that loads the config" --limit 5
zurdo vela
Runs the optional watcher that keeps the Lumen index warm between runs.
| Subcommand | Effect |
|---|---|
start | Spawn a detached watcher and wait until it's ready |
stop | Ask it to exit; 0 even when none runs |
status | PID, version and root; nonzero when none runs |
serve | Run it in the foreground |
zurdo vela start
zurdo mcp
Serves Lumen and run state to an MCP client over stdio, one session per launch.
| Subcommand | Effect |
|---|---|
serve | Read JSON-RPC from stdin until end of file; no flags of its own |
Your MCP client launches it; you don't type it. It needs lumen.enabled = true. Tools are on Agent access (MCP).
{ "mcpServers": { "zurdo": { "command": "zurdo", "args": ["mcp", "serve"] } } }
The binary
zurdo skills
Lists the eight bundled skills, or installs them into a provider's discovery path.
| Flag | Effect |
|---|---|
list | Every bundled skill, and whether it's installed |
install <name> | Install one skill for the active executor |
--all | Install every bundled skill |
--provider <p> | Install for this provider instead; repeatable |
--all-providers | Install for every [providers.*] block |
zurdo skills install --all --all-providers
zurdo self-update
Replaces the running binary with the latest release, or a pinned one, after verifying its signature.
| Flag | Effect |
|---|---|
--check | Print the current and resolved versions; download nothing |
--to <version> | Resolve this release instead of the latest (a leading v is optional) |
It refuses, exit 1, when Homebrew manages the binary; update it through Homebrew instead. Releases older than v1.28.0 are unsigned, so it refuses them too.
zurdo self-update --check
zurdo self-update --to 1.36.0
zurdo completions
Prints a shell completion script for bash, zsh, fish, elvish or powershell.
| Argument | Effect |
|---|---|
<shell> | The shell to generate for |
eval "$(zurdo completions zsh)"
zurdo help
Prints a command's help, or an offline guide page.
| Topic | Covers |
|---|---|
prd-grammar | The PRD format |
hints | Every hint type |
config | .zurdo/config.toml |
state-dir | The .zurdo/<slug>/ layout |
exit-codes | What each exit status means |
workflow | The PRD loop |
zurdo help exit-codes
Exit codes
| Code | Meaning |
|---|---|
0 | Success: every task passed, or a read-only command finished |
1 | Unhandled error; also a refused self-update |
2 | PRD or config error: grammar, validate, analyze findings, a scaffold refusal, a missing or invalid [coverage] table, a coverage report that is missing, unreadable or names no file in the tree |
3 | Pre-flight failure: missing provider CLI, a held lock, no prior run, no analyzer, a failing [[coverage.source]] probe |
4 | State needs --reset, no run state yet, or a failed model probe |
5 | A task finished failed or blocked-by-dependency |
6 | Iteration budget exhausted (run, analyze --fix, scaffold) |
7 | analyze --fix thrash: warnings not decreasing over 3 iterations |
8 | analyze --fix got an unparseable model reply |
9 | Every task passed and the completion gate failed |