On this page

← CLI

Reference

CLI cheatsheet

Commands are grouped as rcf help groups them, with one line per command and the CLI's own descriptions. Use rcf help <group> <verb> for flags.

Every verb on this page ships in the installed CLI (rcf-lite at the version shown by rcf version). This page and the tree behind it are checked at build time against rcf help for that installed version, so a slug named here is one you can run. If a verb ever lands on the roadmap before it ships, it will carry a To-do tag on its row until the release lists it.

core

Command Does
rcf init Scaffold a new RCF project in this directory.
rcf doctor Diagnose and repair init-hygiene drift.
rcf guidance [topic] Print a method document from the installed pack.
rcf mcp Serve the project over MCP (local stdio).
rcf version [--check] Print the installed version; --check compares it against the release feed.
rcf feedback <verb> Log a blueprint or core finding locally, then ask once, preview, submit or bundle it. Verbs: add, list, status, defer, discard, preview, submit, opt-out, opt-in, hook. In a linked git worktree the store is the main checkout's .rcf/feedback/. Exit 1 is a designed outcome: the store was still busy when the wait ran out, a worktree's held queue could not move, or submit filed an issue it could not record in time. See How the agent files feedback.
rcf help [group] [verb] Print help for a group or a verb.
rcf --version Print the package version and exit.

discover

