Get started

Check the setup, scaffold a config, run a first pack. This page documents every command in the start group, in the order sbomflow help start lists them. Each command's section is generated from the command itself — its summary, description and options from the parser, and its reads, writes, exit codes, examples and see-also from the command catalog — so it says exactly what sbomflow <command> --help says. Every example below is executed offline by the test suite, and every non-zero exit code is either produced by an executed probe or carries a recorded reason why no offline probe can produce it.

See the CLI overview for how the thirteen groups fit together and the command reference for every command's options in one place.

Overview#

• sbomflow setup — guided interactive onboarding (a real terminal only). It asks what you want to get done first; a product class is asked only when you choose the cra goal, and every other goal runs and scaffolds with requirement_regime: none. With no terminal it prints the same guidance as before and exits 2.
• sbomflow help goals — the goals, each with exact offline steps. The same goals are on Goals; Use SBOMFlow without CRA assessment and Keeping runtime evidence in custody walk two of them end to end.
• sbomflow quickstart <dir> — auto-detect, scaffold config, run an offline audit. After a run with no requirement regime its next steps teach the release-gate goal's gate and point at sbomflow help goals.
• sbomflow doctor <dir> — report your environment and config facts.
• sbomflow doctor --analysis-control <path> — check an offline runtime control receipt. A valid SBOM proves something about the tree, not about the run that produced it; this is how you check the second thing.
• sbomflow init <dir> — scaffold a placeholder sbomflow.yaml.
• sbomflow examples [command] — worked examples that are guaranteed to run.

quickstart discloses what it is about to touch before it writes anything — scan root, output directory, the config it will create, the detected build inputs, a bounded in-scope file count and the offline posture. --yes accepts that disclosure without prompting; --json prints the same disclosure as one versioned document and exits without writing, auditing or asking. A home-rooted path prints as ~/my-product; a path outside your home prints verbatim, on purpose.

Worked examples#

Every command's --help page ends with its examples, and every one of them is executed by the test suite, as are the examples on these group pages. For the worked-example registry — "show me waiver usage", "how do I diff two releases?" — ask the CLI:

sbomflow examples                 # every worked example, grouped by command
sbomflow examples store           # just the ones for `store`
sbomflow examples audit --json    # machine-readable

These are not prose. Every example is stored as data and executed against the bundled demo fixture by the test suite, so a renamed flag or a newly required argument fails the build rather than failing you at the terminal. None of them touch the network, which is what makes running them in tests possible.

Who this is for: evaluators, new operators, security leads and CI owners.

sbomflow setup#

Guided interactive first-run onboarding (a real terminal only; never in CI).

Guided, interactive first-run onboarding: detect the product, confirm
identity and output location, preview exactly what will be written, then
run the first offline audit and explain the result.

Requires a real terminal; it never prompts in CI or redirected IO, and
without a terminal it prints the scriptable path (`sbomflow quickstart .`)
and exits 2.

Options

Examples

In a terminal, walk the guided first run; with no terminal (CI, a pipe) it prints the scriptable path instead and exits 2. Exits 2.

sbomflow setup .

Never prompt: print the scriptable path for automation and exit 2. Exits 2.

sbomflow setup . --no-input

Pre-fill the editable defaults the wizard offers; with no terminal it still asks nothing and exits 2. Exits 2.

sbomflow setup . --product-name Gateway --product-version 2.4.1 --output evidence

Run the wizard in the current directory; with no terminal it prints the scriptable path instead and exits 2. Exits 2.

sbomflow setup

See also: sbomflow quickstart, sbomflow doctor, sbomflow help goal sbom.

sbomflow quickstart#

First run: detect the project, scaffold config, run an offline audit, summarize.

The fastest first run: detect the project type, scaffold sbomflow.yaml
(unless --no-init), run a fully offline audit, and print a short summary.

Before the first write it discloses the scope: scan root, output, detected
inputs, a bounded file count, the network posture and what already exists.
It asks only when no target is given; naming a directory, or --yes,
proceeds without a question, so scripts and CI never prompt.

Options

Examples

Scan the project, scaffold its config and run the first offline audit.

sbomflow quickstart . --output evidence --as-of 2026-06-26T12:00:00+00:00

Print the pre-write disclosure as JSON and exit without writing anything.

