@haystackeditor/cli

Set up Haystack verification for your project. When PRs are opened, an AI agent spins up your app in a sandbox and verifies changes work correctly.

Quick Start

Fastest: AI-Assisted Setup

npx @haystackeditor/cli skills install

This auto-detects your coding CLI (Claude Code, Codex, Cursor) and installs the Haystack MCP server.

Then invoke the setup in your coding CLI:

| CLI | How to invoke | |-----|---------------| | Claude Code | /setup-haystack | | Codex CLI | /setup-haystack or ask "set up haystack verification" | | Cursor | /setup-haystack (in Composer) |

The AI will analyze your codebase, create .haystack.json, and configure verification flows.

Alternative: Direct CLI Setup

For quick setup without AI assistance:

npx @haystackeditor/cli init

This runs an interactive wizard that auto-detects your project and creates .haystack.json.

Additional Skills

| Skill | Purpose | |-------|---------| | /setup-haystack | Start here - diagnoses project, creates config | | /prepare-haystack | Add aria-labels and data-testid for browser automation | | /setup-haystack-secrets | Configure API keys, LLM credentials, secrets |

CLI Commands

All commands can be run directly:

haystack skills

Install AI skills into your coding CLI (auto-detects Claude Code, Codex, Cursor):

npx @haystackeditor/cli skills install              # Auto-detect CLI
npx @haystackeditor/cli skills install --cli codex  # Install for Codex
npx @haystackeditor/cli skills install --cli cursor # Install for Cursor
npx @haystackeditor/cli skills install --cli manual # Show manual setup
npx @haystackeditor/cli skills list                 # List available skills

haystack init

npx @haystackeditor/cli init       # Interactive wizard
npx @haystackeditor/cli init -y    # Accept all defaults

haystack status

Check if your project is configured:

npx @haystackeditor/cli status

haystack login

Authenticate with GitHub (required for secrets management):

npx @haystackeditor/cli login

This uses GitHub's device flow - you'll get a code to enter at github.com/login/device.

# Log out (removes stored credentials)
npx @haystackeditor/cli logout

haystack secrets

Manage secrets that will be injected into your sandbox environment:

# List all secrets (keys only, values are never shown)
npx @haystackeditor/cli secrets list

# Set a secret
npx @haystackeditor/cli secrets set OPENAI_API_KEY sk-xxx

# Delete a secret
npx @haystackeditor/cli secrets delete OPENAI_API_KEY

Secrets are encrypted and stored securely. They're automatically injected as environment variables when the sandbox runs your app.

Scopes: By default, secrets are user-scoped. You can also scope to an org or repo:

# Org-scoped (available to all repos in the org)
npx @haystackeditor/cli secrets set API_KEY xxx --scope org --scope-id myorg

# Repo-scoped (available only to this repo)
npx @haystackeditor/cli secrets set API_KEY xxx --scope repo --scope-id owner/repo

Configuration

The init command creates .haystack.json:

version: "1"
name: my-app

dev_server:
  command: pnpm dev
  port: 3000
  ready_pattern: "Local:"
  env:
    SKIP_AUTH: "true"

verification:
  commands:
    - name: build
      run: pnpm build
    - name: lint
      run: pnpm lint

Customizing After Init

| If your app has... | Add this | |-------------------|----------| | Login/authentication | Auth bypass env var in dev_server.env | | Key user journeys | Flows describing what to verify | | API calls needing auth | Fixtures to mock responses |

Use /setup-haystack in Claude Code for AI-assisted configuration of flows and fixtures.

How It Works

1. Run npx @haystackeditor/cli init or use /setup-haystack in Claude Code
2. Commit the generated .haystack.json
3. Install the Haystack GitHub App
4. When PRs are opened, Haystack's AI agent:
   • Spins up your app in a cloud sandbox
   • Runs verification commands
   • Captures screenshots and evidence
   • Reports results on the PR

License

MIT