FAQ
Frequently asked questions
Short, factual answers about the Bomly CLI, the Bomly Guard GitHub Action, and the Bomly MCP server. If your question is missing, please open a discussion — real questions are how this page grows.
What is Bomly?
Bomly is a free, open-source CLI for dependency intelligence. It scans source trees, SBOMs, Git refs, and container images, builds one dependency graph, and explains why each package is present. When you ask for it, Bomly enriches packages with vulnerability and license data, evaluates policy, and writes automation-friendly output for CI. It ships as one binary, with no service to host.
Is Bomly really free?
Yes. The Bomly CLI and the Bomly Guard GitHub Action are open source under the Apache License 2.0. There is no account, no login, and no subscription required to run Bomly locally or in CI.
What data leaves my machine when I run Bomly?
By default, nothing. Bomly has no telemetry, no usage tracking, and no crash reporting. Network enrichment is opt-in: when you pass --enrich, Bomly queries public data sources such as OSV, CISA KEV, and deps.dev for vulnerability and license data. One detail to know: detectors that use a build tool, such as Maven or Gradle, may resolve packages from the package registry, because that is how those build tools work.
Who builds Bomly?
Bomly is built by Ahmed ElMallah, a senior software engineer at GitHub, as a personal open-source project. Development happens in the open at github.com/bomly-dev, and the roadmap is driven by real usage and reported issues. Bomly is a personal project — it is not affiliated with or endorsed by GitHub.
How do I get help or report a bug?
Open an issue on the bomly-cli repository for bugs, or start a GitHub Discussion for questions and feedback. Security reports go through the repository security policy so they can be handled privately. The support page lists all the ways to reach the project.
Getting started
How do I install Bomly?
The quickest ways are Homebrew (brew install bomly-dev/tap/bomly) and the install script (curl -fsSL https://bomly.dev/install.sh | sh). On Windows you can use WinGet (winget install Bomly.BomlyCLI) or Scoop, and every release also ships binaries and Linux packages on GitHub. The default bomly binary has Syft and Grype built in; a smaller bomly-lite binary uses the syft and grype already on your PATH.
Which ecosystems does Bomly support?
Bomly has native detectors for Go, npm (including pnpm and Yarn), Maven and Gradle, Python (pip, pipenv, Poetry, uv), PHP Composer, Ruby Bundler, Rust Cargo, .NET NuGet, Swift (SwiftPM and CocoaPods), Dart pub, Scala sbt, Elixir Mix, C/C++ Conan, and GitHub Actions workflows, plus SPDX and CycloneDX SBOM ingest. Bundled Syft-based detectors cover the long tail, including container images and OS-level packages. The support matrix in the docs lists every detector and the files it reads.
Scanning & SBOMs
Can Bomly read or generate SBOMs?
Both. bomly scan --sbom --path ./sbom.cdx.json reads an existing SPDX or CycloneDX SBOM and turns it into a dependency graph you can diff, explain, and audit. Bomly also writes SBOMs in SPDX 2.3 and CycloneDX 1.6, either to stdout or to files while still printing the normal report.
Does Bomly scan container images?
Yes. bomly scan --image ghcr.io/example/app:latest reads the image layers and resolves the packages inside them into the same dependency graph. Container image support comes from the bundled Syft detectors, which also cover OS-level packages such as apk and dpkg databases.
How do I find out why a package is in my project?
Run bomly explain <package>, for example bomly explain lodash. Bomly prints the dependency paths that bring the package in, so you can see which direct dependency is responsible, and it includes advisory and fix context when enrichment data is present. This works for transitive packages that never appear in your own manifests.
How do I compare dependencies between two branches or two SBOMs?
Use bomly diff. bomly diff --base main --head HEAD compares two Git refs, bomly diff --sbom --base ./old.spdx.json --head ./new.spdx.json compares two SBOM files, and --image compares two container tags or digests. Findings are grouped into introduced, resolved, and persisted, so you can see exactly what a change adds or fixes.
CI & policy
How do I fail CI when a change introduces a high-severity vulnerability?
Run bomly scan --enrich --audit --fail-on high in your pipeline. Exit codes are stable for scripts: 0 for clean results and 2 for policy violations, so any CI system can gate on the result. Add --format sarif to send findings to GitHub code scanning or any other SARIF-aware tool. On GitHub pull requests, the Bomly Guard action packages this whole flow for you.
Can I enforce a license policy?
Yes. Use --allow-license to define an allowlist of SPDX license expressions, --deny-license to block specific ones, and --license-exempt-package for packages you have reviewed and accepted. Combined with --fail-on, license findings can fail the scan in CI. The same options are available as inputs on the Bomly Guard action.
Can Bomly warn me about typosquatted package names?
Yes. The package auditor compares new package names against a protected set: pass --protected-package for the names you care about, and tune --typosquat-threshold (default 0.90) and --typosquat-mode (warn or fail). The check is name-based and needs no network enrichment. Under bomly diff, the packages already in your base branch seed the protected set, so only newly introduced names are checked.
What output formats does Bomly produce?
The default output is a human-readable text report. With --format you can switch to json, markdown, SARIF 2.1.0 (requires --audit), SPDX 2.3, or CycloneDX 1.6, and -o format=path writes several formats in one run while still printing the normal report.
Plugins
Can I extend Bomly with plugins?
Yes. Managed plugins add new detectors, matchers, and auditors without changing the binary. Install one from a local archive, a URL with a checksum, or a GitHub release (bomly plugins install github:owner/repo@tag); installed plugins stay disabled until you run bomly plugins enable, which is the explicit trust decision. The docs include guides for writing your own plugin in Go.
What is Bomly Guard?
Bomly Guard is the official GitHub Action for Bomly. It installs the Bomly CLI and runs bomly diff against the pull request's merge base, so every PR gets a dependency review with vulnerability, license, and policy findings. It is free and open source under Apache 2.0 — no server, no signup.
How do I add Guard to my repository?
Add one step to a pull_request workflow: uses: bomly-dev/bomly-guard@v1, with the policy inputs you want, such as fail-on: high. Check out the repository with fetch-depth: 0 so both refs can be resolved. Guard reports a normal GitHub check, so you can make it required through branch protection.
Does Guard post results to my pull request?
Guard always writes a job summary with the results. Set comment-summary-in-pr to always or on-failure and it also posts a single PR comment — updated in place on new pushes — with an overview, the dependency changes, and the policy findings. With upload-sarif enabled, findings also go to GitHub code scanning as alerts.
Can I reproduce Guard's CI result locally?
Yes. Guard is a thin wrapper around the Bomly CLI, so the same command runs on your machine: bomly diff --base main --head HEAD with the same policy flags reproduces the review before you push. This also makes CI results easy to debug.
How do I set up the Bomly MCP server?
Install the Bomly CLI and run bomly mcp serve — the MCP server is built into the same binary, so there is nothing else to install. Then register it in your agent's MCP configuration: Claude Code (~/.claude.json), Cursor (.cursor/mcp.json), VS Code and GitHub Copilot (.vscode/mcp.json), or Codex (~/.codex/config.toml). The MCP page walks through the whole setup.
Which agents and editors work with the Bomly MCP server?
Any MCP client that supports stdio transport can use it. Documented setups exist for Claude Code, Cursor, VS Code, GitHub Copilot, and Codex. The server runs as a local child process of your agent — there is no remote endpoint to configure.
What tools does the MCP server expose?
Four tools. bomly_scan scans a path, Git URL, container image, or SBOM and returns a compact summary grouped by remediation. bomly_explain shows dependency paths, advisories, and fix context for one package. bomly_diff reports the dependency changes between two refs, images, or SBOM files as introduced, resolved, and persisted. bomly_plugins lists the plugins in your installation. Responses are compact on purpose, sized for agent tool-result limits.
Does the MCP server need network access or an account?
No account and no API key. The server runs locally over stdio, and network enrichment is opt-in per tool call through the enrich argument — without it, the matchers make no vulnerability or license calls. As with the CLI, some build-tool detectors may still resolve packages from a registry while constructing the graph.
How do I make my agent check dependencies before committing?
Add a short instruction to your repository's agent guidance file — CLAUDE.md, AGENTS.md, or copilot-instructions.md — telling the agent to run a dependency diff against the base branch before committing dependency or lockfile changes. The Bomly docs include a ready snippet for this. It is a workflow hint, not a security guarantee: the agent decides when to call the tools.
Still have a question? Start a discussion — answers to real questions get added here.