Wacht Bench

Wacht Bench is the AI-assisted development surface for Wacht.

It bundles the things AI coding assistants need to build Wacht apps without guessing:

• Skills — task-shaped playbooks installed under ./skills, scoped per framework and per platform surface.
• Docs MCP — the Wacht Docs MCP server at https://wacht.dev/docs/mcp, so assistants always read the current SDK, API, and guide content instead of hallucinating.
• Bench CLI (@wacht/bench) — init, login, projects, deployments, users, orgs, workspaces, config, api, and completion commands for everything else.

The CLI is opinionated about being agent-first: it scaffolds context, never patches your app code. Your editor agent does the wiring.

Install Wacht skills

Install the full skill pack:

wacht skills install

Install one skill:

wacht skills install --skill wacht-nextjs-patterns

Install into specific agents (skips the interactive picker):

wacht skills install --agent claude-code,cursor,codex
wacht skills install --all-agents

Install at user scope instead of project scope with --global. Copy files instead of symlinking with --copy.

Use the Bench CLI

The package is @wacht/bench. Installing it provides the wacht binary.

Run without installing:

npx @wacht/bench@latest init

To install globally:

npm i -g @wacht/bench@latest
# or
pnpm add -g @wacht/bench@latest

Then:

wacht init
wacht login
wacht deployments select
wacht --version

wacht init detects Next.js, React Router, and TanStack Router projects, then writes a short, agent-readable context: .env.wacht.example (the SDK env vars your app actually reads) and a ## Wacht Bench block in your AGENTS.md that tells your assistant which skill to load, where to find the Docs MCP, and which CLI commands to use. It does not wire framework code, patch app files, or edit package dependencies.

Bootstrap a new project

init --starter clones a ready-to-run starter and bootstraps it.

wacht init --starter nextjs           # → ./wacht-nextjs-starter
wacht init --starter react-router
wacht init --starter tanstack

Pass --target <dir> to choose the destination.

Connect Wacht Docs MCP

wacht mcp install detects every supported AI client on the machine and lets you bulk-apply the Wacht Docs MCP server to the ones you pick.

wacht mcp install              # interactive: detect + multi-select + apply
wacht mcp list                 # show known clients + detection + install status
wacht mcp uninstall            # remove from selected clients

Non-interactive form for CI or scripts:

wacht mcp install --client cursor-user,vscode-user,codex --yes
wacht mcp install --all --yes

Supported clients (user and project scope where applicable):

• Claude Desktop
• Claude Code (~/.claude.json or .mcp.json)
• Cursor (~/.cursor/mcp.json or .cursor/mcp.json)
• VS Code (mcp.json)
• Windsurf
• Codex CLI (TOML)

Bench merges the wacht-docs server into the existing config — other servers are preserved. Use wacht mcp config --client <name> to print raw JSON for a client without writing to disk.

See Docs MCP for more setup options.

Drive the platform from the terminal

Once you are signed in (wacht login) and have an active deployment (wacht deployments select), Bench can drive the Wacht Machine API directly:

wacht projects list
wacht deployments current

wacht users list
wacht users get <user_id>
wacht users create --field email_address=person@example.com

wacht orgs list
wacht orgs get <organization_id>
wacht orgs create --field name="Acme"

wacht workspaces list --org <organization_id>
wacht workspaces create --org <organization_id> --field name="Production"

For everything not yet wrapped as a first-class command, Bench exposes the full Wacht Platform OpenAPI surface:

wacht api ls --search users
wacht api describe createUser
wacht api call createUser --field email_address=person@example.com

describe resolves $ref schemas inline, so you see nested object fields and discriminated-union variants without grepping the raw JSON. call validates JSON request bodies against the operation's schema before sending — typos and missing required fields fail locally with a JSON-pointer pointing at the bad path. Pass --no-validate to bypass.

For larger payloads, read the body from disk:

wacht api call createAiAgent --body @./agent.json

The schema is cached at ~/.wacht/platform-api.openapi.json; pass --refresh to refetch.

Bench is a spec-level tool — it gives you direct access to the API verbs. Higher-level workflows (creating an agent, scheduling a task, sharing a chat URL) usually compose several verbs; the Agents guide describes those as product actions, the agent runtime reference lists the verbs in order.

Pull deployment credentials into .env.local

wacht env pull mints a fresh backend API key for the active deployment and writes it — plus the publishable key — into your project's local env file. Default file is .env.local for Next.js, .env for Vite-based stacks (React Router, TanStack).

cd my-app
wacht env pull

Each call issues a new key under a deployment-scoped system app. Existing keys keep working — re-pulling on a teammate's machine doesn't invalidate yours. Pass --file <path> to override the destination or --print to dump credentials to stdout without writing.

The key prefix and live/test mode are set by the server when the key is minted; the CLI writes whatever the credentials endpoint returns. The underlying endpoint (POST /deployments/{id}/credentials) is exposed only on the machine API and authenticated with the CLI's machine session — there is no backend-SDK or REST way to mint a key from application code. If your automation needs a backend key, run wacht env pull from the same machine, or rotate keys manually from the API-Auth UI in the console.

Manage deployment settings as code

wacht config pull --file wacht.config.json
wacht config diff --file wacht.config.json
wacht config apply --file wacht.config.json --dry-run
wacht config apply --file wacht.config.json --yes

Production applies require an explicit deployment confirmation:

wacht config apply --file wacht.config.json --production --confirm <deployment_id> --yes

Secrets and provider credentials are never written to config files.

Shell completion

wacht completion bash > /etc/bash_completion.d/wacht
wacht completion zsh  > "${fpath[1]}/_wacht"
wacht completion fish > ~/.config/fish/completions/wacht.fish

Recommended assistant instruction

Drop this into your AGENTS.md or assistant rules so every Wacht task starts in the right place:

Use Wacht skills for Wacht implementation work.
Before coding, use Wacht Docs MCP at https://wacht.dev/docs/mcp for current Wacht SDK, API, and guide details.
Run the validation commands named by the active skill before finishing.

wacht init writes a project-scoped AGENTS.md block that includes this guidance, plus a routing table that points agents at the right skill, MCP, and CLI commands for each task.

What the skill pack covers

• New Wacht setup and framework detection
• Next.js, React Router, and TanStack Router patterns
• Backend JS integrations
• Organizations and workspaces
• API Auth and OAuth clients
• Webhooks and replay
• Notifications and realtime streams
• Agents, MCP servers, approvals, hooks, and skill bundles
• Testing Wacht auth and integration flows

Read next

• Bench Skills
• Docs MCP
• Next.js Quick Start
• Backend JS SDK