OSPulse CLI

The OSPulse CLI is the command-line front end to the same API the web app uses. It exists so that a build agent — or you, at a terminal, inside a project directory — can scan a dependency tree and turn the result into a pass or fail decision without writing any client code.

What it is for

Three jobs, in rough order of how often people use them:

If you need something the CLI does not do, everything it can do is reachable over the REST API, which is a supported and equally first-class path.

Authenticate

The CLI authenticates with the same API tokens as everything else. The supported way to supply one is the OSPULSE_TOKEN environment variable — that keeps the token out of your shell history, out of ps output, and out of any command you might paste into an issue.

export OSPULSE_TOKEN="$(op read op://engineering/ospulse/token)"   # or your secret manager
ospulse scan .

Create the token with the narrowest scope that works, and give CI its own token rather than sharing yours. A CI token that is revoked mid-incident should not also lock you out of your laptop.

Typical commands

ospulse scan .

ospulse watch .

ospulse policy evaluate .

ospulse scan . --format json > ospulse-scan.json
jq '[.violations[] | select(.severity == "High")] | length' ospulse-scan.json

Exit codes and CI gating

The CLI follows the standard Unix convention: 0 means the command succeeded and your gate passed; any non-zero exit means it did not. That single rule is all a pipeline needs — most CI systems fail a step automatically on a non-zero exit, so a gate is often just the command itself with nothing around it.

What matters more in practice is telling apart two very different failures:

• The gate failed — the CLI ran fine and your policy said no. This is a real finding and the build should stop.
• The CLI could not run — bad token, no network, an unparseable manifest, the API returning 5xx. This is an operational problem, and failing the build on it may be right or may be noise, depending on how much you trust your runners.

Rather than branching on specific numeric codes — which can change between versions — branch on the JSON output, which is stable and self-describing:

set +e
ospulse policy evaluate . --format json > result.json
status=$?
set -e
 
if [ "$status" -ne 0 ] && [ ! -s result.json ]; then
  echo "::warning::OSPulse could not complete — treating as infrastructure failure"
  exit 0            # or exit 1, if you want hard failures on tooling problems
fi
 
exit "$status"

In a pipeline

The CLI is designed to be a single step in an existing pipeline, not a pipeline of its own. A minimal GitHub Actions job:

name: OSPulse
 
on:
  pull_request:
  push:
    branches: [main]
 
jobs:
  supply-chain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Scan and gate
        env:
          OSPULSE_TOKEN: ${{ secrets.OSPULSE_TOKEN }}
        run: |
          ospulse scan . --format json > ospulse-scan.json
          ospulse policy evaluate . --format json > ospulse-policy.json
 
      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: ospulse
          path: ospulse-*.json

Note if: always() on the upload — you want the evidence most when the gate failed.

Scan in CI/CD covers the equivalents for GitLab CI, Azure Pipelines, and Jenkins, plus how to scope gates so pull requests are strict and nightly builds are informational.

Keeping runners current

A pinned CLI version makes builds reproducible; a pinned CLI version that nobody ever bumps makes them stale. The API exposes the current released version so you can automate the check:

curl -s https://api.ospulse.app/api/v1/cli-version

{
  "version": "1.4.2"
}

That endpoint needs no special privileges, which makes it easy to wire into a scheduled job:

latest="$(curl -s https://api.ospulse.app/api/v1/cli-version | jq -r '.version')"
current="$(ospulse --version | awk '{print $NF}')"
 
if [ "$latest" != "$current" ]; then
  echo "OSPulse CLI $current is behind $latest — update the runner image"
fi

When to use the API instead

The CLI is the right tool when the thing you want is a decision in a pipeline. Reach for the API directly when you need to:

• Query historical data — score history, trends, or audit entries — rather than the current state.
• Build a bespoke integration such as a Slack bot or an internal dashboard.
• Drive workflows the CLI does not cover, like SBOM export, CRA evidence, or warehouse export.

The two share tokens, tenancy, and policy definitions, so mixing them is normal — gate with the CLI, report with the API.

Next steps