check

Run a scan and exit non-zero when one or more --fail-on rules trip. Designed to gate CI / pre-commit.

Synopsis

archora check [path] --fail-on <rule> [--fail-on <rule>…] [options]

At least one --fail-on is required.

Rules

--fail-on is repeatable. Each rule is <key>:<value>:

Rule	Trips when …	Needs --base?
grade:<A|B|C|D|F>	archDebt grade ≤ threshold	no
cycles:<N>	total cycles in scan > N	no
layer-violations:<N>	total layer violations > N	no
recommendations:<N>	total recommendations > N	no
new-cycles:<N>	diff vs --base introduces > N new cycles	yes

Threshold semantics: cycles:0 trips when there is more than zero cycles, i.e. any cycle at all. cycles:5 allows up to 5.

Options

Option	Meaning
--fail-on <rule>	Repeatable. Rule that fails the run (see above).
--base <file>	Baseline JSON snapshot. Required for new-cycles.
--quiet	Suppress the "OK / FAIL" summary on stderr.
--help, -h	Show help and exit.

Output

• Pass: stderr line OK: N rule(s) passed. Grade …, K cycles, L violations., exit 0.
• Fail: stderr lines FAIL: M/N rule(s) tripped followed by - <rule> → <description> per failed rule, exit 1.

Nothing is written to stdout. This makes check safe to chain with another command.

Examples

# Gate any cycles, bad grade, or any layer violation
archora check . \
  --fail-on grade:D \
  --fail-on cycles:0 \
  --fail-on layer-violations:0

# Allow some debt but block regressions
archora check . \
  --fail-on grade:C \
  --fail-on new-cycles:0 \
  --base scan-baseline.json

Exit codes

Code	Meaning
0	All rules passed.
1	One or more rules tripped.
2	Bad invocation (no --fail-on, invalid rule, missing baseline).

See CI integration for GitHub Actions / GitLab examples.