bomly-cli

Analyze Your Software DNA.

Bomly scans source trees, SBOMs, Git refs, and container images, generates SPDX and CycloneDX SBOMs, enriches packages with vulnerability and license data, evaluates policy, and diffs dependency state across refs.

One binary. Native detectors for the ecosystems developers use every day. Offline-safe unless you opt in. Built for CI as much as for local use.

Why Bomly

• One CLI, full pipeline. Detect, enrich, audit, explain, diff, and write SBOMs from the same binary.
• Native detectors first. Real dependency graphs (with edges) for Go, npm, pnpm, yarn, Maven, Gradle, Python, Composer, Bundler, GitHub Actions, and SBOM ingest. Syft fills the long tail for containers and rarer ecosystems.
• Offline-safe by default. A scan without --enrich makes zero outbound HTTP calls. Built-in enrichment uses OSV, KEV, deps.dev, and OpenSSF Scorecard.
• Reachability that respects your time (experimental). --analyze tells you whether your app actually calls a vulnerable symbol — Tier-1 (govulncheck) for Go; Tier-3 import-graph closure for npm, Python, and JVM languages. See REACHABILITY.md for limitations.
• Stable exit codes for CI. 0 clean, 2 policy violation, plus 1, 3, 4 for other failure classes. See Exit codes.

Highlights

• Scan local trees, SBOMs (SPDX 2.3, CycloneDX 1.6), Git repositories, container images.
• Write SBOMs in either format as the primary output or alongside any report: --format spdx, -o cyclonedx=….
• Enrich with OSV, KEV, deps.dev, and OpenSSF Scorecard via --enrich; lifecycle enrichment can be added with an external matcher plugin.
• Audit with --audit --fail-on <severity>; SARIF emitted with --format sarif.
• Explain transitive paths with bomly explain <package>.
• Diff dependency state across Git refs or SBOM files with bomly diff.
• Filter by ecosystem, detector, matcher, auditor, scope.

Quick Start

# Scan the current project
bomly scan

# Write SBOMs in two formats
bomly scan -o spdx=sbom.spdx.json -o cyclonedx=sbom.cdx.json

# Write one SBOM to stdout
bomly scan --format spdx

# Enrich packages with external vulnerability and license data
bomly scan --enrich

# Emit structured JSON for automation
bomly scan --json

# Evaluate policy using existing package vulnerability data
bomly scan --audit --fail-on high

# Enrich first, then audit and emit SARIF
bomly scan --enrich --audit --fail-on high --format sarif

# Explain why a dependency exists
bomly explain lodash

# Compare dependency state across Git refs
bomly diff --base main --head feature/my-change

Walkthrough: Getting Started.

Installation

# Go toolchain — Go 1.21 or later on PATH
go install github.com/bomly-dev/bomly-cli/cmd/bomly@latest

Or grab a prebuilt archive from GitHub Releases. Each release publishes bomly (full binary with builtin Syft and Grype) and bomly-lite (smaller binary that shells out to external syft and grype) archives for Linux, macOS, and Windows.

Verify:

bomly version

Full install matrix — bomly vs bomly-lite, checksum verification, PowerShell instructions, uninstall, CI install — lives in docs/INSTALLATION.md.

What It Scans

Native detectors:

• Go modules
• npm, pnpm, Yarn
• Maven, Gradle
• Python (pip, Pipenv, Poetry, uv)
• Composer (PHP)
• Bundler (Ruby)
• GitHub Actions
• SPDX 2.3 and CycloneDX 1.6 SBOM ingest

Syft-backed for many more, including container images. See docs/SUPPORT_MATRIX.md for the full matrix.

Component guides:

• Detectors, Matchers, Auditors, Reachability
• Per-ecosystem detector guides and per-matcher reference

Core Commands

bomly scan

Use scan to resolve dependencies from a local path, a remote Git repository, a container image, or an SBOM file.

# Scan a directory
bomly scan --path .

# Scan a container image
bomly scan --container ghcr.io/example/app:latest

# Treat a file as an SBOM input
bomly scan --sbom --path ./existing-sbom.json

# Filter to runtime dependencies only
bomly scan --scope runtime

# Explore the result in the interactive terminal UI
bomly scan --interactive

Matchers are offline-safe by default — without --enrich, Bomly makes zero outbound HTTP calls. Note that some detectors are build-tool primaries (Go's go list, Maven's mvn dependency:tree, Gradle's gradle dependencies, sbt's sbt dependencyTree) and may download packages from package registries during normal graph resolution. That's a property of those build tools, not a Bomly choice; lockfile-parser detectors (npm, pnpm, yarn, Composer, Bundler, NuGet, GitHub Actions, …) and SBOM ingest are fully offline. See Detectors → Network behavior.

Use --enrich when you want Bomly to call external vulnerability, license, or lifecycle services. Use --audit when you want Bomly to evaluate vulnerability data that already exists on packages. Use both together when you want fetched vulnerability data evaluated in one run.

bomly explain

Use explain to show the dependency path that introduced a package.

