CLI reference

Install with pip install linebreak-gate (or uv tool install linebreak-gate). Exit codes everywhere: 0 pass, 1 blocking findings, 2 tool/config error: fail closed.

scan

Runs the dependency CVE scan (and the AI code review when enabled) and gates on the result. Records the full evidence under .linebreak/audit/.

linebreak-gate scan [--path .] [--fail-on critical|high|medium|low] [--format summary|json]

--fail-on overrides the floor in .linebreak/gate.yml for this run; the default floor is critical.

report

Human-readable summary of the recorded scan, or --format json for a machine-readable export you can attach to an audit package. If no scan is recorded, it says so and reminds you that a missing scan keeps the gate closed.

linebreak-gate report [--path .] [--format summary|json]

override

Records a human-approved exception for one exact finding or criterion: never a blanket waiver. Both --reason and --approver are required; the CLI refuses otherwise. The override lands in the git-committed audit file.

linebreak-gate override \
  --finding "dep:lodash@4.17.20:CVE-2024-0001" \
  --reason "not exploitable here; upstream fix tracked in #123" \
  --approver "sec-lead@example.com"

# or, for an acceptance criterion:
linebreak-gate override --criterion <id> --reason "..." --approver "..."

check

Evaluates the approved acceptance criteria against the working tree: pass / fail / needs-signoff per criterion. Same engine the MCP bridge’s check_story tool runs. Scope it per story on pull requests (--story or --started-only, with --manual warn so pending sign-offs are listed, not blocking) and run it in full with --manual block at release. Criteria marked check.when: release are skipped by --stage pr and evaluated by --stage release (the default).

linebreak-gate check [--path .] [--format summary|json] [--story <id> ...|--started-only] [--manual block|warn] [--stage release|pr]

signoff

Records an attributed human sign-off for one manual criterion: the checks a machine can’t run. The note says what was verified.

linebreak-gate signoff --criterion <id> --approver "qa@example.com" --note "verified on staging"

init

Sets the repo up end to end: writes the workflow file, offers to store the secrets (GitHub CLI) and require the gate check on the default branch, and prints deep links for anything it can’t do. Idempotent; --force overwrites, --non-interactive never prompts, --fail-on also writes .linebreak/gate.yml with that floor.

linebreak-gate init [--fail-on high] [--force] [--non-interactive]

spec: author, approve, inspect

linebreak-gate spec new                     # scaffold a draft (never touches spec/)
linebreak-gate spec approve <draft.yml> \
  --approver "Ana Lopez <ana@example.com>" \
  [--role architect]                        # validate + land as the approved bundle
linebreak-gate spec list                    # approved stories + approval attribution
linebreak-gate spec next                    # next approved story not yet done
linebreak-gate spec show <story-id>         # one story: criteria, statements, check types
linebreak-gate spec check <story-id>        # run ONE story's checks (0/1/2 exit contract)

Authoring is tool-agnostic: fill the draft with your editor, Claude Code, ChatGPT, or distill it from the PRD you already have. Approval is the moment that counts: a named human lands the bundle. spec check honors the gate’s full exit contract: a signature the gate would reject is exit 1 even when the criteria pass.

mcp: serve the approved spec

linebreak-gate mcp                                # serve over stdio (what editors launch)
linebreak-gate mcp install --editor claude-code   # writes .mcp.json in the repo
linebreak-gate mcp install --editor cursor        # writes .cursor/mcp.json
linebreak-gate mcp install --editor codex         # appends to ~/.codex/config.toml
linebreak-gate mcp install --print                # print the generic stdio config

An existing config is merged or printed, never silently overwritten; the command says which it did. Repo configs carry no absolute paths, so every clone and teammate gets a working setup. See the MCP bridge for the six tools.

badge

Prints a ready-to-paste “gated by LineBreak” README badge.

linebreak-gate badge [--format markdown|html|url]