ShipGate CLI v3.0.0

Tier‑1: block risky AI-assisted merges on GitHub pull requests for Next.js (App Router) — CI runs shipgate next --strict (golden path: shipgate-next composite) → NO_SHIP fails the job when you configure it as a required check in your repo → fix hints → optional JSON/Markdown export. No ShipGate cloud account required for this path — see docs/data-handling.md · docs/security.md. The ShipGate monorepo runs three enforced Tier‑1 jobs in ci.yml (next-mini fixture, shipgate-dashboard, docs-site) and a shipgate-pr-gate on the same roots — see docs/dogfooding-status.md.

Advanced (optional): ISL specs, codegen, go / scan / vibe, and the proof bundle flow stay available for teams that want specifications — they are not the headline buyer journey.

GitHub PR  →  CI runs shipgate next  →  SHIP / NO_SHIP  →  optional evidence files

Quick Start (Tier‑1)

npm install -g @shipgate.dev/cli

# From your Next.js app root (same folder as package.json):
shipgate next . --strict --format quiet --ci

# Golden-path artifacts for PR comments / audits (schemas in this package):
shipgate next . --strict --format quiet --ci \
  --evidence-out .shipgate/shipgate-next-evidence.json \
  --summary-out .shipgate/shipgate-next-summary.md

Copy-paste CI: monorepo examples/golden-path-next. Positioning matrix: docs/supported-matrix.md. Runtime modes & env: docs/runtime-modes.md · .shipgate.yml: docs/config-semantics.md · GitHub Actions: docs/github-actions.md · Deprecations: docs/deprecations.md.

AI code provenance (audit trail)

Line-level who wrote what: git blame + commit trailers (Copilot, Cursor, Claude Code, etc.), per file or whole project. Use it for review packs, compliance questions, and the hosted dashboard.

shipgate provenance                    # project summary
shipgate provenance src/api.ts       # single-file blame
shipgate provenance --format json    # machine-readable export
shipgate provenance init             # pre-commit hook + session file (AI-Tool trailer)
shipgate provenance upload --scan    # summary → dashboard (after shipgate auth login)

Docs: CLI: provenance (this repo’s docs site). CI: shipgate/gate-action and shipgate/isl-verify can emit ai-percentage, top-agent, and total-lines on PRs when provenance is enabled (default on).

Quick Start (best-effort)

# Broad pipeline — useful, but not the Tier‑1 Next.js PR wedge:
shipgate go

# Natural language → code (bring your own AI keys where required):
shipgate vibe "build a todo API with auth and JWT"

Pricing

ShipGate is built to work for everyone. Starter membership is $29 — full CLI, AI spec generation (bring your own OPENAI_API_KEY or ANTHROPIC_API_KEY), verify and gate. Learn more →

Trust: Tier-1 vs best-effort

Tier‑1 for commercial positioning is shipgate next on Next.js App Router + GitHub PRs — see Supported path, Tier-1 supported surface, and exit codes (source: packages/docs/src/content/docs/trust/ in this repo). Repo matrix: docs/supported-matrix.md.

Commands

Core workflows

| Command | What it does | |---------|-------------| | shipgate next [path] | Tier‑1 Next.js App Router gate: routes, env vs .env*, specless checks → SHIP/NO_SHIP. Optional .shipgate/next.yml. Use --evidence-out / --summary-out for JSON + Markdown (schema: schemas/golden-path-evidence.schema.json). | | shipgate go [path] | Best-effort: detect → scan → optional provenance → gate. Not the primary Next.js PR story. | | shipgate go --fix | Go + auto-heal violations | | shipgate go --deep | Go with thorough scan and higher coverage target | | shipgate vibe "<prompt>" | Best-effort: NL → ISL spec → codegen → verify → SHIP/NO_SHIP | | shipgate vibe "<prompt>" --lang python | Vibe in Python (also: rust, go, typescript) | | shipgate scan <path> | Best-effort: scan codebase, AI-generate ISL specs, coverage + gate verdict. Dashboard: uploads findings when logged in (shipgate auth login) on a local run; in CI/automation (or --ci), upload is off unless you pass --upload. See repo docs/data-handling.md. |

Verification

| Command | What it does | |---------|-------------| | shipgate verify <path> | Advanced: verify implementation against ISL specs + evidence bundle | | shipgate gate <spec> --impl <path> | Advanced: SHIP/NO_SHIP vs .isl spec. Use in CI with --ci | | shipgate check <files...> | Parse and type-check ISL files | | shipgate heal <path> | AI-powered auto-fix for spec violations |

Code Generation

| Command | Target | |---------|--------| | shipgate gen ts <file.isl> | TypeScript types, interfaces, validators | | shipgate gen python <file.isl> | Python Pydantic models, pytest tests | | shipgate gen rust <file.isl> | Rust structs, traits, Serde derives | | shipgate gen go <file.isl> | Go structs, interfaces | | shipgate gen graphql <file.isl> | GraphQL schema | | shipgate gen openapi <file.isl> | OpenAPI 3.0 specification |

Analysis & Compliance

| Command | What it does | |---------|-------------| | shipgate policy list | Show all policy rules from the bundled manifest (count varies by version) with severity and remediation | | shipgate trust-score | Detailed trust breakdown | | shipgate coverage | Spec coverage per file | | shipgate drift | Code vs spec divergence detection | | shipgate security-report | Secrets, auth gaps, injection risks | | shipgate compliance soc2 | SOC 2 compliance audit | | shipgate provenance | Line-level AI attribution (project summary, per-file blame, JSON/CSV export) | | shipgate provenance upload | Send provenance JSON to the dashboard (POST /api/v1/provenance/upload); use --file <path> or --scan; requires shipgate auth login and dashboard projectId (or defaultProjectId in config) | | shipgate provenance init | Install pre-commit hook + session file for AI tool tagging |

