CLI reference
The sbombox command line tool generates, assesses and publishes software bills of materials. It works the same on a laptop and in any CI system. New to SBOMBox? Start with Install.
Quick start
From the root of a repository:
# Sign in once
sbombox login
# Choose a project, allow CI, write the workflow
sbombox init
# Optional: score locally before you push
sbombox check --fail-under 7Commit and push. Each CI run then generates, scores and uploads an SBOM with no secrets configured. Every command accepts --help; sbombox --version prints the installed version.
Commands at a glance
| Command | Purpose |
|---|---|
sbombox login | Sign in to SBOMBox in your browser. |
sbombox logout | Sign out and delete stored credentials. |
sbombox whoami | Show the account you are signed in as. |
sbombox init | Set up a repository in one step. |
sbombox projects | List projects or choose the active one. |
sbombox ci | Let CI pipelines upload without stored credentials. |
sbombox generate | Generate an SBOM for a project directory or a container image. |
sbombox check | Generate and score an SBOM in one step, for pre-commit hooks. |
sbombox score | Score an SBOM's quality from 0 to 10. |
sbombox compliance | Check an SBOM against a compliance ruleset. |
sbombox list | List the components in an SBOM. |
sbombox fix | Repair common SBOM defects automatically. |
sbombox share | Write a report that is safe to share outside your organization. |
sbombox push | Upload an SBOM to SBOMBox. |
sbombox status | Show the active project's latest SBOM, score and vulnerabilities. |
sbombox upgrade | Upgrade to the current version published by SBOMBox. |
sbombox config | Print the default .sbombox.yml, or write it. |
Set up
Sign in, connect a repository to a project, and allow its CI to upload.
sbombox login
Sign in to SBOMBox in your browser.
sbombox loginStarts an OAuth device sign-in. The CLI prints a web address and a one-time code; open the address, confirm the code and approve. The token is stored in your operating system's keychain, or in ~/.sbombox/token.json (readable only by you) where no keychain is available. CI pipelines do not need to sign in: see Authentication.
Exit codes: 0 signed in · 5 sign-in failed or timed out
sbombox logout
Sign out and delete stored credentials.
sbombox logoutRemoves the token from the keychain and from the fallback file.
Exit codes: 0 always
sbombox whoami
Show the account you are signed in as.
sbombox whoamiPrints the email address of the signed-in account. Use it to confirm which credentials the CLI will use.
Exit codes: 0 success · 3 API unreachable · 5 not signed in
sbombox init
Set up a repository in one step.
sbombox init [--project UUID] [--no-trust] [--dir PATH]Run once in the root of a repository, after sbombox login. It:
- Selects the project:
--project, then.sbombox.yml, then your only project, or asks you to choose. - Writes
.sbombox.ymlwith the project ID, if the file does not exist. - Allows this repository's CI to upload without a stored secret (the same as sbombox ci trust). Needs the project admin role; otherwise it warns and continues.
- Writes
.github/workflows/sbombox.ymlfor GitHub, or prints the lines to add to.gitlab-ci.ymlfor GitLab.
Existing files are never overwritten. Commit the result and push.
Options
| Option | Default | Description |
|---|---|---|
-p, --project UUID | - | Project to use, skipping the selection step. |
--no-trust | - | Do not change the project's CI trust rules. |
--dir PATH | . | Repository root. |
Examples
Interactive setup
sbombox login
sbombox initScripted setup for a known project
sbombox init --project 0193c0de-7a1e-7c3b-9f4e-2d8a6b1c5e90Exit codes: 0 success · 2 no project could be selected
sbombox projects
List projects or choose the active one.
sbombox projects list
sbombox projects use UUIDlist shows the ID, name and slug of every project you can access. use sets the active project by writing project_id to .sbombox.yml in the current directory, creating the file if needed. Commands that need a project use the active one unless you pass --project.
Examples
Find a project ID and make it active
sbombox projects list
sbombox projects use 0193c0de-7a1e-7c3b-9f4e-2d8a6b1c5e90Exit codes: 0 success · 3 API error · 5 not signed in
sbombox ci
Let CI pipelines upload without stored credentials.
sbombox ci trust [--repo OWNER/NAME] [--branch NAME]
[--provider github|gitlab] [--project UUID]
sbombox ci show [--project UUID]trust adds a rule to the project allowing a repository's GitHub Actions or GitLab CI pipelines to upload SBOMs. Pipelines then sign in with the identity token their CI issues for each run, so there is no secret to create, store or rotate. Existing rules are kept, and running it twice changes nothing.
show lists the repositories allowed to upload. Every change to these rules is recorded in your organization's audit log, with the before and after. Changing rules requires the project admin role.
Options
| Option | Default | Description |
|---|---|---|
--repo OWNER/NAME | git origin | Repository to allow. GitLab: group/project. |
--branch NAME | any branch | Accept uploads from this branch only. |
--provider | from origin | github or gitlab. |
-p, --project UUID | active project | Project to change. |
Examples
Allow this repository, from any branch
sbombox ci trustAllow only main of another repository
sbombox ci trust --repo acme/payments-api --branch mainExit codes: 0 success · 2 no project or repository · 3 API error · 5 not permitted
Create and assess SBOMs
Generate an SBOM and measure it. These commands run on your machine and send nothing to SBOMBox.
sbombox generate
Generate an SBOM for a project directory or a container image.
sbombox generate [--dir PATH | --image REF [--platform OS/ARCH]]
[--format cyclonedx|spdx] [--output FILE] [--upload]Detects every ecosystem in the directory from its manifests and lockfiles, then runs the most accurate generator installed, and says which one it used.
How the generator is chosen
| Project | Tried in order |
|---|---|
Python with uv.lock | uv export (uv 0.9.11+), cyclonedx-py, cdxgen, syft |
| Other Python | cyclonedx-py, cdxgen, syft |
JavaScript with package-lock.json | npm sbom (npm 9.5+), cyclonedx-npm, cdxgen, syft |
JavaScript with pnpm-lock.yaml | pnpm sbom (pnpm 11.1+), then with --lockfile-only, cdxgen, syft |
| Go or Rust only | cyclonedx-gomod / cargo-cyclonedx if installed, cdxgen, syft |
| Java, Gradle, other, or several languages | cdxgen, syft, then any native tool |
Package-manager-native tools resolve their own ecosystem most faithfully, so they go first for single-language projects. A multi-language repository needs a tool that sees all of it. Independent studies rank cdxgen as the most complete universal tool, particularly for Java, but it needs Node.js and is much slower, so it is opt-in; syft is the fast, dependency-free default. A tool that fails falls through to the next.
Package managers' own commands come first. npm, pnpm and uv write SBOMs themselves, so nothing extra is installed for them. SBOMBox runs them with release settings (runtime dependencies only, application root, from the lockfile) and fills in the hashes pnpm and uv leave off components. To force a generator or an order, set SBOMBOX_GENERATOR, e.g. SBOMBOX_GENERATOR=cyclonedx-npm or SBOMBOX_GENERATOR=npm-sbom,syft. Per-language details are in the language guides.
Commit your lockfile. It matters more than the tool: with one, every generator lists exact versions and transitive dependencies; without one, generate warns that the SBOM may be incomplete.
Options
| Option | Default | Description |
|---|---|---|
--dir PATH | . | Project directory to scan. |
--image REF | - | Scan a container image instead, e.g. ghcr.io/acme/api:1.4.0. Uses the SBOM BuildKit attached to the image if there is one, else syft. Private registries use your docker login. See container images. |
--platform OS/ARCH | linux/amd64 | With --image: platform of a multi-platform image. |
-f, --format | cyclonedx | cyclonedx (CycloneDX 1.6) or spdx (SPDX 2.3). |
-o, --output FILE | sbom.json | File to write. |
--upload | - | Upload to the active project afterwards, as push does. |
Examples
CycloneDX for the current directory
sbombox generateSPDX for one service in a monorepo
sbombox generate --dir services/billing --format spdxA container image, uploaded
sbombox generate --image ghcr.io/acme/api:1.4.0 --uploadExit codes: 0 success · 2 --dir and --image together, or --platform without --image · 4 no manifest found, image unreadable or generation failed
sbombox check
Generate and score an SBOM in one step, for pre-commit hooks.
sbombox check [--fail-under N] [--profile ID]
[--keep FILE] [--dir PATH]Builds an SBOM in a temporary file, scores it and prints one summary line with the three weakest checks. Nothing is uploaded and nothing is written to the repository unless you pass --keep. A directory with no manifest passes. See Check before you commit for hook setup.
Options
| Option | Default | Description |
|---|---|---|
--fail-under N | 0 | Exit 1 if the score is below N (0-10). 0 never fails. |
-p, --profile ID | - | Also report a compliance ruleset. |
--keep FILE | - | Save the generated SBOM. |
--dir PATH | . | Project directory to scan. |
Examples
Block commits that drop the score below 7
sbombox check --fail-under 7Exit codes: 0 passed · 1 score below --fail-under · 4 generation failed
sbombox score
Score an SBOM's quality from 0 to 10.
sbombox score FILE [--format basic|detailed|json]
[--fail-under N]Scores any CycloneDX or SPDX file in eight categories: identification, provenance, integrity, completeness, licensing, vulnerability, structural and component quality. The total is a weighted average with a letter grade from A to F.
detailed shows every check, how many components pass it (for example 31/212) and what it measures. Start with the checks that pass the fewest components. Provenance walks through reading a result.
Arguments
| Argument | Description |
|---|---|
FILE | CycloneDX or SPDX file, JSON or XML. |
Options
| Option | Default | Description |
|---|---|---|
-f, --format | basic | basic (one line), detailed (every check) or json. |
--fail-under N | 0 | Exit 1 if the total is below N (0-10). 0 never fails. |
Examples
See what lowers the score
sbombox score sbom.json --format detailedGate a build
sbombox score sbom.json --fail-under 7Exit codes: 0 success · 1 score below --fail-under · 4 file unreadable or not an SBOM
sbombox compliance
Check an SBOM against a compliance ruleset.
sbombox compliance FILE [--profile ID] [--format table|json]Reports each requirement of the ruleset as pass, partial or fail, then an overall result. Available rulesets: ntia-2021, cisa-2026, cisa-2025, cra-readiness, bsi-tr-03183-2@2.1.0 (also @2.0.0 and @1.1), fsct-v3 and openchain-telco. See Rulesets. Short aliases (ntia, cisa, bsi, cra) select the current version of each standard. An unknown ID is an error, never a silent fallback to another ruleset.
Arguments
| Argument | Description |
|---|---|
FILE | CycloneDX or SPDX file. |
Options
| Option | Default | Description |
|---|---|---|
-p, --profile ID | ntia-2021 | Ruleset to check against. |
-f, --format | table | table or json. |
Examples
EU Cyber Resilience Act readiness
sbombox compliance sbom.json --profile cra-readinessExit codes: 0 checked, whatever the result · 2 unknown ruleset · 4 file unreadable
sbombox list
List the components in an SBOM.
sbombox list FILE [--missing FIELD]Shows each component's name, version, package URL, licences and supplier. Use --missing to find exactly the components a score check counts against.
Arguments
| Argument | Description |
|---|---|
FILE | CycloneDX or SPDX file. |
Options
| Option | Default | Description |
|---|---|---|
-m, --missing FIELD | - | Only components without: suppliers, authors, publishers, provenance (none of those three), licenses, hashes or versions. |
Examples
Components with no supplier
sbombox list sbom.json --missing suppliersExit codes: 0 success · 2 unknown --missing value · 4 file unreadable
sbombox fix
Repair common SBOM defects automatically.
sbombox fix FILE [--dry-run] [--output FILE]Applies only changes that can be derived from the SBOM itself: adds a creation timestamp, normalises licence identifiers to SPDX, fills package URLs, removes duplicate components and adds missing hashes. It never invents supplier, author or publisher values. The file keeps its original format.
Arguments
| Argument | Description |
|---|---|
FILE | CycloneDX or SPDX file. |
Options
| Option | Default | Description |
|---|---|---|
--dry-run | - | List the changes without writing anything. |
-o, --output FILE | input file | Write here instead of overwriting the input. |
Examples
Review, then write to a copy
sbombox fix sbom.json --dry-run
sbombox fix sbom.json -o sbom.fixed.jsonExit codes: 0 success · 4 file unreadable
Publish
Send SBOMs to SBOMBox, where they are stored, monitored for new vulnerabilities and recorded in the audit log.
sbombox push
Upload an SBOM to SBOMBox.
sbombox push FILE [--project ID] [--branch NAME]
[--version LABEL] [--json]The branch, commit, CI system and run link are detected automatically and stored with the upload. Uploading the same file again for the same branch and version stores nothing new but is still recorded in the audit log.
In GitHub Actions or GitLab CI with no SBOMBOX_TOKEN, it signs in with the run's own identity token. SBOMBox then verifies the repository, commit and workflow itself rather than trusting what the job reports, and marks the SBOM P2. See Authentication.
Arguments
| Argument | Description |
|---|---|
FILE | CycloneDX or SPDX file, up to 50 MB. |
Options
| Option | Default | Description |
|---|---|---|
-p, --project ID | active project | Project UUID or org/project slug. |
-b, --branch NAME | from CI or git | Branch label. |
-v, --version LABEL | - | Release label, e.g. v1.4.0. |
--json | - | Print the API response as JSON on stdout. Messages go to stderr. |
Examples
Upload a release
sbombox push sbom.json --version v1.4.0Capture the SBOM ID in a script
id=$(sbombox push sbom.json --json | jq -r .id)Exit codes: 0 uploaded · 2 no project · 3 API error · 5 not signed in or CI identity refused
sbombox status
Show the active project's latest SBOM, score and vulnerabilities.
sbombox statusPrints the latest SBOM's format and component count, its score and grade, and up to 20 open vulnerability findings.
Exit codes: 0 success · 2 no active project · 3 API error · 5 not signed in
Configure
Keep the CLI current, and set project defaults for the current directory.
sbombox upgrade
Upgrade to the current version published by SBOMBox.
sbombox upgradeAsks SBOMBox which CLI version is current and installs it. SBOMBox decides which versions are current and which are still supported, not a local setting.
The CLI checks at most once a day and prints a notice when a newer version is available; in GitHub Actions the notice appears as a warning on the run. If your version falls below the supported minimum, the API refuses it with exit code 6 and the upgrade command.
Exit codes: 0 upgraded or already current · 2 not installed with uv; prints the command to run · 3 SBOMBox unreachable
sbombox config
Print the default .sbombox.yml, or write it.
sbombox config [--init]Prints a commented template. With --init, writes it to .sbombox.yml unless the file exists. See Configuration.
Options
| Option | Default | Description |
|---|---|---|
--init | - | Write the file instead of printing it. |
Exit codes: 0 always
Authentication
The CLI uses the first credential it finds, in this order:
| Method | Use it for | How |
|---|---|---|
SBOMBOX_TOKEN | CI systems without identity tokens (Jenkins, CircleCI, Azure Pipelines) | Create an API token in project settings and store it as a masked secret. |
| Saved sign-in | Your own machine | sbombox login |
| Keyless CI identity | GitHub Actions and GitLab CI (recommended) | Run sbombox ci trust once. Each run gets a token valid for 15 minutes, for one project, that can only upload. |
Keyless uploads are the strongest evidence for an audit: SBOMBox verifies the repository, commit, workflow and run itself and stores them with the SBOM as provenance level P2. Uploads with a token record what the CI reports, as P1.
Configuration
Settings come from, highest priority first: command options, environment variables, then .sbombox.yml in the current directory. Commit .sbombox.yml so everyone on the team uses the same project. Never put a token in it.
# .sbombox.yml
api_url: https://api.sbombox.com
project_id: "0193c0de-7a1e-7c3b-9f4e-2d8a6b1c5e90"| Key | Description |
|---|---|
project_id | Active project. Set by sbombox init and sbombox projects use. |
api_url | API address. Change it only for self-hosted deployments. |
Environment variables
| Variable | Description |
|---|---|
SBOMBOX_TOKEN | API token. Takes precedence over every other credential. Store it as a masked CI secret, never in the repository. |
SBOMBOX_PROJECT | Project UUID. Overrides project_id in .sbombox.yml. |
SBOMBOX_API_URL | API address for self-hosted deployments. Default https://api.sbombox.com. |
SBOMBOX_ID_TOKEN | CI identity token for keyless sign-in on GitLab and other CI systems. On GitLab, declare it under id_tokens with aud: sbombox-api. GitHub Actions needs nothing. |
SBOMBOX_OIDC_AUDIENCE | Audience requested for the CI identity token. Default sbombox-api. Change it only if your SBOMBox deployment uses another. |
SBOMBOX_VERSION | Installer only: pin a CLI version, e.g. 0.2.0. Default: the current version published by SBOMBox. Versions below the supported minimum are refused. |
SBOMBOX_NO_MODIFY_PATH | Installer only: set to 1 to leave shell profiles unchanged. |
SBOMBOX_NO_UPDATE_CHECK | Set to 1 to silence the daily update notice, e.g. on air-gapped machines. The server's minimum version still applies. |
NO_COLOR | Set to any value to turn off coloured output. |
Scripting and automation
- Machine-readable output:
score --format json,compliance --format jsonandpush --jsonprint JSON on stdout. - Streams: with
push --json, data goes to stdout and messages to stderr, so output can be piped straight intojq. - No prompts: only
initcan ask a question, and only when you have several projects. Pass--projectin scripts. - Colour is turned off automatically when output is not a terminal.
- Exit codes are stable across releases. Branch on them, not on message text.
- Version:
sbombox --versionprints the installed version, read from the installed package itself.
Exit codes
| Code | Meaning | Typical cause |
|---|---|---|
0 | Success | - |
1 | Quality gate failed | Score is below --fail-under (score, check). |
2 | Usage error | Missing project, unknown ruleset or filter, invalid option. |
3 | API error | SBOMBox unreachable or returned an error. |
4 | Local error | No manifest found, generation failed, or the file is not a readable SBOM. |
5 | Authentication error | Not signed in, token expired, permission denied, or CI identity refused. |
6 | Upgrade required | This CLI version is below the minimum SBOMBox supports. Run sbombox upgrade. |
Troubleshooting
| Message | What to do |
|---|---|
| No CI identity token available | The GitHub job lacks permissions: id-token: write, or the GitLab job lacks the SBOMBOX_ID_TOKEN declaration. Pull requests from forks never receive one; the GitHub Action skips the upload for them. |
| SBOMBox refused the CI identity (403) | The repository or branch is not allowed to upload to this project. A project admin runs sbombox ci trust in the repository; sbombox ci show lists what is allowed. |
| CLI upgrade required (exit 6) | SBOMBox no longer accepts this CLI version. Run sbombox upgrade, or re-run the installer. In CI, remove any pinned version or raise it. |
| Not logged in | Run sbombox login, or set SBOMBOX_TOKEN. |
| No project specified | Pass --project, set SBOMBOX_PROJECT, or run sbombox projects use. |
| Could not detect project ecosystem | Run in the directory that holds the manifest, or pass --dir. |
| Generation failed | No SBOM generator is installed. Run the installer again; it adds syft when none is present. |
| Unknown profile | Use one of the IDs listed under compliance. |