bomly explain requests

bomly diff

Use diff to compare dependency state between two Git refs or two SBOM files.

# Git refs
bomly diff --base main --head HEAD

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

Output Modes

Full details: Output formats, SBOM formats, Exit codes.

Configuration

Bomly loads configuration in this order, with later sources taking precedence:

1. ~/.bomly/config.yaml
2. <project>/.bomly/config.yaml
3. BOMLY_* environment variables
4. CLI flags

Use --config <path> to add an explicit config file to the load list.

See docs/CONFIG_REFERENCE.md for the generated reference.

Plugins

Bomly supports managed external plugins for detectors, matchers, and auditors.

Install, enable, and verify external plugins before they can participate in scans:

# Install a published plugin from GitHub Releases
bomly plugin install github:bomly-dev/bomly-plugin-bun-lock-detector@v0.1.0
bomly plugin enable bomly.examples.detector.bun-lock

# Verify it
bomly plugin verify bomly.examples.detector.bun-lock

# Run it explicitly during a scan
bomly scan --path ./my-bun-project --detectors bomly.examples.detector.bun-lock --json

Detector plugins declare package-manager support and evidence patterns through their detector contract. Bomly uses those patterns during runtime preparation so external detectors can participate in subproject discovery alongside built-ins.

The plugin hub lives in docs/PLUGINS.md. Implementation guides are available for detectors, matchers, and auditors. Example plugin repos are Bun Lock Detector, ClearlyDefined License Matcher, EOL Lifecycle Matcher, and Meme Dependency Auditor.

Architecture

Bomly keeps the CLI thin and pushes orchestration into the scan runtime.

flowchart LR
    A[CLI command] --> B[Resolve execution target]
    B --> C[Prepare runtime]
    C --> D[Discover subprojects]
    D --> E[Run detector chains]
    E --> F[Consolidate graph]
    F --> G[Optional package enrichment]
    G --> H[Optional policy evaluation]
    H --> I[Render text, JSON, SARIF, or SBOM]

Extensible by design

The pipeline is built around typed extension points. Every built-in is just an implementation of the same contract an external plugin uses, so you can add an ecosystem, or a vulnerability or license source, or a policy check without forking Bomly. Three of these are pluggable today — detectors, matchers, and auditors; external analyzer plugins are planned (the built-in reachability analyzers are not yet an extension point).

flowchart LR
    R[Configure runtime] --> X[Index subprojects] --> D[Detect: resolve + consolidate] --> M[Match] --> An[Analyze] --> Au[Audit] --> O[Output]

    PD([Detector plugins]) -.-> D
    PM([Matcher plugins]) -.-> M
    PAu([Auditor plugins]) -.-> Au
    PAn([Analyzer plugins: planned]) -. planned .-> An

Plugins ship as signed, versioned gRPC binaries (v1 protocol), are disabled until you explicitly enable them, and participate in the exact same planning flow as built-ins. See docs/PLUGINS.md and the implementation guides for detectors, matchers, and auditors.

More detail lives in docs/ARCHITECTURE.md.

Repository Layout

cmd/bomly/                 CLI entry point
internal/cli/              Commands, config loading, progress, help
internal/engine/           Runtime preparation, orchestration, consolidation
internal/engine/diff/      Diff orchestration and audit deltas
internal/engine/explain/   Dependency path explanation
internal/engine/scan/      Scan command pipeline API
internal/detectors/        Ecosystem-specific dependency resolution
internal/matchers/         External enrichment matchers and shared matcher cache
internal/analyzers/        Reachability analyzers (govulncheck, jsreach, pyreach, jvmreach)
internal/auditors/         Policy evaluation and finding creation
internal/output/           Text, JSON, SARIF rendering and structured response payloads
internal/sbom/             SPDX and CycloneDX encoding and decoding
internal/registry/         Canonical support and discovery registry
internal/plugin/           Managed external plugins (install, verify, run)
docs/                      Public reference documentation

Development

make build
make build-lite
make test
make run ARGS="scan"

If you change config, schema, or support-matrix inputs, run make generate as well.

CI and Releases

Bomly uses GitHub Actions for:

• fast PR validation
• integrated go vet checks in PR validation
• merge-queue smoke coverage before merge
• nightly smoke coverage for upstream drift detection
• automatic semantic version tagging on main
• draft prerelease packaging to GitHub Releases

See docs/development/CI.md for workflow triggers, required checks, release packaging, checksum handling, and the planned future attestation step.

To gate your own repository's pull requests, drop in the Bomly Guard action — it diffs and audits dependency changes on each PR and posts a summary comment. See docs/CI_INTEGRATION.md for that and direct-CLI recipes across GitHub Actions, GitLab, Jenkins, Azure, and CircleCI.

Contributor guidance lives in CONTRIBUTING.md.

License

Bomly CLI is licensed under the Apache License 2.0.

The core CLI — scanning, SBOM generation, and vulnerability matching against public data sources — is open source and free to use. Premium data enrichment and the SBOM management platform are separate commercial offerings.