@cursor/july 0.1.113 → 0.2.0

package/docs/reference/cli.md

@@ -1,551 +1,507 @@
 ---
 title: "CLI"
-description: "Commands and common flags for local development, running servers, and Cursor-managed hosting."
+description: "Look up Agent SDK commands, targets, flags, outputs, and exit status."
 ---
 
-# CLI reference
-
-`@cursor/july` installs one command, `agent-sdk`; `npx @cursor/july <cmd>`
-runs it. Run the CLI with Node 22.13 or newer. Don't run it with Bun; Bun
-corrupts tool-result streams from the Cursor SDK.
-
-`agent-sdk help` prints the built-in summary. The Slack and GitHub packs
-also provide `agent-sdk slack help` and `agent-sdk github help`.
-
-| Command                                                 | Description                                                    |
-| ------------------------------------------------------- | -------------------------------------------------------------- |
-| [`serve`](#serve)                                       | Serve agents over HTTP                                         |
-| [`dev`](#dev)                                           | Start local development with `serve --dev`                     |
-| [`chat`](#chat)                                         | Talk to a running agent                                        |
-| [`resume`](#resume)                                     | Reattach chat to a previous session                            |
-| [`logs`](#logs)                                         | Follow local or hosted logs                                    |
-| [`sessions`](#sessions)                                 | List sessions on a running agent                               |
-| [`session`](#session)                                   | Inspect one session                                            |
-| [`cost`](#cost)                                         | Report per-session token usage and estimated cost              |
-| [`playground`](#playground)                             | Open the local or hosted playground                            |
-| [`docs`](#docs)                                         | Serve the shipped documentation site locally                   |
-| [`run`](#run)                                           | Run one or more turns locally, remotely, or on a hosted agent  |
-| [`call`](#call)                                         | Call a server tool without a model turn                        |
-| [`eval`](#eval)                                         | Run filesystem evals                                           |
-| [`trajectory`](#trajectory)                             | Summarize a saved event stream                                 |
-| [`init`](#init)                                         | Scaffold a project, or print the setup guide                   |
-| [`convert-automation`](#convert-automation)             | Export a Cursor Automation into an agent project               |
-| [`install-skills`](#install-skills)                     | Refresh coding-agent skills (`npm install` already copies them) |
-| [`info`](#info)                                         | Print the discovered agent surface                             |
-| [`validate`](#validate)                                 | Check a project and fail on errors                             |
-| [`login` / `logout` / `whoami`](#login-logout-whoami)   | Manage the host's Cursor credential                            |
-| `version`                                               | Print the installed version and exit (also `--version` / `-V`) |
-| [`update`](#update)                                     | Upgrade the installed CLI                                      |
-| [`deploy`](#deploy)                                     | Deploy one or more agents to Cursor managed hosting            |
-| [`deployments`](#deployments)                           | List hosted deployments                                        |
-| [`deployment`](#deployment)                             | Inspect one hosted deployment                                  |
-| [`stop`](#stop)                                         | Stop a hosted deployment                                       |
-| [`delete`](#delete)                                     | Delete a hosted deployment                                     |
-| [`rotate-token`](#rotate-token)                         | Replace a deployment's alias token                             |
-| [`secrets`](#secrets)                                   | Manage deployment secrets                                      |
-| [`mcp`](#mcp)                                           | Proxy the agent's MCP endpoint over stdio; `mcp install` writes `~/.cursor/mcp.json` |
-| [`mcp oauth`](#mcp-oauth)                               | Authorize host MCP OAuth; optional `--store` to deployment secrets |
-| [`slack ...`](#slack)                                   | Provision, set up, and check Slack channels                    |
-| [`github ...`](#github)                                 | Forward, replay, and inspect GitHub webhook channels           |
-
-## Choose a target
-
-Request-sending commands support three target types.
-
-| Target | How to select it | Commands |
+# CLI
+
+`@cursor/july` provides the `agent-sdk` command for developing, inspecting,
+testing, and deploying Agent SDK projects. Run it with Node 22.13 or newer;
+Bun isn't supported. Commands exit nonzero when validation or a synchronous
+request fails; asynchronous commands can exit `0` once work is accepted.
+
+Use `npx @cursor/july <command>` to run the CLI without a global install.
+`agent-sdk help` prints top-level help; the Slack, GitHub, GitLab, and
+Bitbucket command packs provide their own `help` subcommands.
+
+## Command catalog
+
+### Development commands
+
+| Command | Contract |
+| --- | --- |
+| `help`, `--help`, `-h` | Print top-level help |
+| [`serve`](#serve) | Serve one or more agents over HTTP |
+| [`dev`](#dev) | Serve agents with local-development behavior |
+| [`docs`](#docs) | Serve the documentation bundled with `@cursor/july` |
+| [`init`](#init) | Scaffold an Agent SDK project |
+| [`convert-automation`](#convert-automation) | Export a Cursor Automation into a project |
+| [`install-skills`](#install-skills) | Refresh the bundled coding-agent skills |
+| [`info`](#info) | Print the discovered project surface |
+| [`validate`](#validate) | Check project diagnostics and set the exit status |
+| [`manifest`](#manifest) | Print deployment metadata as JSON |
+| [`version`](#version) | Print the installed package version |
+| [`update`](#update) | Upgrade the installed CLI |
+| [`login`](#login-logout-whoami) | Sign the host in to Cursor |
+| [`logout`](#login-logout-whoami) | Remove the stored Cursor credential |
+| [`whoami`](#login-logout-whoami) | Show the active Cursor credential |
+
+### Session and eval commands
+
+| Command | Contract |
+| --- | --- |
+| [`chat`](#chat) | Talk to a running agent |
+| [`resume`](#resume) | Reattach chat to a previous session |
+| [`run`](#run) | Start or continue work on a local, running, or managed agent |
+| [`call`](#call) | Call a server tool without a model turn |
+| [`skill`](#skill) | Read an authored skill without a model turn |
+| [`logs`](#logs) | Follow or dump agent logs |
+| [`sessions`](#sessions) | List sessions |
+| [`session`](#session) | Inspect a session or start a managed session turn |
+| [`cost`](#cost) | Report token usage and estimated cost |
+| [`playground`](#playground) | Open an agent's playground |
+| [`trajectory`](#trajectory) | Summarize a saved event stream |
+| [`eval`](#eval) | List, run, inspect, or cancel evals |
+
+### Managed hosting commands
+
+| Command | Contract |
+| --- | --- |
+| [`deploy`](#deploy) | Deploy one or more agents |
+| [`deployments`](#deployments) | List deployments |
+| [`deployment`](#deployment) | Inspect one deployment |
+| [`stop`](#stop) | Stop a deployment |
+| [`cancel-runs`](#cancel-runs) | Cancel active runs and reminder wakes |
+| [`event-repos`](#event-repos) | Replace a managed application's event repositories |
+| [`upgrade`](#upgrade) | Move a managed application to a release |
+| [`delete`](#delete) | Delete a deployment |
+| [`rotate-token`](#rotate-token) | Replace a deployment's alias token |
+| [`secrets`](#secrets) | Set, list, or remove deployment secrets |
+
+### Connection and channel commands
+
+| Command | Contract |
+| --- | --- |
+| [`mcp`](#mcp) | Proxy an agent's MCP endpoint over stdio |
+| [`mcp install`](#mcp) | Add the agent to an MCP client config |
+| [`mcp oauth`](#mcp-oauth) | Authorize an MCP connection |
+| [`slack`](#slack) | Provision and check Slack channel apps |
+| [`github`](#github) | Forward, replay, and inspect GitHub webhooks |
+| [`gitlab`](#gitlab) | Replay and inspect GitLab webhooks |
+| [`bitbucket`](#bitbucket) | Replay and inspect Bitbucket webhooks |
+
+## Targets {#choose-a-target}
+
+Commands that send requests support these targets:
+
+| Target | Selection | Commands |
 | --- | --- | --- |
-| Ephemeral local server | Omit `--url` and `--prod` | `run`, `call`, `eval` |
-| Running server | Pass `--url <baseUrl>`, unless the command uses the localhost default described next | `chat`, `resume`, `logs`, `sessions`, `session`, `cost`, `playground`, `run`, `call`, `eval`, `mcp` |
-| Cursor managed hosting | Pass `--prod` | `chat`, `resume`, `logs`, `sessions`, `session`, `cost`, `playground`, `run`, `call`, `eval`, `mcp` |
-
-`chat`, `logs`, `sessions`, `session`, `cost`, and `playground` default to
-`http://127.0.0.1:3000`. A `--url` must include the agent slug for a
-multi-agent server, such as `http://127.0.0.1:3000/pr-approver`.
-`--slug` doesn't change an explicit URL. `mcp` has no default target;
-pass `--url` or `--prod`.
-
-With `--prod`, `--slug` selects the deployment and `--team` selects the
-Cursor team. The slug defaults to the `--dir` basename. The team
-defaults to the signed-in account's team. `--url` and `--prod` are
-mutually exclusive.
-
-Use `--bearer-token <token>` when a running server requires bearer
-authentication. Hosted commands use your Cursor credential to request
-short-lived engine access. `--api-key` overrides the Cursor credential
-for `login`, `serve`, hosted targets, and managed-hosting commands.
-`--state-root` applies to `serve` and ephemeral `run`, `call`, and
-`eval` servers. Running and hosted targets ignore it.
-
-For ephemeral `run`, `call`, and `eval` commands, omitting `--slug`
-selects an unslugged root mount when one exists. Otherwise, the Agent SDK
-selects the first discovered agent.
-
-## serve
-
-`serve` hosts every agent under `--dir` in multi-agent mode by default.
-
-```bash
-agent-sdk serve [--dir <path>] [--port 3000] [--host 127.0.0.1] [--dev]
-                  [--mode multi|single] [--api-key <key>]
-                  [--state-root <path>] [--bearer-token <secret> | --allow-anonymous]
-                  [--allow-anonymous-cursor-github]
-                  [--allow-anonymous-cursor-account-mcp]
-                  [--public-url <url>] [--cloud-tools-url <url>]
-                  [--no-schedules] [--no-playground]
-                  [--no-docs] [--cursor-events --repo owner/name]...
-```
-
-If `--dir` is an agent project, it mounts under its directory name. If
-it contains agent projects, each child mounts separately. The index
-lives at `/`. Each agent is available at `/<slug>/v1/*` and
-`/<slug>/playground`. On a TTY, press Enter to restart.
-Unless `--state-root` is set, each mount uses a state directory under
-the agent project. Slugged mounts get a subdirectory named for the slug.
-
-| Flag | Meaning |
+| Ephemeral local server | Omit `--url` and `--prod` | `run`, `call`, `skill`, `eval` |
+| Running server | Pass `--url <baseUrl>` | `chat`, `resume`, `run`, `call`, `skill`, `eval`, `logs`, `sessions`, `session`, `cost`, `playground`, `mcp` |
+| Default local server | Omit `--url` and `--prod`; uses `http://127.0.0.1:3000` | `chat`, `resume`, `logs`, `sessions`, `session`, `cost`, `playground` |
+| Hosted deployment | Pass `--prod` | `chat`, `resume`, `run`, `call`, `skill`, `eval`, `logs`, `sessions`, `session`, `cost`, `playground`, `mcp` |
+| Managed application | Pass `--prod` | `run`, `session` |
+
+An explicit `--url` must include the slug for a multi-agent server, such as
+`http://127.0.0.1:3000/pr-approver`. `--slug` never changes an explicit URL.
+`--url` and `--prod` are mutually exclusive.
+
+| Option | Contract |
+| --- | --- |
+| `--dir <path>` | Select the project root. The default is the current directory. |
+| `--url <baseUrl>` | Use a running agent instead of local project discovery. |
+| `--prod` | Use a hosted deployment or managed application. Command support depends on the target type as listed above. |
+| `--slug <slug>` | Select an agent from a multi-agent project or a hosted resource. Under `--prod`, the default is the `--dir` basename. |
+| `--team <id>` | Select a Cursor team. The signed-in account's team is the default. |
+| `--api-key <key>` | Override the Cursor credential for commands that authenticate with Cursor. |
+| `--bearer-token <token>` | Authenticate to a running server with a bearer token. |
+| `--state-root <path>` | Select local state for `serve` and ephemeral `run`, `call`, `skill`, and `eval` targets. Running and `--prod` targets ignore it. |
+| `--json` | Request machine-readable output when the command supports it. `run` already defaults to JSON. |
+
+## Local servers
+
+### Serve agents {#serve}
+
+`serve` mounts every project discovered under `--dir`:
+
+```bash
+agent-sdk serve [--dir <path>] [--port <n>] [--host <host>]
+  [--mode multi|single] [--dev] [--api-key <key>]
+  [--state-root <path>]
+  [--bearer-token <secret> | --allow-anonymous]
+  [--allow-anonymous-cursor-github]
+  [--allow-anonymous-cursor-account-mcp]
+  [--public-url <url>] [--cloud-tools-url <url>]
+  [--no-schedules] [--no-playground] [--no-docs]
+  [--cursor-events --repo <owner/name>]...
+```
+
+| Option | Contract |
 | --- | --- |
-| `--port` | Listen on this port. `0` selects an available port. The default is `3000`. When the default is taken, serve tries the next free port and prints a notice; an explicit `--port` fails with a next-port hint instead. |
-| `--host` | Bind this host. The default is loopback-only `127.0.0.1`. |
-| `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and widen playground session access on loopback. |
-| `--mode` | Use `multi` for slugged routes and an index, or `single` for one agent at the unslugged `/v1/*`. The default is `multi`. |
-| `--api-key` | Use this Cursor API key. Otherwise the command uses `CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY` when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the stored login. |
-| `--state-root` | Store sessions, streams, workspaces, and channel state here. Keep durable production state outside the agent repository. |
-| `--bearer-token` | Require this bearer token on routes without authored auth. Mutually exclusive with `--allow-anonymous`. |
-| `--allow-anonymous` | Admit every caller as one `anonymous` principal. Use only behind a trusted network boundary. |
-| `--allow-anonymous-cursor-github` | Allow anonymous callers to drive sessions holding a Cursor account's repo-scoped GitHub credential. Use only behind an authenticating proxy. |
-| `--allow-anonymous-cursor-account-mcp` | Allow anonymous callers to drive Cursor account MCP connectors (`defineConnection({ cursorAccount: true })`). Use only behind an authenticating proxy (hosted alias token counts). |
-| `--public-url` | Set the externally reachable host URL. Cloud-runtime peer connections need it to call back into this server. |
-| `--cloud-tools-url` | Authenticated HTTP MCP URL for this deployment's direct server-tool endpoint. Hosted deployments configure it automatically. |
-| `--no-schedules` | Disable the cron runner outside dev mode. |
-| `--no-playground` | Skip the web playground. |
+| `--port <n>` | Listen on this port. The default is `3000`; `0` selects an available port. When an omitted default is occupied, the CLI selects the next port. An occupied explicit port fails with a next-port hint. |
+| `--host <host>` | Bind this host. The default is loopback-only `127.0.0.1`. |
+| `--mode multi` | Mount projects at `/<slug>/v1/*` and `/<slug>/playground`, with an index at `/`. This is the default. |
+| `--mode single` | Mount one project at `/v1/*` and `/playground`. |
+| `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and enable local playground access. |
+| `--state-root <path>` | Store local sessions, streams, workspaces, and channel state here. Keep durable state outside a repository whose rules shouldn't reach agent workspaces. |
+| `--bearer-token <secret>` | Require this token on routes without authored authentication. Mutually exclusive with `--allow-anonymous`. |
+| `--allow-anonymous` | Admit callers as one anonymous principal. Use it only behind a trusted network boundary. |
+| `--allow-anonymous-cursor-github` | Let anonymous callers use sessions with a Cursor account's repository-scoped GitHub credential. Requires an authenticating proxy. |
+| `--allow-anonymous-cursor-account-mcp` | Let anonymous callers use Cursor account MCP connections. Requires an authenticating proxy. |
+| `--public-url <url>` | Publish the externally reachable host URL for peer-agent callbacks. |
+| `--cloud-tools-url <url>` | Publish the authenticated server-tool MCP URL used by cloud turns. Managed hosting sets it automatically. |
+| `--no-schedules` | Disable schedule firing outside dev mode. |
+| `--no-playground` | Skip the playground. |
 | `--no-docs` | Skip the documentation site at `/docs`. |
-| `--cursor-events` | Pull SCM events from Cursor in addition to authored webhook routes. Requires a signed-in host. Pass repeatable `--repo owner/name` values; repos declared by `githubChannel({ cursorAccount })` also enable it. |
+| `--cursor-events` | Receive SCM events through Cursor. Requires sign-in and one or more repeatable `--repo owner/name` values. |
 
-Multi-agent slugs must start with a letter or digit, then contain only
-letters, digits, `_`, or `-`. The reserved slugs are `v1`, `playground`,
-and `docs`.
+Multi-agent slugs start with a letter or digit and contain only letters,
+digits, `_`, or `-`. The reserved slugs are `v1`, `playground`, and `docs`.
 
-## dev
+### Develop locally {#dev}
 
-`dev` is the local-development shortcut for `serve --dev`. Pass the
-agent folder as a positional path, or run it from inside the project:
+`dev` is `serve --dev` with an optional positional project path:
 
 ```bash
 agent-sdk dev
-agent-sdk dev ./sdk-pr-reviewer
 agent-sdk dev ./sdk-pr-reviewer --port 3000
 ```
 
-`dev` accepts the same flags as [`serve`](#serve). You can use `--dir`
-instead of the positional path.
-Dev mode is always on: schedules and reminders wait for manual dispatch,
-and GitHub accepts unsigned loopback deliveries. Prefer this over
-`serve --dev` while iterating. Pass at most one positional path. Don't
-combine a positional path with a different `--dir`.
-
-## chat
+It accepts every `serve` option. Pass at most one positional path, and don't
+combine it with a different `--dir`.
 
-`chat` talks to a running agent from the terminal. It never starts a
-server.
+### Serve the docs {#docs}
 
 ```bash
-agent-sdk chat --url http://127.0.0.1:3000/pr-approver
-agent-sdk chat --message "Is the PR ready to approve?"
-agent-sdk chat --message "Inspect PR 42" --json
-agent-sdk chat --prod --slug pr-approver --team 123
+npx @cursor/july docs
+agent-sdk docs [--port <n>] [--host 127.0.0.1] [--print]
 ```
 
-`chat` streams text, tool calls, and a per-turn usage footer.
-On a TTY, `--message` seeds the interactive REPL. With non-TTY input,
-`--message` runs one turn and exits; without it, `chat` reads
-newline-delimited messages until EOF. `--json` requires `--message`,
-runs one turn, and prints
-`{ ok, sessionId, continuationToken, trajectory }`. `--text` prints a
-compact trajectory when combined with `--json`. `--no-color` forces
-plain interactive output.
+`docs` serves the bundled documentation without an agent project. It uses an
+available loopback port by default and stays open until Ctrl-C. `--print`
+prints the URL without opening a browser.
 
-Use `--session <id>` to reattach a stored session. The command looks up
-its continuation token when you omit `--continuation-token`. Use
-`--resume` to select the most recently updated session with a
-continuation token.
+## Sessions and turns
 
-## resume
+### Chat with an agent {#chat}
 
-`resume` is the direct way to reattach the chat REPL.
+`chat` connects to a running server and never starts an ephemeral one:
 
 ```bash
-agent-sdk resume ses_123 --url http://127.0.0.1:3000/pr-approver
-agent-sdk resume --url http://127.0.0.1:3000/pr-approver
-agent-sdk resume ses_123 --prod --team 123 --slug pr-approver
-agent-sdk resume ses_123 --message "Continue the review" --json
+agent-sdk chat [--url <baseUrl> | --prod] [--message <text>]
+  [--session <id> | --resume] [--continuation-token <token>]
+  [--slug <slug>] [--team <id>] [--json] [--text] [--no-color]
 ```
 
-Pass a session ID to select it. Omit the ID to select the most recently
-updated followable session from `/v1/sessions`. The command looks up a
-missing continuation token, replays the transcript, and accepts
-follow-ups. `resume --json` requires `--message`. The same operation is
-available as `chat --session <id>` or `chat --resume`.
+| Input mode | Behavior |
+| --- | --- |
+| TTY without `--message` | Open an interactive REPL. |
+| TTY with `--message` | Send the message, then keep the REPL open. |
+| Non-TTY with `--message` | Send one turn and exit. |
+| Non-TTY without `--message` | Read newline-delimited messages until EOF. |
+| `--json --message <text>` | Send one turn and print `{ ok, sessionId, continuationToken, trajectory }`. |
+| `--json --text --message <text>` | Print a compact trajectory instead of JSON. |
+
+Use `--session <id>` to reattach a stored session. If you omit
+`--continuation-token`, the CLI looks it up from the target's session list.
+`--resume` selects the most recently updated session with a continuation
+token. An explicit session ID takes precedence.
 
-## logs
+### Resume a session {#resume}
 
-`logs` follows the local or hosted log buffer.
+`resume` provides the same reattachment contract as `chat --session`:
 
 ```bash
-agent-sdk logs [--url http://127.0.0.1:3000] [--once] [--json]
-agent-sdk logs --prod [--slug <slug>] [--team <id>] [--once] [--json]
+agent-sdk resume [sessionId] [--url <baseUrl> | --prod]
+  [--message <text>] [--json] [--text]
+  [--continuation-token <token>] [--slug <slug>] [--team <id>]
 ```
 
-Local mode reads `/v1/logs` from the running server. Hosted mode reports
-deploy progress until the deployment is running or degraded, then
-follows reachable runtime logs.
-The command follows until Ctrl-C by default. `--once` prints the current
-buffer and exits. `--json` emits newline-delimited JSON events.
+Omit the session ID to select the most recently updated followable session.
+The command replays the transcript before accepting follow-ups.
+`resume --json` requires `--message`.
 
-## sessions
+### Run turns {#run}
 
-`sessions` lists sessions on a running or hosted agent.
+`run` sends messages to an ephemeral, running, or `--prod` target:
 
 ```bash
-agent-sdk sessions [--url <baseUrl> | --prod] [--slug <slug>]
-                  [--team <id>] [--bearer-token <token>] [--json]
+agent-sdk run [--dir <path>] [--message <text>]...
+  [--messages-file <path>] [--url <baseUrl> | --prod]
+  [--session <id>] [--continuation-token <token>]
+  [--events <file> | --no-events] [--text]
+  [--timeout-ms <n>] [--no-stream] [--slug <slug>] [--team <id>]
+  [--dry-run] [--as-of <instant>] [--component <key>]
 ```
 
-Text output shows session ID, channel, mode, turn count, running status,
-and update time. `--json` prints full session summaries in
-`{ sessions }`, including continuation tokens.
+| Option | Contract |
+| --- | --- |
+| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. Managed starts accept one message. |
+| `--messages-file <path>` | Read a JSON array of strings. File messages run before repeated `--message` values. |
+| `--session <id>` | Continue a session. Managed session starts accept a hosted `ses_...` ID. |
+| `--continuation-token <token>` | Continue the session selected by `--session` on a running server. Managed session starts use `--session` instead. |
+| `--events <file>` | Write the raw NDJSON stream to this path. |
+| `--no-events` | Skip the NDJSON trace. |
+| `--text` | Print a compact trajectory instead of JSON. |
+| `--timeout-ms <n>` | Stop waiting after a positive number of milliseconds. There is no default timeout. |
+| `--no-stream` | Hide live tool and reply progress on stderr. |
+| `--dry-run` | Mark a managed session turn as non-mutating. |
+| `--as-of <instant>` | Freeze a managed session's clock at a timezone-bearing ISO-8601 instant. |
+| `--component <key>` | Select a managed application's component instead of its default. |
+
+For local and running-server targets, JSON output contains `ok`, `sessionId`,
+`continuationToken`, `trace`, `playgroundUrl`, `playgroundHint`, `visualize`,
+and `trajectory`. The `trace` value gives the saved path when event output is
+enabled. A managed session start confirms acceptance; a continuation also
+returns `sessionId`. Managed starts return before the turn finishes and ignore
+`--events`, `--no-events`, `--text`, `--timeout-ms`, and `--no-stream`.
+A successful managed start exits `0` on acceptance, before its turn outcome is
+known. A fresh start doesn't return `sessionId` synchronously.
 
-## session
+### Call a tool {#call}
 
-`session` inspects the event stream for one session.
+`call` invokes a server tool without a model turn:
 
 ```bash
-agent-sdk session <sessionId> [--url <baseUrl> | --prod]
-                 [--slug <slug>] [--team <id>]
-                 [--json | --text | --events] [--out <file.ndjson>]
+agent-sdk call <tool> [--input <json>]
+  [--dir <path> | --url <baseUrl> | --prod]
+  [--session <id>] [--slug <slug>] [--team <id>]
 ```
 
-By default, `session` prints a compact trajectory. `--text` selects the
-same format. `--json` prints the trajectory object. `--events` prints
-`{ sessionId, events }` with the raw event list. You can't combine
-`--events` and `--json`. `--out <file.ndjson>` writes the raw NDJSON
-trace to a file instead of printing. The file uses the same format as
-`run --events` and the playground download. Use
-[`resume`](#resume) to continue the conversation.
+`--input` accepts JSON and defaults to `{}`. `--session` uses the session
+workspace and records the call on its event stream. The command prints the
+server's JSON response and succeeds only when the HTTP response succeeds with
+`ok: true`.
+
+See [Tools](./tools.md#call-a-tool-without-a-model-turn) for validation,
+busy-session behavior, and error codes.
 
-## cost
+### Read a skill {#skill}
 
-`cost` reports token usage and estimated cost.
+`skill` reads an authored skill without a model turn:
 
 ```bash
-agent-sdk cost [sessionId] [--url <baseUrl> | --prod]
-              [--slug <slug>] [--team <id>] [--json]
+agent-sdk skill <name> [--dir <path> | --url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>] [--text]
 ```
 
-With a session ID, `cost` prints per-turn token usage and estimated
-cost for that session. Without one, it prints one row per session on
-the target plus a total. Costs are the engine's recorded estimates from
-`turn.completed` events; turns persisted before cost tracking count as
-unpriced. `--json` prints the underlying report, or `{ sessions }` when
-aggregating. Like `session`, the command supports `--dir`,
-`--bearer-token`, and the `--url`/`--prod` targets, and defaults to the
-local server.
-
-## playground
+The default output is the server's JSON response. `--text` prints the rendered
+`SKILL.md` content.
 
-`playground` opens an agent's web playground.
+### List sessions {#sessions}
 
 ```bash
-agent-sdk playground [--url <baseUrl> | --prod] [--session <id>]
-                    [--slug <slug>] [--team <id>]
-                    [--bearer-token <token>] [--print]
+agent-sdk sessions [--url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>] [--bearer-token <token>] [--json]
 ```
 
-`--session` opens a deep link to one session. `--print` prints the URL
-without opening a browser.
+Text output shows the session ID, channel, mode, turn count, running status,
+and update time. `--json` prints `{ sessions }`, including continuation
+tokens.
 
-For an unauthenticated local URL, `playground` opens the browser and
-exits. `--prod` and `--bearer-token` start a loopback proxy to inject
-browser-inaccessible credentials. The proxy stays open until Ctrl-C,
-including when you pass `--print`.
+### Inspect a session {#session}
 
-## docs
+```bash
+agent-sdk session <sessionId> [--url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>]
+  [--json | --text | --events] [--out <file.ndjson>]
+
+agent-sdk session --prod [<sessionId>] --slug <slug> --message <text>
+  [--dry-run] [--as-of <instant>] [--component <key>]
+```
+
+| Option | Contract |
+| --- | --- |
+| No output option | Print a compact trajectory. |
+| `--text` | Select the compact trajectory explicitly. |
+| `--json` | Print the trajectory object. |
+| `--events` | Print `{ sessionId, events }` with the raw event list. |
+| `--out <file.ndjson>` | Write the raw NDJSON trace instead of printing it. |
+| `--prod --message <text>` | Start a managed session or continue the supplied managed session ID. |
 
-`docs` serves the documentation shipped inside `@cursor/july` and opens
-it in a browser. You don't need an agent project.
+`--events` and `--json` are mutually exclusive. Managed sessions without an
+event trajectory return hosted execution status and logs in text or JSON;
+`--events` and `--out` require an event trajectory. Use [`resume`](#resume) to
+continue a conversational session.
+
+### Follow logs {#logs}
 
 ```bash
-npx @cursor/july docs
-agent-sdk docs [--port <n>] [--host 127.0.0.1] [--print]
+agent-sdk logs [--url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>] [--once] [--json]
 ```
 
-The site is the same documentation mounted at `/docs` on a running
-`serve` host. `docs` starts a loopback-only static server (default port
-is an ephemeral port) and keeps it open until Ctrl-C. `--print` prints
-the URL without opening a browser.
-
-## run
+The command follows logs until Ctrl-C. `--once` prints the current buffer and
+exits; `--json` emits newline-delimited JSON events. A hosted deployment
+reports deployment progress before runtime logs become available.
 
-`run` sends one or more turns and prints a JSON result.
+### Report costs {#cost}
 
 ```bash
-agent-sdk run --dir . --message "Is https://github.com/acme/checkout/pull/42 ready?"
-agent-sdk run --dir . --message "Inspect PR 42" --message "Summarize the risks"
-agent-sdk run --url http://127.0.0.1:3000/pr-approver --message "Inspect PR 42"
-agent-sdk run --prod --slug pr-approver --team 123 --message "Inspect PR 42"
-agent-sdk run --dir . --messages-file ./prompts.json
+agent-sdk cost [sessionId] [--url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>] [--json]
 ```
 
-Without `--url` or `--prod`, the command starts an ephemeral server on
-an available port. Its state root is a temporary directory outside the
-project unless you pass `--state-root`. The command closes the server
-after the turns finish.
+With a session ID, `cost` prints per-turn token usage and estimated cost.
+Without one, it prints one row per session and a total. Turns saved before
+cost tracking appear as unpriced. `--json` prints the underlying report or
+`{ sessions }` for an aggregate.
 
-| Flag | Meaning |
-| --- | --- |
-| `--message <text>` | Send a user message. Repeat the flag for a multi-turn run. |
-| `--messages-file <path>` | Read a JSON array of strings. File messages run before repeated `--message` values. |
-| `--session <id>` | Follow up an existing session. Unlike `chat`, `run` doesn't look up a missing continuation token. |
-| `--continuation-token <token>` | Continue the existing session selected by `--session`. |
-| `--events <file>` | Write the raw NDJSON event stream to this path. |
-| `--no-events` | Don't write an event stream. |
-| `--text` | Print a compact trajectory instead of the JSON result. |
-| `--timeout-ms <n>` | Abort the turn after a positive number of milliseconds. There is no default timeout. |
-| `--no-stream` | Hide live tool and reply progress on stderr. Progress is on by default when stderr is a TTY. |
-| `--slug <slug>` | Pick one agent when local discovery mounts several agents. With `--prod`, select the hosted deployment. |
-
-The default trace path is
-`<state-root>/traces/<sessionId>.ndjson`. JSON output contains
-`ok`, `sessionId`, `continuationToken`, `trace`, `playgroundUrl`,
-`playgroundHint`, `visualize`, and `trajectory`. The command exits
-non-zero when the trajectory fails.
-
-## call
-
-`call` invokes a server tool directly, with no model turn.
-
-```bash
-agent-sdk call inspect_pr --dir . \
-  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
-agent-sdk call inspect_pr --url http://127.0.0.1:3000/pr-approver \
-  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
-agent-sdk call refresh_cache --url http://127.0.0.1:3000/pr-approver \
-  --session ses_123
-agent-sdk call inspect_pr --prod --slug pr-approver --team 123 --input '{}'
-```
-
-`call` sends `POST /v1/tools/:toolName` and runs the tool in the serving
-process without a model turn. `--input` accepts any valid JSON and
-defaults to `{}`. Tools with a Zod input schema validate and transform
-the value before execution. A local call needs no inference credential.
-A hosted call still needs Cursor credentials to reach the deployment.
-
-`--session` runs the tool inside an existing session and records it on
-the event stream. If a model turn is active or pending, a read-effect
-tool runs alongside it and a write-effect tool gets `session_busy`;
-retry after the turn finishes. The command
-prints the server's JSON response and exits non-zero unless the HTTP
-response succeeds with `ok: true`. See
-[Tools](./tools.md#call-a-tool-without-a-model-turn).
-
-## eval
-
-`eval` runs the project's filesystem evals.
-
-```bash
-agent-sdk eval --dir . --list          # discovered datapoints
-agent-sdk eval --dir .                 # run all
-agent-sdk eval --dir . builds/checkout # one datapoint
-agent-sdk eval --dir . builds          # every datapoint in the file
-agent-sdk eval --dir . --tag smoke     # by tag (repeatable)
-agent-sdk eval --dir . --json          # machine-readable results
-agent-sdk eval --dir . --verbose       # stream t.log lines + reply snippets
-agent-sdk eval --prod --slug pr-approver --team 123
-# prints Eval ID immediately on --prod/--url; then:
-agent-sdk eval status <evalId> --prod --slug pr-approver
-agent-sdk eval cancel <evalId> --prod --slug pr-approver
-```
-
-`eval` runs `evals/**/*.eval.{ts,js}` on an ephemeral server. With
-`--prod` or `--url`, the target server runs its own evals as a
-server-side batch. Select one or more exact case IDs, file ID prefixes,
-or tags.
-Omit selectors to run all cases. Repeated `--tag` flags use OR matching.
-
-An eval run requires `evals/evals.config.{ts,js}` with `maxConcurrency`
-between 1 and 200. Timeout priority is the case's `timeoutMs`, the CLI's
-`--timeout-ms`, the config's `timeoutMs`, then 180 seconds.
-
-| Flag | Meaning |
-| --- | --- |
-| `--list` | Print discovered cases without running. `--list --json` prints them as an array. |
-| `--tag <tag>` | Run cases with this tag. Repeated flags use OR matching. |
-| `--json` | Print `{ ok, passed, failed, scored, skipped, strict, results }`; see [Run evals in CI](../evals.md#run-evals-in-ci) for the result shape. |
-| `--verbose` | Stream `t.log` lines and reply snippets. |
-| `--no-stream` | Hide live progress on stderr. |
-| `--strict` | Exit `1` when a scored case misses a soft threshold. |
-| `--max-concurrency <n>` | Override `maxConcurrency` from `evals.config.ts`. |
-| `--junit <path>` | Write JUnit XML for CI annotations. |
-| `--artifacts <dir>` | Write run artifacts here. The default is a timestamped directory under `evals/` in the project state directory (not affected by `--state-root`). |
-| `--no-artifacts` | Skip run artifacts. |
-| `--skip-report` | Ignore reporters from `evals.config.ts` and eval files. |
-| `--out <path>` | Also write the full results JSON to this path (also for `eval status <evalId>`). |
-| `--no-wait` | Return with the Eval ID as soon as a `--prod` or `--url` batch is accepted. |
-| `--timeout-ms <n>` | Per-case timeout override. |
+### Open the playground {#playground}
 
-Failed cases exit `1`. A scored case also exits `1` under `--strict`.
-No matching cases exit `2`. `eval status` exits `3` while the remote batch
-is still running.
+```bash
+agent-sdk playground [--url <baseUrl> | --prod] [--session <id>]
+  [--slug <slug>] [--team <id>] [--bearer-token <token>] [--print]
+```
 
-## trajectory
+The command prints the playground URL and opens it unless `--print` is set.
+`--session` opens a deep link. A running target with credentials that a
+browser can't send starts a loopback proxy and stays open until Ctrl-C.
 
-`trajectory` summarizes a saved event stream.
+### Inspect a trajectory {#trajectory}
 
 ```bash
-agent-sdk trajectory --events /tmp/run.ndjson [--text]
+agent-sdk trajectory --events <file.ndjson> [--text]
 ```
 
-`trajectory` converts a saved NDJSON stream into the trajectory JSON
-returned by `run`. `--text` prints the compact view. The command exits
-non-zero when the reconstructed trajectory failed.
+The command converts an NDJSON stream into the trajectory JSON returned by
+`run`. `--text` prints the compact view.
 
-## init
+## Evals
 
-`init` scaffolds a new project.
+### Run evals {#eval}
+
+`eval` discovers `evals/**/*.eval.{ts,js}` and runs selected cases:
 
 ```bash
-agent-sdk init ./my-agent          # scaffold package.json, tsconfig.json, agent/ + a demo tool
-agent-sdk init ./my-demo --template demo              # record a PR walkthrough
-agent-sdk init ./grokbot --template grokbot-agents    # talk to Grok Bot agents
-agent-sdk init ./code-wiki --template code-wiki       # keep wiki pages current after merge
-agent-sdk init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
-agent-sdk init ./my-reviewer --template security-reviewer   # review PRs for security bugs
-agent-sdk init ./thermo-review --template thermo-review       # review PRs for bugs and breakage
-agent-sdk init ./thermo-quality --template thermo-quality-review # review PRs for code quality
-agent-sdk init ./security-help --template security-help   # answer security questions in Slack
-agent-sdk init ./my-triage --template triage-linear   # comment on Linear issues
-agent-sdk init ./my-triage --template triage-jira     # comment on Jira issues
-agent-sdk init ./my-owners --template agentic-owners  # review PRs via owners policies
-agent-sdk init ./pr-autofixer --template pr-autofixer # fix PRs on a cloud VM
-agent-sdk init ./pr-autofixer --template pr-autofixer \
-  --var repos=acme/widgets,acme/api --json
-agent-sdk init ./my-agent --json   # machine-readable summary for tooling
-agent-sdk init                     # no directory: print the setup guide
+agent-sdk eval [--dir <path>] [evalId...]
+  [--list] [--tag <tag>]... [--json] [--verbose]
+  [--timeout-ms <n>] [--strict] [--max-concurrency <n>]
+  [--junit <path>] [--artifacts <dir> | --no-artifacts]
+  [--skip-report] [--out <file.json>] [--no-stream]
+  [--url <baseUrl> | --prod] [--no-wait]
+  [--slug <slug>] [--team <id>]
 ```
 
-`init` leaves existing files unchanged and labels each one `create` or
-`exist`. It prints the project path, then runs `npm install` so
-`@cursor/july` resolves for `dev` and `run`.
+Select an exact case such as `weather/nyc`, a file prefix such as `weather`,
+several IDs, or no IDs for every case. Repeat `--tag` for OR matching.
+Projects must provide `evals/evals.config.{ts,js}` with `maxConcurrency`
+between 1 and 200.
 
-Templates may ship `init.json`. On a TTY, `init` asks those questions
-before writing files. `code-wiki`, `pr-autofixer`, `security-help`, and
-`agents-md` ask for GitHub repos. `agents-md` also asks for Slack
-channels. `grokbot-agents` asks for Grok Bot names. Repeat
-`--var id=value` to answer without a prompt.
-`--json` and non-TTY hosts skip the interview unless `--var` is set.
+| Option | Contract |
+| --- | --- |
+| `--list` | List matching cases without running them. `--list --json` prints an array. |
+| `--tag <tag>` | Select a tag. Repeat the option for OR matching. |
+| `--json` | Print `{ ok, passed, failed, scored, skipped, strict, results }`. |
+| `--verbose` | Stream `t.log` lines and reply snippets. |
+| `--no-stream` | Hide live progress on stderr. |
+| `--strict` | Treat a scored case below its soft threshold as a failure. |
+| `--max-concurrency <n>` | Override `maxConcurrency` from the eval config for an ephemeral local run. |
+| `--timeout-ms <n>` | Override the per-case timeout. A case timeout takes precedence, followed by this option, the config timeout, and the 180-second default. |
+| `--junit <path>` | Write JUnit XML for an ephemeral local run. |
+| `--artifacts <dir>` | Select the artifact directory for an ephemeral local run. The default is a timestamped directory under the project's state directory. |
+| `--no-artifacts` | Skip artifacts for an ephemeral local run. |
+| `--skip-report` | Ignore reporters from eval files and the eval config during an ephemeral local run. |
+| `--out <file.json>` | Also write the full result JSON. |
+| `--no-wait` | Return after a running server or hosted deployment accepts the batch. |
 
-On a TTY, `init` also asks whether to refresh the coding-agent skills in
-`~/.cursor/skills/agentsdk/`. Installing `@cursor/july` already copies
-them via postinstall (with `alwaysApply: true` so Cursor injects the
-bodies), so this prompt is a chance to overwrite with the package
-version. The prompt is skipped for `--json` and non-interactive hosts.
+A running server or hosted deployment prints its Eval ID when it accepts the
+batch.
+Use these commands to inspect or cancel it:
 
-If the host isn't signed in, `init` runs `agent-sdk login` and waits for
-the browser flow. It then prints the `cd`, `agent-sdk login`, and
-`agent-sdk dev` steps still needed.
+```bash
+agent-sdk eval status [evalId] --prod [--slug <slug>] [--team <id>]
+agent-sdk eval status [evalId] --url <baseUrl>
+agent-sdk eval cancel <evalId> --prod [--slug <slug>] [--team <id>]
+agent-sdk eval cancel <evalId> --url <baseUrl>
+```
 
-With `--json`, `init` still installs dependencies but never blocks on
-login or skill installation. It prints `{ ok, directory, template, created,
-skipped, installed, installError, cliOnPath, cliLinkError, next }`. The
-`next` list includes `login` when the host is unsigned.
+`eval status` without an ID lists recent remote runs. `eval status --out`
+requires an ID. The `status` and `cancel` subcommands require `--url` or
+`--prod`.
 
-## convert-automation
+## Projects
 
-`convert-automation` exports a Cursor Automation into an agent project.
+### Scaffold a project {#init}
 
 ```bash
-agent-sdk convert-automation <url> [--dir <path>] [--json]
+agent-sdk init [directory] [--template <name>] [--var id=value]... [--json]
 ```
 
-`<url>` is the dashboard URL (`…/automations/<uuid>` or
-`…/custom-agents/<uuid>`) or a bare UUID. The command fetches the
-Automation with your Cursor credentials. It writes converted files to
-`--dir`, which defaults to `./<automation-name>`, adds missing `init`
-scaffold files, and runs `npm install`. File generation does not
-overwrite existing paths. The install may still update lockfiles or run
-lifecycle scripts from an existing `package.json`.
+Without a directory, `init` prints the setup guide and changes no files. With
+a directory, it preserves existing scaffold files, adds missing files,
+installs dependencies, and tries to put `agent-sdk` on `PATH`.
+
+| Option | Contract |
+| --- | --- |
+| `--template <name>` | Use a bundled template: `agentic-owners`, `agents-md`, `code-wiki`, `demo`, `grokbot-agents`, `pr-autofixer`, `security-help`, `security-reviewer`, `thermo-quality-review`, `thermo-review`, `triage-jira`, or `triage-linear`. |
+| `--var id=value` | Answer a template question without a prompt. Repeat for multiple answers. |
+| `--json` | Skip interactive login and skill prompts, then print `{ ok, directory, template, created, skipped, installed, installError, cliOnPath, cliLinkError, next }`. `ok` reflects dependency installation. |
 
-MCP servers convert to Cursor-account connections resolved at runtime.
-The project contains their names, not server URLs or credentials.
-Local runs use the signed-in account. Hosted deployments use a separate
-service account; authorize each generated connection with
-[`mcp oauth`](#mcp-oauth) after the first deploy. Review the generated
-project, then run `validate` and `dev`.
+On a TTY, templates with questions run their interview before writing files.
+`init` also offers to refresh the bundled coding-agent skills and starts login
+when the host has no Cursor credential.
 
-Warnings do not change the exit status. Bad arguments, authentication
-failures, fetch failures, and file write failures return a nonzero exit
-code.
+### Convert an Automation {#convert-automation}
+
+```bash
+agent-sdk convert-automation <url-or-uuid> [--dir <path>] [--json]
+```
+
+The input can be a Cursor Automation dashboard URL or its UUID. The output
+directory defaults to `./<automation-name>`. Generated files don't overwrite
+existing paths, and missing scaffold files are added. The following
+`npm install` can update lockfiles and run lifecycle scripts from an existing
+`package.json`.
 
 `--json` prints
 `{ ok, directory, files, warnings, setupSteps, installed, installError, mcpConnections }`.
-On failure it prints `{ ok: false, error }` and still writes the prose
-error to stderr.
-
-The [Convert a Cursor Automation](../guides/convert-automation.md) guide
-covers generated files and behavior the converter cannot reproduce.
+Conversion warnings and dependency-install failures remain visible in this
+output without failing a completed file conversion. Invalid input,
+authentication, export, and file-write failures exit nonzero.
 
-## install-skills
+See [Convert a Cursor Automation](../guides/convert-automation.md) for the
+generated project and features that need manual review.
 
-`install-skills` copies the package's coding-agent skills into
-`~/.cursor/skills/agentsdk/` with `alwaysApply: true` so Cursor loads
-them as global rules. Installing `@cursor/july` already does this in
-postinstall (`npm install`, `npx`, a version bump). Use this command
-to refresh without reinstalling the package, or from a monorepo
-source checkout (postinstall skips that tree).
+### Install coding-agent skills {#install-skills}
 
 ```bash
 agent-sdk install-skills [--print] [--json]
 ```
 
-Running the command is the confirmation: it never prompts, and it
-overwrites the installed skills with the version bundled in the
-package. `init` offers the same refresh once, interactively. `--print`
-previews the skills, the removals, and the install path without writing
-anything. `--json` prints
+The command replaces the installed Agent SDK skills under
+`~/.cursor/skills/agentsdk/` with the package copy and removes stale bundled
+skills. `--print` previews the change. `--json` prints
 `{ ok, dryRun, directory, firstInstall, skills, removed }`.
 
-Set `CURSOR_JULY_SKIP_SKILL_INSTALL=1` to skip the postinstall copy.
-`CURSOR_JULY_SKILLS_HOME` overrides the `~/.cursor/skills` directory.
+Package installation already performs this copy. Set
+`CURSOR_JULY_SKIP_SKILL_INSTALL=1` to skip that install hook, or set
+`CURSOR_JULY_SKILLS_HOME` to choose another skills directory.
 
-## info
-
-`info` prints the discovered agent surface.
+### Inspect a project {#info}
 
 ```bash
-agent-sdk info --dir . [--json]
+agent-sdk info [--dir <path>] [--json]
 ```
 
-`info` reports the model, instruction size, tools, skills, MCP
-connections, subagents, channel routes, schedules, hooks, and
-diagnostics. Text output summarizes each mounted agent. `--json` prints
-`{ agents: [{ slug, ...projectInfo }] }`, with one entry per mounted
-slug. Use `validate`, not `info --json`, when a script needs an error
-exit status.
+Text output lists the model, instructions, tools, skills, extensions,
+connections, subagents, channels, schedules, hooks, hosting settings, and
+diagnostics. For one unslugged project, `--json` prints its project info
+object. For slugged or multi-agent discovery, it prints `{ agents }`.
+
+### Validate a project {#validate}
 
-## validate
+```bash
+agent-sdk validate [--dir <path>]
+```
 
-`validate` checks the project and sets the exit code.
+`validate` prints every discovered project's diagnostics and exits nonzero
+when any diagnostic has error severity. Use it instead of `info --json` when a
+script needs validation status.
+
+### Print a deployment manifest {#manifest}
 
 ```bash
-agent-sdk validate --dir .
+agent-sdk manifest [--dir <path>] [--json]
 ```
 
-`validate` prints diagnostics for each agent and exits non-zero when any
-diagnostic has error severity. `serve` also refuses to start when errors
-are present. Warnings don't change the exit status.
+`manifest` validates one project and prints its deployment metadata without a
+network request. Default output is indented JSON; `--json` prints one compact
+line.
 
-## login / logout / whoami
+## Credentials and versions
 
-Three commands manage the host's Cursor credential.
+### Manage credentials {#login-logout-whoami}
 
 ```bash
 agent-sdk login [--api-key <key>] [--key-name <name>]
@@ -553,418 +509,394 @@ agent-sdk whoami [--json]
 agent-sdk logout
 ```
 
-`login` signs the host in to Cursor: browser sign-in mints a named,
-dashboard-revocable API key, and only the key is stored (the default
-name is `<invoked command> (<hostname>)`). It powers inference, the cloud
-runtime, and Cursor account MCP connections. `--key-name` changes the
-name of a browser-minted key. `login --api-key` validates and stores a
-key you already created.
+| Command | Contract |
+| --- | --- |
+| `login` | Use a supplied API key, or open browser sign-in and store the resulting dashboard-revocable key in the CLI config directory. `--key-name` labels a browser-created key. |
+| `whoami` | Show the active credential and its source. `--json` returns the same identity as JSON. |
+| `logout` | Remove the stored credential file. It doesn't revoke the API key; revoke the key in the Cursor dashboard. |
 
-`whoami` shows which credential is active and why. An explicit key
-wins, then `CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE` (hosted default
-`/run/cursor/secrets/CURSOR_API_KEY` when unset), then
-`CURSOR_SERVICE_ACCOUNT_KEY`, then the stored login. A host that has
-both the service-account key and a bind file authenticates as the file
-principal. `logout` removes the local credential file but doesn't
-revoke the API key. Revoke it in the Cursor dashboard when it should
-stop working.
+### Print the version {#version}
 
-Login and account RPCs honor `CURSOR_API_BASE_URL`. The SDK harness
-honors `CURSOR_BACKEND_URL`. Set both to the same URL, or keys minted
-on one host are rejected by the other.
+```bash
+agent-sdk version [--json]
+agent-sdk --version
+agent-sdk -V
+```
 
-## update
+Text output is the version number. `--json` prints
+`{ name, version }`.
 
-`update` upgrades an installed copy to the latest published version.
+### Update the CLI {#update}
 
 ```bash
 agent-sdk update
 ```
 
-The command checks npm's `latest` tag, detects how the Agent SDK was installed,
-and runs the matching npm, pnpm, Yarn, or Bun upgrade command. It handles
-global installs and project dependencies. It doesn't prompt before
-running the package-manager command.
-
-Source checkouts, `npx` or `pnpm dlx` caches, and unknown install layouts
-aren't changed. The command prints a manual upgrade hint instead.
+`update` checks npm's `latest` tag and upgrades a recognized global or project
+install with its package manager. If it can't identify an installed copy, it
+prints a manual upgrade command instead.
 
-Published installs also check for a newer version at most once every 24
-hours and print an update warning on stderr. Source checkouts, CI, and
-commands with an explicit `--json` flag skip this automatic check.
+Published installs check for updates at most once every 24 hours. Set
+`AGENT_SERVE_NO_UPDATE_CHECK`, `NO_UPDATE_NOTIFIER`, or `CI` to disable the
+automatic warning.
 
-## deploy
+## Managed hosting
 
-`deploy` sends one or more agents to Cursor managed hosting.
+### Deploy agents {#deploy}
 
 ```bash
 agent-sdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
-                [--repo <https-url>] [--ref <git-ref>] [--path <agent-path>]
-                [--cursor-events-repo owner/name]...
-                [--allow-domain <domain>]...
-                [--no-wait] [--json]
-```
-
-Managed hosting requires team membership and the team's cloud-agent
-entitlement. A team service-account API key with agent access can
-deploy. `--team` defaults to the signed-in account's team.
-
-For a single project, the slug defaults to a normalized version of the
-directory name. Deployment slugs contain lowercase letters, digits, `_`,
-or `-`, with a maximum of 64 characters. For a directory with several
-agents, select one with `--slug`, deploy all with `--all`, or choose from
-the TTY prompt. Non-interactive callers must pass `--slug` or `--all`.
-If `--dir` contains no agent project or child agents, `deploy` requires
-`--slug` (or a slug derived from the directory name) and an https git
-repository URL (`--repo`, or inferred from `origin` when `--dir` is an
-agent project). `--all` fails when there is no agent project.
-
-The command infers `--repo`, `--ref`, and `--path` from the current Git
-checkout when possible. Explicit flags take precedence. `--repo` must
-use HTTPS. Repeat `--cursor-events-repo` to select SCM event sources.
-Repeat `--allow-domain` to add engine egress domains; these values are
-combined with `hosting.egressDomains` from the agent config. Egress
-domains apply only to repository-backed deployments. Each domain must
-be a lowercase hostname with at least two labels and an alphabetic
-top-level domain. One leading `*.` wildcard is allowed. A deployment
-can declare at most 20 domains.
-
-By default, the command polls every three seconds for up to ten minutes
-and succeeds only when the deployment reaches `running`. `--no-wait`
-returns after the deployment request is accepted. Multi-agent deploys
-run sequentially. When several agents are selected, `--path` is ignored
-and each project infers its own path. A single-target `--json` run
-prints one object; a multi-target run prints an array.
-
-The first deployment can return an alias token. It appears once in text
-or JSON output and can't be retrieved later. Store it as a secret. Send
-it as `X-Agent-Alias-Token` when calling the stable alias URL, or use it
-to sign in to the hosted playground.
-
-See [Deployment](../deployment.md) for the hosting security model and
-state layout.
-
-## deployments
-
-`deployments` lists the selected team's deployments.
+  [--repo <https-url>] [--ref <git-ref>] [--path <agent-path>]
+  [--cursor-events-repo <owner/name>]...
+  [--allow-domain <domain>]... [--no-wait] [--json]
+```
+
+Managed hosting requires a team with agent hosting enabled. A team
+service-account API key with agent access can deploy.
+
+| Option | Contract |
+| --- | --- |
+| `--slug <slug>` | Select one project and set its deployment slug. |
+| `--all` | Deploy every child project under a multi-agent `--dir`. Mutually exclusive with `--slug`. |
+| `--team <id>` | Select the Cursor team. |
+| `--repo <https-url>` | Set the source repository. The CLI infers it from the current checkout when possible. HTTPS is required. |
+| `--ref <git-ref>` | Set the source Git ref. The CLI infers the current branch when possible. |
+| `--path <agent-path>` | Set the project path relative to the repository root. |
+| `--cursor-events-repo <owner/name>` | Add a repository whose SCM events reach the deployment. Repeat for multiple repositories. |
+| `--allow-domain <domain>` | Add an egress hostname. Repeat for multiple domains; values are combined with `hosting.egressDomains`. |
+| `--no-wait` | Return after the deployment request is accepted. |
+| `--json` | Print one object for one target or an array for multiple targets. |
+
+Deployment slugs contain lowercase letters, digits, `_`, or `-`, start with a
+letter or digit, and have at most 64 characters. Egress entries are lowercase
+hostnames with an alphabetic top-level domain; one leading `*.` wildcard is
+allowed, with at most 20 entries.
+
+By default, `deploy` waits until the deployment is running and exits nonzero
+if it reaches a failed state. A first deployment can return an alias token
+once. Store it as a secret and send it as `X-Agent-Alias-Token` when calling
+the stable alias URL.
+
+### List deployments {#deployments}
 
 ```bash
 agent-sdk deployments [--team <id>] [--json]
 ```
 
-Text output shows each slug, status, deployment kind, and
-update time. `--json` prints `{ deployments }`.
+Text output shows slug, status, generation, kind, and update time. `--json`
+prints `{ deployments }` and may also include `applications`. An empty list
+succeeds.
 
-## deployment
-
-`deployment` prints the full status of one deployment.
+### Inspect a deployment {#deployment}
 
 ```bash
 agent-sdk deployment <slug> [--team <id>] [--json]
 ```
 
-Text output includes status, kind, alias, source, egress
-domains, secret names, engine state, and the last error when present.
-`--json` returns the full API response. It can include short-lived
-`engineAccess.headers`, so handle JSON output as a credential.
+Text output includes status, source, routes, secret names, egress domains, and
+the latest error. `--json` can include short-lived access headers, so handle
+its output as a credential.
+
+### Stop a deployment {#stop}
+
+```bash
+agent-sdk stop <slug> [--team <id>] [--no-wait] [--cancel-runs] [--json]
+```
 
-## stop
+The command waits for `stopped` by default. `--no-wait` returns after the
+request is accepted. `--cancel-runs` also requests cancellation of active
+runs and reminder wakes for a managed application. Other deployment types
+reject this option.
 
-`stop` shuts down a deployment.
+### Cancel active runs {#cancel-runs}
 
 ```bash
-agent-sdk stop <slug> [--team <id>] [--no-wait] [--json]
+agent-sdk cancel-runs <slug> [--team <id>] [--json]
 ```
 
-The command polls for up to ten minutes until the status reaches
-`stopped`. `--no-wait` returns after the stop request is accepted.
+The command requests cancellation for a managed application's active runs and
+reminder wakes. Other deployment types reject it. For a multi-tenant
+application, this cancels every install; use `stop --cancel-runs` for
+install-local cancellation. It exits nonzero if any cancellation request fails
+to start.
+
+### Replace event repositories {#event-repos}
+
+```bash
+agent-sdk event-repos <slug> [--repo <owner/name>]...
+  [--team <id>] [--json]
+```
 
-## delete
+The supplied repositories replace the managed application's complete event
+repository list; they aren't merged with the previous list. Omit `--repo` to
+clear the list.
 
-`delete` removes a hosted deployment. You can delete a deployment that
-still runs. The command frees the slug. A later deploy can use the same
-name. Spend stays on the archived service account.
+### Upgrade a managed application {#upgrade}
 
 ```bash
-agent-sdk delete <slug> [--team <id>] [--no-wait] [--json]
+agent-sdk upgrade <slug> [--release <id-or-version>]
+  [--team <id>] [--json]
 ```
 
-The command waits until the deployment is gone. `--no-wait` returns after
-the delete request is accepted. Architecture v2 slugs use the Agent SDK
-control plane. Architecture v1 slugs use the Agent Serve control plane.
+`--release` accepts a release ID or version. Omit it to select the newest
+ready release. `--json` prints `{ releaseId }`.
+
+### Delete a deployment {#delete}
 
-## rotate-token
+```bash
+agent-sdk delete <slug> [--team <id>] [--no-wait] [--json]
+```
 
-`rotate-token` replaces the alias token used by callers and the hosted
-playground.
+`delete` removes the deployment and frees its slug. It waits until the
+deployment is gone unless `--no-wait` is set.
+
+### Rotate an alias token {#rotate-token}
 
 ```bash
 agent-sdk rotate-token <slug> [--team <id>] [--json]
 ```
 
-The old token stops working immediately. The replacement is shown once.
+The old token stops working immediately. The replacement appears once;
 `--json` prints `{ aliasToken }`.
 
-## mcp
-
-`mcp` proxies an agent's MCP endpoint over stdio for MCP clients that
-spawn local servers, such as Cursor.
+### Manage deployment secrets {#secrets}
 
 ```bash
-agent-sdk mcp --prod [--slug <slug>] [--team <id>]
-agent-sdk mcp --url <baseUrl> [--bearer-token <token>]
-agent-sdk mcp install [--prod | --url <baseUrl>] [--name <serverName>]
-                     [--print] [--json] [--remote]
+agent-sdk secrets set <slug> NAME [NAME2 ...]
+  [--team <id>] [--from-argv] [--json]
+agent-sdk secrets list <slug> [--team <id>] [--json]
+agent-sdk secrets unset <slug> NAME [--team <id>] [--json]
 ```
 
-The bare command reads newline-delimited JSON-RPC on stdin and forwards
-one POST per message to `<target>/v1/mcp`. It requires `--prod` or
-`--url`. With `--prod`, it resolves the hosted deployment through the
-signed-in Cursor account and re-mints short-lived engine credentials as
-they expire, so no durable secret lands in a config file. stdout is
-reserved for the MCP wire; logging goes to stderr.
+Pass secret names to `set`. On a TTY, the CLI prompts for hidden values; with
+piped input, provide one line per name. It rejects `NAME=VALUE` arguments
+unless `--from-argv` is set because command-line values can enter shell
+history and captured terminals.
+
+Names use `UPPER_SNAKE_CASE`, start with a letter, and contain at most 64
+characters. Names beginning with `CURSOR_` are reserved. Values contain at
+most 4096 bytes, and each deployment holds at most 32 secrets.
+
+`list` returns names and creation times, never values. JSON output is
+`{ secretNames }` for `set`, `{ secrets }` for `list`, and `{ removed }` for
+`unset`. Changes are available to subsequent hosted work.
 
-`mcp install` writes the matching entry into `~/.cursor/mcp.json` so
-the agent shows up as an MCP server in Cursor. `--name` overrides the
-server name (the default is the slug, or a name derived from `--url`).
-`--print` prints the entry instead of writing the file, and `--json`
-prints a machine-readable result. `--remote` (with `--prod`) writes a
-remote HTTP entry pointing at the stable Cursor MCP gateway instead of
-the local stdio proxy, for MCP hosts that can't spawn stdio servers.
-The remote entry carries your API key in plain text, so treat the file
-as a credential.
+## MCP connections
 
-## mcp oauth
+### Connect an MCP client {#mcp}
+
+```bash
+agent-sdk mcp --prod [--slug <slug>] [--team <id>]
+agent-sdk mcp --url <baseUrl> [--bearer-token <token>]
 
-`mcp oauth` authorizes a `defineConnection({ url, oauth: true })` or
-`defineConnection({ cursorAccount: true })` connection.
+agent-sdk mcp install --prod [--slug <slug>] [--team <id>]
+  [--name <server-name>] [--print] [--json] [--remote]
+agent-sdk mcp install --url <baseUrl> [--bearer-token <token>]
+  [--name <server-name>] [--print] [--json]
+```
 
-URL connections run a browser PKCE flow. Tokens are written to
-`mcp-auth.json` under the CLI config directory (override with
-`AGENT_SERVE_CONFIG_DIR`). Pass `--store` to upsert matching
-`MCP_OAUTH_<CONNECTION>_*` secrets on the hosted deployment.
-`--store` is the path for the next deploy. Hosted Connect lets the
-current process retry.
+| Command | Contract |
+| --- | --- |
+| `mcp` | Read newline-delimited JSON-RPC from stdin and proxy it to the selected agent's MCP endpoint. stdout is reserved for MCP messages. A target is required. |
+| `mcp install` | Add the selected agent to `~/.cursor/mcp.json`. `--name` sets the server name, `--print` previews the entry, and `--json` prints a machine-readable result. A `--url` entry with `--bearer-token` contains that token; handle printed and written copies as credentials. |
+| `mcp install --remote --prod` | Write a remote HTTP entry for clients that can't spawn a stdio process. The entry contains the API key in plain text and must be handled as a credential. |
 
-Cursor-account connections authorize the hosted deployment's service
-account through the Cursor backend's connector consent flow. Those
-tokens live on the Cursor backend, so `--store` isn't needed; the
-command prints a note when you pass it anyway.
+### Authorize MCP OAuth {#mcp-oauth}
 
 ```bash
-agent-sdk mcp oauth <connection> [--dir .] [--store] [--slug <slug>] [--team <id>]
+agent-sdk mcp oauth <connection> [--dir <path>] [--store]
+  [--slug <slug>] [--team <id>]
 ```
 
 `<connection>` is the basename under `agent/mcp-connections/` or
 `agent/host-connections/`.
-`--slug` defaults to the `--dir` basename. `--team` defaults to the
-signed-in account's team. You need `agent-sdk login` (or `--api-key`)
-before `--store`.
 
-Secret names are `MCP_OAUTH_<NAME>_ACCESS_TOKEN`,
-`_REFRESH_TOKEN`, and `_CLIENT_ID` (`<NAME>` is the connection id in
-upper snake case). Declare them in `hosting.secretNames` so deploy
-validation expects them. Secrets apply on the next deploy.
+| Connection | Result |
+| --- | --- |
+| `defineConnection({ url, oauth: true })` | Open a browser PKCE flow and save tokens in `mcp-auth.json` under the CLI config directory. `--store` also sets the matching deployment secrets. |
+| `defineConnection({ cursorAccount: true })` | Authorize the managed deployment's service account through Cursor. `--store` isn't needed. |
 
-Tokens are bound to the connection's resource URL. Changing the URL
-invalidates the local entry; run `mcp oauth` again.
+Stored secret names are `MCP_OAUTH_<NAME>_ACCESS_TOKEN`,
+`MCP_OAUTH_<NAME>_REFRESH_TOKEN`, and `MCP_OAUTH_<NAME>_CLIENT_ID`. Declare
+them in `hosting.secretNames`. URL-connection tokens are bound to the resource
+URL; authorize again after changing it.
 
-See the [Host MCP OAuth guide](../guides/mcp-oauth.md).
+See [Host MCP OAuth](../guides/mcp-oauth.md) for the full setup flow.
 
-## secrets
+## Channel helpers
 
-`secrets` manages environment secrets for a deployment.
+### Configure Slack {#slack}
 
 ```bash
-agent-sdk secrets set <slug> NAME [NAME2 ...] [--team <id>] [--json]
-agent-sdk secrets list <slug> [--team <id>] [--json]
-agent-sdk secrets unset <slug> NAME [--team <id>] [--json]
+agent-sdk slack setup
+agent-sdk slack create [--dir <path>] [--name <name>] [--prod]
+  [--slack-team <id>] [--team <id>] [--icon <url-or-file>]
+  [--prefix <prefix> | --no-prefix] [--channel-posts] [--json]
+agent-sdk slack destroy [--dir <path>] [--prod]
+  [--slack-team <id>] [--team <id>] [--json]
+agent-sdk slack icon <url-or-file> [--dir <path>] [--prod]
+  [--slack-team <id>] [--team <id>] [--json]
+agent-sdk slack init --manual [--dir <path>] [--name <name>]
+  [--prefix <prefix> | --no-prefix] [--channel-posts]
+  [--install | --no-install] [--slack-team <id>] [--prod]
+agent-sdk slack manifest [--dir <path>] [--name <name>]
+  [--env dev|prod|both] [--channel-posts] [--print]
+agent-sdk slack doctor [--dir <path>]
+  [--prefix <prefix> | --no-prefix] [--channel <id>]... [--json]
 ```
 
-Pass names only. On a TTY, `secrets set` prompts for each value with
-hidden input (nothing echoes). When stdin is piped, provide one line per
-name. Values never print on stdout.
+| Subcommand | Contract |
+| --- | --- |
+| `setup` | Print the setup choices without changing files. |
+| `create` | Open the signed-in Cursor dashboard wizard, write the resulting token pair to `.env.local`, and run `doctor`. The development app is the default; `--prod` selects production. A second create overwrites the live app manifest. |
+| `destroy` | Delete the provisioned app. Existing local token entries remain but stop working. |
+| `icon` | Set an HTTPS or local PNG, JPG, or GIF icon of at most 512 KB. |
+| `init --manual` | Write the channel, manifests, Slack CLI project, and setup files for a manually managed app. |
+| `manifest` | Generate Slack manifests. `--env` defaults to `both`; with `--print`, select one environment when you need one JSON document. |
+| `doctor` | Check both tokens, Socket Mode connectivity, Slack authentication, and any repeatable `--channel` values. |
+
+The default token prefix is the project directory name normalized to upper
+snake case. `--no-prefix` uses `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`.
+Channel-post subscriptions are off by default; `--channel-posts` adds message
+events for public and private channels as required by
+`engagement.channelPosts`.
+Multi-agent servers need one token pair per agent.
+
+See [Slack](../guides/slack.md) for app consent and manual setup.
 
-Do not put values on the command line. `NAME=VALUE` in argv shows up in
-shell history and in agent-captured terminals. The CLI refuses that form
-unless you pass `--from-argv` (still warns). Prefer a file redirect when
-a human is not at the prompt:
+### Test GitHub webhooks {#github}
 
 ```bash
-agent-sdk secrets set weather-agent WEATHER_API_KEY < ./weather-api-key.txt
+agent-sdk github forward [--dir <path>] [--slug <slug>] [--channel <id>]
+  [--repo owner/repo | --org <org>] [--events a,b,c]
+  [--url <url>] [--host <host>] [--port <n>]
+  [--secret <secret>] [--install]
+agent-sdk github replay <pr-url-or-owner/repo#N>
+  [--events a,b,c | '*'] [--action <action>] [--conclusion <result>]
+  [--comment <body>] [--context <name>] [--dir <path>]
+  [--slug <slug>] [--channel <id>] [--url <url>]
+  [--secret <secret>] [--dry-run] [--out <dir>] [--json]
+agent-sdk github events [--dir <path>] [--host <host>] [--port <n>] [--json]
+agent-sdk github doctor [--install] [--json]
 ```
 
-Secret names use `UPPER_SNAKE_CASE`, start with a letter, and contain at
-most 64 characters. Names beginning with `CURSOR_` are reserved. Values
-can contain at most 4096 bytes, and one deployment can hold 32 secrets.
+| Subcommand | Contract |
+| --- | --- |
+| `forward` | Forward live deliveries with `gh webhook forward`. The CLI derives URLs and events from discovered channels and can fan out to several matches. |
+| `replay` | Read a pull request, synthesize selected webhook payloads, and post them to matching channels. The default event is `pull_request`; `'*'` selects the channel's supported declared events. |
+| `events` | List discovered channel URLs and event sets. No channels is a successful empty result. |
+| `doctor` | Check the GitHub CLI, its login, and the pinned webhook extension. `--install` installs or repairs the extension. |
 
-`secrets list` returns names and creation times, never values. Secret
-changes reach the engine on its next deploy. `secrets set` upserts the
-named secrets without deleting others.
+Replay supports `pull_request`, `issue_comment`,
+`pull_request_review_comment`, `check_run`, `check_suite`, `workflow_run`, and
+`status`. `--dry-run` prints without posting. `--out` writes fixtures and
+still posts unless combined with `--dry-run`.
 
-JSON output is `{ secretNames }` for `set`, `{ secrets }` for `list`,
-and `{ removed }` for `unset`.
+Forwarding requires repository admin access, or organization owner access for
+`--org`. It uses the GitHub CLI's stored login; unset `GITHUB_TOKEN` and
+`GH_TOKEN` before forwarding. Replay needs only pull-request read access.
 
-## slack
+See [GitHub](../guides/github.md) for channel setup and live delivery.
 
-The `slack` pack provisions, generates, and checks Socket Mode channel
-setup.
+### Test GitLab webhooks {#gitlab}
 
 ```bash
-agent-sdk slack setup
-agent-sdk slack create [--dir <path>] [--name <name>] [--prod]
-                      [--slack-team <T…>] [--team <id>]
-                      [--icon <https-url-or-file>]
-                      [--prefix <prefix> | --no-prefix]
-                      [--channel-posts] [--json]
-agent-sdk slack destroy [--dir <path>] [--prod] [--slack-team <T…>]
-                       [--team <id>] [--json]
-agent-sdk slack icon <https-url-or-file> [--dir <path>] [--prod]
-                    [--slack-team <T…>] [--team <id>] [--json]
-agent-sdk slack init --manual [--dir <path>] [--name <name>]
-                    [--prefix <prefix> | --no-prefix] [--channel-posts]
-                    [--install | --no-install] [--slack-team <T…>] [--prod]
-agent-sdk slack manifest [--dir <path>] [--name <name>]
-                    [--env dev|prod|both] [--channel-posts] [--print]
-agent-sdk slack doctor [--dir <path>] [--prefix <prefix> | --no-prefix] [--json]
-```
-
-`slack setup` prints the two-product chooser plus the `--manual` setup
-checklist. It doesn't change files.
-
-`slack create` opens the signed-in Cursor dashboard wizard. Finish Slack
-consent and the bot name there. The CLI writes the token pair into
-`<dir>/.env.local` and runs `doctor`. It requires a signed-in host
-(`agent-sdk login` or `CURSOR_API_KEY`). A team service-account key
-cannot create Slack apps. `--prod` provisions the production app; the
-default is the development app. `--name` / `--icon`
-/ `--channel-posts` prefill the wizard. A second create for the same
-slug and env overwrites the live Slack app. If Slack needs a workspace
-admin's approval, the wizard waits; keep the CLI running, open Slack's
-**Request approval** page (the CLI prints the link), and click **Retry**
-after the admin approves. Token values never print.
-
-`slack destroy` deletes the provisioned app for the selected
-environment. Tokens already written to `.env.local` stay in place and
-stop working.
-
-`slack icon` sets the provisioned app's icon from an https image URL or
-a local png, jpg, or gif file of at most 512KB.
-
-`slack init` without `--manual` exits non-zero and writes no files. Use
-`slack create` for the dashboard wizard. `slack init --manual` writes
-the channel file, development and production manifests, a Slack CLI
-`.slack/` project (hook + manifests, committed with the repo). When
-Slack CLI is logged in, it installs the app. Otherwise `next` asks
-you to install it. `--install` requires that install. `--no-install`
-skips it. `--prod` selects the deployed app.
-`--slack-team` picks the workspace. Slack CLI keeps install tokens in
-that process; copy `xoxb` and mint `xapp` (`connections:write`) into
-`.env.local`. Tokens that appear in `.env` during that install are
-copied onto the prefixed names. Paste `.slack/manifest.dev.json` at
-api.slack.com when the Slack CLI is missing. Do not run
-`slack deploy`. The command refuses to overwrite the channel file.
-It updates the Slack CLI hook and manifests when `.slack/` already
-exists. If a collision occurs, it exits non-zero; files created
-earlier in the run remain. The token prefix defaults to the directory
-basename normalized to uppercase snake case.
-Explicit `--prefix` values use the same normalization. For example,
-`pr-approver` becomes `PR_APPROVER_SLACK_BOT_TOKEN`. `--no-prefix`
-uses shared `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`.
-`--channel-posts` subscribes the manifests to channel-post events.
-The command always prints a JSON summary.
-
-`slack manifest` regenerates selected manifest files. `--env` defaults
-to `both`, and `--name` defaults to the directory name. `--print` writes
-the manifest JSON to stdout instead of changing files. With the default
-`--env both`, it prints development JSON, a `--- prod ---` separator,
-then production JSON.
-
-`slack doctor` checks both tokens, Socket Mode connectivity, and
-Slack's `auth.test`. It exits non-zero when any check fails.
-
-See the [Slack guide](../guides/slack.md).
-
-## github
-
-The `github` pack discovers `githubChannel()` definitions and sends live
-or synthesized deliveries to them.
+agent-sdk gitlab replay <mr-url-or-group/project!N>
+  [--events a,b,c | '*'] [--action <action>]
+  [--conclusion <status>] [--comment <body>]
+  [--dir <path>] [--slug <slug>] [--channel <id>]
+  [--url <url>] [--host <host>] [--port <n>]
+  [--secret <secret>] [--dry-run] [--out <dir>] [--json]
+agent-sdk gitlab events [--dir <path>] [--host <host>] [--port <n>] [--json]
+agent-sdk gitlab forward [--dir <path>] [--host <host>] [--port <n>]
+```
+
+| Subcommand | Contract |
+| --- | --- |
+| `replay` | Read a merge request, synthesize selected webhook payloads, and post them to matching channels. The default event is `merge_request`; `'*'` selects the channel's declared events. |
+| `events` | List discovered GitLab channel URLs and object kinds. |
+| `forward` | Print the public-hook and tunnel recipe for live deliveries. |
+
+Replay supports `merge_request`, `note`, `pipeline`, and `push`. It requires
+`GITLAB_TOKEN` with project read access. `--secret` defaults to
+`GITLAB_WEBHOOK_SECRET`; `--dry-run` and `--out` follow the GitHub replay
+contract.
+
+See [GitLab](../guides/gitlab.md) for channel setup and self-managed hosts.
+
+### Test Bitbucket webhooks {#bitbucket}
 
 ```bash
-agent-sdk github doctor [--install] [--json]
-agent-sdk github events [--dir <path>] [--host <host>] [--port <n>] [--json]
-agent-sdk github forward [--dir <path>] [--slug <slug>] [--channel <id>]
-    [--repo owner/repo | --org <org>] [--events a,b,c] [--url <url>]
-    [--host <host>] [--port <n>] [--secret <secret>] [--install]
-agent-sdk github replay <pr-url|owner/repo#N> --dir .
-    [--events a,b,c|'*'] [--action <action>] [--conclusion <result>]
-    [--comment <body>] [--context <name>] [--slug <slug>] [--channel <id>]
-    [--host <host>] [--port <n>] [--url <url>] [--secret <secret>]
-    [--dry-run] [--out <dir>] [--json]
-```
-
-`github events` prints each discovered channel's delivery URL and event
-set. When it finds no channels, it returns an empty result and exits
-successfully.
-
-`github forward` wraps `gh webhook forward`. It infers the repository
-from the Git remote when you omit `--repo` and `--org`. URLs and events
-come from the discovered channels; `--events` overrides the event set.
-Use `--slug` or `--channel` to narrow discovery when several channels
-match. Otherwise, one local proxy fans deliveries out to every match.
-`--url` targets one channel. For `forward`, pass `--events` when no
-matched channel can supply the event set.
-
-Repository forwarding needs repo-admin access. Organization forwarding
-needs org-owner access. The relay authenticates with the GitHub CLI's
-stored login. A `GITHUB_TOKEN` or `GH_TOKEN` environment override can
-make delivery requests return `401`, even when hook creation succeeds.
-Unset those variables before forwarding.
-
-Pass `--secret` or set `GITHUB_WEBHOOK_SECRET` to sign deliveries.
-`serve --dev` accepts unsigned loopback deliveries. A non-dev target
-requires the same secret on both sides.
-
-`github replay` needs read access, not admin access. It reads the pull
-request through `gh api`, builds GitHub webhook payloads, and posts them
-to the selected channels. Supported events are `pull_request`,
-`issue_comment`, `pull_request_review_comment`, `check_run`,
-`check_suite`, `workflow_run`, and `status`. The default is
-`pull_request` with action `synchronize`. Comment events need
-`--comment`.
-
-Use `--events '*'` to replay every supported event declared by the
-channel. `--dry-run` prints payloads without posting them. `--out`
-writes fixture files but still posts unless you also pass `--dry-run`.
-
-`github doctor` checks `gh`, its login, and the pinned
-`cli/gh-webhook` extension. `--install` installs or repairs the
-extension. An environment-token override is a warning and doesn't make
-`github doctor` fail.
-
-See the [GitHub guide](../guides/github.md).
+agent-sdk bitbucket replay <pr-url-or-workspace/repo#N>
+  [--events a,b,c | '*'] [--comment <body>]
+  [--dir <path>] [--slug <slug>] [--channel <id>]
+  [--url <url>] [--host <host>] [--port <n>]
+  [--secret <secret>] [--dry-run] [--out <dir>] [--json]
+agent-sdk bitbucket events [--dir <path>] [--host <host>] [--port <n>] [--json]
+agent-sdk bitbucket forward [--dir <path>] [--host <host>] [--port <n>]
+```
+
+| Subcommand | Contract |
+| --- | --- |
+| `replay` | Read a pull request, synthesize webhook payloads in the host's Cloud or Data Center format, and post them to matching channels. |
+| `events` | List discovered Bitbucket channel URLs and event keys. |
+| `forward` | Print the repository-hook and tunnel recipe for live deliveries. |
+
+Replay supports `pullrequest:created`, `pullrequest:updated`,
+`pullrequest:comment_created`, and `repo:push`, along with their supported Data
+Center forms. It requires `BITBUCKET_TOKEN` with pull-request read access.
+`--secret` defaults to `BITBUCKET_WEBHOOK_SECRET`; `--dry-run` and `--out`
+follow the GitHub replay contract.
+
+See [Bitbucket](../guides/bitbucket.md) for Cloud and Data Center setup.
 
 ## Environment variables
 
-These environment variables affect the CLI and its channel packs.
+Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
+`CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, then the stored login.
 
-| Variable | Meaning |
+| Variable | Contract |
+| --- | --- |
+| `CURSOR_API_KEY` | Cursor credential. |
+| `CURSOR_API_KEY_FILE` | Path to a Cursor credential file. |
+| `CURSOR_SERVICE_ACCOUNT_KEY` | Team service-account credential used after the API key and key-file sources. |
+| `CURSOR_API_BASE_URL` | Backend for login, account, deployment, and event commands. |
+| `CURSOR_BACKEND_URL` | Backend for Agent SDK turns. Set it with `CURSOR_API_BASE_URL` when using a non-default backend. |
+| `AGENT_SERVE_CONFIG_DIR` | Override the CLI config directory for stored credentials and update state. |
+| `AGENT_SERVE_NO_UPDATE_CHECK`, `NO_UPDATE_NOTIFIER`, `CI` | Disable published-version checks when set to a non-empty value other than `0`. |
+| `CURSOR_JULY_SKIP_SKILL_INSTALL` | Skip the package install hook that refreshes coding-agent skills. |
+| `CURSOR_JULY_SKILLS_HOME` | Override the coding-agent skills directory. |
+| `GITHUB_WEBHOOK_SECRET` | Default signature secret for GitHub forwarding and replay. |
+| `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_INSTALLATION_ID` | GitHub App credentials for outbound API calls. |
+| `GITHUB_TOKEN`, `GH_TOKEN` | Token credentials for outbound GitHub calls. Unset both for `github forward`. |
+| `GITLAB_TOKEN` | Token for GitLab API reads and direct channel calls. |
+| `GITLAB_API_BASE_URL` | Override the GitLab REST base URL for self-managed hosts. |
+| `GITLAB_WEBHOOK_SECRET` | Default GitLab webhook token for replay and channel verification. |
+| `BITBUCKET_TOKEN` | Token for Bitbucket API reads and direct channel calls. |
+| `BITBUCKET_API_BASE_URL` | Override the Bitbucket Data Center REST base URL. |
+| `BITBUCKET_WEBHOOK_SECRET` | Default Bitbucket signing secret for replay and channel verification. |
+| `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | Slack tokens for one agent. Multi-agent servers use `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN`. |
+
+## Exit status
+
+| Command | Nonzero contract |
 | --- | --- |
-| `CURSOR_API_KEY` | Cursor credential. It takes precedence over `CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, and the stored login. |
-| `CURSOR_API_KEY_FILE` | Path to a Cursor credential file. Used when `CURSOR_API_KEY` is unset. When this variable is unset, the hosted default `/run/cursor/secrets/CURSOR_API_KEY` is tried. A present file takes precedence over `CURSOR_SERVICE_ACCOUNT_KEY` and the stored login. |
-| `CURSOR_SERVICE_ACCOUNT_KEY` | Team service-account credential. Used when `CURSOR_API_KEY` and `CURSOR_API_KEY_FILE` (including the hosted default path) are unset. It takes precedence over the stored login. |
-| `CURSOR_API_BASE_URL` | Backend used by login, account, deployment, and event-relay RPCs. |
-| `CURSOR_BACKEND_URL` | Backend used by the Cursor SDK harness. |
-| `AGENT_SERVE_CONFIG_DIR` | Directory for stored credentials and update-check state. Defaults to the CLI config directory under `~/.config`. |
-| `AGENT_SERVE_NO_UPDATE_CHECK` / `NO_UPDATE_NOTIFIER` | Disable the automatic published-version check when set to a non-empty value other than `0`. |
-| `CI` | Disable the automatic published-version check when set. |
-| `GITHUB_WEBHOOK_SECRET` | Default signing secret for GitHub forwarding and replay. |
-| `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` / `GITHUB_APP_INSTALLATION_ID` | GitHub App authentication for outbound API calls. |
-| `GITHUB_TOKEN` / `GH_TOKEN` | Token authentication for outbound API calls. Unset both for `github forward`. |
-| `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` | Slack tokens for one agent. Use `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` for each agent on a multi-agent host. |
-
-## What's next
-
-- [Project layout](./project-layout.md): files the CLI discovers
-- [HTTP API](./http-api.md): routes used by `chat`, `call`, and other clients
-- [Deployment](../deployment.md): production auth, state, and operations
+| No command | Print help and exit `1`. Explicit `help`, `--help`, and `-h` exit `0`. |
+| `run` | For local and running-server trajectories, exit `1` when the trajectory fails. |
+| `call` | Exit `1` unless the response succeeds with `ok: true`. |
+| `skill` | Exit `2` when the name is missing and `1` when the request fails. |
+| `trajectory` | Exit `1` when the reconstructed trajectory failed. |
+| `eval` | Exit `1` for failed cases, or scored cases below threshold with `--strict`; exit `2` for invalid eval options or an execution with no matching cases. An empty `--list` succeeds. |
+| `eval status` | Exit `3` while the batch runs, `1` when it failed or was cancelled, and `2` for invalid usage. |
+| `chat`, `session` | Exit `2` for documented option conflicts or missing required input. |
+| `validate` | Exit `1` when any project diagnostic has error severity. |
+| `convert-automation` | Exit `1` for invalid input, authentication, export, or file-write failure. Warnings and dependency-install failure don't change a successful conversion exit. |
+| Other commands | Exit nonzero when validation, authentication, a request, or the requested operation fails. |
+
+## Related
+
+- [Project layout](./project-layout.md)
+- [Sessions, events, and streaming](./sessions.md)
+- [Evals](./evals.md)
+- [HTTP API](./http-api.md)
+- [Deployment](../deployment.md)