Reference

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 7

Commit 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

CommandPurpose
sbombox loginSign in to SBOMBox in your browser.
sbombox logoutSign out and delete stored credentials.
sbombox whoamiShow the account you are signed in as.
sbombox initSet up a repository in one step.
sbombox projectsList projects or choose the active one.
sbombox ciLet CI pipelines upload without stored credentials.
sbombox generateGenerate an SBOM for a project directory or a container image.
sbombox checkGenerate and score an SBOM in one step, for pre-commit hooks.
sbombox scoreScore an SBOM's quality from 0 to 10.
sbombox complianceCheck an SBOM against a compliance ruleset.
sbombox listList the components in an SBOM.
sbombox fixRepair common SBOM defects automatically.
sbombox shareWrite a report that is safe to share outside your organization.
sbombox pushUpload an SBOM to SBOMBox.
sbombox statusShow the active project's latest SBOM, score and vulnerabilities.
sbombox upgradeUpgrade to the current version published by SBOMBox.
sbombox configPrint 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 login

Starts 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 logout

Removes 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 whoami

Prints 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:

  1. Selects the project: --project, then .sbombox.yml, then your only project, or asks you to choose.
  2. Writes .sbombox.yml with the project ID, if the file does not exist.
  3. 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.
  4. Writes .github/workflows/sbombox.yml for GitHub, or prints the lines to add to .gitlab-ci.yml for GitLab.

Existing files are never overwritten. Commit the result and push.

Options

OptionDefaultDescription
-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 init

Scripted setup for a known project

sbombox init --project 0193c0de-7a1e-7c3b-9f4e-2d8a6b1c5e90

Exit codes: 0 success · 2 no project could be selected

sbombox projects

List projects or choose the active one.

sbombox projects list
sbombox projects use UUID

list 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-2d8a6b1c5e90

Exit 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

OptionDefaultDescription
--repo OWNER/NAMEgit originRepository to allow. GitLab: group/project.
--branch NAMEany branchAccept uploads from this branch only.
--providerfrom origingithub or gitlab.
-p, --project UUIDactive projectProject to change.

Examples

Allow this repository, from any branch

sbombox ci trust

Allow only main of another repository

sbombox ci trust --repo acme/payments-api --branch main

Exit 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

ProjectTried in order
Python with uv.lockuv export (uv 0.9.11+), cyclonedx-py, cdxgen, syft
Other Pythoncyclonedx-py, cdxgen, syft
JavaScript with package-lock.jsonnpm sbom (npm 9.5+), cyclonedx-npm, cdxgen, syft
JavaScript with pnpm-lock.yamlpnpm sbom (pnpm 11.1+), then with --lockfile-only, cdxgen, syft
Go or Rust onlycyclonedx-gomod / cargo-cyclonedx if installed, cdxgen, syft
Java, Gradle, other, or several languagescdxgen, 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

OptionDefaultDescription
--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/ARCHlinux/amd64With --image: platform of a multi-platform image.
-f, --formatcyclonedxcyclonedx (CycloneDX 1.6) or spdx (SPDX 2.3).
-o, --output FILEsbom.jsonFile to write.
--upload-Upload to the active project afterwards, as push does.

Examples

CycloneDX for the current directory

sbombox generate

SPDX for one service in a monorepo

sbombox generate --dir services/billing --format spdx

A container image, uploaded

sbombox generate --image ghcr.io/acme/api:1.4.0 --upload

Exit 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

OptionDefaultDescription
--fail-under N0Exit 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 7

Exit 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

ArgumentDescription
FILECycloneDX or SPDX file, JSON or XML.

Options

OptionDefaultDescription
-f, --formatbasicbasic (one line), detailed (every check) or json.
--fail-under N0Exit 1 if the total is below N (0-10). 0 never fails.

Examples

See what lowers the score

sbombox score sbom.json --format detailed

Gate a build

sbombox score sbom.json --fail-under 7

Exit 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

ArgumentDescription
FILECycloneDX or SPDX file.

Options

OptionDefaultDescription
-p, --profile IDntia-2021Ruleset to check against.
-f, --formattabletable or json.

Examples

EU Cyber Resilience Act readiness

sbombox compliance sbom.json --profile cra-readiness

Exit 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

ArgumentDescription
FILECycloneDX or SPDX file.

Options

OptionDefaultDescription
-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 suppliers

Exit 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

ArgumentDescription
FILECycloneDX or SPDX file.

Options

OptionDefaultDescription
--dry-run-List the changes without writing anything.
-o, --output FILEinput fileWrite 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.json

Exit codes: 0 success · 4 file unreadable

sbombox share

Write a report that is safe to share outside your organization.

sbombox share FILE [--output FILE]

Writes scores and aggregate counts only, with no component names, versions or identifiers. Suitable for customers, auditors and security questionnaires.

Arguments

ArgumentDescription
FILECycloneDX or SPDX file.

Options

OptionDefaultDescription
-o, --output FILEreport.jsonFile to write.

Exit 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

ArgumentDescription
FILECycloneDX or SPDX file, up to 50 MB.

Options

OptionDefaultDescription
-p, --project IDactive projectProject UUID or org/project slug.
-b, --branch NAMEfrom CI or gitBranch 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.0

Capture 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 status

Prints 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 upgrade

Asks 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

OptionDefaultDescription
--init-Write the file instead of printing it.

Exit codes: 0 always

Authentication

The CLI uses the first credential it finds, in this order:

MethodUse it forHow
SBOMBOX_TOKENCI systems without identity tokens (Jenkins, CircleCI, Azure Pipelines)Create an API token in project settings and store it as a masked secret.
Saved sign-inYour own machinesbombox login
Keyless CI identityGitHub 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"
KeyDescription
project_idActive project. Set by sbombox init and sbombox projects use.
api_urlAPI address. Change it only for self-hosted deployments.

Environment variables

VariableDescription
SBOMBOX_TOKENAPI token. Takes precedence over every other credential. Store it as a masked CI secret, never in the repository.
SBOMBOX_PROJECTProject UUID. Overrides project_id in .sbombox.yml.
SBOMBOX_API_URLAPI address for self-hosted deployments. Default https://api.sbombox.com.
SBOMBOX_ID_TOKENCI 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_AUDIENCEAudience requested for the CI identity token. Default sbombox-api. Change it only if your SBOMBox deployment uses another.
SBOMBOX_VERSIONInstaller 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_PATHInstaller only: set to 1 to leave shell profiles unchanged.
SBOMBOX_NO_UPDATE_CHECKSet to 1 to silence the daily update notice, e.g. on air-gapped machines. The server's minimum version still applies.
NO_COLORSet to any value to turn off coloured output.

Scripting and automation

Exit codes

CodeMeaningTypical cause
0Success-
1Quality gate failedScore is below --fail-under (score, check).
2Usage errorMissing project, unknown ruleset or filter, invalid option.
3API errorSBOMBox unreachable or returned an error.
4Local errorNo manifest found, generation failed, or the file is not a readable SBOM.
5Authentication errorNot signed in, token expired, permission denied, or CI identity refused.
6Upgrade requiredThis CLI version is below the minimum SBOMBox supports. Run sbombox upgrade.

Troubleshooting

MessageWhat to do
No CI identity token availableThe 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 inRun sbombox login, or set SBOMBOX_TOKEN.
No project specifiedPass --project, set SBOMBOX_PROJECT, or run sbombox projects use.
Could not detect project ecosystemRun in the directory that holds the manifest, or pass --dir.
Generation failedNo SBOM generator is installed. Run the installer again; it adds syft when none is present.
Unknown profileUse one of the IDs listed under compliance.