Exit codes

Normal rcf command outcomes use exit codes 0 through 5, but individual commands use subsets and some meanings are command-specific. Foreground rcf audit view returns 130 on SIGINT. CI steps and scripts should branch on the contract for the command they invoke. In particular, rcf verify run uses 5 when its severity gate trips or its verdict is NOT-DEPLOYED, BLOCKED or LAUNCH-FAILURE.

0: success

The verb did its job. Note that for the audit and validate verbs, "success" describes the run, not necessarily a clean bill of health in every mode: a clean rcf define validate exits 0, and so does a plain rcf audit coverage that reports gaps, because reporting is its job. It is --strict that turns a gap into a refusal.

1: unexpected failure

The crash class: an unexpected input/output failure or an error the verb did not anticipate, such as a filesystem that refuses a write. Handled read failures use command-specific codes: an unreadable --from-file exits 2, while an unreadable verify chain exits 3. rcf feedback also uses 1 by design, and rcf feedback --help lists each case: another rcf feedback command still held the project's feedback store when the wait ran out, a linked worktree's held queue could not move into the main checkout, submit filed an issue it could not record in time, or another command took the store over from this one. In each case stderr names what happened and nothing is lost. Outside those cases, if you meet a 1 reproducibly, that is a bug report worth filing.

2: usage

The command line itself is wrong: a misspelled verb, a missing argument, a flag the verb does not take. Also returned when a verb cannot run where it was invoked, such as a tree verb outside an initialised project, or when rcf init finds an existing config file it cannot parse and refuses to modify it. rcf verify run --hand against a loopback --url exits 2 without --engine and --served-sha, and either flag on a packed-package target exits 2. rcf verify run --out takes a file path: naming a directory exits 2 before any request reaches the target, and so does --out alongside --hand, where the report path is the verb's. rcf feedback add exits 2 when the .gitignore that should cover .rcf/feedback/ does not; in a linked git worktree that is the main checkout's.

3: command-specific failure

Code 3 is command-specific. It covers validation, chain-load, soundness, capability, conflict or availability failures. For tree-validation paths, it means structural failure in the documents: a schema violation, a reference that resolves to nothing, or a required piece of the chain that is absent. rcf define validate exits 3 and lists the issues whenever the tree is broken. The same code backs refusals that are really soundness findings, such as marking a work item complete while an in-scope acceptance criterion has no source file recorded against it. It also backs the capability-refusal on rcf define blueprint add: a blueprint that declares requiresAppliedCapabilities refuses at add time when its effective capability set contains none of the named capabilities. That set combines capabilities from applied blueprints with capabilities confirmed through custom-auth providesCapability elicitation, so a custom-auth answer can satisfy the gate without an applied shelf blueprint. The refusal message names the security-auth-* prefix so an operator knows which blueprint to add first. The named allowSkipFlag on the blueprint (--allow-no-auth-yet for both the shipped admin console and the shipped account-settings shell) records an acknowledgement on the sidecar and lets the add proceed with the capability-gated surfaces disabled. rcf define create <kind> --id and rcf define ledger <name> add --id exit 3 when the id already exists with different content, naming the differing fields; an identical replay exits 0 and writes nothing. Blueprint conflicts also exit 3, as does rcf version --check when neither the network nor a usable cache can provide an update signal.

4: refused

The tool understood the request completely and is declining it, by design. rcf build mark refuses backward transitions, such as moving a work item from inProgress back to notStarted; rcf define update <fbs-id> --set executionStatus=<status> is the deliberate correction override. The everyday mark command refuses to write verified; the finalise gate writes that status after verification, while rcf define update <fbs-id> --set executionStatus=verified is the sanctioned explicit manual override. The finalise gate itself refuses a Test-stage report it cannot trust, such as one not committed at HEAD, edited since, outside the project root or read through a symbolic link, and rcf verify run refuses a --served-sha that is not the committed HEAD. rcf audit coverage --strict refuses while any acceptance criterion in scope lacks a test whose pointer resolves. A 4 is never a malfunction: it is the referee doing its job, and the right response is to change the work, not the command.

5: verification gate tripped

rcf verify run exits 5 when its configured severity gate trips or its verdict is NOT-DEPLOYED, BLOCKED or LAUNCH-FAILURE. The command still writes its report.

The site's drift checker checks only that every exit code it extracts from installed rcf-lite has a heading here. Its extractor is limited to codes 0 through 4, and it does not validate the meanings above or detect code 5. The forward-only lifecycle behind the refusal examples is explained in the five-stage build cycle.