Quick Start
ShipGuard runs locally and gates your release with deterministic exit codes. No account, no upload — install and scan in under 30 seconds. Tuned for Next.js + Supabase / Firebase apps that ship to Vercel.
Install
$ npm i -g @agenticcli/shipguard
Or run once without installing: npx @agenticcli/shipguard scan.
Quick start
Scaffold a policy file, then run your first scan:
Use --changed in CI to scan only files modified in the current PR — it keeps scans under 2 seconds.
Commands
| command | what it does |
|---|---|
| shipguard init | create shipguard.policy.yml and .shipguard/ |
| shipguard scan | run all enabled checks on the repo |
| scan --changed | only scan files changed since last commit |
| scan --report | write a Markdown report to .shipguard/reports/ |
| scan --strict | exit 1 on any high / critical finding (for CI) |
| scan --json | emit machine-readable findings for agents |
Exit codes
| code | meaning | action |
|---|---|---|
| exit 0 | scan completed — verdict is in the JSON "recommendation" field | read recommendation, then ship or fix |
| exit 1 | blocked — only with --strict, and only if a finding is blocking | fix and re-scan |
| exit 2 | config error | check shipguard.policy.yml |
| exit 3 | runtime error | file an issue |
CI integration
# .github/workflows/gate.yml
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- run: npx @agenticcli/shipguard scan --changed --strict
Without
fetch-depth: 0, git may not have enough history for --changed to compute the diff.Policy file
Optional shipguard.policy.yml at the project root controls which findings block, which warn, and which paths to ignore:
version: 1
block:
- hardcoded_secret
- payment_webhook_without_signature_check
- supabase_rls_disabled
warn:
- missing_input_validation
ignore:
paths: ["node_modules/**", ".next/**"]