sbomflow quickstart . --json

Run with no requirement regime assessed and no config scaffolded, then print the guided tour.

sbomflow quickstart . --output evidence --requirement-regime none --no-init --tour

Write a ready-to-commit GitHub Actions workflow instead of auditing.

sbomflow quickstart . --ci github

Naming the directory is the go-ahead: detect, scaffold config, run an offline audit and summarize, with no question asked.

sbomflow quickstart .

See also: sbomflow audit, sbomflow doctor, sbomflow init, sbomflow help goal sbom.

sbomflow init#

Scaffold sbomflow.yaml and optional reviewer templates.

Write a placeholder sbomflow.yaml for a project: product identity,
the declared class and the requirement regime, each a value you edit.
The template flags add inert *.TEMPLATE.json reviewer files and routing
stubs; they record no decision, and init never classifies the product.
An existing config is refused (exit 3) unless --force is given.

Options

Examples

Overwrite the project's config with a fresh scaffold.

sbomflow init . --force

Scaffold a config that assesses no requirement regime.

sbomflow init . --force --requirement-regime none

Also write inert reviewer templates that record no decision.

sbomflow init . --force --with-review-templates

Refuse to overwrite a config that is already there. Exits 3.

sbomflow init .

See also: sbomflow validate-config, sbomflow quickstart, sbomflow doctor.

sbomflow doctor#

Run offline environment/config preflight checks.

Report local environment and config facts before a first run: Python version,
optional extras, config discovery/validity, and what a scan would pick up. It
fabricates nothing and changes nothing.

--pilot adds the machine-checkable half of the pilot-readiness checklist: a
smoke analysis of a synthetic product, a pinned determinism double-run, disk
space, and target writability (a temporary directory and a deleted write-probe
in the target). It reports whether the ENVIRONMENT is ready — never the
product, the evidence, or the review workflow.

TARGET is one existing place, and doctor never substitutes another for it.
Accepted: an existing directory (the project root), or an existing SBOMFlow
config file — sbomflow.yaml / sbomflow.yml / sbomflow.json, the project marker
— whose directory is the root. Refused, with a stable code and before anything
is read or written: a path that does not exist (E001), one that cannot be
examined (E004), a symbolic link named as the target, a regular file that is
not a config file, and any other file type (E019). There is no fallback to the
parent directory, a neighbour, or the current directory, and a repair never
creates a directory. `..` is resolved, not refused, so every path printed is
the physical one that will be touched.

--fix prints a plan of provably safe, reversible remediations (a mischosen
config-key casing, a missing inert *.TEMPLATE.json review scaffold) — never a
reviewer decision file or evidence artifact. Without --apply it is the dry
run: it reads only, writes nothing, and lists every proposed path,
precondition and reversal. --apply executes only the actions still valid at
apply time, each re-checked against the resolved target immediately before its
write, so a plan cannot authorise a write into a substituted path. A
precondition that has drifted since the plan was built is skipped with a
reason and every other action still proceeds (exit 0); a target that changed
under the run, or a write the filesystem refused, is reported per action and
exits 2. Rolling back is the reversal line printed beside each action.

--analysis-control PATH runs the offline runtime control receipt: a packaged
reserved synthetic corpus is executed in a throwaway directory and PATH
records which named controls THIS INSTALLATION could perform. It reads no
customer project and reaches no verdict about one. Exit 0 only when every
declared control passed; a written degraded/failed/indeterminate receipt exits
6.

Options

Examples

Report the environment and config facts for a project.

sbomflow doctor .

Print a plan of safe, reversible repairs without writing anything.

sbomflow doctor . --fix

Write this installation's offline control receipt.

sbomflow doctor . --analysis-control analysis-control-receipt.json

See also: sbomflow quickstart, sbomflow validate-config, sbomflow support-bundle, sbomflow help exit.

sbomflow examples#

Print worked examples that are executed by the test suite.

Print worked, copy-pasteable examples for a command.

Every example is executed against the bundled demo fixture by the test
suite, so an example that stops working fails the build rather than you.

Options

Examples

Print every worked example, grouped by command.

sbomflow examples

Print only the examples for one command.

sbomflow examples store

Print the worked examples as JSON.

sbomflow examples --json

See also: sbomflow commands, sbomflow help, sbomflow help goals.