cli-is-deterministic-and-stream-correct
IN derived (depth 1)
The CLI achieves full scriptability through three deterministic properties: flat dict dispatch with no dynamic plugin resolution, binary exit codes (0 success, 1 error) with no ambiguous intermediate codes, and clean stream separation (diagnostics to stderr, results to stdout)
Summary
The CLI is fully scriptable and automation-friendly because its behavior is predictable in three specific ways: commands are resolved through a simple dictionary lookup with no runtime surprises, every command exits with either 0 or 1 so scripts can reliably check success or failure, and diagnostic output never contaminates the data stream since errors go to stderr and results go to stdout. This means any wrapper script, CI pipeline, or tool that shells out to this CLI can depend on stable, parseable behavior without defensive workarounds.
Justifications
SL — Three independent CLI interface properties — dispatch determinism, exit code simplicity, and stream correctness — combine into full scriptability: shell scripts can dispatch, check status, and parse output without heuristics
Antecedents (all must be IN):
- cli-dispatch-is-flat-dict-lookup — CLI dispatch uses a flat `commands` dict mapping subcommand strings to `cmd_*` handler functions — no plugin system or subclass hierarchy.
- cli-exit-code-contract-is-binary — Every CLI subcommand returns exit code 0 for success and 1 for any user-facing error; no other exit codes are used or tested.
- cli-errors-use-stderr-success-uses-stdout — CLI error diagnostics are written to stderr and success output to stdout; tests consistently assert on the correct stream.
Dependents
These beliefs depend on this one:
- cli-is-verified-end-to-end — The CLI is verified through hermetic end-to-end integration tests (isolated databases per test, full argv-parsing pipeline, deterministic stream-correct output) — unless cmd_propagate bypasses the API layer, leaving one code path's safety guarantees unverifiable through the standard integration testing harness.