Safeguard CLI: Supply Chain Security Without Leaving Your Terminal

Developers live in the terminal. Security tooling that requires switching to a web dashboard for every check creates friction that slows adoption. The Safeguard CLI was built to eliminate that friction by bringing the full power of the Safeguard platform to the command line.

Installation and Setup

The CLI ships as a single binary for Linux, macOS, and Windows. No runtime dependencies. No package managers required for the basic install, though we also publish to Homebrew, npm, and Chocolatey for those who prefer managed installs.

# macOS
brew install safeguard-sh/tap/safeguard

# npm (cross-platform)
npm install -g @safeguard-sh/cli

# Direct download
curl -fsSL https://get.safeguard.sh | bash

Authentication uses API tokens generated from the Safeguard dashboard. Configure once and the token is stored in your system keychain:

safeguard auth login --token sg_live_xxxx

SBOM Generation

The CLI wraps established SBOM generators (Syft, Trivy) and adds Safeguard-specific enrichment on top.

# Generate from a directory
safeguard sbom generate --path ./my-project --format cyclonedx

# Generate from a container image
safeguard sbom generate --image my-app:latest --format spdx

# Generate from a lockfile
safeguard sbom generate --lockfile ./package-lock.json

The output is a standards-compliant SBOM in your chosen format. Safeguard adds enrichment during generation: Package URLs (purls) for precise component identification, CPE mappings for vulnerability correlation, and hash values for integrity verification.

You can pipe the output directly to an upload command or save it for local inspection:

# Generate and upload in one step
safeguard sbom generate --path . --format cyclonedx | safeguard sbom upload --project my-app --release v2.1.0

# Save locally
safeguard sbom generate --path . --format cyclonedx --output sbom.json

Vulnerability Scanning

The scan command runs vulnerability analysis against a project directory, container image, or existing SBOM:

# Scan a directory
safeguard scan --path ./my-project

# Scan a container image
safeguard scan --image my-app:latest

# Scan an existing SBOM
safeguard scan --sbom ./sbom.json

Results include the component name, version, CVE identifier, severity, and whether a fix is available. The default output is a table format for terminal readability, but JSON and SARIF outputs are available for integration with other tools.

# JSON output for programmatic use
safeguard scan --path . --output json

# SARIF for GitHub Advanced Security integration
safeguard scan --path . --output sarif > results.sarif

The scan uses Safeguard's vulnerability intelligence, which aggregates NVD, OSV, GitHub Advisories, and our own curated data. This means the results match what you see in the Safeguard dashboard, providing consistency between local development and CI/CD.

Policy Checks

Policy checks evaluate your project against your organization's supply chain security policies. This is the command that typically gates releases in CI/CD pipelines.

# Check policies for a project
safeguard policy check --project my-app --release v2.1.0

# Check against a local SBOM without uploading
safeguard policy check --sbom ./sbom.json

The output clearly indicates pass or fail, with details on any violations:

Policy Check: FAILED

Violations:
  [CRITICAL] Component jackson-databind@2.9.8 has 12 known vulnerabilities (3 critical)
    Policy: no-critical-vulns
    Action: Block release

  [WARNING] Component commons-io@2.6 has not been updated in 847 days
    Policy: dependency-freshness
    Action: Warn (non-blocking)

1 blocking violation(s), 1 warning(s)

Exit codes follow Unix conventions: 0 for pass, 1 for policy violations, 2 for errors. This makes integration with CI/CD systems straightforward -- the pipeline fails if the exit code is non-zero.

Supply Chain Queries

The query command connects to Griffin AI, letting you ask natural-language questions about your supply chain from the terminal:

safeguard query "which of our products use Log4j below 2.17.1?"
safeguard query "show me the dependency diff between my-app v2.0 and v2.1"
safeguard query "list all components with GPL licenses"

For structured queries, the data command provides direct access to the Safeguard API:

# List all projects
safeguard data list projects

# Get SBOMs for a specific project
safeguard data list sboms --project my-app

# Search for a specific component across all projects
safeguard data search components --name jackson-databind

CI/CD Integration

The CLI is designed for CI/CD. Here is a typical GitHub Actions workflow:

name: Supply Chain Security
on: [push]

jobs:
  supply-chain-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Safeguard CLI
        run: curl -fsSL https://get.safeguard.sh | bash

      - name: Generate SBOM
        run: safeguard sbom generate --path . --format cyclonedx --output sbom.json

      - name: Upload SBOM
        run: safeguard sbom upload --project ${{ github.repository }} --release ${{ github.sha }} --file sbom.json
        env:
          SAFEGUARD_TOKEN: ${{ secrets.SAFEGUARD_TOKEN }}

      - name: Policy Check
        run: safeguard policy check --project ${{ github.repository }} --release ${{ github.sha }}
        env:
          SAFEGUARD_TOKEN: ${{ secrets.SAFEGUARD_TOKEN }}

Equivalent configurations work in GitLab CI, Jenkins, Azure DevOps, CircleCI, and any other CI/CD system that can run shell commands. The pattern is always the same: generate, upload, check.

Local Development Workflow

Beyond CI/CD, the CLI is useful during local development. Before you add a new dependency, you can check its health score and vulnerability status:

# Check a package before adding it
safeguard check package lodash@4.17.21

Before you commit, you can run a local policy check to catch violations before the CI/CD pipeline does:

# Pre-commit check
safeguard scan --path . --exit-code

This shifts supply chain security left to the earliest possible point -- the developer's machine, before code even reaches the repository.

Configuration

The CLI supports configuration through a .safeguard.yml file in your project root, command-line flags, and environment variables. Project-level configuration is useful for setting defaults:

# .safeguard.yml
project: my-app
format: cyclonedx
policy:
  fail-on: critical,high
  warn-on: medium
scan:
  ignore:
    - CVE-2024-0001  # False positive, not reachable

Environment variables follow the SAFEGUARD_ prefix convention. Every flag has a corresponding environment variable, which makes CI/CD configuration clean.

Performance

The CLI is built in Go for fast startup and low resource usage. SBOM generation for a typical Node.js project with 500 dependencies completes in under 10 seconds. Vulnerability scanning against a 1000-component SBOM completes in under 5 seconds. Policy checks complete in under 2 seconds.

These timings matter in CI/CD where every added minute to the pipeline faces pushback from development teams. The entire Safeguard pipeline step (generate + upload + check) typically adds less than 30 seconds to a build.

Getting Started

Install the CLI, configure your authentication token, and run safeguard scan --path . in any project directory. You will get a vulnerability report in seconds, with no prior setup required beyond the authentication.

For the full CI/CD integration, add the SBOM generation and policy check steps to your pipeline. Most teams have this running in production within an hour of starting the setup.