@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

For AI agents: the machine-readable contract

Most consumers of this CLI are coding agents. These invariants hold everywhere:

• --json means pure stdout. When --json is passed, stdout carries exactly one JSON document (NDJSON stream for setup --json); all progress, spinners, and prose go to stderr. On failure, stdout still gets a versioned error envelope (haystack schema error: {"schema_version": "1.0.0", "status": "error", "error": "..."}) and the process exits 1.
• Every JSON payload is versioned and schema'd. Payloads carry schema_version; print the contract with haystack schema <name> (haystack schema lists all: triage, pr, pr-status, inbox, ask, traces, submit, action, cloud-verifier, error, setup). Schemas are JSON-Schema 2020-12 and CI-guarded against drift.
• One state vocabulary. All state tokens are snake_case across every command: verdicts are good_to_merge / needs_review / needs_input; feed buckets are analyzing, good_to_merge, issues, needs_assignment, needs_shepherding, etc. No command emits kebab-case states.
• PR refs are uniform. Every command taking a PR accepts 123, #123, owner/repo#123, or a GitHub PR URL. Bare numbers infer the repo from the origin remote.
• Exit codes: 0 = the requested action happened (a created PR with findings is still 0 — read the verdict from the JSON); 1 = it did not. Commands never print an error and exit 0.
• Waiting is bounded and skippable. submit waits up to 10 min for analysis, triage polls up to 5 min, review up to 25 min; every waiting command takes --no-wait. Non-terminal outcomes include a next field with the follow-up command (usually haystack triage <ref> --json).
• "review" disambiguation: haystack review re-runs the machine analysis. For human review use haystack submit --review or haystack request-review.

The agent workflow for submitting:

haystack submit --json          # emits the submit payload incl. ref + analysis verdict
haystack triage <ref> --json    # poll findings later / after --no-wait

haystack mcp runs a stdio MCP server exposing the same payloads as tools: inbox_list, pr_get, pr_status, triage_get, ask_haystack, traces_list, traces_get, dismiss, mark_reviewed, undismiss, request_review, trigger_review, and schema.

haystack verify mcp runs the cloud-verifier MCP server. Retained application state is available through verify_reopen, verify_refork, and verify_cleanup. Agents select state by an exact Archil fork ID or a stable run/test/side coordinate; refork returns a durable child ID that can be reopened or nested again without receiving provider credentials. The matching CLI flow is:

haystack verify reopen latest 3
# inspect or mutate the returned sandbox
haystack verify refork latest 3 attempt:fix-2
haystack verify reopen archil:<disk-id>:branch:<returned-child>

haystack verify hosted is the authenticated production entry point for exact GitHub commit pairs. It uses the repository-default saved account, submits an idempotent run, and waits up to 35 minutes by default:

haystack verify hosted start owner/repo \
  --base <40-character-commit-sha> \
  --head <40-character-commit-sha> \
  --json

Use --no-wait to return as soon as the workflow is queued. The result includes an account-bound next_command; use it verbatim on machines with multiple saved GitHub accounts. Repeating the same repository/base/head tuple reuses the same production run by default. Pass a new explicit --idempotency-key only when a fresh execution is intentional. A bounded wait that expires still emits the cloud-verifier schema with timed_out: true, the last observed status, and next_command, then exits 2. Read or resume a known run with:

haystack verify hosted status cv_<48-lowercase-hex-characters> \
  --account <login> \
  --wait \
  --json

To execute a completed run's exact validated risk plan again, keep the same repository and commit pair and pass:

haystack verify hosted start owner/repo \
  --base <40-character-commit-sha> \
  --head <40-character-commit-sha> \
  --replay-plan-from cv_<48-lowercase-hex-characters> \
  --json

A successful replay emits a schema-9 terminal result whose riskPlanReplayReceipt binds the source run and canonical risk-plan hash. The replay does not mint or deliver a planning-model credential.

Agents can use the same production lifecycle over stdio MCP:

haystack verify hosted mcp --account <login>

The hosted server exposes only verify_start, verify_status, and verify_wait. Tool results use the same cloud-verifier schema as the CLI; credentials, repository source, provider metadata, and sandbox mutation are not exposed.

Freeze one production plan and repeat its exact execution to detect executor or assessment drift:

haystack verify hosted reproducibility owner/repo \
  --base <40-character-commit-sha> \
  --head <40-character-commit-sha> \
  --runs 3 \
  --json

The first run creates the source plan; every later run names it through replayPlanFromRunId. Each run gets a distinct idempotency key derived from one printed series key. Pass --series-key <key> to resume the same series without creating duplicate runs. The report verifies schema-9 replay provenance and compares stable risk-cell, capability, and comparison IDs. Missing replay provenance, assessment drift, timeouts, unsupported receipts, and inconclusive cells all prevent a reproducible verdict and exit 2.

