@cursor/bdk 0.2.13 → 0.2.15

package/dist/docs/reference/cli.md

@@ -65,12 +65,17 @@ provide their own `help` subcommands.
 | [`deployments`](#deployments) | List deployments |
 | [`deployment`](#deployment) | Inspect one deployment |
 | [`stop`](#stop) | Stop a deployment |
+| [`start`](#start) | Start a stopped deployment |
+| [`kill`](#kill) | Stop a deployment, cancel its runs, and lock deploys |
+| [`unlock-deploys`](#unlock-deploys) | Let a killed deployment deploy again |
 | [`cancel-runs`](#cancel-runs) | Cancel active runs and reminder wakes |
 | [`event-repos`](#event-repos) | Replace a deployment's event repositories |
 | [`upgrade`](#upgrade) | Move a deployment to a release |
+| [`rollback`](#rollback) | Move a deployment to an earlier release |
 | [`delete`](#delete) | Delete a deployment |
 | [`rotate-token`](#rotate-token) | Replace a deployment's alias token |
 | [`secrets`](#secrets) | Set, list, or remove deployment secrets |
+| [`images`](#images) | Push, list, or remove container images for persistent agents |
 
 ### Connection and channel commands
 
@@ -93,7 +98,7 @@ Commands that send requests support these targets:
 | 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` | `run`, `session`, `playground` |
+| Hosted deployment | Pass `--prod` | `run`, `session`, `logs`, `playground` |
 
 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.
@@ -103,8 +108,8 @@ An explicit `--url` must include the slug for a multi-agent server, such as
 | --- | --- |
 | `--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 the hosted deployment. Only `run`, `session`, and `playground` accept it. |
-| `--slug <slug>` | Select an agent from a multi-agent project or a hosted resource. Under `--prod`, the default is the `--dir` basename. |
+| `--prod` | Use the hosted deployment. Only `run`, `session`, `logs`, and `playground` accept it; `chat`, `resume`, `call`, `skill`, `sessions`, `cost`, and `mcp` report that the deployment doesn't support the command, and `eval` rejects the flag. |
+| `--slug <slug>` | Select an agent from a multi-agent project or a hosted deployment. 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. |
@@ -229,28 +234,31 @@ bdk run [--dir <path>] [--message <text>]...
 
 | Option | Contract |
 | --- | --- |
-| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. `--prod` starts accept one message. |
+| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. A `--prod` run takes exactly one message. |
 | `--messages-file <path>` | Read a JSON array of strings. File messages run before repeated `--message` values. |
-| `--session <id>` | Continue a session. With `--prod`, pass a hosted `ses_...` ID. |
-| `--continuation-token <token>` | Continue the session selected by `--session` on a running server. `--prod` starts use `--session` instead. |
+| `--session <id>` | Continue a session. With `--prod`, pass a hosted `ses_...` ID from a session that `run --prod` or `session --prod` started; Slack, SCM, and custom-route sessions can't be continued this way. |
+| `--continuation-token <token>` | Continue the session selected by `--session` on a running server. `--prod` doesn't accept it. |
 | `--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 `--prod` turn as non-mutating. |
-| `--as-of <instant>` | Freeze a `--prod` session's clock at a timezone-bearing ISO-8601 instant. |
-| `--component <key>` | Select a hosted deployment's component instead of its default. |
+| `--dry-run` | Start a `--prod` session that runs read tools and stubs write tools. |
+| `--as-of <instant>` | Freeze a `--prod` session's clock at an ISO-8601 instant with a timezone, such as `2026-08-31T12:00:00Z`. |
+| `--component <key>` | Wake a named component of a `--prod` deployment instead of its default. A continued session must belong to that component. |
 
 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. With `--prod`, `run` prints a `deliveryId` when the deployment accepts
-the turn and returns before the turn finishes. A fresh start has no
-`sessionId` yet, even with `--dry-run`; a continuation includes it. `--prod`
-starts ignore `--events`, `--no-events`, `--text`, `--timeout-ms`, and
-`--no-stream`, and a successful start exits `0` before the turn outcome is
-known. See [Verify a hosted turn](/docs/deployment.md#verify-a-hosted-turn).
+enabled.
+
+With `--prod`, `run` returns as soon as the deployment accepts the turn and
+exits `0` before the turn outcome is known. It prints `deliveryId`,
+`workflowId`, and `sessionMode`, plus `dryRun` and `asOf` when set. A fresh
+start has no `sessionId` yet; a continuation echoes the `--session` value.
+`--events`, `--no-events`, `--text`, `--timeout-ms`, and `--no-stream` have no
+effect. See [Verify a hosted turn](/docs/deployment.md#verify-a-hosted-turn) for
+finding and following the new session.
 
 ### Call a tool {#call}
 
@@ -296,9 +304,9 @@ Text output shows the session ID, channel, mode, turn count, running status,
 and update time. `--json` prints `{ sessions }`, including continuation
 tokens.
 
-Hosted deployments don't support `sessions`. Find a hosted session in the
-deployment's **Sessions** list in the dashboard, then check it with
-[`session <sessionId> --prod`](#session).
+Hosted deployments don't support `sessions`. Find a hosted session ID in the
+[`logs --prod`](#logs) headers or the deployment's **Sessions** list in the
+dashboard, then check it with [`session <sessionId> --prod`](#session).
 
 ### Inspect a session {#session}
 
@@ -308,7 +316,7 @@ bdk session <sessionId> [--url <baseUrl> | --prod]
   [--json | --text | --events] [--out <file.ndjson>]
 
 bdk session --prod [<sessionId>] --slug <slug> --message <text>
-  [--dry-run] [--as-of <instant>] [--component <key>]
+  [--team <id>] [--dry-run] [--as-of <instant>] [--component <key>]
 ```
 
 | Option | Contract |
@@ -318,28 +326,33 @@ bdk session --prod [<sessionId>] --slug <slug> --message <text>
 | `--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 hosted session or continue the supplied hosted session ID. |
+| `--prod --message <text>` | Start a hosted session, or continue the supplied hosted session ID, with the same contract as [`run --prod`](#run). |
 
-`--events` and `--json` are mutually exclusive. With `--prod`, the command
-prints the session's runs and logs in text or JSON, and `--events` and `--out`
-aren't available. While a hosted turn is running, text output also reports the
-event count so far and prints `Turn running; runs may lag behind events.` Use
-[`resume`](#resume) to continue a conversational session.
+`--events` and `--json` are mutually exclusive. Use [`resume`](#resume) to
+continue a conversational session on a local or running server.
+
+With `--prod`, the command prints the session's hosted executions: one line
+per run with its status, duration, and time, followed by that run's log
+lines. `--json` prints `{ sessionId, executions, startLog, ... }`. `--events`
+and `--out` aren't available. While a turn is running, text output also
+reports the event count and latest event type and prints
+`Turn running; runs may lag behind events.` A run can show `running` with no
+logs until the turn ends, so a growing event count is the progress signal.
 
 ### Follow logs {#logs}
 
 ```text
 bdk logs [sessionId] [--url <baseUrl> | --prod]
-  [--session <sessionId>] [--slug <slug>] [--once] [--json]
+  [--session <sessionId>] [--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. With `--prod`, it follows
-the output of the hosted deployment's most recent sessions and prints a
-`==> <sessionId> (<channel>) <==` header each time the output switches
-sessions. Pass a session ID, as an argument or with `--session`, to follow only
-that session. Hosted log events carry `sessionId` and `line` rather than
-`index` and `at`.
+the output of the hosted deployment's most recent sessions on every channel
+and prints a `==> <sessionId> (<channel>) <==` header each time the output
+switches sessions. Pass a session ID, as an argument or with `--session`, to
+follow only that session; a session ID requires `--prod`. Hosted log events
+carry `sessionId` and `line` rather than `index` and `at`.
 
 ### Report costs {#cost}
 
@@ -363,8 +376,8 @@ bdk playground [--url <baseUrl> | --prod] [--session <id>]
 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.
-`--session` links for a hosted deployment may not open yet; check that session
-with [`session <sessionId> --prod`](#session) instead.
+With `--prod`, the URL opens the deployment's playground under **Deployed
+Agents** in the dashboard.
 
 ### Inspect a trajectory {#trajectory}
 
@@ -654,6 +667,36 @@ 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.
 
+### Start a deployment {#start}
+
+```text
+bdk start <slug> [--team <id>] [--json]
+```
+
+`start` resumes a stopped deployment. It doesn't remove the deploy lock
+that [`kill`](#kill) sets.
+
+### Kill a deployment {#kill}
+
+```text
+bdk kill <slug> [--team <id>] [--json]
+```
+
+Use `kill` in an emergency. It locks deploys of the slug, stops the
+deployment, and requests cancellation of its active runs and reminder
+wakes. To bring the deployment back, run
+[`unlock-deploys`](#unlock-deploys) and then [`start`](#start).
+
+### Unlock deploys {#unlock-deploys}
+
+```text
+bdk unlock-deploys <slug> [--team <id>] [--json]
+```
+
+`unlock-deploys` removes the lock that `kill` sets, so `deploy`,
+`upgrade`, and `rollback` work for the slug again. It doesn't resume
+traffic; run `start` for that.
+
 ### Cancel active runs {#cancel-runs}
 
 ```text
@@ -684,6 +727,17 @@ bdk upgrade <slug> [--release <id-or-version>]
 `--release` accepts a release ID or version. Omit it to select the newest
 ready release. `--json` prints `{ releaseId }`.
 
+### Roll back a deployment {#rollback}
+
+```text
+bdk rollback <slug> [--release <id-or-version>]
+  [--team <id>] [--json]
+```
+
+`rollback` moves the deployment to an earlier ready release without
+building a new one. Omit `--release` to select the release before the
+current one. `--json` prints `{ releaseId }`.
+
 ### Delete a deployment {#delete}
 
 ```text
@@ -732,6 +786,24 @@ most 4096 bytes, and each deployment holds at most 32 secrets.
 `{ secretNames }` for `set`, `{ secrets }` for `list`, and `{ removed }` for
 `unset`. Changes are available to subsequent hosted work.
 
+### Manage container images {#images}
+
+```text
+bdk images push <local-image> --name <name> [--team <id>] [--json]
+bdk images list [--team <id>] [--json]
+bdk images rm <name> [--team <id>] [--json]
+```
+
+A persistent agent can run inside a container image that your team pushes
+and names in `hosting.image`. `push` needs Docker on your machine. It
+checks the local image first: the image must be `linux/amd64` and have
+`bash`, `git`, `node` 22.13 or newer, and `npm` on `PATH`. The command
+then compresses the image and uploads it under `--name`.
+
+`list` shows the team's images and how many the team can keep, and `rm`
+deletes one image. A deploy pins the image it uses, so after you push a
+new image under the same name, deploy again to pick it up.
+
 ## MCP connections
 
 ### Connect an MCP client {#mcp}
@@ -748,10 +820,13 @@ bdk mcp install --url <baseUrl> [--bearer-token <token>]
 | `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. |
 
+Hosted deployments don't support `mcp` or `mcp install`; both report that the
+deployment doesn't support the command when you pass `--prod`.
+
 ### Authorize MCP OAuth {#mcp-oauth}
 
 ```text
-bdk mcp oauth <connection> [--dir <path>] [--store]
+bdk mcp oauth <connection> [--dir <path>]
   [--slug <slug>] [--team <id>]
 ```
 
@@ -760,13 +835,11 @@ bdk mcp oauth <connection> [--dir <path>] [--store]
 
 | 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 hosted deployment's service account through Cursor. `--store` isn't needed. |
+| `defineConnection({ url, oauth: true })` | Open a browser PKCE flow and save tokens in `mcp-auth.json` under the CLI config directory. |
+| `defineConnection({ cursorAccount: true })` | Authorize the hosted deployment's service account through Cursor. |
 
-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.
+URL-connection tokens are bound to the resource URL; authorize again after
+changing it.
 
 See [Host MCP OAuth](/docs/guides/mcp-oauth.md) for the full setup flow.