Shipgate CLI v2.1.0

ShipGate — Stop AI from shipping fake features. Define what your code should do. We enforce it.

The Shipgate CLI is your command-line gateway to Intent Specification Language (ISL) — a formal language for specifying what your code must do. With ISL, you can define behavioral contracts, generate code, and verify that AI-generated implementations match your intentions.

🚀 Quick Start

Installation

# Install globally (recommended)
npm install -g shipgate

# Or use npx (no installation required)
npx shipgate <command>

# Verify installation
shipgate --version

Your First Project

# Initialize a new project
npx shipgate init my-api
cd my-api

# Check the generated spec
npx shipgate check src/*.isl

# Generate TypeScript code
npx shipgate generate --target typescript src/

# Verify implementation
npx shipgate verify src/my-api.isl --impl ./src

📋 Commands Overview

| Command | Purpose | Key Features | |---------|---------|--------------| | init | Create new ISL project | Auto-configuration, templates | | check | Parse & validate ISL files | Type checking, syntax validation | | generate | Code from ISL specs | TypeScript, Python, Rust, Go, OpenAPI | | verify | Verify implementation | Behavioral verification, evidence | | gate | SHIP/NO-SHIP decision | CI integration, trust scoring | | parse | Inspect ISL AST | Debug specifications | | repl | Interactive ISL shell | Explore ISL interactively |

🛠️ Detailed Command Reference

shipgate init [name]

Initialize a new ISL project with recommended structure and configuration.

# Initialize in current directory
npx shipgate init

# Create new project directory
npx shipgate init my-project
cd my-project

# Skip prompts (use defaults)
npx shipgate init -y

# Overwrite existing config
npx shipgate init --force

Creates:

my-project/
├── src/
│   └── my-project.isl     # Example specification
├── generated/             # Code output directory
├── isl.config.json        # Project configuration
├── package.json           # Node.js project setup
└── README.md              # Project documentation

shipgate check <files...>

Parse and type-check ISL files with comprehensive error reporting.

# Check all ISL files
npx shipgate check src/**/*.isl

# Strict mode (warnings become errors)
npx shipgate check --strict src/

# JSON output for CI
npx shipgate check --format json src/ > results.json

# Quiet mode (minimal output)
npx shipgate check --quiet src/

Options:

• --strict - Enable strict mode (all warnings become errors)
• --format <format> - Output format: pretty, json, quiet
• --config <path> - Custom config file path

Exit Codes:

• 0 - All checks passed
• 1 - Errors found

shipgate generate <files...>

Generate production-ready code from ISL specifications.

# Generate TypeScript
npx shipgate generate --target typescript src/

# Generate Python with custom output
npx shipgate generate --target python --output src/generated src/

# Generate OpenAPI spec
npx shipgate generate --target openapi src/api.isl

# Generate Rust types
npx shipgate generate --target rust --output src/types src/

Supported Targets:

• typescript - TypeScript types and interfaces
• python - Python dataclasses and type hints
• rust - Rust structs and enums
• go - Go structs and interfaces
• openapi - OpenAPI 3.0 specifications
• graphql - GraphQL schemas

Options:

• --target, -t - Target language (required)
• --output, -o - Output directory (default: generated/)
• --config, -c - Config file path
• --watch - Watch for changes and regenerate

shipgate verify <files...>

Verify implementation against ISL specifications.

npx shipgate verify specs/critical-flow.isl --impl ./src

shipgate parse <file>

Parse an ISL file and display the AST.

npx shipgate parse specs/example.isl

shipgate gate <files...>

Run the ShipGate (SHIP/NO-SHIP gate) on ISL files.

npx shipgate gate specs/
npx shipgate gate --ci --output json

shipgate proof badge <bundle-path>

Generate a badge (SVG or URL) from a proof bundle for display in README or CI.

# Generate SVG badge
npx shipgate proof badge ./proof-bundle -o badge.svg

# Generate badge URL
npx shipgate proof badge ./proof-bundle --format url --bundle-url https://example.com/bundle

# With custom badge service
npx shipgate proof badge ./proof-bundle --format url --badge-url-base https://badges.example.com

The badge displays the proof verdict (PROVEN, INCOMPLETE, VIOLATED, UNPROVEN) with color coding:

• 🟢 PROVEN - Green badge
• 🟡 INCOMPLETE_PROOF - Yellow badge
• 🔴 VIOLATED - Red badge
• ⚪ UNPROVEN - Grey badge

shipgate proof attest <bundle-path>

Generate SLSA-style attestation JSON from a proof bundle for supply chain security.

# Output to stdout
npx shipgate proof attest ./proof-bundle

# Save to file
npx shipgate proof attest ./proof-bundle -o attestation.json

# Include full manifest
npx shipgate proof attest ./proof-bundle --include-manifest -o attestation.json

The attestation includes:

• Verdict and reason
• Spec information (domain, version, hash)
• Gate, build, and test results
• Toolchain versions
• Bundle fingerprint

shipgate proof comment <bundle-path>

Generate GitHub PR comment from a proof bundle.

# Output to stdout (for GitHub Actions)
npx shipgate proof comment ./proof-bundle

# Save to file
npx shipgate proof comment ./proof-bundle -o pr-comment.md

The comment includes:

• Verdict summary with emoji indicators
• Phase-by-phase breakdown (Gate, Build, Tests, Verify)
• Spec and toolchain information
• Bundle ID and generation timestamp

shipgate repl

Start an interactive REPL for exploring ISL.

npx shipgate repl

Configuration

The init command creates isl.config.json in your project root:

{
  "defaultTarget": "typescript",
  "strictMode": true,
  "outputDir": "./generated",
  "include": ["src/**/*.isl"],
  "exclude": ["src/drafts/**"],
  "output": {
    "types": true,
    "tests": true,
    "docs": false
  }
}

Environment Variables

• ISL_CONFIG - Path to config file
• ISL_DEBUG - Enable debug output
• ISL_NO_COLOR - Disable colored output
• ANTHROPIC_API_KEY - API key for AI-enhanced features (optional)

Examples

Initialize a project

# In current directory
npx shipgate init

# Or create a new folder
npx shipgate init my-project

This creates:

• src/my-project.isl - Example ISL specification
• isl.config.json - Configuration file
• package.json - Node.js project file

Check ISL files

npx shipgate check src/*.isl

Generate TypeScript types

npx shipgate generate --target typescript src/

Documentation

• Full documentation: https://shipgate.dev/docs
• GitHub: https://github.com/guardiavault-oss/ISL-LANG

License

MIT