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.

A universal "result envelope" wrapping every command's stdout is a recorded rejection, not an oversight: 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

At v0.2 the CLI grammar has 122 command paths (78 top-level commands + 44 nested verbs). Of these, 36 take --json, 2 are machine-native without a flag, 59 produce artifacts on disk as their machine interface, 22 are human-only by design, and 3 are audited gaps where adding --json is planned.

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.

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

Only three of the 122 paths were verdicted a real gap, all of them read-only verifiers or listings whose sibling commands already speak --json:

• schema list — the machine-readable listing already exists internally; only the flag is missing. Planned.
• index validate — integrity notes and errors are free text today; every comparable verifier ships --json. Planned.
• verify-bundle — bundle verification detail (which layer passed or failed) is text-only; a CI consumer verifying a received handoff currently parses prose. Planned.

"Planned" means exactly that: the flags will arrive in a follow-up change, additively — no existing output, exit code, or artifact changes. Nothing else on this page is a commitment to add flags; the remaining non---json rows are deliberate.

Doctor wishlist facts (recorded verdicts)

The same audit reviewed the two outstanding doctor wishlist rows, 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.