CLI Usage

This page covers the commands you run directly, outside the interactive terminal. Most people start with the terminal instead: run safeguard, type /login, then /scan .. See Interactive terminal and Slash commands.

safeguard --help lists every command in the build you have, and safeguard <command> --help lists its flags. If this page and --help disagree, --help is right.

Command structure

safeguard <command> [subcommand] [flags]

Sign in

Authentication is an OAuth 2.0 device-code flow. It works the same from the terminal (/login) and from the command line:

# Opens your browser; approve the session there
safeguard login

# On a machine with no browser: prints a URL and a code to enter elsewhere
safeguard login --no-browser

# Who am I signed in as, and when does the token expire
safeguard whoami

# Revoke the session and remove the local token
safeguard logout

The token is stored on the machine that signed in. There is no API-key environment variable for the CLI: a machine is authorized by signing in once.

Scan

safeguard scan builds an SBOM for a target, matches it against vulnerability databases, and writes the results as JSON files under --output (default ./output). It takes exactly one target:

# A local directory (your own or proprietary code)
safeguard scan --dir .

# A container image
safeguard scan --image nginx:latest

# A private registry
safeguard scan --image myregistry.azurecr.io/myapp:v1 \
  --registry-username "$REGISTRY_USER" \
  --registry-password "$REGISTRY_PASSWORD"

# A Git repository
safeguard scan --repo https://github.com/org/repo

# A private repository
safeguard scan --repo https://github.com/org/private-repo --git-token "$GIT_TOKEN"

# An SBOM you already have (SPDX or CycloneDX, detected automatically)
safeguard scan --sbom sbom.json

Useful flags:

Results include vuln.json, license.json and collection.json, among others, in a folder per scan. To see them in the platform alongside your other projects, scan from the interactive terminal (/scan .) while signed in: the runner uploads the SBOM and findings, never your source.

Exit codes

safeguard scan does not fail on findings. It exits 0 when the scan ran, whatever it found, 1 when the command itself failed (a bad flag, an unreadable target), 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; gating on findings is done by policy gates in the platform.

Find secrets and misconfigurations

# Secrets and misconfigurations in the current directory
safeguard detect

# Only secrets, as SARIF, written to a file
safeguard detect --detect secrets --format sarif --output detect.sarif

# Only report high and critical
safeguard detect --severity high

--format takes table (default), json or sarif. Values are redacted in the output unless you pass --redact=false.

Validate an SBOM

safeguard validate sbom.json
safeguard validate ./sboms --recursive
safeguard validate sbom.json --strict -o report.json

It checks CycloneDX (JSON and XML), SPDX (JSON, YAML, tag-value and RDF) and VEX (CSAF and OpenVEX) documents against their specifications. --strict treats warnings as errors, and --fail-fast stops at the first error.

Fix and review

# Update vulnerable dependencies
safeguard fix --help

# Review the working-tree changes for correctness and security
safeguard review --help

# Run the assistant non-interactively, for example in CI
safeguard exec "summarise the critical findings in this repository"

safeguard exec runs one agent turn and exits. Its default permission mode is strict: nothing is asked and anything the policy file has not pre-approved is denied. It refuses to run outside a git repository unless you pass --skip-git-repo-check. --output-format json gives a machine-readable result.

Keep it current

# Refresh the vulnerability databases (grype and trivy)
safeguard update

# Update the safeguard binary itself
safeguard self-update

# Check whether a new release exists without installing it
safeguard self-update --check

Check the installation

safeguard doctor

doctor checks the environment, sign-in, tools and policy, and prints what is wrong in the order that matters. It changes nothing and exits 0 whenever the checks ran, so read its lines rather than its exit code.

Ask for help

safeguard support ask "how do I scope a DAST scan to one host?"
safeguard support bug "the scan reported zero findings on a repo with known CVEs"
safeguard support feedback "the findings table should remember my filters"
safeguard support list
safeguard support show SUP-7KQ4-M2XD
safeguard support reply SUP-7KQ4-M2XD "it happens on every scan of that repo"

These raise the same tickets as the product's Help & Feedback sheet, and you follow them in the app's Messages › Support too. You need to be signed in. --priority low|normal|high|urgent sets the urgency (default normal), and --yes answers the confirmation in advance. In the interactive terminal, /bug, /feedback and /support do the same. See Help and support.

Environment variables

The CLI has no API-key variable and no config-file path variable. The ones you are most likely to want:

The installer reads its own variables, listed on Installation.

Getting help

safeguard --help
safeguard scan --help
safeguard detect --help
safeguard validate --help

Next Steps

• Configure the CLI
• Troubleshoot issues
• View support matrix