CLI overview

SBOMFlow is one coherent sbomflow command tree. Everything runs offline by default. This page follows the thirteen job groups sbomflow --help and sbomflow help show, in the same order; run sbomflow help <group> for one group's commands, and sbomflow help <command> or sbomflow <command> --help for the authoritative, generated help for any command. Each group also has its own page, generated from the same source, documenting every command in it: what it reads and writes, its exit codes, its executed examples and every option.

Every example a help page, sbomflow examples or a group page prints is one example in the command catalog, and every one is executed by SBOMFlow's tests — from the source tree, and through an installed wheel — and must return the exit it states and write or print what it is recorded to. sbomflow examples <command> prints the examples of a command and its subcommands, the same lines their --help pages print. See testing and trust for what that does and does not show.

Command groups#

sbomflow --help leads with what SBOMFlow is and the first steps, then lists the groups; sbomflow help lists them with pointers to every other help page. Each group id is also a help topic:

No requirement regime is assumed: the regimes group holds the EU CRA views, which you use only when you choose that regime. sbomflow help all (or sbomflow commands) lists every command, and sbomflow help topics every help topic, group id and keyword. The section headings below spell & as "and", so a link to one of them reads the same in every Markdown renderer.

Each group page — sbomflow help <group> and its page here — opens with a "Who this is for" line naming the people whose jobs its commands do. The line is derived from the new-user journeys the command catalog records: a role, a job, the words that person would type and the command that does it. The test suite walks every journey through the real help pages and fails if a command is not reachable within two screens of sbomflow --help, or if none of its journey's words leads to it through sbomflow help <word>.

Get started#

Check the setup, scaffold a config, run a first pack. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Get started, with the detail this section used to carry.

Run a release audit#

Produce a release-evidence pack from a build and read it. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Run a release audit, with the detail this section used to carry.

--as-of (accepted by analyze, audit, and the decision commands) pins the evidence instant the run measures every date against, which is what makes a re-run byte-reproducible. It pins the clock, not the advisory data — the contract, and what follows from it, is stated once in What --as-of pins.

Review decisions, approvals and the release gate#

Record named human decisions and approvals; apply a gate. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Review decisions, approvals and the release gate, with the detail this section used to carry.

Vulnerabilities, VEX and exploitation context#

Local advisory data and scanner results, matched offline. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Vulnerabilities, VEX and exploitation context, with the detail this section used to carry.

Build, firmware and update inputs#

Builds, firmware, container images and update packages, read into evidence. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Build, firmware and update inputs, with the detail this section used to carry.

Integrity, provenance and reproducibility#

Check signatures, provenance and reproducible bytes. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Integrity, provenance and reproducibility, with the detail this section used to carry.

Runtime and test evidence custody#

Keep traces, dumps and test results by their identity. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Runtime and test evidence custody, with the detail this section used to carry.

Compare releases and keep history#

Compare releases, keep an index, render dashboards. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Compare releases and keep history, with the detail this section used to carry.

Share and hand off#

Hand a finished pack to a reviewer, auditor or customer. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Share and hand off, with the detail this section used to carry.

Trackers and notifications (dry run by default)#

Plan tracker and notification updates; --apply sends them. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Trackers and notifications (dry run by default), with the detail this section used to carry.

Requirement regimes (optional; CRA available today)#

Runs assess CRA unless none is chosen; views are opt-in. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Requirement regimes (optional; CRA available today), with the detail this section used to carry.

Post-market cases (experimental)#

Track a case and draft its documents; nothing is filed. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Post-market cases (experimental), with the detail this section used to carry.

Configure, maintain and look things up#

Config, schema migration of old output directories, help. Every command in this group — what it reads and writes, its exit codes, its executed examples and every option — is on its group page, Configure, maintain and look things up, with the detail this section used to carry.

Flag conventions#

Two rules, and the second matters more when you are writing a script.

--output always means "where this command writes", and its help says what kind of thing the value names. 49 commands take --output and it is not one kind of value: on 12 it names a directory, on 13 a single file, and on 24 a file that defaults to stdout when you leave it out. Rather than ask you to infer that from the command, every --output help line now carries one of three markers:

• (directory) — the value names a directory the command writes into.
• (file) — the value names one file.
• (file; default stdout) — the value names one file, and omitting it prints the document to stdout instead.