Command Does
rcf discover intake Classify supplied artefacts.
rcf discover preflight Elicit third-party service dependencies.
rcf discover req-classify <req-id> Classify one or every REQ by shape.
rcf discover req-baseline <verb> Sweep and record baseline ACs per REQ.
rcf discover ui-classify <fbs-id> Classify one FBS as UI-bearing or not.
rcf discover ui-baseline <verb> Rule and record the project's UI defaults.
rcf discover journey <verb> Author and inspect the journey record (rcf/discovery/journey.json). Verbs: add --from <path>, import --from <path>, check, `declare --ui none

define

Command Does
rcf define create <kind> Create a new document. --id <id> overrides the auto-assigned id and is idempotent by id: replaying an existing id with identical content prints <id>: unchanged and exits 0; different content refuses with exit 3 and names the differing fields (use rcf define update to patch).
rcf define read <id> Print a document's body.
rcf define update <id> Patch fields on an existing document. rcf define update <ac-id> --set verification=<value> sets an acceptance criterion's verification flag, external or testOnly; any other value exits 3 and leaves the story unchanged. --ac <ac-id> --probe <json> (or --probe-file <path>) sets an acceptance criterion's probe for deterministic verify; a probe with no assertion is refused with exit 3.
rcf define delete <id> Delete a document.
rcf define link <us-id> Link a US to a TAC.
rcf define unlink <us-id> Unlink a US from a TAC.
rcf define validate Walk the tree and report schema and reference issues. Exits 3 on any finding, including these four kinds: an interface kind outside the closed vocabulary, a bracketed AC class prefix outside the five known classes, a tacIds naming a non-TAC, and an unresolving ownerRef or object-form deliveredBy. It also refuses a live criterion that is new or amended since the base and carries no verification flag; the base is --base <ref>, else the merge-base of HEAD with origin/main, and with neither it prints one warning and skips that rule. --report verification prints the worklist of every live unflagged criterion and changes no exit code. Flags: --base <ref> (exit 2 when it does not resolve), --report verification, --quiet, --json, --no-code.
rcf define design <fbs-id> <verb> Design substage for a UI-bearing FBS.
rcf define blueprint <verb> Compose blueprints onto the project. add supports --answer <id>=<value> (repeatable), --answers <file>, and --allow-no-auth-yet for the capability-refusal override.
rcf define standards <verb> Register standards packs against the project.
rcf define ledger <name> <verb> Read and write the four DEFINE sidecar ledgers under rcf/define/ (brief, decisions, concerns, probes); verbs are add, update, resolve, list. add --id <n> is idempotent by id: an identical replay prints unchanged and exits 0; different content at that id exits 3 naming the differing fields.
rcf define readiness Compute the DEFINE stage-gate readiness view (D1 to D8, two levels, per-persona blockers). Flags: --level intent|build, --persona productOwner|engineer, --check <stage>|all (exits 4 on a failing D1, D2, D4, D7 or D8 and on an unacknowledged D3 or D5 bite at the current hash), --litmus <n> (requires n distinct litmus readings at the current litmus hash), --json.
rcf define questions Print the persona question set for the intent-complete loop: one plain question per failing product-owner item, each carrying its exact write-back. Flags: --persona, --stage, --limit, --json.
rcf define freeze Close a change: run readiness, refuse on any failing stage, and write rcf/define/freeze.json. Flags: --ack <gate> with --reason <text> (repeatable; only define.shapes, define.crosscut and define.consistency are ackable), --litmus <n>, --litmus-attested <D3,D6>, --note <text>, --status, --json.

build

Command Does
rcf build queue Show the FBS build queue.
rcf build bundle <fbs-id> Spec bundle for one FBS (or --next). Every bundle needs --base-suite <file>, a green base-suite record for the base (the merge-base of HEAD with the trunk); it refuses with exit 4 when the record is missing, made at another commit or red, and no flag gets past that. --acs <AC id>[,...] on an FBS at complete or verified bundles an amend round over those criteria only. Flags: --next refuses with exit 4 on an unfrozen tree or an all-impacted delta; --override "<reason>" writes freeze.override { reason, by, at } and proceeds past the freeze gate only; --format md|json, --out <path>, --strict. --allow-unverified exits 2, and rcf/define/backstop.json is ignored with a warning.
rcf build base-suite --out <file> Record the RCF suite run on the base head: runs the suite (--command "<suite>", default the suiteCommand of rcf/test-strength.json) at a clean committed HEAD and writes the record every bundle checks. --out inside rcf/ exits 2; a dirty working tree exits 4.
rcf build mark <fbs-id> <status> Record a lifecycle transition. The ladder caps at inProgress: complete (written only by rcf build finalise), verified (written only by a release Verify) and backward marks are refused with exit 4.
rcf build finalise <fbs-id> Light Finalise: write complete from the round's recorded verdicts. Runs on the PR branch before the merge: checks the REVIEW verdict (MERGE, adequacy PASS) at the reviewed head, the TEST PASS at that head, a test-strength record for that head covering every touched criterion (a fail or blocked result prints a line and is not refused), a Code Node on every touched criterion and the separation audit over the range, then writes complete; the merge carries it. It never reads a verify report and never writes verified. Flags: --ci-run <ref> (required; exit 4 without it), --merge-suite <file> (a green base-suite record at the newest FINALISE: merge from main after the reviewed head), --quiet. --report, --max-report-age, --mode, --url, --allow-pre-merge, --provision-mode, --ship-without-eval and --ship-without-verified exit 2.
rcf build review <fbs-id> Stage-3-to-Stage-4 audit.
rcf build fbs <fbs-id> <verb> FBS-level operations.
rcf build test-suite <ts-id> <verb> Test-suite operations.
rcf build verdict review | test Record a round's REVIEW or TEST verdict as a file under rcf/verdicts/<h12>/ for the stage's own commit to add. review --fbs <id> --acs <AC ids> --code MERGE|FINDINGS --adequacy PASS|FINDINGS [--finding "<spec|build|test>:<AC id|->:<text>"] names the committed HEAD; test --fbs <id> --result PASS|FAIL --tap <file> --runtime "<text>" [--reason <text>] reads the TAP of the suite the verifier ran and never runs it. Neither commits; a dirty tree or a second verdict for the same head exits 4.

verify

Command Does
rcf verify run Run adversarial verification; emit a report. Release mode, --release <label> --since <ref> with exactly one of --url, --artefact <tgz> or --package <dir>, is the release Verify: it runs the bound e2e tests of the live external criteria of the specs changed since <ref>, plus the smoke suites rcf/release-verify.json names, against the URL or a package installed cold, prints a line per criterion (a fail line followed by reason: <reason>), and exits 0 PASS, 4 FAIL, 2 usage, 1 install failure; --record writes rcf/verify-reports/releases/<label>.json and verified on each spec whose external criteria all passed, and without it nothing is written in the project. --mode and --offline exit 2 in release mode. Other flags: --repo <path-or-ref>, --profile deployed|ci|local-dev, --url <app-url>, --out <file> (the report's file path; a directory exits 2 before any request reaches the target, and --out with --hand exits 2), --fbs <id> (repeatable; a comma list is accepted; narrows per-AC verdicts, provisioning, the adversarial brief and the deterministic skip ledger to the acceptance criteria bound to the named FBS items), --hand <hand> (writes the Test-stage report to rcf/verify-reports/<fbs-id>/<head12>.json; needs exactly one --fbs), --verifier-id <id>, --engine <name> and --served-sha <sha> (required with --hand and a loopback --url, exit 2 without them; recorded as target.engine, target.port and target.servedSha; a served sha that is not the committed HEAD exits 4; exit 2 on a non-URL target), --replace <reason>, --artefact <tgz> and --package <dir> (package target mode: run the bound test files against the installed tarball), --offline (package target mode only), --mode agentScreenshotCritique|deterministic (agent is the parent-session default, deterministic is the model-free in-process mode a dispatched worker can run), --parity-env <env>, --severity-gate PASS|COSMETIC|DEGRADED|BROKEN, --provision <path>, --provision-mode run|skip, --persona <name>.
rcf verify report <path> Re-render a prior report artifact.
rcf verify provision Stand up prerequisite accounts and sandboxes.
rcf verify cleanup Tear down provisioned artefacts.
rcf verify mcp Serve verify over MCP (local stdio).
rcf verify browser <fbs-id> Stage 5 browser-verification gate; runs any Playwright probe pack a blueprint ships. Flags: --probe-pack <name>, --no-browser, --no-boot.

audit

Command Does
rcf audit view Live HTML tree render (long-running server).
rcf audit coverage [scope-id] Structural coverage over the REQ chain. A criterion carrying supersededBy reads retired (<successor>) and counts toward no requirement; a broken supersession fails --strict with exit 4. Each criterion row shows its flag, end and now, and a spec table follows, as information that never changes the exit code.
rcf audit eval coverage [scope-id] EVAL coverage over nonDeterministic ACs. A retired criterion reads retired, never missing.
rcf audit trace <id> Walk the graph forward, back, or both from a node.
rcf audit impact <id> Change-impact fan-out from a node.
rcf audit separation Stage-prefix separation and round order over pull request commits: each commit, merges included, is judged by its DEFINE:, BUILD:, REVIEW:, TEST: or FINALISE: prefix against the file classes that stage owns, and the range on round order from the verdict files the REVIEW: and TEST: commits add. A commit with no prefix or a malformed one fails; a Hand: trailer is optional and only checked against the prefix, and Hand: mixed fails. Flags: --base <ref>, --head <ref>, --json (SeparationRow v2). --require-hand is retired and exits 2. Exits 4 on a violation; a shallow clone is refused.
rcf audit test-strength Structural check and mutation proof of the touched criteria's bound tests, as a report. Scope: --acs <ids>, else the newest REVIEW verdict's touched criteria, else --fbs <ids>. Each bound test runs through the runner rcf/test-strength.json declares for it (runners: nodeTest, vitest or playwright, optionally "cwd": "project") at its package directory, in a working copy of HEAD; sources are JavaScript, TypeScript, JSX, Vue and, for symbol-level Code Nodes, Python through the host's python3 3.9 or later. Flags: --record (writes rcf/verdicts/<H12>/test-strength.json for the reviewed head), --json, --jobs <n>, --mutant-timeout <seconds>, --max-mutants <n>. Exits 0 every criterion passes, 4 a criterion fails, 5 blocked, 2 usage or a whole-run failure, 3 the chain does not load, 130 and 143 on SIGINT and SIGTERM.