The Safeguard CLI builds an SBOM from your project, matches it against vulnerability databases and writes the results as files, all on your own machine. It is a single static binary, so there is no Node, Python or JVM to install first. This guide takes you from nothing to a first scan, then shows how to use it in CI.
It runs on macOS, Windows and Linux. Some people call it "like Claude Code for security", because you can also just ask it questions in plain language.
What it is
The CLI does five jobs.
- Scans a directory, a Git repository, a container image or an existing SBOM.
- Finds hardcoded secrets and misconfigurations.
- Validates SPDX, CycloneDX and VEX documents.
- Runs scan jobs assigned by the platform, locally, and uploads results but never source.
- Includes an assistant that can fix what it finds, interactively or in CI.
Many package managers are supported, including npm, Yarn, pnpm, pip, Poetry, Maven, Gradle, Go modules, Cargo, NuGet, Bundler and Composer. The CLI scanner can optionally use an LLM for source analysis, and it also works in Zero AI mode where nothing needs a model.
One thing to know up front: policy gates are evaluated in the platform, not by the CLI. The CLI produces the evidence, and the platform decides whether it passes.
How to use it
Step 1: install
On macOS and Linux:
curl -fsSL https://cli.safeguard.sh/install | bash
On Windows, in PowerShell:
irm https://cli.safeguard.sh/install.ps1 | iex
The installer picks your OS and architecture, downloads the release, verifies it against the published checksums and puts one binary called safeguard on your PATH. If you would rather read the script before running it, and you should, do this instead:
curl -fsSL https://cli.safeguard.sh/install -o install.sh && less install.sh
bash install.sh
Confirm it worked:
safeguard --version
If the version looks wrong, an older copy is probably earlier on your PATH. Run which -a safeguard to see every copy.
Step 2: first run and sign in
safeguard
Running it with no arguments opens the interactive terminal. The first run downloads the scanner tools it needs. Type /login, approve the session in the browser that opens, and you are signed in. /whoami shows who you are.
Step 3: scan
Inside the terminal, scan the folder you are in:
/scan .
Or ask in plain language, for example "how many critical vulns do we have". When you scan from the terminal while signed in, the runner uploads the SBOM and the findings so you can see them in the platform next to your other projects. Your source stays on your machine.
Step 4: scan from a plain command
You can also run scans without the terminal. Each of these takes exactly one target:
# A local directory
safeguard scan --dir .
# A container image
safeguard scan --image nginx:latest
# A Git repository
safeguard scan --repo https://github.com/org/repo
# An SBOM you already have, SPDX or CycloneDX
safeguard scan --sbom sbom.json
Results land under ./output by default, in a folder per scan. You will find files such as vuln.json, license.json and collection.json.
Step 5: secrets and SARIF
safeguard detect --detect secrets --format sarif --output detect.sarif
The format can be a table, JSON or SARIF. SARIF is the one most CI systems and code scanning views understand. Secret values are redacted in the output unless you ask otherwise.
Exit codes you need to know
This surprises people, so read it twice. safeguard scan does not fail the build because it found vulnerabilities. It exits 0 when the scan ran, whatever it found. It exits 1 when the command itself failed, and 2 when results were written but the vulnerability scan did not actually run, so a script never mistakes that for a clean pass.
There is no severity threshold flag. If you want a pull request or pipeline to fail on findings, set that up as a policy gate in the platform.
CI notes
On a fresh CI container that has never opened the interactive terminal, the scanners are not there yet. The docs say to put syft and grype on the PATH or point the TOOLS_DIR variable at a folder that holds them. Pin the CLI version in CI so a build does not change under you:
curl -fsSL https://cli.safeguard.sh/install | SAFEGUARD_VERSION=<version> bash
Replace the placeholder with a release listed at cli.safeguard.sh/releases. To run the assistant non-interactively, safeguard exec runs one turn and exits. Its default permission mode is strict, so anything not pre-approved by policy is denied.
Keep it healthy
safeguard doctor # checks environment, sign-in, tools and policy
safeguard update # refreshes vulnerability databases
safeguard self-update # updates the binary itself
Try it yourself
Pick a repo you own with a lockfile. Install the CLI, run safeguard, sign in, and type /scan .. Then open the output folder and find the package that has the highest severity. Ask the assistant why that finding matters for your code.
To see what a dependency inventory looks like before you install anything, click through the demo below.
Click through it at your own pace, or open it full screen.
Quick check
Does a scan with critical findings make safeguard scan exit non-zero?
No. It exits 0 whenever the scan ran. Gating on findings is done by policy gates in the platform.
What leaves your machine when you scan from the signed-in terminal?
The SBOM and the findings. Your source code does not.
Why pin SAFEGUARD_VERSION in CI?
A plain install always fetches the newest release. Pinning keeps builds repeatable.