haystack setup --json speaks NDJSON: events (question, permission, progress, result) on stdout, replies on stdin keyed by requestID/permissionID. haystack schema setup documents the full protocol, including the reply shapes. Pre-supply answers with --repo, --yes, --no-auto-merge, or --answers <file> to skip questions. Note: --yes enables auto-merge (the wizard default) — pass --no-auto-merge to opt out.

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 --json               # Agent mode: one JSON doc on stdout, progress on stderr
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

The --json payload (haystack schema submit) reports the PR ref, the resolved title/body and where each came from, auto-merge/auto-fix state with its source (flag vs .haystack.json), and the analysis outcome in the shared verdict vocabulary.

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.

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, designed for session-start hooks.

The --json output includes every finding and its customer-facing suggested_fix when available.

haystack inbox list

List PRs in your Haystack inbox with the reason each PR is present and the next action:

haystack inbox list
haystack inbox list --json

haystack pr get

Get the useful state of one PR: triage, minimal merge blockers, and customer-trace availability:

haystack pr get 42
haystack pr get owner/repo#42 --json

haystack ask

Ask Haystack Chat about a PR. Machine output contains the answer and every customer-facing source Chat consulted:

haystack ask 42 "Why is this finding legitimate?"
haystack ask owner/repo#42 "Show the implementation" --json
haystack ask owner/repo#42 "What about its callers?" --session <session-id> --json

Chat may search the complete authorized repository when the changed files are insufficient. Search results and fetched source are included in evidence.

haystack traces

Inspect retained customer-owned Entire checkpoints and transcript chunks:

haystack traces list owner/repo#42 --json
haystack traces get owner/repo#42 <checkpoint-id> --json
haystack traces get owner/repo#42 <checkpoint-id> --cursor 20 --limit 20 --json

These commands expose customer coding-session data, not Haystack's internal analysis-agent execution.

haystack review

Trigger a fresh machine analysis of a PR's current head (Haystack analyzes once at PR open; later pushes only get a resolution check). For requesting human review, use haystack request-review.

haystack review 42                   # Re-analyze and wait for the result
haystack review 42 --no-wait         # Trigger and exit
haystack review 42 --json            # Machine-readable outcome (schema: action)

haystack request-review

Tag a PR as needing human review (adds haystack:needs-review), optionally requesting a specific GitHub user:

haystack request-review 42                 # Into the needs-assignment queue
haystack request-review 42 octocat         # Also request review from octocat
haystack request-review 42 --json

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 dismiss 42 --json           # Machine-readable (schema: action)

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, 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 (must end in [bot]):
haystack config wait-for-reviewers add cursor-bugbot[bot]

Reviewer names are validated: anything that is neither a known friendly name nor a ...[bot] username is rejected (a stored typo would make the merge queue wait forever for a bot that can't post).

haystack skills

Manage AI skills for your coding CLI:

haystack skills install              # Install portable .agents/skills
haystack skills install --cli codex  # Portable install for Codex
haystack skills install --cli claude # Also install Claude command shims
haystack skills install --cli manual # Install portable skills and print their location
haystack skills list                 # List available skills
haystack skills scaffold-provisional-universe --input /tmp/facts.json # Write a missing-authority receipt
haystack skills prepare-universe-review --json # Build a filtered reviewer source snapshot
haystack skills validate-universe --json # Parse and cross-check universe artifacts

Installed skills include /map-cloud-verifier-universe, which asks the customer's coding agent to map the application's production dependencies and uses a read-only reviewer subagent to check the map before Cloud Verifier onboarding. It first checks for an authoritative hosted-deployment source; if that source is private, it produces a provisional map and one bounded request for a summary from the customer's local replicator or catalog. It never asks for production credentials or direct Haystack access to production.

Start a customer-owned Cloud Verifier adapter before a universe map exists, from only the three selections the user actually makes — which application, which environment, and which approved replica destination:

haystack cloud-verifier connector bootstrap \
  --application-id Checkout \
  --environment-id production \
  --destination-policy-file ./replica-destination-policy.json

Application and environment accept a plain name and are normalized to stable IDs (application:checkout, environment:production); pass an explicit application:<id> when you want to choose it yourself. The destination is named by its approved policy document, whose SHA-256 the command computes and reports. Pass --destination-policy-sha256 <64-hex> instead only if your tooling already holds the digest. Exactly one of the two is required.

The scaffold stays blocked until the customer's coding agent completes bounded local discovery and provider-profile conformance. It includes the lifecycle and binding executable, encrypted connector-owned vault contract, cold golden refresh scheduler, and a setup/update-only reviewer-subagent request. No reviewer runs on ordinary verification requests or routine golden refreshes.

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