Machine output coverage

Which commands speak --json, which print machine output by default without a flag, which produce machine-readable artifacts on disk instead, and which are for a person at a terminal. Every command path carries one verdict, recorded once in the bundled command catalog and read from there by this page, sbomflow help machine-output, the last line of every command's own help and sbomflow commands --json. The offline test suite holds each verdict to evidence, 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, under the contract below.
3. Machine output by default where the document is the product. The build-evidence, update-evidence, ingest and verification commands print their JSON document on stdout when no --output is given; --output FILE writes the same document to a file instead. Those documents name their contract under a schema key, the name the same bytes carry as a file.
4. 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.

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 --json contract#

Every command path that takes --json keeps four promises. They are checked by running every such path: once with the shortest invocation that reaches the command and points at nothing, and again over real invocations against a freshly built pack, store, custody set, case, index and vulnerability snapshot.

1. Exactly one document. Under --json, stdout holds one JSON document and nothing else. Progress, notes, receipts and warnings go to stderr, so sbomflow … --json | jq never breaks on a stray line. A command that records something (approve --role, review --accept, regime-profile init) prints its human receipt on stderr and puts its document on stdout: the approval status, the refreshed review queue, the profile as written.
2. Versioned. The document carries schema_version. Three documents are JSON arrays — index query, store list and store query — and there the 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, gate simulate, store verify-gates and store verify-replay shipped their version under a schema key first; each now carries schema_version as well, with the same value, and the original key is unchanged.
3. The same exit code with and without --json. Three declared exceptions, each because --json changes what the invocation does rather than how it is shown: - quickstart --json prints the pre-write disclosure and exits without writing or auditing anything, so the refusal that guards the write when no target is named and no terminal can confirm the scope (exit 2) is never reached; - ingest-codex-security --json and ingest-preserved-artifact --json are write-free, so combining --json with a write destination (--output, or --output-dir) is refused with [E019] and exit 2 rather than leaving the destination silently unwritten.
4. A failure still answers on stdout. When a command that took --json fails after it has started, stdout carries one versioned sbomflow-cli-error-v1 document: the [E0xx] code, the title, the detail, the repair, the docs link, the exit code the process actually returned and the retry and state-change semantics. 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. The stderr text is unchanged. What this does not cover: a usage error the argument parser rejects before any command runs (an unknown option, a missing required option, an invalid choice) prints the usage and a coded line on stderr, nothing on stdout, and exits 2, with or without --json.

Where to look a verdict up#

• sbomflow help machine-output lists every verdict with its count, every path that takes --json, every path that prints machine output without a flag, and this contract in four sentences.
• sbomflow help <command> (or sbomflow <command> --help) ends with a Machine output: line: that command's verdict and the reason for it.
• sbomflow commands --json carries the same verdict on every command as a machine_output object (verdict, why, and served_by when a sibling command serves the data), alongside each command's options and network class. It is the command catalog. sbomflow help --json is a different document: the network-policy registry, one row per command with its network class and egress gates. Neither replaces the other.

The census#

In this build the CLI grammar has 174 command paths (95 top-level commands + 79 nested verbs), re-derived from the parser on every generation, never carried forward from a previous release. Of these, 70 take --json, 26 print machine output by default without a flag, 52 produce artifacts on disk as their machine interface, and 26 are human-only by design.

Every verdict is checked against evidence, not against its help text: has-json against the real parser, machine-native against an executed run of the command whose stdout parses as one JSON document, artifact-suffices against what the command declares it writes (and never against a command whose --output defaults to stdout), and human-only-by-design against the parser, which knows which paths only dispatch to their nested verbs.

The audited matrix#

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.