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. Asks what you want to get done first. A product class is asked only when you choose the cra goal, with a clear note that SBOMFlow records your declaration and does not classify the product; every other goal scaffolds requirement_regime: none. See Goals.
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. The schema is bundled in the installed package at data/schemas/sbomflow/config-v1.schema.json; copy it beside your config (or point at its installed path) and give your editor's YAML language server a header line, e.g.:

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

When the optional [validate] extra is installed (python -m pip install jsonschema into the same environment; v0.5.5 is not on a package index, so pip install 'sbomflow[validate]' would fail), sbomflow validate-config applies the same schema and reports any mismatches; on the standard standard-library-only install this step is skipped. One deliberate difference: a quoted boolean the config parser accepts ("yes", "on", "1", " false") is linted as the boolean it is read as, so validate-config does not warn about it, while an editor using the schema may still suggest a bare true/false. 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.

sbomflow quickstart follows the same order for the product identity, including on a project that already has a config. With no --product-name/--product-version of your own, the identity comes from the config file the run discovers, and quickstart prints an identity: line naming that file — so quickstart and a plain sbomflow audit on the same directory record the same product_id, which is what release identity, store add and drift all key on. Pass either flag and that flag wins for its own half of the identity, leaving the other half to the config. With no config, both halves fall back to what the manifests detected.

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: integers and numbers are parsed, list keys are comma-split, and booleans accept exactly eight words, case-insensitively and ignoring surrounding whitespace — true, yes, 1, on for true and false, no, 0, off for false. Anything else fails fast with exit 2 and the code invalid_config_boolean: an unreadable boolean has no safe reading, so it is never guessed at. The same eight words are what sbomflow validate-config accepts in sbomflow.yaml, and the file layer additionally accepts a real YAML or JSON true/false literal. Note that in a YAML file a bare 1 is an integer, not one of these words, and is refused — quote it as "1", or just write true. A key left empty (offline: with nothing after it) is a value of null, not an absent key, and is refused too; delete the line to get the default. 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)
SBOMFLOW_FILE_HASH_ALGORITHMS="sha256,sha512"  # -> scan.file_hash_algorithms (list)

This override is read by the same function as the file value, so the same refusals apply: SBOMFLOW_FILE_HASH_ALGORITHMS=sha512 (no sha256) or a name the key does not accept exits 2 rather than quietly changing what the run records.

A few keys are file-only and have no environment override: the SBOM author block, the withheld-element declaration with its redaction contact (product.sbom_withheld_fields, product.sbom_redaction_contact), the SBOM access pointer (product.sbom_access), the preserved-artifact rows (preserved_artifacts) and the evidence plan (preserved_artifact_expectations), saved review filters (review.filters), the CPE map (identity.cpe_map) and the gate policy (policy). Each is a structure one environment string cannot express, and a value taken from the environment would bypass the parser that reads it from the file. Their SBOMFLOW_* names are still recognised: setting one prints a startup warning saying it was ignored and why, and the file's value stands.

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.