Skip to content

Exit Codes & Finding Severities

BoardReadyOps CLI commands and the finding severities that drive them follow one small, stable vocabulary across the whole tool. This page is the single reference for both: what a nonzero exit status means, and what each severity level implies for gating. It is generated by hand from the CLI source below (not the reverse); if you change one, update the other.

Process exit codes

Every boardreadyops subcommand that runs the validation pipeline (run, check, fix, generate, release prepare, and their aliases) shares this convention. See src/cli/commands/run.ts for the canonical implementation (prepareRun, runCommand).

Exit code Meaning Where it comes from
0 Success. No findings at or above the --fail-on threshold. runCommand returns result.summary.failed ? 1 : 0 (src/cli/commands/run.ts).
1 The pipeline ran but reported blocking findings, or a decision-producing command (release prepare, release handoff, policy, review) failed its gate. run.ts, releasePrepareExitCode (src/release/prepare.ts:56), src/cli/commands/policy.ts, src/cli/commands/review.ts.
2 Configuration or usage error: invalid boardreadyops.yml, an unknown flag value, or an unhandled error caught at the top of the CLI before a result could be produced. prepareRun (src/cli/commands/run.ts:109-119) for invalid config; src/cli/index.ts:33-36 as the top-level catch-all for any error that escapes a command handler; also used directly by explain, fix, generate, sbom, init, vendor, and release for bad arguments.
3 Environment error: a required external dependency is missing, in practice kicad-cli when --require-kicad is set. prepareRun (src/cli/commands/run.ts:122-132); release prepare's generation stage (src/cli/commands/release.ts:117-123); generate (src/cli/commands/generate.ts:56).
4 Internal/unexpected error, scoped to the boardreadyops runner subcommands (runner once, runner serve, runner activate, enrollment commands). src/cli/commands/runner.ts (each runner subcommand catches its own errors and returns 4 rather than letting them propagate).

Notes and exceptions to the shared convention:

  • boardreadyops doctor always exits 0. It is a diagnostic report, not a gate; read its checks[].items[].severity (pass/warn/fail/info) instead of the process exit code. See src/cli/commands/doctor.ts.
  • boardreadyops plan documents its own exit codes (0/1/2) because it does not use run.ts's exit code 3; see Agent Planning Output.
  • boardreadyops release handoff and boardreadyops policy exit 1 when required outputs or policy conditions are not met, and 0 otherwise — see docs/cli.md for both commands.
  • A caught top-level error (src/cli/index.ts) always exits 2, even for commands whose own code would otherwise use a different nonzero value, because the error occurs before that command's own exit-code logic runs.

Finding severities

Findings use a fixed five-level severity scale, ranked highest to lowest. Defined in src/core/findings.ts.

Severity Rank Selectable via --fail-on
critical 4 (highest) Yes
high 3 Yes
medium 2 Yes
low 1 Yes
info 0 (lowest) No — informational findings never fail a gate

--fail-on <severity> (default: high, see Configuration) sets the minimum severity that counts toward exit code 1. Findings below the threshold, and findings marked suppressed: true, are still reported but never change the exit code (shouldFail, src/core/findings.ts). --fail-on never disables gating entirely — the command always exits 0 regardless of findings.

See also

  • CLI — full command reference.
  • Agent Planning Output — boardreadyops plan's own exit codes.
  • Policy Engine — how policy evaluation composes with --fail-on.
  • Golden Demo — worked example of exit 1 (broken board) vs. exit 0 (fixed board).