npm package: @haystackeditor/cli
Description: Set up Haystack for your project — automated PR review, triage, and merge queue
Author: Haystack
Latest version: 0.11.0

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

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

```bash
haystack setup
```

### `haystack init`

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

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

### `haystack status`

Check if your project is configured:

```bash
haystack status
```

### `haystack login`

Authenticate with GitHub (required for setup and secrets):

```bash
haystack login
```

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

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

```bash
haystack submit                      # Triage -> create PR -> wait for analysis
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:

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

### `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.

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

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

### `haystack check-pending`

Check the status of a previously submitted PR's analysis (from the current repo):

```bash
haystack check-pending              # Rich terminal output
haystack check-pending --hook       # Minimal output (for session-start hooks)
haystack check-pending --json       # Machine-readable JSON
haystack check-pending --clear      # Clear pending state
```

### `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.

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

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

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

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

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

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

```bash
# 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 (check-pending 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`):

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

```json
{
  "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](https://haystackeditor.com/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