CLI

breakwater run    <suite-dir> [--seed N] [--steps A..=B] [--auth mock|real] [--json <file>] [--no-color]
breakwater export <suite-dir> --out <file.rs> [--seed N] [--from <run.json>]
breakwater report <run.json> [--html <file>]

run executes cargo test --manifest-path <suite-dir>/Cargo.toml --test suite breakwater_suite -- --exact with BREAKWATER_SEED, BREAKWATER_STEPS, BREAKWATER_AUTH and BREAKWATER_REPORT in the environment. The suite applies the first three through SuiteConfig::from_env, writes its RunReport to the fourth through Exporter::write_if_requested, and returns without asserting when it is driven that way; the CLI judges the JSON. Cargo’s own output goes to stderr unchanged; the CLI prints the header, the shrunk sequence one step per line (index, handler, actor, ledger gap, arguments as k=v, outcome), the violation and the seed to reproduce with.

export turns the shrunk sequence into a regression test: a file that embeds the steps as JSON and calls common::replay_json, the entry point each example’s tests/common/mod.rs exposes. That function rebuilds the fixture and calls Suite::replay, which executes exactly the recorded steps (handler and actor by name, arguments rebuilt by Handler::args_from_json, gaps as recorded) and checks every invariant after each. The generated test asserts the same invariant fails at the same step with the same message. examples/*/tests/repro_*.rs are such files, committed as regression tests.

report renders a JSON report in the terminal, and with --html writes a single static page (inline CSS and SVG, no scripts, no external resources): header, step timeline over ledger sequence with the violating step highlighted, per-step table, and a cumulative-spend chart with the limit line for rolling_cap or a TTL-over-ledgers chart with the zero line for no_mid_lifecycle_expiry. docs/reports/ holds one page per demo.

Exit codes: 0 all invariants held, 1 violation found, 2 usage or configuration error (bad arguments, no tests/suite.rs, cargo failed without writing a report). The JSON report is the RunReport structure and is stable for CI consumption.