@haystackeditor/cli

Set up Haystack for your project. When PRs are opened, Haystack automatically reviews them for bugs, instruction drift, and rule violations — then routes them to the right place.

Quick Start

npm install -g @haystackeditor/cli
haystack login
haystack setup

The setup command walks you through an interactive wizard:

1. Select repositories to configure
2. Scan for coding rules (conventions your team follows)
3. Scan for CI/bot signals (checks to wait for before merging)
4. Scan for review policies (who should review what)
5. Review and toggle discovered items
6. Write .haystack.json to your repos

CLI Commands

haystack setup

Interactive onboarding wizard — scan your repos and generate .haystack.json:

haystack setup

haystack init

Quick local setup — auto-detects your project and creates .haystack.json without scanning:

haystack init              # Auto-detect and create config
haystack init --force      # Overwrite existing .haystack.json

haystack status

Check if your project is configured:

haystack status

haystack login

Authenticate with GitHub (required for setup and secrets):

haystack login

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

# Log out (removes stored credentials)
haystack logout

haystack submit

Create a PR from current changes. Runs pre-PR triage (code review, rules validation, instruction drift), pushes your branch, and opens the PR.

haystack submit                      # Triage -> create PR -> wait for analysis
haystack submit --auto-fix           # Discouraged alpha auto-fix for straightforward mechanical issues
haystack submit --title "Fix auth"   # Custom PR title
haystack submit --draft              # Create as draft PR
haystack submit --force              # Skip triage checks
haystack submit --no-wait            # Don't wait for analysis results

Review routing: By default, PRs go to the auto-merge queue -- if analysis passes, the PR is merged automatically. Use --review to route it for human review instead:

haystack submit --review             # Needs review (goes to assignment queue)
haystack submit --review octocat     # Request review from a specific teammate

When --review is used without a username, the PR is labeled haystack:needs-review and appears in your team's assignment queue. When a username is provided, that person is also requested as a reviewer on GitHub.

The --auto-fix flag is an alpha feature and is discouraged by default. It opts into a sandbox agent that attempts straightforward mechanical fixes before surfacing issues in the Feed. For most PRs, prefer plain haystack submit.

haystack triage

View Haystack analysis results for any PR. Shows the same data as the Haystack web feed: rating, verdict, structured findings with details, verified bugs, human review reasons, and agent fix prompts.

haystack triage                             # Last submitted PR
haystack triage 42                          # Current repo, PR #42
haystack triage owner/repo#99               # Fully qualified
haystack triage https://github.com/o/r/pull/1  # From GitHub URL
haystack triage 42 --json                   # Machine-readable JSON output
haystack triage 42 --no-wait                # Don't wait if analysis is pending
haystack triage --hook                      # Minimal one-liner (for session hooks)
haystack triage --clear                     # Clear pending submit state

When called without a PR identifier, checks the last PR submitted via haystack submit. The --hook flag produces a single-line summary with the Haystack rating and auto-fixer status, designed for session-start hooks.

The --json output includes agentFixPrompt fields -- ready-to-paste instructions for coding agents to fix each finding.

haystack dismiss

Dismiss analysis findings for a PR, moving it from "Issues Found" to "Good to Merge" in the feed. The override is tied to the PR's current HEAD commit.

haystack dismiss 42                  # Dismiss findings for PR #42
haystack dismiss acme/widgets#99     # Dismiss for specific repo

haystack undismiss

Clear all overrides (dismissed findings and/or review-not-needed) for a PR, returning it to its original feed bucket.

haystack undismiss 42                # Undo overrides for PR #42
haystack undismiss acme/widgets#99   # Undo for specific repo

haystack mark-reviewed

Mark human review as not needed for a PR, moving it from "Needs Review" to "Good to Merge" in the feed. The override is tied to the PR's current HEAD commit.

haystack mark-reviewed 42                  # Mark review not needed for PR #42
haystack mark-reviewed acme/widgets#99     # Mark for specific repo

haystack pr-status

Show what bucket a PR is in within the Haystack pipeline (analyzing, auto-fixing, good-to-merge, issues, needs-assignment, etc.):

haystack pr-status 42                          # Current repo, PR #42
haystack pr-status acme/widgets#99             # Specific repo
haystack pr-status https://github.com/o/r/pull/1  # From URL
haystack pr-status 42 --json                   # Machine-readable output

haystack config

Manage user preferences:

# Agentic tool selection
haystack config agentic-tool              # Show current setting
haystack config agentic-tool opencode     # Use Haystack billing (default)
haystack config agentic-tool claude-code  # Use your Claude Max subscription
haystack config agentic-tool codex        # Use your ChatGPT subscription

# Auto-merge for safe PRs
haystack config auto-merge           # Show current status
haystack config auto-merge on        # Enable auto-merge
haystack config auto-merge off       # Disable auto-merge

# AI reviewer wait list (merge queue waits for ALL configured bots before merging)
haystack config wait-for-reviewers                    # Show status
haystack config wait-for-reviewers add cursor         # Wait for Cursor BugBot
haystack config wait-for-reviewers add cursor coderabbit  # Add multiple
haystack config wait-for-reviewers remove cursor      # Stop waiting
haystack config wait-for-reviewers clear              # Wait for none
# Also accepts raw GitHub bot usernames:
haystack config wait-for-reviewers add cursor-bugbot[bot]

haystack skills

Manage AI skills for your coding CLI:

haystack skills install              # Auto-detect CLI and install
haystack skills install --cli codex  # Install for Codex only
haystack skills install --cli manual # Show manual setup instructions
haystack skills list                 # List available skills

haystack hooks

Manage git hooks for AI agent quality checks:

# Install hooks + Entire CLI
haystack hooks install               # Install with pinned Entire version
haystack hooks install --force       # Overwrite existing hooks
haystack hooks install --skip-entire # Only install Haystack hooks

# Status and updates
haystack hooks status                # Check installation status
haystack hooks update                # Update Entire CLI to latest

# Session hooks (triage on CLI start)
haystack hooks install-session              # Auto-detect CLIs
haystack hooks install-session --cli claude # Claude Code only
haystack hooks install-session --cli all    # All detected CLIs
haystack hooks session-status               # Check session hook status

haystack policy

Manage review policies (.haystack/review-policy.md):

# List and inspect
haystack policy list                          # List all policies

# Add policies
haystack policy add                           # Interactive add
haystack policy add "Database changes"        # Start with name
haystack policy add-instruction "Never flag weak test coverage as needing review"

# Remove policies
haystack policy remove "Database changes"

# Initialize with defaults
haystack policy init                          # Create with sensible defaults
haystack policy init --force                  # Overwrite existing

Configuration

The setup wizard writes .haystack.json to your repos with discovered rules, signals, and policies. You can also create a base config locally with haystack init:

{
  "version": "1",
  "name": "my-app"
}

How It Works

1. Run haystack setup to configure your repos (or haystack init for local-only config)
2. Install the Haystack GitHub App
3. When PRs are opened, Haystack automatically:
   • Analyzes the code for bugs, instruction drift, and rule violations
   • Reports results on the PR
   • Routes the PR to the right inbox tab (Good to Merge, Issues Found, etc.)
   • If auto-merge is enabled, clean PRs merge automatically

License

MIT