This page takes you from installation to a useful first scan in about five minutes. It is for developers and security engineers who have never run Bomly. Each section ends with a link to the page that goes deeper.
On Linux or macOS:
curl -fsSL https://bomly.dev/install.sh | shOn Windows:
winget install Bomly.BomlyCLICheck that it worked:
bomly versionInstallation covers Homebrew, Scoop, Linux packages, go install, the smaller bomly-lite binary, checksums, and uninstalling.
Run this from inside any source tree:
bomly scanBomly finds every lockfile or manifest in the directory, reads each one with the best available detector, and prints a 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 is the next section.
Other targets use the same command:
bomly scan --path ./services/api # another directory
bomly scan --url https://github.com/example/repo --ref v1.2.0 # a Git repository, no manual clone
bomly scan --image ghcr.io/example/app:latest # a container image
bomly scan --json # structured output (same as --format json)Scan targets lists every input, and Monorepos explains --recursive.
A plain scan does not contact any vulnerability or license service. Add --enrich to look packages up:
bomly scan --enrichThe 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
By default enrichment uses Grype for vulnerabilities and deps.dev for licenses. Matchers lists the optional sources (OSV with the CISA KEV catalog, OpenSSF Scorecard, and plugin matchers) and the cache rules. Network and privacy lists everything that can reach the network, including the build tools some detectors run.
Use -o to write an SPDX 2.3 or CycloneDX 1.7 Software Bill of Materials (SBOM):
bomly scan -o spdx=sbom.spdx.json -o cyclonedx=sbom.cdx.jsonWhen every -o names a file, the run writes the files and prints nothing. Add --format text to keep the terminal report. See SBOM formats.
Add --audit --fail-on <severity> to turn findings into an exit code:
bomly scan --enrich --audit --fail-on highOn a project with vulnerable packages the report gains a Findings section and the process exits with code 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 no finding matched. Exit 2 means at least one did. Exit codes lists the rest.
To fail only when a high-or-higher finding is also reachable from your code, add the experimental reachability analysis:
bomly scan --enrich --audit --analyze --fail-on high --fail-on reachableAuditors lists every --fail-on value. Read Reachability before you gate CI on it.
Ask for every path that pulls a package in:
bomly explain sendecosystem 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)
Bomly prints every path, not only the shortest, so you can see each route you would have to break to remove the package. See the explain command.
Compare two Git refs, or two SBOM files:
bomly diff --base main --head HEAD
bomly diff --sbom --base ./old.spdx.json --head ./new.spdx.json --jsonAdd --enrich --audit --fail-on high to gate a pull request. The diff audits only the packages the change touched, so existing findings elsewhere never block a PR. See the diff command.
- Tutorial — the same features chained into a CI gate on a real project
- Use cases — recipes for PR gates, SBOMs, triage, licenses, and offline scans
- Output formats — text, JSON, SARIF, SBOM
- MCP server — let an AI coding agent call
scan,explain, anddiff - Interactive TUI — browse a scan with
bomly scan --interactive - CI integration — GitHub Actions, GitLab, Jenkins, Azure DevOps, CircleCI
- Troubleshooting — common errors and fixes