Interactive setup

sbomflow setup is a guided, first-run experience for a real terminal. It reuses the same project detection, doctor, init, config validation, and offline audit that the individual commands use — it does not add hidden behavior.

sbomflow setup

What it does#

1. Shows a short, restrained welcome and a one-line reminder that SBOMFlow creates evidence-readiness records and does not determine conformity.
2. Lets you pick an output style (system, light, dark, high-contrast, ANSI-limited, or no color) when the terminal supports styling. NO_COLOR, TERM=dumb, redirected output, and --no-color keep output plain.
3. Detects your project read-only (it never executes your build) and shows each detected value and where it came from, so you can correct it.
4. Lets you declare the product class, with a clear note that SBOMFlow records your declaration and does not classify the product.
5. Chooses an output directory and protects against overwriting.
6. Shows a read-only local capability summary using the same facts as doctor.
7. Keeps offline as the recommended default; any online enrichment is explained separately, including exactly what would be sent.
8. Previews the files and exact command before writing anything and writes config atomically. Ctrl-C before or during the audit leaves config unchanged; an interrupted audit output directory may contain incomplete artifacts and should be removed or replaced by a fresh run.
9. Runs a first offline audit and finishes with observed counts, artifact paths, and the next review / gate / explain commands.
10. Closes with a short guided first-gap walkthrough: it shows the top-severity evidence gap using the same explanation sbomflow explain --gap prints, then the exact explain / review commands to record your first decision (and how to build the reviewer console). It teaches the review motion and records nothing on your behalf. This step appears only in a real terminal — the automation path is unchanged.

When it has no gaps to walk, it says which of four things happened, because "zero gaps" and "I could not read your gaps" are different facts and only the first is a clean result:

A gap list that is partly readable is walked normally, and the step says how many entries it skipped and that the list you are seeing is therefore partial. Only your own audit writes this file; these states matter when a pack was hand-written, produced by another tool, or damaged after the run.

Automation#

Setup is interactive-only. It never runs in CI, when input/output is redirected, or when --no-input is passed — it exits with a clear message pointing to the scriptable path (quickstart + audit). Product identity, declared class, output directory, timestamp, colour, and style can be supplied as flags to set the editable defaults; automation should continue to use quickstart or audit.

Editor autocomplete for sbomflow.yaml#

SBOMFlow ships a JSON Schema for the product configuration so editors can offer completion and inline validation while you hand-edit sbomflow.yaml. Point your editor's YAML language server at it with a header line, e.g.:

# yaml-language-server: $schema=https://sbomflow.dev/schemas/config/v1
product:
  name: Example Gateway
  version: "2.4.1"

The schema is also bundled in the package at data/schemas/sbomflow/config-v1.schema.json. When the optional [validate] extra (pip install 'sbomflow[validate]') is installed, sbomflow validate-config applies the same schema and reports any mismatches; on the standard standard-library-only install this step is skipped. The schema stays in lock-step with the keys validate-config recognises (a drift test enforces it), so it can never advertise a key the tool does not read.

To see exactly which value applied, run sbomflow config show <file>: it prints the merged effective configuration with each key marked config (set in the file) or default (built-in). The resolution order is flag > environment > config file > default — a command-line flag overrides an environment override, which overrides the config file, which overrides the built-in default (a value you set equal to the default reads as default). A matrix test locks that precedence so a refactor cannot silently invert it.

Environment overrides (SBOMFLOW_*)#

For CI that configures via the environment rather than a committed file, any config key is overridable with an SBOMFLOW_<SECTION>_<KEY> variable — the name set is generated from the config schema, so a new key is env-settable automatically. Values are typed: booleans accept 1/true/yes/on, integers and numbers are parsed (a malformed value fails fast, exit 2), and list keys are comma-split. Examples:

SBOMFLOW_PRODUCT_NAME="Gateway"          # -> product_name
SBOMFLOW_EVIDENCE_VALID_DAYS=30          # -> evidence_valid_days (int)
SBOMFLOW_OSV_ENABLED=true                # -> osv.enabled  (nested section)
SBOMFLOW_TEST_RESULT_PATHS="a.json,b.json"  # -> test_result_paths (list)

An unrecognised SBOMFLOW_* name prints a startup warning so a typo cannot silently do nothing. Credential variables (GITHUB_TOKEN, …) do not carry the prefix and are never merged into config or artifacts.

Every path key in sbomflow.yaml (reviews, approvals, external_sboms, test_results, policy, build.provenance, …) resolves relative to the config file's directory, not your current working directory — so a config and its referenced files move together and behave the same however you invoke SBOMFlow. A guard test keeps every path key on that one rule.