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. |