Machine output coverage

Which commands speak --json, which produce machine-readable output another way, and where a real gap remains — audited per command against the shipped command grammar, and machine-checked by the offline test suite so this page cannot silently rot when a command is added or gains a flag.

If you are scripting against SBOMFlow, start with the CLI overview's integration contract; this page is the per-command census behind it.

The machine interface, in order of authority#

1. Artifacts on disk are the API. SBOMFlow's product is deterministic, versioned JSON files. A command that writes artifacts already has a machine interface — usually a richer one than any terminal flag could carry. sbomflow schema list names the families; sbomflow schema show <family> documents the fields offline.
2. --json where operators read terminals. Read/status commands emit one pure, versioned JSON document on stdout (schema_version on every payload), with the same exit codes as the human output. Stdout stays pure: progress, notes and warnings go to stderr.
3. Exit codes are a machine contract of their own. Every command's exit code follows the published exit-code reference, and errors carry stable [E0xx] codes in both text and JSON.
4. A failed --json run still answers on stdout. When a command that took --json fails, the coded error is also emitted as a versioned sbomflow-cli-error-v1 document on stdout, carrying the [E0xx] code, the title, the detail, the repair, the docs link, the exit code and the retry/state-change semantics. A consumer therefore parses exactly one stream in success and in failure, and an empty stdout never has to be read as either. The stderr text is unchanged, and a command that already emits its own document on the failure path (validate --json prints its validate-report and then fails) keeps exactly that document — stdout never carries two.

A universal "result envelope" wrapping every command's stdout is deliberately not provided: artifacts on disk are the primary machine interface, and re-wrapping every command's output for symmetry would break existing consumers without serving a named need.

The census#

In this build the CLI grammar has 147 command paths (85 top-level commands + 62 nested verbs) — re-derived from the parser by the offline suite on every run, never carried forward from a previous release. Of these, 56 take --json, 2 are machine-native without a flag, 67 produce artifacts on disk as their machine interface, and 22 are human-only by design. The three audited gaps the first pass found are now closed, so no row is left verdicted add.

Every verdict below was audited against the command's implementation, not its help text: what it writes, what its exit code means, and which sibling command already serves the same data.

Where schema_version sits. Every --json payload carries it. Most payloads are JSON objects and carry it as a top-level key. Two — store list and store query — are JSON arrays, and their contract name rides on each element rather than in a wrapper: wrapping the array would break every consumer already parsing it, for a key those consumers do not read. upgrade plan and gate simulate shipped their version under a schema key before this promise was written; both now carry schema_version as well, with the same value, and the original key is unchanged.

The audited matrix#

<!-- JSON-COVERAGE:BEGIN — machine-checked against the shipped CLI grammar by the offline test suite. Every command path appears exactly once as the row's first backtick token; the verdict column uses only the five values defined above; a row's has-json verdict must match the real parser. Do not add, remove, or reword rows without re-running the suite. -->

<!-- JSON-COVERAGE:END -->

The three audited gaps — CLOSED#

Only three of the 123 non-dispatch paths audited in that pass were verdicted a real gap, all of them read-only verifiers or listings whose sibling commands already speak --json. All three now ship the flag, additively:

• schema list — the machine-readable listing already existed internally, behind a flag the parser never declared, so the branch could not be reached. Declaring --json exposes the document and revives that dead branch.
• index validate — integrity notes and errors are now a structured document. The exit code is unchanged, so a caller that switches on --json cannot get a different verdict from the one the text reported.
• verify-bundle — verification detail, per-layer under --layered, at parity with passport verify --json. Version skew stays context: it appears in the document but changes no layer status and no exit code.

Human text, exit codes, and artifacts are byte-identical to before on every one of the three.

verify-bundle --layered: what a zero exit proves#

Every layered document carries exit_code_scope, and the human output prints the same sentence, because a consumer reading only one of the two must not have to find that boundary in prose somewhere else. Exit 0 proves that no layer failed and that every layer named by --require-layers reached a trusted status. It does not prove the bundle is trusted (read verdict / trusted_use), that an unrequired layer verified, that the evidence inside the bundle is correct, or anything at all about conformity.

--require-layers content,envelope,semantics,authority adds an expectation block — required, met, unmet, and a per-layer row carrying the observed status alongside the accepted_statuses that would have satisfied the requirement — and exits 7 when a well-formed report does not meet it. The full layer report is still emitted: an expectation narrows what the exit code means, never what the run reports. Without the flag the block is absent and every exit code is exactly what it was; a genuine verification failure stays 3 and outranks 7; an unknown layer name is refused as an input error (2) before verification runs, because a stricter check that silently did not happen is worse than no check. Nothing else on this page is a commitment to add flags; the remaining non---json rows are deliberate.

Doctor facts added by the same audit#

The same audit reviewed two outstanding doctor requests, and both shipped alongside it as facts-only additions — doctor reports local facts, fabricates nothing, and never decides:

• offline docs availability — whether sbomflow help error and sbomflow help exit render from this install, with their code counts, and which web docs URLs error messages will print (recorded, never fetched).
• path length — the absolute target path's length in characters and bytes next to the filesystem's own reported PATH_MAX / NAME_MAX limits, or an honest "not reported" where the platform has no answer.

See Troubleshooting for what doctor reports and why each row is context, never a verdict.