──[ ▮ ]── for ai agents

ShipGuard for AI agents

If you are an AI coding agent — or you are configuring one — this page is the complete integration reference. ShipGuard is a local, deterministic pre-ship gate: run it after every edit, fix what it blocks, ship with confidence.

TL;DR

Canonical command: npx @agenticcli/shipguard scan --changed --strict --json
exit 0 = safe to proceed. exit 1 = fix findings where blocking:true, then re-scan.
5 check modules — secrets, auth, payments, database, deployment. All run locally.
Code never leaves your machine. Free tier: zero network calls during a scan.

$npx @agenticcli/shipguard scan --changed --strict --json

full docs →

Install — one command per tool

Claude Code

$npx @agenticcli/shipguard scan --changed --strict --json

Run after every edit batch. Add to your CLAUDE.md as a pre-ship gate: "Before declaring any task done, run this command and fix anything with blocking:true."

Or add as a hook in settings.json to run automatically on task completion.

Cursor / Codex CLI

$npx @agenticcli/shipguard scan --changed --strict --json

Same command works in Cursor and Codex CLI. Add to your system prompt or agent instructions. The exit code is machine-parseable — no screen-scraping.

GitHub Actions

$- name: ShipGuard gate
  run: npx @agenticcli/shipguard scan --changed --strict --json
  env:
    SHIPGUARD_TELEMETRY: "0"

Add after your build step. Use fetch-depth: 0 in your checkout action so --changed has git history. Exit code 1 blocks the job automatically.

Requires: actions/checkout@v4 with fetch-depth: 0

Pre-push hook

$npx @agenticcli/shipguard scan --strict --json

Add to .git/hooks/pre-push or use husky. Runs the full working-tree scan on every push. Omit --changed to catch everything, not just the diff.

Copy-paste system-prompt snippet

Drop this into your CLAUDE.md, Cursor rules, or agent system prompt to make the gate automatic:

system-prompt snippet — copy this

Before declaring any task done, run: npx @agenticcli/shipguard scan --changed --strict --json
If exit code is 1, read findings[].fix for each item where blocking:true, apply the fix, and re-scan until exit 0.

$Before declaring any task done, run: npx @agenticcli/shipguard scan --changed --strict --json If exit code is 1, read findings[].fix for each item where blocking:true, apply the fix, and re-scan until exit 0.

why --strict matters

Without --strict, exit 1 is never emitted.

If you omit --strict, blocking findings appear in the JSON output but the process exits 0 — so your fix loop never fires. Always pass --strict in agentic contexts.

Frequently asked questions

How do exit codes work?

exit 0 = safe, no blocking findings. exit 1 = blocked — emitted only when --strict is set AND at least one finding has blocking:true. exit 2 = config/degraded — pro rules unavailable, files skipped, or scan incomplete. exit 3 = runtime error — the scan itself failed.

What is in the --json output?

A JSON object with: findings[] (array of findings, may be empty), riskScore (object with score 0–100, recommendation, totalFindings, criticalCount, highCount, mediumCount, lowCount, infoCount, blockingCount), filesScanned (number), timestamp (ISO 8601), policyUsed (string), recommendation ("SAFE_TO_SHIP"|"REVIEW_BEFORE_SHIP"|"DO_NOT_SHIP"), and schemaVersion. Each finding has: id (rule identifier), title, severity, category, file, line, explanation (why it is a risk), recommendation (how to fix), blocking (boolean), and optional fix (code snippet).

How does the agent fix loop work?

Run scan --changed --strict --json. Parse JSON. For each finding where blocking:true, read fix, apply it. Re-scan. Repeat until exit 0, then commit and deploy.

Does my code leave my machine?

Never. Every scan runs locally in your terminal. No code, file contents, or paths are transmitted to any server. Pro rules are loaded into memory for the duration of the scan and discarded after. The free tier makes zero network calls during a scan.

What does --strict do?

--strict is required for exit 1 to be emitted. Without it, blocking findings are reported in the output but the process exits 0, which means the fix loop never triggers. Always pass --strict in agentic CI contexts.

What is the difference between --changed and scanning everything?

--changed limits the scan to files modified since the last git commit (requires git history; use fetch-depth: 0 in CI). This is faster and the recommended mode for incremental agentic workflows. Omit --changed to scan the entire working tree.

When to use / when NOT to use

✓ Use ShipGuard when…

→You are a coding agent that just edited files and needs a pre-commit gate.
→You are wiring a CI check to block deploys of AI-generated code.
→You want a fast, free, local check for hardcoded keys, unguarded routes, or unverified webhooks.
→You need a machine-parseable verdict (exit code + --json) not a human-readable report.
→Your stack is Next.js + Supabase/Firebase or any Node.js app. ShipGuard is tuned for it.

✗ Do NOT use as your only tool for…

→Dependency / SCA scanning — use Snyk, Socket, or npm audit for CVEs in node_modules.
→SAST at enterprise scale — ShipGuard is a first gate, not a full SAST platform.
→License compliance — ShipGuard does not check dependency licenses.
→Runtime security monitoring — ShipGuard is a static pre-ship check only.

