@cursor/bdk 0.2.1

package/docs/reference/cli.md

@@ -0,0 +1,909 @@
+---
+title: "CLI"
+description: "Look up BDK commands, targets, flags, outputs, and exit status."
+---
+
+# BDK CLI
+
+The Grok Bot Development Kit (BDK) uses the `@cursor/bdk` package and `bdk`
+CLI.
+
+> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
+> after publication.
+
+```text
+bdk <command>
+```
+
+The command catalog below documents the `bdk` binary that will ship with
+`@cursor/bdk`. Run the published binary with Node 22.13 or newer; Bun is not
+supported. Commands exit nonzero when validation or a synchronous request fails;
+asynchronous commands can exit `0` once work is accepted. Project paths use the
+[BDK project layout](./project-layout.md).
+
+After publication, install `@cursor/bdk` to obtain the binary. `bdk 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/bdk` |
+| [`init`](#init) | Scaffold a BDK 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`, `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`:
+
+```text
+bdk 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]
+  [--allow-anonymous-grokbot]
+  [--public-url <url>]
+  [--no-schedules] [--no-playground] [--no-docs]
+  [--cursor-events --repo <owner/name>]...
+```
+
+| Option | Contract |
+| --- | --- |
+| `--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. |
+| `--allow-anonymous-grokbot` | Let anonymous callers drive hosted Grok Bot runtime agents. Requires an authenticating proxy. |
+| `--public-url <url>` | Set the externally reachable base URL that turns running off the serve host use for peer MCP and host bridges. It does not expose the server; configure the listener or proxy separately. Local-runtime peers use loopback. |
+| `--no-schedules` | Disable schedule firing outside dev mode. |
+| `--no-playground` | Skip the playground. |
+| `--no-docs` | Skip the documentation site at `/docs`. |
+| `--cursor-events` | Receive SCM events through Cursor. Requires sign-in and one or more repeatable `--repo owner/name` values. |
+
+Multi-agent slugs start with a letter or digit and contain only letters,
+digits, `_`, or `-`. The reserved slugs are `v1`, `playground`, and `docs`.
+
+### Develop locally {#dev}
+
+`dev` is `serve --dev` with an optional positional project path:
+
+```text
+bdk dev
+bdk dev ./bdk-pr-reviewer --port 3000
+```
+
+It accepts every `serve` option. Pass at most one positional path, and don't
+combine it with a different `--dir`.
+
+### Serve the docs {#docs}
+
+```text
+bdk docs [--port <n>] [--host 127.0.0.1] [--print]
+```
+
+`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.
+
+## Sessions and turns
+
+### Chat with an agent {#chat}
+
+`chat` connects to a running server and never starts an ephemeral one:
+
+```text
+bdk chat [--url <baseUrl> | --prod] [--message <text>]
+  [--session <id> | --resume] [--continuation-token <token>]
+  [--slug <slug>] [--team <id>] [--json] [--text] [--no-color]
+```
+
+| 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.
+
+### Resume a session {#resume}
+
+`resume` provides the same reattachment contract as `chat --session`:
+
+```text
+bdk resume [sessionId] [--url <baseUrl> | --prod]
+  [--message <text>] [--json] [--text]
+  [--continuation-token <token>] [--slug <slug>] [--team <id>]
+```
+
+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`.
+
+### Run turns {#run}
+
+`run` sends messages to an ephemeral, running, or `--prod` target:
+
+```text
+bdk 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>]
+```
+
+| 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.
+
+### Call a tool {#call}
+
+`call` invokes a server tool without a model turn:
+
+```text
+bdk call <tool> [--input <json>]
+  [--dir <path> | --url <baseUrl> | --prod]
+  [--session <id>] [--slug <slug>] [--team <id>]
+```
+
+`--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.
+
+### Read a skill {#skill}
+
+`skill` reads an authored skill without a model turn:
+
+```text
+bdk skill <name> [--dir <path> | --url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>] [--text]
+```
+
+The default output is the server's JSON response. `--text` prints the rendered
+`SKILL.md` content.
+
+### List sessions {#sessions}
+
+```text
+bdk sessions [--url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>] [--bearer-token <token>] [--json]
+```
+
+Text output shows the session ID, channel, mode, turn count, running status,
+and update time. `--json` prints `{ sessions }`, including continuation
+tokens.
+
+### Inspect a session {#session}
+
+```text
+bdk session <sessionId> [--url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>]
+  [--json | --text | --events] [--out <file.ndjson>]
+
+bdk 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. |
+
+`--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}
+
+```text
+bdk logs [--url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>] [--once] [--json]
+```
+
+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.
+
+### Report costs {#cost}
+
+```text
+bdk cost [sessionId] [--url <baseUrl> | --prod]
+  [--slug <slug>] [--team <id>] [--json]
+```
+
+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.
+
+### Open the playground {#playground}
+
+```text
+bdk playground [--url <baseUrl> | --prod] [--session <id>]
+  [--slug <slug>] [--team <id>] [--bearer-token <token>] [--print]
+```
+
+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.
+
+### Inspect a trajectory {#trajectory}
+
+```text
+bdk trajectory --events <file.ndjson> [--text]
+```
+
+The command converts an NDJSON stream into the trajectory JSON returned by
+`run`. `--text` prints the compact view.
+
+## Evals
+
+### Run evals {#eval}
+
+`eval` discovers `evals/**/*.eval.{ts,js}` and runs selected cases:
+
+```text
+bdk 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>]
+```
+
+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.
+
+| 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. |
+
+A running server or hosted deployment prints its Eval ID when it accepts the
+batch.
+Use these commands to inspect or cancel it:
+
+```text
+bdk eval status [evalId] --prod [--slug <slug>] [--team <id>]
+bdk eval status [evalId] --url <baseUrl>
+bdk eval cancel <evalId> --prod [--slug <slug>] [--team <id>]
+bdk eval cancel <evalId> --url <baseUrl>
+```
+
+`eval status` without an ID lists recent remote runs. `eval status --out`
+requires an ID. The `status` and `cancel` subcommands require `--url` or
+`--prod`.
+
+## Projects
+
+### Scaffold a project {#init}
+
+```text
+bdk init [directory] [--template <name>] [--var id=value]... [--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 `bdk` on `PATH`.
+
+| Option | Contract |
+| --- | --- |
+| `--template <name>` | Use a bundled template: `agentic-owners`, `agents-md`, `code-wiki`, `demo`, `grokbot-agents`, `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. |
+
+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.
+
+### Convert an Automation {#convert-automation}
+
+```text
+bdk 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 }`.
+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.
+
+See [Convert a Cursor Automation](../guides/convert-automation.md) for the
+generated project and features that need manual review.
+
+### Install coding-agent skills {#install-skills}
+
+```text
+bdk install-skills [--print] [--json]
+```
+
+The command replaces the installed BDK skills with the package copy and
+removes stale bundled skills. `--print` previews the change. `--json` prints
+`{ ok, dryRun, directory, firstInstall, skills, removed }`.
+
+When `@cursor/bdk` publishes, package installation will perform this copy.
+Run `bdk install-skills` when you need to refresh it.
+
+### Inspect a project {#info}
+
+```text
+bdk info [--dir <path>] [--json]
+```
+
+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}
+
+```text
+bdk validate [--dir <path>]
+```
+
+`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}
+
+```text
+bdk manifest [--dir <path>] [--json]
+```
+
+`manifest` validates one project and prints its deployment metadata without a
+network request. Default output is indented JSON; `--json` prints one compact
+line.
+
+## Credentials and versions
+
+### Manage credentials {#login-logout-whoami}
+
+```text
+bdk login [--api-key <key>] [--key-name <name>]
+bdk whoami [--json]
+bdk logout
+```
+
+| 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. |
+
+### Print the version {#version}
+
+```text
+bdk version [--json]
+bdk --version
+bdk -V
+```
+
+Text output is the version number. `--json` prints
+`{ name, version }`.
+
+### Update the CLI {#update}
+
+```text
+bdk update
+```
+
+`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 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.
+
+## Managed hosting
+
+### Deploy agents {#deploy}
+
+```text
+bdk 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 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}
+
+```text
+bdk deployments [--team <id>] [--json]
+```
+
+Text output shows slug, status, generation, kind, and update time. `--json`
+prints `{ deployments }` and may also include `applications`. An empty list
+succeeds.
+
+### Inspect a deployment {#deployment}
+
+```text
+bdk deployment <slug> [--team <id>] [--json]
+```
+
+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}
+
+```text
+bdk stop <slug> [--team <id>] [--no-wait] [--cancel-runs] [--json]
+```
+
+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.
+
+### Cancel active runs {#cancel-runs}
+
+```text
+bdk cancel-runs <slug> [--team <id>] [--json]
+```
+
+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}
+
+```text
+bdk event-repos <slug> [--repo <owner/name>]...
+  [--team <id>] [--json]
+```
+
+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.
+
+### Upgrade a managed application {#upgrade}
+
+```text
+bdk upgrade <slug> [--release <id-or-version>]
+  [--team <id>] [--json]
+```
+
+`--release` accepts a release ID or version. Omit it to select the newest
+ready release. `--json` prints `{ releaseId }`.
+
+### Delete a deployment {#delete}
+
+```text
+bdk delete <slug> [--team <id>] [--no-wait] [--json]
+```
+
+`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}
+
+```text
+bdk rotate-token <slug> [--team <id>] [--json]
+```
+
+The old token stops working immediately. The replacement appears once;
+`--json` prints `{ aliasToken }`.
+
+### Manage deployment secrets {#secrets}
+
+```text
+bdk secrets set <slug> NAME [NAME2 ...]
+  [--team <id>] [--from-argv] [--json]
+bdk secrets list <slug> [--team <id>] [--json]
+bdk secrets unset <slug> NAME [--team <id>] [--json]
+```
+
+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 connections
+
+### Connect an MCP client {#mcp}
+
+```text
+bdk mcp --prod [--slug <slug>] [--team <id>]
+bdk mcp --url <baseUrl> [--bearer-token <token>]
+
+bdk mcp install --prod [--slug <slug>] [--team <id>]
+  [--name <server-name>] [--print] [--json] [--remote]
+bdk mcp install --url <baseUrl> [--bearer-token <token>]
+  [--name <server-name>] [--print] [--json]
+```
+
+| 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. |
+
+### Authorize MCP OAuth {#mcp-oauth}
+
+```text
+bdk mcp oauth <connection> [--dir <path>] [--store]
+  [--slug <slug>] [--team <id>]
+```
+
+`<connection>` is the basename under `bot/mcp-connections/` or
+`bot/host-connections/`.
+
+| 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. |
+
+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 [Host MCP OAuth](../guides/mcp-oauth.md) for the full setup flow.
+
+## Channel helpers
+
+### Configure Slack {#slack}
+
+```text
+bdk slack setup
+bdk slack create [--dir <path>] [--name <name>] [--prod]
+  [--slack-team <id>] [--team <id>] [--icon <url-or-file>]
+  [--prefix <prefix> | --no-prefix] [--channel-posts] [--json]
+bdk slack destroy [--dir <path>] [--prod]
+  [--slack-team <id>] [--team <id>] [--json]
+bdk slack icon <url-or-file> [--dir <path>] [--prod]
+  [--slack-team <id>] [--team <id>] [--json]
+bdk slack init --manual [--dir <path>] [--name <name>]
+  [--prefix <prefix> | --no-prefix] [--channel-posts]
+  [--install | --no-install] [--slack-team <id>] [--prod]
+bdk slack manifest [--dir <path>] [--name <name>]
+  [--env dev|prod|both] [--channel-posts] [--print]
+bdk slack doctor [--dir <path>]
+  [--prefix <prefix> | --no-prefix] [--channel <id>]... [--json]
+```
+
+| 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.
+
+### Test GitHub webhooks {#github}
+
+```text
+bdk 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]
+bdk 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]
+bdk github events [--dir <path>] [--host <host>] [--port <n>] [--json]
+bdk github doctor [--install] [--json]
+```
+
+| 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. |
+
+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`.
+
+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.
+
+See [GitHub](../guides/github.md) for channel setup and live delivery.
+
+### Test GitLab webhooks {#gitlab}
+
+```text
+bdk 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]
+bdk gitlab events [--dir <path>] [--host <host>] [--port <n>] [--json]
+bdk 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}
+
+```text
+bdk 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]
+bdk bitbucket events [--dir <path>] [--host <host>] [--port <n>] [--json]
+bdk 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
+
+Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
+`CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, then the stored login.
+
+| 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 BDK 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`. |
+| `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 |
+| --- | --- |
+| 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)