npm package: @shipgate.dev/cli
Description: ShipGate — merge gate for Next.js on GitHub PRs (`shipgate next`). SHIP/NO_SHIP plus optional spec workflows.
Author: ShipGate Contributors
Latest version: 3.0.1

# ShipGate CLI v3.0.0

[![npm version](https://badge.fury.io/js/@shipgate.dev%2Fcli.svg)](https://badge.fury.io/js/@shipgate.dev%2Fcli)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/npm/dm/@shipgate.dev/cli)](https://www.npmjs.com/package/@shipgate.dev/cli)

> **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)

```bash
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`](../../examples/golden-path-next/README.md). Positioning matrix: [`docs/supported-matrix.md`](../../docs/supported-matrix.md). **Runtime modes & env:** [`docs/runtime-modes.md`](../../docs/runtime-modes.md) · **`.shipgate.yml`:** [`docs/config-semantics.md`](../../docs/config-semantics.md) · **GitHub Actions:** [`docs/github-actions.md`](../../docs/github-actions.md) · **Deprecations:** [`docs/deprecations.md`](../../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.

```bash
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](/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)

```bash
# 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 →](https://shipgate.dev)

---

## Trust: Tier-1 vs best-effort

**Tier‑1** for commercial positioning is **`shipgate next`** on **Next.js App Router** + **GitHub PRs** — see **[Supported path](https://shipgate.dev/getting-started/supported-path/)**, **[Tier-1 supported surface](https://shipgate.dev/trust/tier-1-surface/)**, and **[exit codes](https://shipgate.dev/trust/exit-codes/)** (source: `packages/docs/src/content/docs/trust/` in this repo). Repo matrix: [`docs/supported-matrix.md`](../../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:

```bash
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`](../../examples/golden-path-next/README.md).

---

## 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:

```bash
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

```bash
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):

```bash
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:

```bash
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:

```bash
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:

```isl
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:

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

Or the full workflow:

```yaml
- 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](https://shipgate.dev/)
- [ISL Reference](https://shipgate.dev/isl-reference/)
- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=shipgate.shipgate-isl)
- [GitHub](https://github.com/Ship-Gate/ShipGate)
- [npm — `@shipgate.dev/cli`](https://www.npmjs.com/package/@shipgate.dev%2Fcli)

## License

MIT