CLI

Install and use the Foo Guard CLI for local scans and CI enforcement.

Page text and source link for your AI assistant. Nothing is sent automatically.

Installation

From this repository:

npm run cli:build
npm link --prefix packages/cli

Or from npm (https://www.npmjs.com/package/fooguard):

npm install -g fooguard

Plan requirements

CLI access requires a Pro personal API key or Team organization service key. Free and Individual plans do not include CLI access.

Authentication

export FOOGUARD_API_KEY=agt_live_...
export FOOGUARD_API_URL=https://fooguard.com

Team organization service keys use the agt_team_... prefix.

Common commands

fooguard --help
fooguard scan --help
fooguard scan ./agents --fail-on high
fooguard scan ./agents --fail-on high --min-grade B

Exit codes (CI enforcement)

The CLI exit code is the enforcement signal for CI pipelines:

Code	Meaning	CI behavior
`0`	Policy passed	Pipeline step succeeds
`1`	Security policy failed	Pipeline step fails — findings or grade violated policy
`2`	Operational or configuration error	Pipeline step fails — parser error, API error, invalid config, etc.

fooguard scan ./agents --fail-on high
echo $?   # 0 = pass, 1 = policy violation, 2 = error

Use exit code 1 as your CI security gate. This works in any CI platform — not just GitHub Actions.

Distinguishing policy failure from errors

Exit 1 means the scan ran successfully but policy was not met (findings at/above failOn, or grade below minGrade)
Exit 2 means the scan could not complete (network failure, unsupported file, usage limit, etc.)

Policy sources

Effective policy merges organization policy (Team), repository .fooguard.yml, and CLI flags. The strictest threshold wins.

# CLI override for a single run
fooguard scan ./agents --fail-on critical --min-grade A

See `.agentguard.yml` and CI/CD enforcement.

Baseline regression

fooguard scan ./agents --baseline --baseline-path .agentguard.baseline.json

See Baselines.

The CLI uses the same deterministic analysis engine as the REST API and web analyzer.

Export SARIF

Use --sarif-out to write deterministic findings as SARIF 2.1.0:

fooguard scan ./agents --sarif-out fooguard-results.sarif

The file is written even when policy fails. Exit codes remain unchanged: 0 means policy passed, 1 means policy failed, and 2 means an operational error. An incomplete scan has executionSuccessful: false; do not upload it as a clean replacement for a complete scan. Failures before scanning starts may produce no file. Use a fresh output path for each job to avoid reusing stale results. Existing output files are never overwritten; choose a new filename or deliberately remove the old export before rerunning.

The export includes rule IDs, deterministic explanations and remediation hints, original severity, file-level security scores and grades. Critical/high map to SARIF error, medium/low to warning, and informational findings to note. This mapping is not a CVSS score. Source snippets, raw configuration, credential evidence, and AI-generated remediation are excluded.

Run the CLI from your repository root so file paths match the checkout. CLI exports provide file-level locations; they do not invent source line numbers. The GitHub upload action can generate fingerprints from the checkout. Do not assume direct API uploads without fingerprint generation will deduplicate alerts.

Download from the dashboard

Choose Download SARIF beside the existing report actions on scan results. Personal and Team saved analyses, including skill scans, export the findings already visible to you. Pasted/saved analyses without a retained repository path omit physical locations. Repository scan exports use recorded source lines when available; older scans without detailed findings need a fresh scan before they can be exported.

SARIF export does not change workspace access, plan allowances, findings, or policy. Downloaded files leave Foo Guard's access controls: share them only with the intended recipients.