Getting started

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

Last updated July 30, 2026View source (v0.21.1)

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

Install

If you have Go on PATH:

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

Otherwise download a prebuilt archive from GitHub Releases and put bomly on your PATH. 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.