Utilities

| Command | What it does | |---------|-------------| | shipgate init [name] | Scaffold .shipgate.yml, specs dir, CI workflow (Next.js → shipgate-next.yml; else shipgate.yml) | | shipgate fmt <path> | Auto-format ISL files | | shipgate lint <path> | Lint ISL files for errors | | shipgate repl | Interactive ISL shell | | shipgate proof badge <bundle> | Generate SHIP/NO_SHIP badge SVG | | shipgate proof attest <bundle> | SLSA-style attestation JSON | | shipgate proof comment <bundle> | Advanced: GitHub PR comment from a spec proof bundle (for Next.js without specs, use next --summary-out) |

The next command (Tier‑1)

Use on pull requests in CI; in consumer repos you may mark the job as a required check after validation. From the app root:

shipgate next . --strict --format quiet \
  --evidence-out .shipgate/shipgate-next-evidence.json \
  --summary-out .shipgate/shipgate-next-summary.md

Non-zero exit on NO_SHIP fails the job. See examples/golden-path-next.

The go command (best-effort)

The fastest way to run a broad pipeline on many stacks — not the same promise as shipgate next for Next.js PRs. One command, zero configuration:

shipgate go

Pipeline:

detect → init → infer ISL → truthpack → verify → gate → report

1. Detect — identifies your stack (TypeScript, Python, Rust, Go, or mixed)
2. Init — creates .shipgate.yml and directory structure if missing
3. Infer — AI-generates ISL specs from your source code using spec-assist
4. Truthpack — extracts routes, env vars, auth rules from your codebase
5. Verify — checks code against the inferred specs
6. Gate — SHIP / WARN / NO_SHIP with a coverage score
7. Report — formatted output with next steps

shipgate go .              # Scan current dir
shipgate go ./my-project   # Scan target dir
shipgate go --fix          # Auto-heal violations after scan
shipgate go --deep         # Thorough scan, higher coverage target
shipgate go --provider openai --model gpt-4o  # Custom AI provider

The Vibe pipeline (best-effort)

Go from an English description toward verified code (requires AI keys where applicable):

shipgate vibe "build a todo app with auth and Stripe payments"

Pipeline:

NL prompt → ISL spec → validate → generate code → verify → heal → SHIP

Supports multiple languages:

shipgate vibe "REST API for user management" --lang typescript  # default
shipgate vibe "REST API for user management" --lang python      # FastAPI + pytest
shipgate vibe "REST API for user management" --lang rust        # Axum + cargo
shipgate vibe "REST API for user management" --lang go          # Gin + go test

Multi-language codegen (advanced)

Generate code from ISL specs in 6 languages:

shipgate gen ts auth.isl         # TypeScript
shipgate gen python auth.isl     # Python (Pydantic, pytest, type stubs)
shipgate gen rust auth.isl       # Rust (Serde, traits, validation)
shipgate gen go auth.isl         # Go (structs, interfaces)
shipgate gen graphql auth.isl    # GraphQL schema
shipgate gen openapi auth.isl    # OpenAPI 3.0 YAML

ISL in 60 seconds (advanced)

When you adopt specifications, ISL (Intent Specification Language) defines what your code must do — not how:

domain PaymentService {
  entity Payment {
    id: UUID [immutable, unique]
    amount: Decimal [positive]
    status: PaymentStatus

    invariants {
      amount > 0
      status in ["pending", "completed", "failed"]
    }
  }

  behavior ChargeCard {
    input { cardToken: String, amount: Decimal, currency: String }
    output {
      success: { paymentId: UUID }
      errors { CARD_DECLINED, INSUFFICIENT_FUNDS }
    }

    preconditions {
      input.amount > 0
      input.currency.length == 3
    }

    postconditions {
      success implies Payment.exists({ id: result.paymentId, status: "completed" })
    }
  }
}

CI Integration

Add to any GitHub Actions workflow:

- name: ShipGate
  run: |
    npx @shipgate.dev/cli go . --ci

Or the full workflow:

- name: ShipGate Verify
  run: |
    npx @shipgate.dev/cli verify . --ci --format github
    npx @shipgate.dev/cli gate specs/ --impl src/ --ci

Environment Variables

| Variable | Purpose | |----------|---------| | ANTHROPIC_API_KEY | Anthropic API key for AI features (spec inference, vibe, heal) | | OPENAI_API_KEY | OpenAI API key (alternative to Anthropic) | | ISL_CONFIG | Path to config file | | ISL_DEBUG | Enable debug output | | ISL_NO_COLOR | Disable colored output |

The CLI auto-detects which AI provider to use based on available API keys. Anthropic is preferred when both are set.

Project Structure

.shipgate.yml            # Config: thresholds, ignore patterns, AI provider
.shipgate/
  specs/                 # ISL specifications
  evidence/              # Evidence bundles per verification run
  truthpack/             # Auto-extracted routes, env vars, auth rules

pnpm run build runs prebuild first, which regenerates tsup.aliases.json (gitignored) from your local workspace paths. Do not commit that file.

Links

• Documentation
• ISL Reference
• VS Code Extension
• GitHub
• npm — @shipgate.dev/cli

License

MIT