Getting started

First scan, enrich, audit, diff — all in five minutes.

Last updated September 16, 2026View source (v0.25.0)

This page walks you from installation to your first useful scan in five minutes.

Install

On Linux or macOS:

curl -fsSL https://bomly.dev/install.sh | sh

On Windows:

winget install Bomly.BomlyCLI

If you have Go on PATH:

go install github.com/bomly-dev/bomly-cli/cmd/bomly@latest

Or download a prebuilt archive from GitHub Releases and put bomly on your PATH. See Installation for Linux packages, Scoop, checksums, and pinned versions. Verify:

bomly version

For the full install matrix — bomly vs bomly-lite, checksum verification, PowerShell instructions, uninstall — see Installation.

Scan a project

From inside any source tree:

bomly scan

This runs the default pipeline:

Discover subprojects (every recognized lockfile or manifest).
Run the best detector chain for each subproject.
Render a human-readable report.

On a small npm project it looks like this:

✓ 68 packages in 1 manifest   (1 direct, 67 transitive · runtime 68, dev 0)

Top-level dependencies
  NAME      VERSION   LICENSE   SCOPE     VULNS
  express   4.19.2    MIT       runtime   -

The VULNS column stays empty until you enrich — that's the next section.

Matchers are offline by default — no --enrich means zero outbound enrichment calls. Detectors may still invoke their build tool (Go, Maven, Gradle, sbt) which can download packages from package registries. Lockfile-parser detectors (npm, pnpm, yarn, Composer, Bundler, NuGet, GitHub Actions) and SBOM ingest are fully offline. See Detectors → Network behavior for the full breakdown.

Pass --path to scan a directory other than the current one:

bomly scan --path ./services/api

Need structured output for automation? --json is the shortcut for --format json:

bomly scan --json

Pass --image to scan a container image:

bomly scan --image ghcr.io/example/app:latest

Pass --url (with optional --ref) to scan a Git repository without cloning by hand:

bomly scan --url https://github.com/example/repo --ref v1.2.0

See Scan targets for the full target list.

Add vulnerability and license data

bomly scan is offline by default. Pass --enrich when you want vulnerability, license, and lifecycle data from public sources:

bomly scan --enrich

The same project now shows which packages carry advisories and whether fixes exist:

✓ 68 packages in 1 manifest   (1 direct, 67 transitive · runtime 68, dev 0)

✓ Enriched via Grype, deps.dev License Matcher

✓ 7 fix suggestions for 7 of 7 vulnerable packages.
  Run again with --format json to see remediation details.

Top-level dependencies
  NAME      VERSION   LICENSE   SCOPE     VULNS
  express   4.19.2    MIT       runtime   1L

This calls the enabled built-in matchers, including OSV, KEV, deps.dev, and OpenSSF Scorecard when selected. Responses are cached under ~/.bomly/cache/. See Matchers for the per-source list and cache TTLs. ClearlyDefined license and endoflife.date lifecycle enrichment are available as external matcher plugins.

Generate an SBOM

Use -o to write SPDX 2.3 or CycloneDX 1.7:

bomly scan \
  -o spdx=sbom.spdx.json \
  -o cyclonedx=sbom.cdx.json

-o can be passed multiple times. At most one may omit =<path> (that one goes to stdout). When every -o has a file path and no --format is set, a successful run writes the files and prints nothing — add --format text if you also want the terminal report. See SBOM formats for the format comparison.

Gate CI on a policy

Add --audit --fail-on <severity> to turn findings into a non-zero exit code:

bomly scan --enrich --audit --fail-on high

On a project with vulnerable packages, the report gains a Findings section and the process exits 2:

Findings
  [HIGH]      GHSA-37ch-88jc-xwx2  path-to-regexp@0.1.7
  [HIGH]      GHSA-9wv6-86v2-598j  path-to-regexp@0.1.7
  [HIGH]      GHSA-qwcr-r2fm-qrc7  body-parser@1.20.2
  [HIGH]      GHSA-rhx6-c78j-4q9w  path-to-regexp@0.1.7

Exit 0 means clean. Exit 2 means at least one finding matched the threshold. Exit 4 means an invalid flag value. See Exit codes.

Common combinations:

# Fail on high or critical findings
bomly scan --enrich --audit --fail-on high

# Fail only when a high-or-above finding is actually reachable
bomly scan --enrich --audit --analyze --fail-on high --fail-on reachable

See Auditors for the full grammar and Reachability for what "reachable" means per ecosystem. Reachability is an experimental feature; review its limitations before gating CI on it.

Explain why a package is in the graph

bomly explain send

Bomly prints every dependency path that introduces the package — not just the shortest one — so you can see each route you'd have to break to remove it:

ecosystem  npm
manager    npm
package    send@0.18.0
scope      runtime
direct     no
licenses
  MIT [declared]
introduced by:
  demo@1.0.0
  └─ express@4.19.2
     ├─ send@0.18.0 [analyzed] (transitive)
     └─ serve-static@1.15.0
        └─ send@0.18.0 [analyzed] (transitive)

Diff two versions

Compare two Git refs:

bomly diff --base main --head HEAD

Or two SBOM files:

bomly diff --sbom --base ./old.spdx.json --head ./new.spdx.json --json

Add --enrich --audit --fail-on high to gate PRs (auditing requires enrichment). The diff audits only the packages the change touched — untouched debt elsewhere never blocks a PR — and within that scope it fails when the change introduces a matching finding or keeps one alive at the changed package's new version (see diff).

Use Bomly with an AI agent

Bomly can run as a local MCP server so an agent can call scan, explain, diff, vulnerability fix context, and plugin-list tools directly:

bomly mcp serve

See MCP Server for Claude Code, Cursor, VS Code, and tool-reference details.

Inspect the interactive view

bomly scan --interactive

Opens a terminal UI with tabs for packages, vulnerabilities, licenses, findings, and source. See TUI for keybindings.