--format means the encoding of the artifact the command writes — for example sign-bundle --format in-toto selects the DSSE envelope it emits. There is exactly one exception, and it is recorded as one: update-manifest-evidence --format selects how the input is read (TUF, SUIT, or auto-detected from the bytes).

A spelling that already worked keeps working. Nothing here is renamed or removed. A flag is a published interface, and a rename would break scripts that already run — so where a second spelling exists it is recorded as a variant with the reason it was not converged, rather than deprecated. --dest, --destination, --previous-output, --note and --notes are all in that position. No deprecation warning is emitted for any of them.

Some spellings look like synonyms and are not, which is the trap worth knowing about:

• --reviewer is reserved for the human reviewer of record on the four review paths. --actor, --author and --operator record who touched something and carry no review authority — observed status is never human review status.
• --product selects which product to read; --product-name sets the name written into evidence. Likewise --release selects, --release-id records.
• --dry-run paths act unless you pass it; --apply paths do nothing until you do. They are opposite defaults, not synonyms. On the four sync-* commands --apply is also the network opt-in.
• --as-of normally pins a timestamp so output is reproducible. On ingest-preserved-artifact it instead asserts when the capture was taken, which is why it is not defaulted to the clock.

The whole vocabulary is published, so you can read it rather than infer it:

sbomflow commands --json

That payload carries output_kinds (what --output names on each command), format_encodings (what each --format encodes), flag_variants (every declared variant and why it stands) and flag_vocabulary (alias pairs, such as ingest-preserved-artifact --evidence-dir for --output-dir, which parse identically). The 26 positionals that take an evidence pack all print EVIDENCE_DIR in their usage line.

Output streams#

SBOMFlow keeps a strict stream contract so its output is pipeline-safe: stdout carries the primary/machine output, stderr carries diagnostics. With --json, stdout is pure, parseable JSON and nothing else — human notes, progress, and warnings go to stderr — so sbomflow … --json | jq never breaks on a stray line. Error text always goes to stderr.

Output is plain text by default: redirected or piped output never carries ANSI escape sequences, meaning is never carried by colour alone, and the one interactive surface that uses colour (sbomflow setup) honours both the NO_COLOR convention and its own --no-color flag. Screen readers, narrow terminals, and log processors see the same stable, deterministically ordered text as everyone else.

Embedding & scripting: the supported integration surface#

If you are integrating SBOMFlow into a platform, a pipeline, or another tool, bind to the artifact contract, not to SBOMFlow's Python internals:

• The output files are the API. Every artifact family is versioned and self-describing — sbomflow schema list names them, sbomflow schema show <family> documents the fields offline, and stable families evolve additively.
• Operator commands speak --json. 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 and machine-readable errors carrying stable [E0xx] codes. Which commands take the flag — and how every other command is machine-readable instead — is recorded per command in Machine output coverage, with the contract and its declared exceptions, and checked against the real parser and real runs.
• Discover the surface as data. sbomflow commands --json is the command catalog: every command path with its options, network class and machine-output verdict (machine_output). sbomflow help --json is a different document — the network-policy registry, one row per command with its network class and egress gates. sbomflow help machine-output prints the verdicts on a terminal.
• The Python modules are internal. import sbomflow is not a supported integration surface: module layout and function signatures may change between releases without notice, and import sbomflow is not a supported surface today. If artifacts + --json cannot serve your integration (for example, spawning a subprocess is prohibited in your environment), tell us.

This split is deliberate: one language-neutral contract that every consumer shares is easier to keep stable — and to test — than a parallel Python API.

Progress#

A long scan should not look hung, so analyze (and audit, which runs it) reports each phase on stderr as the phase completes:

sbomflow: scanning project — 22 components
sbomflow: matching vulnerabilities — 2 findings
sbomflow: assessing evidence — 7 evidence gaps

On an interactive terminal the same text is drawn on a single line that is rewritten in place; when stderr is redirected to a pipe, a file, or a CI log you get the plain lines above. Redirected progress carries no ANSI escape sequences and no carriage returns, and it is deterministic: no timestamps, no durations, no ETA, so two runs over the same inputs print the same bytes. Progress never writes to stdout and never changes an artifact.

Silence it with SBOMFLOW_NO_PROGRESS=1, or set TERM=dumb to force the plain rendering on a terminal.