@invariant-ai/cli

AI writes code. Invariant proves it works.

The Invariant command-line interface.

Quick Start

npx @invariant-ai/cli init -y
npx invariant run

Commands

npx invariant init

Initialize Invariant in your project. Automatically:

• Installs Playwright + @invariant-ai/cli
• Creates sample E2E test
• Installs Chromium browser
• Sets up Claude Code hooks for edit tracking

npx @invariant-ai/cli init -y

Options:

• -y, --yes - Skip prompts and use defaults
• --skip-browser-install - Skip Chromium installation
• --skip-hooks - Skip Claude Code hooks installation

npx invariant run

Run tests and capture proof artifacts.

npx invariant run

Options:

• --quick - Quick mode (fail fast, less verbose)
• --headed - Run tests in headed browser mode

npx invariant dashboard

Open the local proof dashboard to view test results and artifacts.

npx invariant dashboard

Options:

• -p, --port <port> - Port to run dashboard on (default: 4747)

Global Install (Optional)

For convenience, install globally to use bare commands:

npm install -g @invariant-ai/cli
invariant run  # works after global install

CI / GitHub Actions

Run Invariant proof on every pull request using the included GitHub Action.

# .github/workflows/invariant-proof.yml
name: Invariant Proof
on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  issues: write

jobs:
  proof:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - uses: ./packages/github-action
        with:
          fail-on-proof-failure: true

The action runs npx --no-install invariant run --ci, posts a proof summary comment on the PR, and optionally fails the step if proof fails. See packages/github-action/README.md for full documentation.

CI Flags

• --json — Output proof report as JSON to stdout (no human text)
• --ci — CI mode: implies --json, no color, no spinners

Exit codes: 0 = passed, 1 = failed, 2 = setup error.

How It Works

1. npx @invariant-ai/cli init -y sets up everything automatically
2. npx invariant run executes tests and generates proof reports
3. Your AI agent sees test results and can iterate until passing

License

MIT