@cursor/bdk 0.2.1 → 0.2.3

package/dist/docs/reference/cli.md

@@ -48,12 +48,12 @@ provide their own `help` subcommands.
 | --- | --- |
 | [`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 |
+| [`run`](#run) | Start or continue work on a local, running, or hosted 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 |
+| [`session`](#session) | Inspect a session or start a hosted session turn |
 | [`cost`](#cost) | Report token usage and estimated cost |
 | [`playground`](#playground) | Open an agent's playground |
 | [`trajectory`](#trajectory) | Summarize a saved event stream |
@@ -68,8 +68,8 @@ provide their own `help` subcommands.
 | [`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 |
+| [`event-repos`](#event-repos) | Replace a deployment's event repositories |
+| [`upgrade`](#upgrade) | Move a deployment 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 |
@@ -95,8 +95,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` | `chat`, `resume`, `run`, `call`, `skill`, `eval`, `logs`, `sessions`, `session`, `cost`, `playground`, `mcp` |
-| Managed application | Pass `--prod` | `run`, `session` |
+| Hosted deployment | Pass `--prod` | `run`, `session`, `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.
@@ -106,7 +105,7 @@ 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 a hosted deployment or managed application. Command support depends on the target type as listed above. |
+| `--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. |
 | `--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. |
@@ -184,9 +183,9 @@ prints the URL without opening a browser.
 `chat` connects to a running server and never starts an ephemeral one:
 
 ```text
-bdk chat [--url <baseUrl> | --prod] [--message <text>]
+bdk chat [--url <baseUrl>] [--message <text>]
   [--session <id> | --resume] [--continuation-token <token>]
-  [--slug <slug>] [--team <id>] [--json] [--text] [--no-color]
+  [--slug <slug>] [--json] [--text] [--no-color]
 ```
 
 | Input mode | Behavior |
@@ -208,9 +207,9 @@ token. An explicit session ID takes precedence.
 `resume` provides the same reattachment contract as `chat --session`:
 
 ```text
-bdk resume [sessionId] [--url <baseUrl> | --prod]
+bdk resume [sessionId] [--url <baseUrl>]
   [--message <text>] [--json] [--text]
-  [--continuation-token <token>] [--slug <slug>] [--team <id>]
+  [--continuation-token <token>] [--slug <slug>]
 ```
 
 Omit the session ID to select the most recently updated followable session.
@@ -232,27 +231,28 @@ bdk run [--dir <path>] [--message <text>]...
 
 | Option | Contract |
 | --- | --- |
-| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. Managed starts accept one message. |
+| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. `--prod` 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. |
+| `--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. |
 | `--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. |
+| `--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. |
 
 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.
+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).
 
 ### Call a tool {#call}
 
@@ -260,8 +260,8 @@ known. A fresh start doesn't return `sessionId` synchronously.
 
 ```text
 bdk call <tool> [--input <json>]
-  [--dir <path> | --url <baseUrl> | --prod]
-  [--session <id>] [--slug <slug>] [--team <id>]
+  [--dir <path> | --url <baseUrl>]
+  [--session <id>] [--slug <slug>]
 ```
 
 `--input` accepts JSON and defaults to `{}`. `--session` uses the session
@@ -269,6 +269,9 @@ 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`.
 
+Hosted deployments don't support `call`. Start a model turn with `run --prod`
+and check it with [`session`](#session).
+
 See [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn) for validation,
 busy-session behavior, and error codes.
 
@@ -277,8 +280,8 @@ busy-session behavior, and error codes.
 `skill` reads an authored skill without a model turn:
 
 ```text
-bdk skill <name> [--dir <path> | --url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--text]
+bdk skill <name> [--dir <path> | --url <baseUrl>]
+  [--slug <slug>] [--text]
 ```
 
 The default output is the server's JSON response. `--text` prints the rendered
@@ -287,14 +290,18 @@ The default output is the server's JSON response. `--text` prints the rendered
 ### List sessions {#sessions}
 
 ```text
-bdk sessions [--url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--bearer-token <token>] [--json]
+bdk sessions [--url <baseUrl>]
+  [--slug <slug>] [--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.
 
+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).
+
 ### Inspect a session {#session}
 
 ```text
@@ -313,29 +320,31 @@ 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 managed session or continue the supplied managed session ID. |
+| `--prod --message <text>` | Start a hosted session or continue the supplied hosted 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.
+`--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.
 
 ### Follow logs {#logs}
 
 ```text
-bdk logs [--url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--once] [--json]
+bdk logs [--url <baseUrl>]
+  [--slug <slug>] [--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.
+exits; `--json` emits newline-delimited JSON events. For a hosted deployment,
+use [`deployment`](#deployment) for rollout status and
+[`session <sessionId> --prod`](#session) for a session's runs and logs.
 
 ### Report costs {#cost}
 
 ```text
-bdk cost [sessionId] [--url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--json]
+bdk cost [sessionId] [--url <baseUrl>]
+  [--slug <slug>] [--json]
 ```
 
 With a session ID, `cost` prints per-turn token usage and estimated cost.
@@ -353,6 +362,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.
 
 ### Inspect a trajectory {#trajectory}
 
@@ -375,8 +386,7 @@ bdk eval [--dir <path>] [evalId...]
   [--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>]
+  [--url <baseUrl>] [--no-wait] [--slug <slug>]
 ```
 
 Select an exact case such as `weather/nyc`, a file prefix such as `weather`,
@@ -399,22 +409,18 @@ between 1 and 200.
 | `--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. |
+| `--no-wait` | Return after a running server accepts the batch. |
 
-A running server or hosted deployment prints its Eval ID when it accepts the
-batch.
+A running server 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`.
+requires an ID. The `status` and `cancel` subcommands require `--url`.
 
 ## Projects
 
@@ -566,7 +572,7 @@ service-account API key with agent access can deploy.
 | `--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. |
+| `--cursor-events-repo <owner/name>` | Watch a repository's Cursor events. Repeat the flag for each repository; the repositories you pass replace the previous list. Without the flag, the deployment watches its GitHub source repository. |
 | `--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. |
@@ -574,7 +580,8 @@ service-account API key with agent access can deploy.
 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.
+allowed, or a trailing `:port` for a protocol that is not HTTPS, with at most
+64 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
@@ -609,8 +616,7 @@ 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.
+runs and reminder wakes.
 
 ### Cancel active runs {#cancel-runs}
 
@@ -618,8 +624,8 @@ reject this option.
 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
+The command requests cancellation for a deployment's active runs and reminder
+wakes. 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.
@@ -631,11 +637,11 @@ 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.
+The supplied repositories replace the deployment's complete event repository
+list; they aren't merged with the previous list. Omit `--repo` to clear the
+list.
 
-### Upgrade a managed application {#upgrade}
+### Upgrade a deployment {#upgrade}
 
 ```text
 bdk upgrade <slug> [--release <id-or-version>]
@@ -690,11 +696,8 @@ most 4096 bytes, and each deployment holds at most 32 secrets.
 ### 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]
 ```
@@ -703,7 +706,6 @@ 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. |
-| `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}
 
@@ -718,7 +720,7 @@ 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 managed deployment's service account through Cursor. `--store` isn't needed. |
+| `defineConnection({ cursorAccount: true })` | Authorize the hosted 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