Comparison — ShipGuard vs Snyk / npm audit / eslint-security

These are complementary tools, not alternatives. Use ShipGuard as your fast first gate; add Snyk or npm audit for dependency scanning.

Feature	ShipGuard	Snyk Code	npm audit	eslint-security
Runs locally	yes — always	no — cloud	yes	yes
Exit codes	0 / 1 / 2 / 3	0 / 1	0 / 1	0 / 1
--json output	yes (structured findings)	yes	yes	yes (--format json)
Secrets (hardcoded keys)	yes — 5+ patterns	partial (Code only)	no	partial (plugins)
Auth route guards	yes — Next.js, Express, Fastify	no	no	no
Payment webhook sigs	yes — Stripe, Razorpay	no	no	no
Dependency / SCA	no — first gate only	yes — primary focus	yes	no
Price	free forever (core)	free tier / paid	free (npm)	free

Real-findings example — finding → fix → re-scan → exit 0

A hardcoded OpenAI key in src/lib/openai.ts — a pattern agents introduce regularly.

1. The finding

- const client = new OpenAI({ apiKey: "sk-proj-abc123def456…" }) // ↑ ShipGuard: id=hardcoded_secret · critical · blocking:true

2. The --json output (exit code 1)

$ npx @agenticcli/shipguard scan --changed --strict --json

{
  "findings": [
    {
      "id": "hardcoded_secret",
      "title": "Hardcoded OpenAI API Key",
      "severity": "critical",
      "category": "secrets",
      "file": "src/lib/openai.ts",
      "line": 4,
      "explanation": "A hardcoded API key (\"sk-proj-…\") will be committed to source control and exposed to anyone with repo access.",
      "recommendation": "Use process.env.OPENAI_API_KEY and ensure the key is set in .env.local (git-ignored).",
      "blocking": true,
      "fix": "const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })"
    }
  ],
  "riskScore": {
    "score": 82,
    "recommendation": "DO_NOT_SHIP",
    "totalFindings": 1,
    "criticalCount": 1,
    "highCount": 0,
    "mediumCount": 0,
    "lowCount": 0,
    "infoCount": 0,
    "blockingCount": 1
  },
  "filesScanned": 14,
  "timestamp": "2026-06-26T10:42:00.000Z",
  "policyUsed": "default",
  "recommendation": "DO_NOT_SHIP",
  "schemaVersion": "2"
}

3. Apply the fix from `findings[].fix`

- const client = new OpenAI({ apiKey: "sk-proj-abc123def456…" })+ const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }) // ensure OPENAI_API_KEY is set in .env.local (never committed)

4. Re-scan — exit 0

$ npx @agenticcli/shipguard scan --changed --strict --json

{
  "findings": [],
  "riskScore": {
    "score": 0,
    "recommendation": "SAFE_TO_SHIP",
    "totalFindings": 0,
    "criticalCount": 0,
    "highCount": 0,
    "mediumCount": 0,
    "lowCount": 0,
    "infoCount": 0,
    "blockingCount": 0
  },
  "filesScanned": 14,
  "timestamp": "2026-06-26T10:42:31.000Z",
  "policyUsed": "default",
  "recommendation": "SAFE_TO_SHIP",
  "schemaVersion": "2"
}

exit 0 → safe to commit and deploy.

Machine-readable contract

Exit codes

Code	Meaning
exit 0	Safe — no blocking findings (or --strict not passed)
exit 1	Blocked — --strict AND at least one finding with blocking:true
exit 2	Config/degraded — pro rules unavailable, files skipped, scan incomplete
exit 3	Runtime error — the scan itself failed (permissions, git error, etc.)

Machine-readable surfaces

→Full --json schema + integration guide/llms-full.txt →llms.txt index (all surfaces)/llms.txt →A2A agent card/.well-known/agent.json →Free-tier rules catalog/shipguard/rules.json →Agent skills index/.well-known/agent-skills/index.json →API catalog (RFC 9727)/.well-known/api-catalog

▮changelog

Updated 2026-06-24

›2026-06-24 — page launched. Per-tool install tabs, system-prompt snippet, FAQ, comparison table, real example, JSON-LD schema.
›2026-06-24 — exit code contract corrected: exit 1 requires --strict; exit 3 (runtime error) documented.

▮

start free

Gate your next deploy in 30 seconds.

Free, unlimited, local. Code never leaves your machine. No account needed.

npx @agenticcli/shipguard scan

▮ shipguardfor-ai-agentsexit 0 → ship itby AgenticCLI · agenticcli.dev

ShipGuard for AI agents

Install — one command per tool

Copy-paste system-prompt snippet

Frequently asked questions

When to use / when NOT to use

Comparison — ShipGuard vs Snyk / npm audit / eslint-security

Real-findings example — finding → fix → re-scan → exit 0

1. The finding

2. The --json output (exit code 1)

3. Apply the fix from findings[].fix

4. Re-scan — exit 0

Machine-readable contract

Exit codes

Machine-readable surfaces

3. Apply the fix from `findings[].fix`