CLI Quickstart: Validate from the Terminal

Each example builds on the one before it — read the ladder in order, or jump to the rung you need. Every shipped artifact is regression-checked against the real CLI and library output.

1. CLI-01: Validate one clean file, see exit 0 — Running validate on a conforming document prints “No findings.” and exits 0.
2. CLI-02: Read a single human finding with line:col — A file that breaks its contract prints one human-formatted finding with id, level, and source line.
3. CLI-03: Switch to JSON output — –format json emits the raw Finding[] array for machine parsing.
4. CLI-04: Emit SARIF for code scanning — –format sarif produces a SARIF 2.1.0 log ready to upload to GitHub code scanning.
5. CLI-05: Validate a whole directory — Passing a directory validates every markdown file the discovered config routes, aggregating findings.
6. CLI-06: Narrow the run with –include — –include scopes a directory run to a glob, validating only the matching subset.
7. CLI-07: Carve out files with –exclude — –exclude drops matching files from the run, here skipping archived entities.
8. CLI-08: Lean on auto-discovered config — With a markdown-contract.yaml in the working dir, validate routes each glob to its contract with no flags.
9. CLI-09: Apply one contract inline with –contract — –contract validates a tree against a single YAML contract directly, no config file needed.
10. CLI-10: Route contracts to dirs with –contract/–path pairs — Paired –contract and –path flags map each contract to its own directory in one run.
11. CLI-11: Override discovery with –config — –config points validate at an explicit config file instead of auto-discovering one.
12. CLI-12: Gate a pre-commit hook on the exit code — The 0/1/2 exit-code contract wires validate straight into a shell gate or git hook.