@cursor/bdk 0.2.1

package/dist/docs/assets/reference_cli.md.BK2QUH67.js

@@ -0,0 +1,97 @@
+import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"CLI","description":"Look up BDK commands, targets, flags, outputs, and exit status.","frontmatter":{"title":"CLI","description":"Look up BDK commands, targets, flags, outputs, and exit status."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),d={name:"reference/cli.md"};function n(c,e,r,l,i,p){return s(),a("div",null,[...e[0]||(e[0]=[o(`<h1 id="bdk-cli" tabindex="-1">BDK CLI <a class="header-anchor" href="#bdk-cli" aria-label="Permalink to &quot;BDK CLI&quot;">​</a></h1><p>The Grok Bot Development Kit (BDK) uses the <code>@cursor/bdk</code> package and <code>bdk</code> CLI.</p><blockquote><p><strong>Docs ahead:</strong> <code>@cursor/bdk</code> is not on npm yet. This command will work after publication.</p></blockquote><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk &lt;command&gt;</span></span></code></pre></div><p>The command catalog below documents the <code>bdk</code> binary that will ship with <code>@cursor/bdk</code>. 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 <code>0</code> once work is accepted. Project paths use the <a href="./project-layout.html">BDK project layout</a>.</p><p>After publication, install <code>@cursor/bdk</code> to obtain the binary. <code>bdk help</code> prints top-level help; the Slack, GitHub, GitLab, and Bitbucket command packs provide their own <code>help</code> subcommands.</p><h2 id="command-catalog" tabindex="-1">Command catalog <a class="header-anchor" href="#command-catalog" aria-label="Permalink to &quot;Command catalog&quot;">​</a></h2><h3 id="development-commands" tabindex="-1">Development commands <a class="header-anchor" href="#development-commands" aria-label="Permalink to &quot;Development commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><code>help</code>, <code>--help</code>, <code>-h</code></td><td>Print top-level help</td></tr><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve one or more agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Serve agents with local-development behavior</td></tr><tr><td><a href="#docs"><code>docs</code></a></td><td>Serve the documentation bundled with <code>@cursor/bdk</code></td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a BDK project</td></tr><tr><td><a href="#convert-automation"><code>convert-automation</code></a></td><td>Export a Cursor Automation into a project</td></tr><tr><td><a href="#install-skills"><code>install-skills</code></a></td><td>Refresh the bundled coding-agent skills</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered project surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check project diagnostics and set the exit status</td></tr><tr><td><a href="#manifest"><code>manifest</code></a></td><td>Print deployment metadata as JSON</td></tr><tr><td><a href="#version"><code>version</code></a></td><td>Print the installed package version</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#login-logout-whoami"><code>login</code></a></td><td>Sign the host in to Cursor</td></tr><tr><td><a href="#login-logout-whoami"><code>logout</code></a></td><td>Remove the stored Cursor credential</td></tr><tr><td><a href="#login-logout-whoami"><code>whoami</code></a></td><td>Show the active Cursor credential</td></tr></tbody></table><h3 id="session-and-eval-commands" tabindex="-1">Session and eval commands <a class="header-anchor" href="#session-and-eval-commands" aria-label="Permalink to &quot;Session and eval commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running agent</td></tr><tr><td><a href="#resume"><code>resume</code></a></td><td>Reattach chat to a previous session</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Start or continue work on a local, running, or managed agent</td></tr><tr><td><a href="#call"><code>call</code></a></td><td>Call a server tool without a model turn</td></tr><tr><td><a href="#skill"><code>skill</code></a></td><td>Read an authored skill without a model turn</td></tr><tr><td><a href="#logs"><code>logs</code></a></td><td>Follow or dump agent logs</td></tr><tr><td><a href="#sessions"><code>sessions</code></a></td><td>List sessions</td></tr><tr><td><a href="#session"><code>session</code></a></td><td>Inspect a session or start a managed session turn</td></tr><tr><td><a href="#cost"><code>cost</code></a></td><td>Report token usage and estimated cost</td></tr><tr><td><a href="#playground"><code>playground</code></a></td><td>Open an agent&#39;s playground</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved event stream</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>List, run, inspect, or cancel evals</td></tr></tbody></table><h3 id="managed-hosting-commands" tabindex="-1">Managed hosting commands <a class="header-anchor" href="#managed-hosting-commands" aria-label="Permalink to &quot;Managed hosting commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy one or more agents</td></tr><tr><td><a href="#deployments"><code>deployments</code></a></td><td>List deployments</td></tr><tr><td><a href="#deployment"><code>deployment</code></a></td><td>Inspect one deployment</td></tr><tr><td><a href="#stop"><code>stop</code></a></td><td>Stop a deployment</td></tr><tr><td><a href="#cancel-runs"><code>cancel-runs</code></a></td><td>Cancel active runs and reminder wakes</td></tr><tr><td><a href="#event-repos"><code>event-repos</code></a></td><td>Replace a managed application&#39;s event repositories</td></tr><tr><td><a href="#upgrade"><code>upgrade</code></a></td><td>Move a managed application to a release</td></tr><tr><td><a href="#delete"><code>delete</code></a></td><td>Delete a deployment</td></tr><tr><td><a href="#rotate-token"><code>rotate-token</code></a></td><td>Replace a deployment&#39;s alias token</td></tr><tr><td><a href="#secrets"><code>secrets</code></a></td><td>Set, list, or remove deployment secrets</td></tr></tbody></table><h3 id="connection-and-channel-commands" tabindex="-1">Connection and channel commands <a class="header-anchor" href="#connection-and-channel-commands" aria-label="Permalink to &quot;Connection and channel commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><a href="#mcp"><code>mcp</code></a></td><td>Proxy an agent&#39;s MCP endpoint over stdio</td></tr><tr><td><a href="#mcp"><code>mcp install</code></a></td><td>Add the agent to an MCP client config</td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize an MCP connection</td></tr><tr><td><a href="#slack"><code>slack</code></a></td><td>Provision and check Slack channel apps</td></tr><tr><td><a href="#github"><code>github</code></a></td><td>Forward, replay, and inspect GitHub webhooks</td></tr><tr><td><a href="#gitlab"><code>gitlab</code></a></td><td>Replay and inspect GitLab webhooks</td></tr><tr><td><a href="#bitbucket"><code>bitbucket</code></a></td><td>Replay and inspect Bitbucket webhooks</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Targets <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Targets {#choose-a-target}&quot;">​</a></h2><p>Commands that send requests support these targets:</p><table tabindex="0"><thead><tr><th>Target</th><th>Selection</th><th>Commands</th></tr></thead><tbody><tr><td>Ephemeral local server</td><td>Omit <code>--url</code> and <code>--prod</code></td><td><code>run</code>, <code>call</code>, <code>skill</code>, <code>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code></td><td><code>chat</code>, <code>resume</code>, <code>run</code>, <code>call</code>, <code>skill</code>, <code>eval</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>mcp</code></td></tr><tr><td>Default local server</td><td>Omit <code>--url</code> and <code>--prod</code>; uses <code>http://127.0.0.1:3000</code></td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code></td></tr><tr><td>Hosted deployment</td><td>Pass <code>--prod</code></td><td><code>chat</code>, <code>resume</code>, <code>run</code>, <code>call</code>, <code>skill</code>, <code>eval</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>mcp</code></td></tr><tr><td>Managed application</td><td>Pass <code>--prod</code></td><td><code>run</code>, <code>session</code></td></tr></tbody></table><p>An explicit <code>--url</code> must include the slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. <code>--slug</code> never changes an explicit URL. <code>--url</code> and <code>--prod</code> are mutually exclusive.</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>--dir &lt;path&gt;</code></td><td>Select the project root. The default is the current directory.</td></tr><tr><td><code>--url &lt;baseUrl&gt;</code></td><td>Use a running agent instead of local project discovery.</td></tr><tr><td><code>--prod</code></td><td>Use a hosted deployment or managed application. Command support depends on the target type as listed above.</td></tr><tr><td><code>--slug &lt;slug&gt;</code></td><td>Select an agent from a multi-agent project or a hosted resource. Under <code>--prod</code>, the default is the <code>--dir</code> basename.</td></tr><tr><td><code>--team &lt;id&gt;</code></td><td>Select a Cursor team. The signed-in account&#39;s team is the default.</td></tr><tr><td><code>--api-key &lt;key&gt;</code></td><td>Override the Cursor credential for commands that authenticate with Cursor.</td></tr><tr><td><code>--bearer-token &lt;token&gt;</code></td><td>Authenticate to a running server with a bearer token.</td></tr><tr><td><code>--state-root &lt;path&gt;</code></td><td>Select local state for <code>serve</code> and ephemeral <code>run</code>, <code>call</code>, <code>skill</code>, and <code>eval</code> targets. Running and <code>--prod</code> targets ignore it.</td></tr><tr><td><code>--json</code></td><td>Request machine-readable output when the command supports it. <code>run</code> already defaults to JSON.</td></tr></tbody></table><h2 id="local-servers" tabindex="-1">Local servers <a class="header-anchor" href="#local-servers" aria-label="Permalink to &quot;Local servers&quot;">​</a></h2><h3 id="serve" tabindex="-1">Serve agents <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;Serve agents {#serve}&quot;">​</a></h3><p><code>serve</code> mounts every project discovered under <code>--dir</code>:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk serve [--dir &lt;path&gt;] [--port &lt;n&gt;] [--host &lt;host&gt;]</span></span>
+<span class="line"><span>  [--mode multi|single] [--dev] [--api-key &lt;key&gt;]</span></span>
+<span class="line"><span>  [--state-root &lt;path&gt;]</span></span>
+<span class="line"><span>  [--bearer-token &lt;secret&gt; | --allow-anonymous]</span></span>
+<span class="line"><span>  [--allow-anonymous-cursor-github]</span></span>
+<span class="line"><span>  [--allow-anonymous-cursor-account-mcp]</span></span>
+<span class="line"><span>  [--allow-anonymous-grokbot]</span></span>
+<span class="line"><span>  [--public-url &lt;url&gt;]</span></span>
+<span class="line"><span>  [--no-schedules] [--no-playground] [--no-docs]</span></span>
+<span class="line"><span>  [--cursor-events --repo &lt;owner/name&gt;]...</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>--port &lt;n&gt;</code></td><td>Listen on this port. The default is <code>3000</code>; <code>0</code> 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.</td></tr><tr><td><code>--host &lt;host&gt;</code></td><td>Bind this host. The default is loopback-only <code>127.0.0.1</code>.</td></tr><tr><td><code>--mode multi</code></td><td>Mount projects at <code>/&lt;slug&gt;/v1/*</code> and <code>/&lt;slug&gt;/playground</code>, with an index at <code>/</code>. This is the default.</td></tr><tr><td><code>--mode single</code></td><td>Mount one project at <code>/v1/*</code> and <code>/playground</code>.</td></tr><tr><td><code>--dev</code></td><td>Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and enable local playground access.</td></tr><tr><td><code>--state-root &lt;path&gt;</code></td><td>Store local sessions, streams, workspaces, and channel state here. Keep durable state outside a repository whose rules shouldn&#39;t reach agent workspaces.</td></tr><tr><td><code>--bearer-token &lt;secret&gt;</code></td><td>Require this token on routes without authored authentication. Mutually exclusive with <code>--allow-anonymous</code>.</td></tr><tr><td><code>--allow-anonymous</code></td><td>Admit callers as one anonymous principal. Use it only behind a trusted network boundary.</td></tr><tr><td><code>--allow-anonymous-cursor-github</code></td><td>Let anonymous callers use sessions with a Cursor account&#39;s repository-scoped GitHub credential. Requires an authenticating proxy.</td></tr><tr><td><code>--allow-anonymous-cursor-account-mcp</code></td><td>Let anonymous callers use Cursor account MCP connections. Requires an authenticating proxy.</td></tr><tr><td><code>--allow-anonymous-grokbot</code></td><td>Let anonymous callers drive hosted Grok Bot runtime agents. Requires an authenticating proxy.</td></tr><tr><td><code>--public-url &lt;url&gt;</code></td><td>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.</td></tr><tr><td><code>--no-schedules</code></td><td>Disable schedule firing outside dev mode.</td></tr><tr><td><code>--no-playground</code></td><td>Skip the playground.</td></tr><tr><td><code>--no-docs</code></td><td>Skip the documentation site at <code>/docs</code>.</td></tr><tr><td><code>--cursor-events</code></td><td>Receive SCM events through Cursor. Requires sign-in and one or more repeatable <code>--repo owner/name</code> values.</td></tr></tbody></table><p>Multi-agent slugs start with a letter or digit and contain only letters, digits, <code>_</code>, or <code>-</code>. The reserved slugs are <code>v1</code>, <code>playground</code>, and <code>docs</code>.</p><h3 id="dev" tabindex="-1">Develop locally <a class="header-anchor" href="#dev" aria-label="Permalink to &quot;Develop locally {#dev}&quot;">​</a></h3><p><code>dev</code> is <code>serve --dev</code> with an optional positional project path:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk dev</span></span>
+<span class="line"><span>bdk dev ./bdk-pr-reviewer --port 3000</span></span></code></pre></div><p>It accepts every <code>serve</code> option. Pass at most one positional path, and don&#39;t combine it with a different <code>--dir</code>.</p><h3 id="docs" tabindex="-1">Serve the docs <a class="header-anchor" href="#docs" aria-label="Permalink to &quot;Serve the docs {#docs}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk docs [--port &lt;n&gt;] [--host 127.0.0.1] [--print]</span></span></code></pre></div><p><code>docs</code> serves the bundled documentation without an agent project. It uses an available loopback port by default and stays open until Ctrl-C. <code>--print</code> prints the URL without opening a browser.</p><h2 id="sessions-and-turns" tabindex="-1">Sessions and turns <a class="header-anchor" href="#sessions-and-turns" aria-label="Permalink to &quot;Sessions and turns&quot;">​</a></h2><h3 id="chat" tabindex="-1">Chat with an agent <a class="header-anchor" href="#chat" aria-label="Permalink to &quot;Chat with an agent {#chat}&quot;">​</a></h3><p><code>chat</code> connects to a running server and never starts an ephemeral one:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk chat [--url &lt;baseUrl&gt; | --prod] [--message &lt;text&gt;]</span></span>
+<span class="line"><span>  [--session &lt;id&gt; | --resume] [--continuation-token &lt;token&gt;]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--team &lt;id&gt;] [--json] [--text] [--no-color]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Input mode</th><th>Behavior</th></tr></thead><tbody><tr><td>TTY without <code>--message</code></td><td>Open an interactive REPL.</td></tr><tr><td>TTY with <code>--message</code></td><td>Send the message, then keep the REPL open.</td></tr><tr><td>Non-TTY with <code>--message</code></td><td>Send one turn and exit.</td></tr><tr><td>Non-TTY without <code>--message</code></td><td>Read newline-delimited messages until EOF.</td></tr><tr><td><code>--json --message &lt;text&gt;</code></td><td>Send one turn and print <code>{ ok, sessionId, continuationToken, trajectory }</code>.</td></tr><tr><td><code>--json --text --message &lt;text&gt;</code></td><td>Print a compact trajectory instead of JSON.</td></tr></tbody></table><p>Use <code>--session &lt;id&gt;</code> to reattach a stored session. If you omit <code>--continuation-token</code>, the CLI looks it up from the target&#39;s session list. <code>--resume</code> selects the most recently updated session with a continuation token. An explicit session ID takes precedence.</p><h3 id="resume" tabindex="-1">Resume a session <a class="header-anchor" href="#resume" aria-label="Permalink to &quot;Resume a session {#resume}&quot;">​</a></h3><p><code>resume</code> provides the same reattachment contract as <code>chat --session</code>:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk resume [sessionId] [--url &lt;baseUrl&gt; | --prod]</span></span>
+<span class="line"><span>  [--message &lt;text&gt;] [--json] [--text]</span></span>
+<span class="line"><span>  [--continuation-token &lt;token&gt;] [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span></code></pre></div><p>Omit the session ID to select the most recently updated followable session. The command replays the transcript before accepting follow-ups. <code>resume --json</code> requires <code>--message</code>.</p><h3 id="run" tabindex="-1">Run turns <a class="header-anchor" href="#run" aria-label="Permalink to &quot;Run turns {#run}&quot;">​</a></h3><p><code>run</code> sends messages to an ephemeral, running, or <code>--prod</code> target:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk run [--dir &lt;path&gt;] [--message &lt;text&gt;]...</span></span>
+<span class="line"><span>  [--messages-file &lt;path&gt;] [--url &lt;baseUrl&gt; | --prod]</span></span>
+<span class="line"><span>  [--session &lt;id&gt;] [--continuation-token &lt;token&gt;]</span></span>
+<span class="line"><span>  [--events &lt;file&gt; | --no-events] [--text]</span></span>
+<span class="line"><span>  [--timeout-ms &lt;n&gt;] [--no-stream] [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span>
+<span class="line"><span>  [--dry-run] [--as-of &lt;instant&gt;] [--component &lt;key&gt;]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>--message &lt;text&gt;</code></td><td>Send a user message. Repeat it for a multi-turn local or <code>--url</code> run. Managed starts accept one message.</td></tr><tr><td><code>--messages-file &lt;path&gt;</code></td><td>Read a JSON array of strings. File messages run before repeated <code>--message</code> values.</td></tr><tr><td><code>--session &lt;id&gt;</code></td><td>Continue a session. Managed session starts accept a hosted <code>ses_...</code> ID.</td></tr><tr><td><code>--continuation-token &lt;token&gt;</code></td><td>Continue the session selected by <code>--session</code> on a running server. Managed session starts use <code>--session</code> instead.</td></tr><tr><td><code>--events &lt;file&gt;</code></td><td>Write the raw NDJSON stream to this path.</td></tr><tr><td><code>--no-events</code></td><td>Skip the NDJSON trace.</td></tr><tr><td><code>--text</code></td><td>Print a compact trajectory instead of JSON.</td></tr><tr><td><code>--timeout-ms &lt;n&gt;</code></td><td>Stop waiting after a positive number of milliseconds. There is no default timeout.</td></tr><tr><td><code>--no-stream</code></td><td>Hide live tool and reply progress on stderr.</td></tr><tr><td><code>--dry-run</code></td><td>Mark a managed session turn as non-mutating.</td></tr><tr><td><code>--as-of &lt;instant&gt;</code></td><td>Freeze a managed session&#39;s clock at a timezone-bearing ISO-8601 instant.</td></tr><tr><td><code>--component &lt;key&gt;</code></td><td>Select a managed application&#39;s component instead of its default.</td></tr></tbody></table><p>For local and running-server targets, JSON output contains <code>ok</code>, <code>sessionId</code>, <code>continuationToken</code>, <code>trace</code>, <code>playgroundUrl</code>, <code>playgroundHint</code>, <code>visualize</code>, and <code>trajectory</code>. The <code>trace</code> value gives the saved path when event output is enabled. A managed session start confirms acceptance; a continuation also returns <code>sessionId</code>. Managed starts return before the turn finishes and ignore <code>--events</code>, <code>--no-events</code>, <code>--text</code>, <code>--timeout-ms</code>, and <code>--no-stream</code>. A successful managed start exits <code>0</code> on acceptance, before its turn outcome is known. A fresh start doesn&#39;t return <code>sessionId</code> synchronously.</p><h3 id="call" tabindex="-1">Call a tool <a class="header-anchor" href="#call" aria-label="Permalink to &quot;Call a tool {#call}&quot;">​</a></h3><p><code>call</code> invokes a server tool without a model turn:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk call &lt;tool&gt; [--input &lt;json&gt;]</span></span>
+<span class="line"><span>  [--dir &lt;path&gt; | --url &lt;baseUrl&gt; | --prod]</span></span>
+<span class="line"><span>  [--session &lt;id&gt;] [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span></code></pre></div><p><code>--input</code> accepts JSON and defaults to <code>{}</code>. <code>--session</code> uses the session workspace and records the call on its event stream. The command prints the server&#39;s JSON response and succeeds only when the HTTP response succeeds with <code>ok: true</code>.</p><p>See <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a> for validation, busy-session behavior, and error codes.</p><h3 id="skill" tabindex="-1">Read a skill <a class="header-anchor" href="#skill" aria-label="Permalink to &quot;Read a skill {#skill}&quot;">​</a></h3><p><code>skill</code> reads an authored skill without a model turn:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk skill &lt;name&gt; [--dir &lt;path&gt; | --url &lt;baseUrl&gt; | --prod]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--team &lt;id&gt;] [--text]</span></span></code></pre></div><p>The default output is the server&#39;s JSON response. <code>--text</code> prints the rendered <code>SKILL.md</code> content.</p><h3 id="sessions" tabindex="-1">List sessions <a class="header-anchor" href="#sessions" aria-label="Permalink to &quot;List sessions {#sessions}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk sessions [--url &lt;baseUrl&gt; | --prod]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--team &lt;id&gt;] [--bearer-token &lt;token&gt;] [--json]</span></span></code></pre></div><p>Text output shows the session ID, channel, mode, turn count, running status, and update time. <code>--json</code> prints <code>{ sessions }</code>, including continuation tokens.</p><h3 id="session" tabindex="-1">Inspect a session <a class="header-anchor" href="#session" aria-label="Permalink to &quot;Inspect a session {#session}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk session &lt;sessionId&gt; [--url &lt;baseUrl&gt; | --prod]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span>
+<span class="line"><span>  [--json | --text | --events] [--out &lt;file.ndjson&gt;]</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>bdk session --prod [&lt;sessionId&gt;] --slug &lt;slug&gt; --message &lt;text&gt;</span></span>
+<span class="line"><span>  [--dry-run] [--as-of &lt;instant&gt;] [--component &lt;key&gt;]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td>No output option</td><td>Print a compact trajectory.</td></tr><tr><td><code>--text</code></td><td>Select the compact trajectory explicitly.</td></tr><tr><td><code>--json</code></td><td>Print the trajectory object.</td></tr><tr><td><code>--events</code></td><td>Print <code>{ sessionId, events }</code> with the raw event list.</td></tr><tr><td><code>--out &lt;file.ndjson&gt;</code></td><td>Write the raw NDJSON trace instead of printing it.</td></tr><tr><td><code>--prod --message &lt;text&gt;</code></td><td>Start a managed session or continue the supplied managed session ID.</td></tr></tbody></table><p><code>--events</code> and <code>--json</code> are mutually exclusive. Managed sessions without an event trajectory return hosted execution status and logs in text or JSON; <code>--events</code> and <code>--out</code> require an event trajectory. Use <a href="#resume"><code>resume</code></a> to continue a conversational session.</p><h3 id="logs" tabindex="-1">Follow logs <a class="header-anchor" href="#logs" aria-label="Permalink to &quot;Follow logs {#logs}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk logs [--url &lt;baseUrl&gt; | --prod]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--team &lt;id&gt;] [--once] [--json]</span></span></code></pre></div><p>The command follows logs until Ctrl-C. <code>--once</code> prints the current buffer and exits; <code>--json</code> emits newline-delimited JSON events. A hosted deployment reports deployment progress before runtime logs become available.</p><h3 id="cost" tabindex="-1">Report costs <a class="header-anchor" href="#cost" aria-label="Permalink to &quot;Report costs {#cost}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk cost [sessionId] [--url &lt;baseUrl&gt; | --prod]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p>With a session ID, <code>cost</code> 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. <code>--json</code> prints the underlying report or <code>{ sessions }</code> for an aggregate.</p><h3 id="playground" tabindex="-1">Open the playground <a class="header-anchor" href="#playground" aria-label="Permalink to &quot;Open the playground {#playground}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk playground [--url &lt;baseUrl&gt; | --prod] [--session &lt;id&gt;]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--team &lt;id&gt;] [--bearer-token &lt;token&gt;] [--print]</span></span></code></pre></div><p>The command prints the playground URL and opens it unless <code>--print</code> is set. <code>--session</code> opens a deep link. A running target with credentials that a browser can&#39;t send starts a loopback proxy and stays open until Ctrl-C.</p><h3 id="trajectory" tabindex="-1">Inspect a trajectory <a class="header-anchor" href="#trajectory" aria-label="Permalink to &quot;Inspect a trajectory {#trajectory}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk trajectory --events &lt;file.ndjson&gt; [--text]</span></span></code></pre></div><p>The command converts an NDJSON stream into the trajectory JSON returned by <code>run</code>. <code>--text</code> prints the compact view.</p><h2 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to &quot;Evals&quot;">​</a></h2><h3 id="eval" tabindex="-1">Run evals <a class="header-anchor" href="#eval" aria-label="Permalink to &quot;Run evals {#eval}&quot;">​</a></h3><p><code>eval</code> discovers <code>evals/**/*.eval.{ts,js}</code> and runs selected cases:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk eval [--dir &lt;path&gt;] [evalId...]</span></span>
+<span class="line"><span>  [--list] [--tag &lt;tag&gt;]... [--json] [--verbose]</span></span>
+<span class="line"><span>  [--timeout-ms &lt;n&gt;] [--strict] [--max-concurrency &lt;n&gt;]</span></span>
+<span class="line"><span>  [--junit &lt;path&gt;] [--artifacts &lt;dir&gt; | --no-artifacts]</span></span>
+<span class="line"><span>  [--skip-report] [--out &lt;file.json&gt;] [--no-stream]</span></span>
+<span class="line"><span>  [--url &lt;baseUrl&gt; | --prod] [--no-wait]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span></code></pre></div><p>Select an exact case such as <code>weather/nyc</code>, a file prefix such as <code>weather</code>, several IDs, or no IDs for every case. Repeat <code>--tag</code> for OR matching. Projects must provide <code>evals/evals.config.{ts,js}</code> with <code>maxConcurrency</code> between 1 and 200.</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>--list</code></td><td>List matching cases without running them. <code>--list --json</code> prints an array.</td></tr><tr><td><code>--tag &lt;tag&gt;</code></td><td>Select a tag. Repeat the option for OR matching.</td></tr><tr><td><code>--json</code></td><td>Print <code>{ ok, passed, failed, scored, skipped, strict, results }</code>.</td></tr><tr><td><code>--verbose</code></td><td>Stream <code>t.log</code> lines and reply snippets.</td></tr><tr><td><code>--no-stream</code></td><td>Hide live progress on stderr.</td></tr><tr><td><code>--strict</code></td><td>Treat a scored case below its soft threshold as a failure.</td></tr><tr><td><code>--max-concurrency &lt;n&gt;</code></td><td>Override <code>maxConcurrency</code> from the eval config for an ephemeral local run.</td></tr><tr><td><code>--timeout-ms &lt;n&gt;</code></td><td>Override the per-case timeout. A case timeout takes precedence, followed by this option, the config timeout, and the 180-second default.</td></tr><tr><td><code>--junit &lt;path&gt;</code></td><td>Write JUnit XML for an ephemeral local run.</td></tr><tr><td><code>--artifacts &lt;dir&gt;</code></td><td>Select the artifact directory for an ephemeral local run. The default is a timestamped directory under the project&#39;s state directory.</td></tr><tr><td><code>--no-artifacts</code></td><td>Skip artifacts for an ephemeral local run.</td></tr><tr><td><code>--skip-report</code></td><td>Ignore reporters from eval files and the eval config during an ephemeral local run.</td></tr><tr><td><code>--out &lt;file.json&gt;</code></td><td>Also write the full result JSON.</td></tr><tr><td><code>--no-wait</code></td><td>Return after a running server or hosted deployment accepts the batch.</td></tr></tbody></table><p>A running server or hosted deployment prints its Eval ID when it accepts the batch. Use these commands to inspect or cancel it:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk eval status [evalId] --prod [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span>
+<span class="line"><span>bdk eval status [evalId] --url &lt;baseUrl&gt;</span></span>
+<span class="line"><span>bdk eval cancel &lt;evalId&gt; --prod [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span>
+<span class="line"><span>bdk eval cancel &lt;evalId&gt; --url &lt;baseUrl&gt;</span></span></code></pre></div><p><code>eval status</code> without an ID lists recent remote runs. <code>eval status --out</code> requires an ID. The <code>status</code> and <code>cancel</code> subcommands require <code>--url</code> or <code>--prod</code>.</p><h2 id="projects" tabindex="-1">Projects <a class="header-anchor" href="#projects" aria-label="Permalink to &quot;Projects&quot;">​</a></h2><h3 id="init" tabindex="-1">Scaffold a project <a class="header-anchor" href="#init" aria-label="Permalink to &quot;Scaffold a project {#init}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk init [directory] [--template &lt;name&gt;] [--var id=value]... [--json]</span></span></code></pre></div><p>Without a directory, <code>init</code> 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 <code>bdk</code> on <code>PATH</code>.</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>--template &lt;name&gt;</code></td><td>Use a bundled template: <code>agentic-owners</code>, <code>agents-md</code>, <code>code-wiki</code>, <code>demo</code>, <code>grokbot-agents</code>, <code>security-help</code>, <code>security-reviewer</code>, <code>thermo-quality-review</code>, <code>thermo-review</code>, <code>triage-jira</code>, or <code>triage-linear</code>.</td></tr><tr><td><code>--var id=value</code></td><td>Answer a template question without a prompt. Repeat for multiple answers.</td></tr><tr><td><code>--json</code></td><td>Skip interactive login and skill prompts, then print <code>{ ok, directory, template, created, skipped, installed, installError, cliOnPath, cliLinkError, next }</code>. <code>ok</code> reflects dependency installation.</td></tr></tbody></table><p>On a TTY, templates with questions run their interview before writing files. <code>init</code> also offers to refresh the bundled coding-agent skills and starts login when the host has no Cursor credential.</p><h3 id="convert-automation" tabindex="-1">Convert an Automation <a class="header-anchor" href="#convert-automation" aria-label="Permalink to &quot;Convert an Automation {#convert-automation}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk convert-automation &lt;url-or-uuid&gt; [--dir &lt;path&gt;] [--json]</span></span></code></pre></div><p>The input can be a Cursor Automation dashboard URL or its UUID. The output directory defaults to <code>./&lt;automation-name&gt;</code>. Generated files don&#39;t overwrite existing paths, and missing scaffold files are added. The following <code>npm install</code> can update lockfiles and run lifecycle scripts from an existing <code>package.json</code>.</p><p><code>--json</code> prints <code>{ ok, directory, files, warnings, setupSteps, installed, installError, mcpConnections }</code>. 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.</p><p>See <a href="./../guides/convert-automation.html">Convert a Cursor Automation</a> for the generated project and features that need manual review.</p><h3 id="install-skills" tabindex="-1">Install coding-agent skills <a class="header-anchor" href="#install-skills" aria-label="Permalink to &quot;Install coding-agent skills {#install-skills}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk install-skills [--print] [--json]</span></span></code></pre></div><p>The command replaces the installed BDK skills with the package copy and removes stale bundled skills. <code>--print</code> previews the change. <code>--json</code> prints <code>{ ok, dryRun, directory, firstInstall, skills, removed }</code>.</p><p>When <code>@cursor/bdk</code> publishes, package installation will perform this copy. Run <code>bdk install-skills</code> when you need to refresh it.</p><h3 id="info" tabindex="-1">Inspect a project <a class="header-anchor" href="#info" aria-label="Permalink to &quot;Inspect a project {#info}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk info [--dir &lt;path&gt;] [--json]</span></span></code></pre></div><p>Text output lists the model, instructions, tools, skills, extensions, connections, subagents, channels, schedules, hooks, hosting settings, and diagnostics. For one unslugged project, <code>--json</code> prints its project info object. For slugged or multi-agent discovery, it prints <code>{ agents }</code>.</p><h3 id="validate" tabindex="-1">Validate a project <a class="header-anchor" href="#validate" aria-label="Permalink to &quot;Validate a project {#validate}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk validate [--dir &lt;path&gt;]</span></span></code></pre></div><p><code>validate</code> prints every discovered project&#39;s diagnostics and exits nonzero when any diagnostic has error severity. Use it instead of <code>info --json</code> when a script needs validation status.</p><h3 id="manifest" tabindex="-1">Print a deployment manifest <a class="header-anchor" href="#manifest" aria-label="Permalink to &quot;Print a deployment manifest {#manifest}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk manifest [--dir &lt;path&gt;] [--json]</span></span></code></pre></div><p><code>manifest</code> validates one project and prints its deployment metadata without a network request. Default output is indented JSON; <code>--json</code> prints one compact line.</p><h2 id="credentials-and-versions" tabindex="-1">Credentials and versions <a class="header-anchor" href="#credentials-and-versions" aria-label="Permalink to &quot;Credentials and versions&quot;">​</a></h2><h3 id="login-logout-whoami" tabindex="-1">Manage credentials <a class="header-anchor" href="#login-logout-whoami" aria-label="Permalink to &quot;Manage credentials {#login-logout-whoami}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk login [--api-key &lt;key&gt;] [--key-name &lt;name&gt;]</span></span>
+<span class="line"><span>bdk whoami [--json]</span></span>
+<span class="line"><span>bdk logout</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><code>login</code></td><td>Use a supplied API key, or open browser sign-in and store the resulting dashboard-revocable key in the CLI config directory. <code>--key-name</code> labels a browser-created key.</td></tr><tr><td><code>whoami</code></td><td>Show the active credential and its source. <code>--json</code> returns the same identity as JSON.</td></tr><tr><td><code>logout</code></td><td>Remove the stored credential file. It doesn&#39;t revoke the API key; revoke the key in the Cursor dashboard.</td></tr></tbody></table><h3 id="version" tabindex="-1">Print the version <a class="header-anchor" href="#version" aria-label="Permalink to &quot;Print the version {#version}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk version [--json]</span></span>
+<span class="line"><span>bdk --version</span></span>
+<span class="line"><span>bdk -V</span></span></code></pre></div><p>Text output is the version number. <code>--json</code> prints <code>{ name, version }</code>.</p><h3 id="update" tabindex="-1">Update the CLI <a class="header-anchor" href="#update" aria-label="Permalink to &quot;Update the CLI {#update}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk update</span></span></code></pre></div><p><code>update</code> checks npm&#39;s <code>latest</code> tag and upgrades a recognized global or project install with its package manager. If it can&#39;t identify an installed copy, it prints a manual upgrade command instead.</p><p>Published installs check for updates at most once every 24 hours. Set <code>AGENT_SERVE_NO_UPDATE_CHECK</code>, <code>NO_UPDATE_NOTIFIER</code>, or <code>CI</code> to disable the automatic warning.</p><h2 id="managed-hosting" tabindex="-1">Managed hosting <a class="header-anchor" href="#managed-hosting" aria-label="Permalink to &quot;Managed hosting&quot;">​</a></h2><h3 id="deploy" tabindex="-1">Deploy agents <a class="header-anchor" href="#deploy" aria-label="Permalink to &quot;Deploy agents {#deploy}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk deploy [--dir &lt;path&gt;] [--slug &lt;slug&gt; | --all] [--team &lt;id&gt;]</span></span>
+<span class="line"><span>  [--repo &lt;https-url&gt;] [--ref &lt;git-ref&gt;] [--path &lt;agent-path&gt;]</span></span>
+<span class="line"><span>  [--cursor-events-repo &lt;owner/name&gt;]...</span></span>
+<span class="line"><span>  [--allow-domain &lt;domain&gt;]... [--no-wait] [--json]</span></span></code></pre></div><p>Managed hosting requires a team with agent hosting enabled. A team service-account API key with agent access can deploy.</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>--slug &lt;slug&gt;</code></td><td>Select one project and set its deployment slug.</td></tr><tr><td><code>--all</code></td><td>Deploy every child project under a multi-agent <code>--dir</code>. Mutually exclusive with <code>--slug</code>.</td></tr><tr><td><code>--team &lt;id&gt;</code></td><td>Select the Cursor team.</td></tr><tr><td><code>--repo &lt;https-url&gt;</code></td><td>Set the source repository. The CLI infers it from the current checkout when possible. HTTPS is required.</td></tr><tr><td><code>--ref &lt;git-ref&gt;</code></td><td>Set the source Git ref. The CLI infers the current branch when possible.</td></tr><tr><td><code>--path &lt;agent-path&gt;</code></td><td>Set the project path relative to the repository root.</td></tr><tr><td><code>--cursor-events-repo &lt;owner/name&gt;</code></td><td>Add a repository whose SCM events reach the deployment. Repeat for multiple repositories.</td></tr><tr><td><code>--allow-domain &lt;domain&gt;</code></td><td>Add an egress hostname. Repeat for multiple domains; values are combined with <code>hosting.egressDomains</code>.</td></tr><tr><td><code>--no-wait</code></td><td>Return after the deployment request is accepted.</td></tr><tr><td><code>--json</code></td><td>Print one object for one target or an array for multiple targets.</td></tr></tbody></table><p>Deployment slugs contain lowercase letters, digits, <code>_</code>, or <code>-</code>, 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 <code>*.</code> wildcard is allowed, with at most 20 entries.</p><p>By default, <code>deploy</code> 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 <code>X-Agent-Alias-Token</code> when calling the stable alias URL.</p><h3 id="deployments" tabindex="-1">List deployments <a class="header-anchor" href="#deployments" aria-label="Permalink to &quot;List deployments {#deployments}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk deployments [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p>Text output shows slug, status, generation, kind, and update time. <code>--json</code> prints <code>{ deployments }</code> and may also include <code>applications</code>. An empty list succeeds.</p><h3 id="deployment" tabindex="-1">Inspect a deployment <a class="header-anchor" href="#deployment" aria-label="Permalink to &quot;Inspect a deployment {#deployment}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk deployment &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p>Text output includes status, source, routes, secret names, egress domains, and the latest error. <code>--json</code> can include short-lived access headers, so handle its output as a credential.</p><h3 id="stop" tabindex="-1">Stop a deployment <a class="header-anchor" href="#stop" aria-label="Permalink to &quot;Stop a deployment {#stop}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk stop &lt;slug&gt; [--team &lt;id&gt;] [--no-wait] [--cancel-runs] [--json]</span></span></code></pre></div><p>The command waits for <code>stopped</code> by default. <code>--no-wait</code> returns after the request is accepted. <code>--cancel-runs</code> also requests cancellation of active runs and reminder wakes for a managed application. Other deployment types reject this option.</p><h3 id="cancel-runs" tabindex="-1">Cancel active runs <a class="header-anchor" href="#cancel-runs" aria-label="Permalink to &quot;Cancel active runs {#cancel-runs}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk cancel-runs &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p>The command requests cancellation for a managed application&#39;s active runs and reminder wakes. Other deployment types reject it. For a multi-tenant application, this cancels every install; use <code>stop --cancel-runs</code> for install-local cancellation. It exits nonzero if any cancellation request fails to start.</p><h3 id="event-repos" tabindex="-1">Replace event repositories <a class="header-anchor" href="#event-repos" aria-label="Permalink to &quot;Replace event repositories {#event-repos}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk event-repos &lt;slug&gt; [--repo &lt;owner/name&gt;]...</span></span>
+<span class="line"><span>  [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p>The supplied repositories replace the managed application&#39;s complete event repository list; they aren&#39;t merged with the previous list. Omit <code>--repo</code> to clear the list.</p><h3 id="upgrade" tabindex="-1">Upgrade a managed application <a class="header-anchor" href="#upgrade" aria-label="Permalink to &quot;Upgrade a managed application {#upgrade}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk upgrade &lt;slug&gt; [--release &lt;id-or-version&gt;]</span></span>
+<span class="line"><span>  [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p><code>--release</code> accepts a release ID or version. Omit it to select the newest ready release. <code>--json</code> prints <code>{ releaseId }</code>.</p><h3 id="delete" tabindex="-1">Delete a deployment <a class="header-anchor" href="#delete" aria-label="Permalink to &quot;Delete a deployment {#delete}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk delete &lt;slug&gt; [--team &lt;id&gt;] [--no-wait] [--json]</span></span></code></pre></div><p><code>delete</code> removes the deployment and frees its slug. It waits until the deployment is gone unless <code>--no-wait</code> is set.</p><h3 id="rotate-token" tabindex="-1">Rotate an alias token <a class="header-anchor" href="#rotate-token" aria-label="Permalink to &quot;Rotate an alias token {#rotate-token}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk rotate-token &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p>The old token stops working immediately. The replacement appears once; <code>--json</code> prints <code>{ aliasToken }</code>.</p><h3 id="secrets" tabindex="-1">Manage deployment secrets <a class="header-anchor" href="#secrets" aria-label="Permalink to &quot;Manage deployment secrets {#secrets}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk secrets set &lt;slug&gt; NAME [NAME2 ...]</span></span>
+<span class="line"><span>  [--team &lt;id&gt;] [--from-argv] [--json]</span></span>
+<span class="line"><span>bdk secrets list &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span>
+<span class="line"><span>bdk secrets unset &lt;slug&gt; NAME [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p>Pass secret names to <code>set</code>. On a TTY, the CLI prompts for hidden values; with piped input, provide one line per name. It rejects <code>NAME=VALUE</code> arguments unless <code>--from-argv</code> is set because command-line values can enter shell history and captured terminals.</p><p>Names use <code>UPPER_SNAKE_CASE</code>, start with a letter, and contain at most 64 characters. Names beginning with <code>CURSOR_</code> are reserved. Values contain at most 4096 bytes, and each deployment holds at most 32 secrets.</p><p><code>list</code> returns names and creation times, never values. JSON output is <code>{ secretNames }</code> for <code>set</code>, <code>{ secrets }</code> for <code>list</code>, and <code>{ removed }</code> for <code>unset</code>. Changes are available to subsequent hosted work.</p><h2 id="mcp-connections" tabindex="-1">MCP connections <a class="header-anchor" href="#mcp-connections" aria-label="Permalink to &quot;MCP connections&quot;">​</a></h2><h3 id="mcp" tabindex="-1">Connect an MCP client <a class="header-anchor" href="#mcp" aria-label="Permalink to &quot;Connect an MCP client {#mcp}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk mcp --prod [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span>
+<span class="line"><span>bdk mcp --url &lt;baseUrl&gt; [--bearer-token &lt;token&gt;]</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>bdk mcp install --prod [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span>
+<span class="line"><span>  [--name &lt;server-name&gt;] [--print] [--json] [--remote]</span></span>
+<span class="line"><span>bdk mcp install --url &lt;baseUrl&gt; [--bearer-token &lt;token&gt;]</span></span>
+<span class="line"><span>  [--name &lt;server-name&gt;] [--print] [--json]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><code>mcp</code></td><td>Read newline-delimited JSON-RPC from stdin and proxy it to the selected agent&#39;s MCP endpoint. stdout is reserved for MCP messages. A target is required.</td></tr><tr><td><code>mcp install</code></td><td>Add the selected agent to <code>~/.cursor/mcp.json</code>. <code>--name</code> sets the server name, <code>--print</code> previews the entry, and <code>--json</code> prints a machine-readable result. A <code>--url</code> entry with <code>--bearer-token</code> contains that token; handle printed and written copies as credentials.</td></tr><tr><td><code>mcp install --remote --prod</code></td><td>Write a remote HTTP entry for clients that can&#39;t spawn a stdio process. The entry contains the API key in plain text and must be handled as a credential.</td></tr></tbody></table><h3 id="mcp-oauth" tabindex="-1">Authorize MCP OAuth <a class="header-anchor" href="#mcp-oauth" aria-label="Permalink to &quot;Authorize MCP OAuth {#mcp-oauth}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk mcp oauth &lt;connection&gt; [--dir &lt;path&gt;] [--store]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--team &lt;id&gt;]</span></span></code></pre></div><p><code>&lt;connection&gt;</code> is the basename under <code>bot/mcp-connections/</code> or <code>bot/host-connections/</code>.</p><table tabindex="0"><thead><tr><th>Connection</th><th>Result</th></tr></thead><tbody><tr><td><code>defineConnection({ url, oauth: true })</code></td><td>Open a browser PKCE flow and save tokens in <code>mcp-auth.json</code> under the CLI config directory. <code>--store</code> also sets the matching deployment secrets.</td></tr><tr><td><code>defineConnection({ cursorAccount: true })</code></td><td>Authorize the managed deployment&#39;s service account through Cursor. <code>--store</code> isn&#39;t needed.</td></tr></tbody></table><p>Stored secret names are <code>MCP_OAUTH_&lt;NAME&gt;_ACCESS_TOKEN</code>, <code>MCP_OAUTH_&lt;NAME&gt;_REFRESH_TOKEN</code>, and <code>MCP_OAUTH_&lt;NAME&gt;_CLIENT_ID</code>. Declare them in <code>hosting.secretNames</code>. URL-connection tokens are bound to the resource URL; authorize again after changing it.</p><p>See <a href="./../guides/mcp-oauth.html">Host MCP OAuth</a> for the full setup flow.</p><h2 id="channel-helpers" tabindex="-1">Channel helpers <a class="header-anchor" href="#channel-helpers" aria-label="Permalink to &quot;Channel helpers&quot;">​</a></h2><h3 id="slack" tabindex="-1">Configure Slack <a class="header-anchor" href="#slack" aria-label="Permalink to &quot;Configure Slack {#slack}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk slack setup</span></span>
+<span class="line"><span>bdk slack create [--dir &lt;path&gt;] [--name &lt;name&gt;] [--prod]</span></span>
+<span class="line"><span>  [--slack-team &lt;id&gt;] [--team &lt;id&gt;] [--icon &lt;url-or-file&gt;]</span></span>
+<span class="line"><span>  [--prefix &lt;prefix&gt; | --no-prefix] [--channel-posts] [--json]</span></span>
+<span class="line"><span>bdk slack destroy [--dir &lt;path&gt;] [--prod]</span></span>
+<span class="line"><span>  [--slack-team &lt;id&gt;] [--team &lt;id&gt;] [--json]</span></span>
+<span class="line"><span>bdk slack icon &lt;url-or-file&gt; [--dir &lt;path&gt;] [--prod]</span></span>
+<span class="line"><span>  [--slack-team &lt;id&gt;] [--team &lt;id&gt;] [--json]</span></span>
+<span class="line"><span>bdk slack init --manual [--dir &lt;path&gt;] [--name &lt;name&gt;]</span></span>
+<span class="line"><span>  [--prefix &lt;prefix&gt; | --no-prefix] [--channel-posts]</span></span>
+<span class="line"><span>  [--install | --no-install] [--slack-team &lt;id&gt;] [--prod]</span></span>
+<span class="line"><span>bdk slack manifest [--dir &lt;path&gt;] [--name &lt;name&gt;]</span></span>
+<span class="line"><span>  [--env dev|prod|both] [--channel-posts] [--print]</span></span>
+<span class="line"><span>bdk slack doctor [--dir &lt;path&gt;]</span></span>
+<span class="line"><span>  [--prefix &lt;prefix&gt; | --no-prefix] [--channel &lt;id&gt;]... [--json]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Subcommand</th><th>Contract</th></tr></thead><tbody><tr><td><code>setup</code></td><td>Print the setup choices without changing files.</td></tr><tr><td><code>create</code></td><td>Open the signed-in Cursor dashboard wizard, write the resulting token pair to <code>.env.local</code>, and run <code>doctor</code>. The development app is the default; <code>--prod</code> selects production. A second create overwrites the live app manifest.</td></tr><tr><td><code>destroy</code></td><td>Delete the provisioned app. Existing local token entries remain but stop working.</td></tr><tr><td><code>icon</code></td><td>Set an HTTPS or local PNG, JPG, or GIF icon of at most 512 KB.</td></tr><tr><td><code>init --manual</code></td><td>Write the channel, manifests, Slack CLI project, and setup files for a manually managed app.</td></tr><tr><td><code>manifest</code></td><td>Generate Slack manifests. <code>--env</code> defaults to <code>both</code>; with <code>--print</code>, select one environment when you need one JSON document.</td></tr><tr><td><code>doctor</code></td><td>Check both tokens, Socket Mode connectivity, Slack authentication, and any repeatable <code>--channel</code> values.</td></tr></tbody></table><p>The default token prefix is the project directory name normalized to upper snake case. <code>--no-prefix</code> uses <code>SLACK_BOT_TOKEN</code> and <code>SLACK_APP_TOKEN</code>. Channel-post subscriptions are off by default; <code>--channel-posts</code> adds message events for public and private channels as required by <code>engagement.channelPosts</code>. Multi-agent servers need one token pair per agent.</p><p>See <a href="./../guides/slack.html">Slack</a> for app consent and manual setup.</p><h3 id="github" tabindex="-1">Test GitHub webhooks <a class="header-anchor" href="#github" aria-label="Permalink to &quot;Test GitHub webhooks {#github}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk github forward [--dir &lt;path&gt;] [--slug &lt;slug&gt;] [--channel &lt;id&gt;]</span></span>
+<span class="line"><span>  [--repo owner/repo | --org &lt;org&gt;] [--events a,b,c]</span></span>
+<span class="line"><span>  [--url &lt;url&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;]</span></span>
+<span class="line"><span>  [--secret &lt;secret&gt;] [--install]</span></span>
+<span class="line"><span>bdk github replay &lt;pr-url-or-owner/repo#N&gt;</span></span>
+<span class="line"><span>  [--events a,b,c | &#39;*&#39;] [--action &lt;action&gt;] [--conclusion &lt;result&gt;]</span></span>
+<span class="line"><span>  [--comment &lt;body&gt;] [--context &lt;name&gt;] [--dir &lt;path&gt;]</span></span>
+<span class="line"><span>  [--slug &lt;slug&gt;] [--channel &lt;id&gt;] [--url &lt;url&gt;]</span></span>
+<span class="line"><span>  [--secret &lt;secret&gt;] [--dry-run] [--out &lt;dir&gt;] [--json]</span></span>
+<span class="line"><span>bdk github events [--dir &lt;path&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;] [--json]</span></span>
+<span class="line"><span>bdk github doctor [--install] [--json]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Subcommand</th><th>Contract</th></tr></thead><tbody><tr><td><code>forward</code></td><td>Forward live deliveries with <code>gh webhook forward</code>. The CLI derives URLs and events from discovered channels and can fan out to several matches.</td></tr><tr><td><code>replay</code></td><td>Read a pull request, synthesize selected webhook payloads, and post them to matching channels. The default event is <code>pull_request</code>; <code>&#39;*&#39;</code> selects the channel&#39;s supported declared events.</td></tr><tr><td><code>events</code></td><td>List discovered channel URLs and event sets. No channels is a successful empty result.</td></tr><tr><td><code>doctor</code></td><td>Check the GitHub CLI, its login, and the pinned webhook extension. <code>--install</code> installs or repairs the extension.</td></tr></tbody></table><p>Replay supports <code>pull_request</code>, <code>issue_comment</code>, <code>pull_request_review_comment</code>, <code>check_run</code>, <code>check_suite</code>, <code>workflow_run</code>, and <code>status</code>. <code>--dry-run</code> prints without posting. <code>--out</code> writes fixtures and still posts unless combined with <code>--dry-run</code>.</p><p>Forwarding requires repository admin access, or organization owner access for <code>--org</code>. It uses the GitHub CLI&#39;s stored login; unset <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> before forwarding. Replay needs only pull-request read access.</p><p>See <a href="./../guides/github.html">GitHub</a> for channel setup and live delivery.</p><h3 id="gitlab" tabindex="-1">Test GitLab webhooks <a class="header-anchor" href="#gitlab" aria-label="Permalink to &quot;Test GitLab webhooks {#gitlab}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk gitlab replay &lt;mr-url-or-group/project!N&gt;</span></span>
+<span class="line"><span>  [--events a,b,c | &#39;*&#39;] [--action &lt;action&gt;]</span></span>
+<span class="line"><span>  [--conclusion &lt;status&gt;] [--comment &lt;body&gt;]</span></span>
+<span class="line"><span>  [--dir &lt;path&gt;] [--slug &lt;slug&gt;] [--channel &lt;id&gt;]</span></span>
+<span class="line"><span>  [--url &lt;url&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;]</span></span>
+<span class="line"><span>  [--secret &lt;secret&gt;] [--dry-run] [--out &lt;dir&gt;] [--json]</span></span>
+<span class="line"><span>bdk gitlab events [--dir &lt;path&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;] [--json]</span></span>
+<span class="line"><span>bdk gitlab forward [--dir &lt;path&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Subcommand</th><th>Contract</th></tr></thead><tbody><tr><td><code>replay</code></td><td>Read a merge request, synthesize selected webhook payloads, and post them to matching channels. The default event is <code>merge_request</code>; <code>&#39;*&#39;</code> selects the channel&#39;s declared events.</td></tr><tr><td><code>events</code></td><td>List discovered GitLab channel URLs and object kinds.</td></tr><tr><td><code>forward</code></td><td>Print the public-hook and tunnel recipe for live deliveries.</td></tr></tbody></table><p>Replay supports <code>merge_request</code>, <code>note</code>, <code>pipeline</code>, and <code>push</code>. It requires <code>GITLAB_TOKEN</code> with project read access. <code>--secret</code> defaults to <code>GITLAB_WEBHOOK_SECRET</code>; <code>--dry-run</code> and <code>--out</code> follow the GitHub replay contract.</p><p>See <a href="./../guides/gitlab.html">GitLab</a> for channel setup and self-managed hosts.</p><h3 id="bitbucket" tabindex="-1">Test Bitbucket webhooks <a class="header-anchor" href="#bitbucket" aria-label="Permalink to &quot;Test Bitbucket webhooks {#bitbucket}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk bitbucket replay &lt;pr-url-or-workspace/repo#N&gt;</span></span>
+<span class="line"><span>  [--events a,b,c | &#39;*&#39;] [--comment &lt;body&gt;]</span></span>
+<span class="line"><span>  [--dir &lt;path&gt;] [--slug &lt;slug&gt;] [--channel &lt;id&gt;]</span></span>
+<span class="line"><span>  [--url &lt;url&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;]</span></span>
+<span class="line"><span>  [--secret &lt;secret&gt;] [--dry-run] [--out &lt;dir&gt;] [--json]</span></span>
+<span class="line"><span>bdk bitbucket events [--dir &lt;path&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;] [--json]</span></span>
+<span class="line"><span>bdk bitbucket forward [--dir &lt;path&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Subcommand</th><th>Contract</th></tr></thead><tbody><tr><td><code>replay</code></td><td>Read a pull request, synthesize webhook payloads in the host&#39;s Cloud or Data Center format, and post them to matching channels.</td></tr><tr><td><code>events</code></td><td>List discovered Bitbucket channel URLs and event keys.</td></tr><tr><td><code>forward</code></td><td>Print the repository-hook and tunnel recipe for live deliveries.</td></tr></tbody></table><p>Replay supports <code>pullrequest:created</code>, <code>pullrequest:updated</code>, <code>pullrequest:comment_created</code>, and <code>repo:push</code>, along with their supported Data Center forms. It requires <code>BITBUCKET_TOKEN</code> with pull-request read access. <code>--secret</code> defaults to <code>BITBUCKET_WEBHOOK_SECRET</code>; <code>--dry-run</code> and <code>--out</code> follow the GitHub replay contract.</p><p>See <a href="./../guides/bitbucket.html">Bitbucket</a> for Cloud and Data Center setup.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables&quot;">​</a></h2><p>Credential resolution follows this order: <code>--api-key</code>, <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then the stored login.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Contract</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential.</td></tr><tr><td><code>CURSOR_API_KEY_FILE</code></td><td>Path to a Cursor credential file.</td></tr><tr><td><code>CURSOR_SERVICE_ACCOUNT_KEY</code></td><td>Team service-account credential used after the API key and key-file sources.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend for login, account, deployment, and event commands.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend for BDK turns. Set it with <code>CURSOR_API_BASE_URL</code> when using a non-default backend.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>Override the CLI config directory for stored credentials and update state.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code>, <code>NO_UPDATE_NOTIFIER</code>, <code>CI</code></td><td>Disable published-version checks when set to a non-empty value other than <code>0</code>.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default signature secret for GitHub forwarding and replay.</td></tr><tr><td><code>GITHUB_APP_ID</code>, <code>GITHUB_APP_PRIVATE_KEY</code>, <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App credentials for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code>, <code>GH_TOKEN</code></td><td>Token credentials for outbound GitHub calls. Unset both for <code>github forward</code>.</td></tr><tr><td><code>GITLAB_TOKEN</code></td><td>Token for GitLab API reads and direct channel calls.</td></tr><tr><td><code>GITLAB_API_BASE_URL</code></td><td>Override the GitLab REST base URL for self-managed hosts.</td></tr><tr><td><code>GITLAB_WEBHOOK_SECRET</code></td><td>Default GitLab webhook token for replay and channel verification.</td></tr><tr><td><code>BITBUCKET_TOKEN</code></td><td>Token for Bitbucket API reads and direct channel calls.</td></tr><tr><td><code>BITBUCKET_API_BASE_URL</code></td><td>Override the Bitbucket Data Center REST base URL.</td></tr><tr><td><code>BITBUCKET_WEBHOOK_SECRET</code></td><td>Default Bitbucket signing secret for replay and channel verification.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code>, <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Multi-agent servers use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code>.</td></tr></tbody></table><h2 id="exit-status" tabindex="-1">Exit status <a class="header-anchor" href="#exit-status" aria-label="Permalink to &quot;Exit status&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Command</th><th>Nonzero contract</th></tr></thead><tbody><tr><td>No command</td><td>Print help and exit <code>1</code>. Explicit <code>help</code>, <code>--help</code>, and <code>-h</code> exit <code>0</code>.</td></tr><tr><td><code>run</code></td><td>For local and running-server trajectories, exit <code>1</code> when the trajectory fails.</td></tr><tr><td><code>call</code></td><td>Exit <code>1</code> unless the response succeeds with <code>ok: true</code>.</td></tr><tr><td><code>skill</code></td><td>Exit <code>2</code> when the name is missing and <code>1</code> when the request fails.</td></tr><tr><td><code>trajectory</code></td><td>Exit <code>1</code> when the reconstructed trajectory failed.</td></tr><tr><td><code>eval</code></td><td>Exit <code>1</code> for failed cases, or scored cases below threshold with <code>--strict</code>; exit <code>2</code> for invalid eval options or an execution with no matching cases. An empty <code>--list</code> succeeds.</td></tr><tr><td><code>eval status</code></td><td>Exit <code>3</code> while the batch runs, <code>1</code> when it failed or was cancelled, and <code>2</code> for invalid usage.</td></tr><tr><td><code>chat</code>, <code>session</code></td><td>Exit <code>2</code> for documented option conflicts or missing required input.</td></tr><tr><td><code>validate</code></td><td>Exit <code>1</code> when any project diagnostic has error severity.</td></tr><tr><td><code>convert-automation</code></td><td>Exit <code>1</code> for invalid input, authentication, export, or file-write failure. Warnings and dependency-install failure don&#39;t change a successful conversion exit.</td></tr><tr><td>Other commands</td><td>Exit nonzero when validation, authentication, a request, or the requested operation fails.</td></tr></tbody></table><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./project-layout.html">Project layout</a></li><li><a href="./sessions.html">Sessions, events, and streaming</a></li><li><a href="./evals.html">Evals</a></li><li><a href="./http-api.html">HTTP API</a></li><li><a href="./../deployment.html">Deployment</a></li></ul>`,195)])])}const g=t(d,[["render",n]]);export{u as __pageData,g as default};

package/dist/docs/assets/reference_cli.md.BK2QUH67.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"CLI","description":"Look up BDK commands, targets, flags, outputs, and exit status.","frontmatter":{"title":"CLI","description":"Look up BDK commands, targets, flags, outputs, and exit status."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),d={name:"reference/cli.md"};function n(c,e,r,l,i,p){return s(),a("div",null,[...e[0]||(e[0]=[o("",195)])])}const g=t(d,[["render",n]]);export{u as __pageData,g as default};

package/dist/docs/assets/reference_connections.md._XpKiOaF.js

@@ -0,0 +1,63 @@
+import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse(`{"title":"MCP connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),n={name:"reference/connections.md"};function l(h,s,o,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="mcp-connections" tabindex="-1">MCP connections <a class="header-anchor" href="#mcp-connections" aria-label="Permalink to &quot;MCP connections&quot;">​</a></h1><p>An MCP connection gives the agent tools from an MCP server. Define one file per server under <code>bot/mcp-connections/</code>; the filename becomes the server name. Default-export <code>defineConnection</code> from <code>@cursor/bdk/connections</code>. The transport is remote HTTP, local stdio, the signed-in Cursor account&#39;s connectors, or a peer agent on the same host.</p><p>Put a server in <code>bot/host-connections/</code> when only host tools should call it. Host connections use the same <code>defineConnection</code> shape and support <code>bdk mcp oauth</code>; the model and playground don&#39;t see them.</p><p>The <code>@cursor/bdk</code> imports and <code>bdk</code> commands on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="remote-mcp-server" tabindex="-1">Remote MCP server <a class="header-anchor" href="#remote-mcp-server" aria-label="Permalink to &quot;Remote MCP server&quot;">​</a></h2><p>Point an MCP connection at a remote server with a URL.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/connections&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.linear.app/mcp&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  headers: { authorization: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Bearer \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">process</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">LINEAR_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Tokens come from env vars. Never hardcode them in the file.</p><h2 id="host-mcp-oauth" tabindex="-1">Host MCP OAuth <a class="header-anchor" href="#host-mcp-oauth" aria-label="Permalink to &quot;Host MCP OAuth&quot;">​</a></h2><p>For servers that speak OAuth, set <code>oauth: true</code> and authorize with the CLI or mid-run Connect. Tokens live in <code>mcp-auth.json</code> under the CLI config directory. <code>--store</code> copies them onto the deployment as <code>MCP_OAUTH_&lt;NAME&gt;_*</code> secrets.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.example.com/inventory&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  oauth: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk mcp oauth inventory           # browser PKCE → local mcp-auth.json</span></span>
+<span class="line"><span>bdk mcp oauth inventory --store   # also upsert deployment secrets</span></span></code></pre></div><p>Full walkthrough: <a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>. Companion skill: <a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><h2 id="per-session-auth" tabindex="-1">Per-session auth <a class="header-anchor" href="#per-session-auth" aria-label="Permalink to &quot;Per-session auth&quot;">​</a></h2><p>For http/sse connections whose credential depends on who the session is for, declare an <code>auth</code> callback instead of static headers. It runs host-side with the session&#39;s <code>SessionInfo</code> and returns headers merged over the static ones:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://api.cursor.com/v1/mcp/plugins&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  auth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">session</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    headers: { Authorization: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Bearer \${</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> grantFor</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">(</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">session</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">)</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The callback is evaluated on every turn, including reminder fires and post-restart follow-ups, so the identity always comes from the session itself, never from state parked in memory. The model never sees a tenant parameter and can never choose the tenant. A callback that throws fails the turn: a turn never silently runs without the connection&#39;s identity. <code>host.mcp</code> calls from server tools keep the static headers only. You can&#39;t combine <code>auth</code> with <code>oauth: true</code>; the host OAuth provider owns the Authorization header.</p><p>Derive the identity from durable session facts: <code>session.auth</code>, <code>session.id</code>, or your channel&#39;s own session state. Do not key it off <code>session.continuationKey</code>. The HTTP channel rotates that key after every accepted follow-up, so a tenant mapping keyed on it breaks mid-conversation.</p><p><code>auth</code> works attached or advertised. Advertise the auth connection instead of attaching it next to a stateful stdio server.</p><h2 id="advertise-tools" tabindex="-1">Advertise tools <a class="header-anchor" href="#advertise-tools" aria-label="Permalink to &quot;Advertise tools {#advertise-tools}&quot;">​</a></h2><p>Set <code>advertiseTools: true</code> when the model should call an MCP server&#39;s tools by name. BDK preserves each tool&#39;s description, input and output schemas, and MCP annotations. Exposed names normalize invalid characters and add numeric suffixes to avoid collisions.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://api.cursor.com/v1/mcp/plugins&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  auth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">session</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({ headers: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> tenantHeaders</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(session) }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Listing, authentication, invalid tool name, and name collision failures fail the turn by default. Set <code>optional: true</code> to omit an unavailable connection instead. Advertised tools behave like server tools, and <a href="./tools.html#call-a-tool-without-a-model-turn">direct tool calls</a> use the same names.</p><p>In a dry-run session, MCP tools marked read-only run normally. Tools marked as writes are stubbed. Tools without effect annotations are unavailable.</p><h2 id="filter-connection-tools" tabindex="-1">Filter connection tools <a class="header-anchor" href="#filter-connection-tools" aria-label="Permalink to &quot;Filter connection tools&quot;">​</a></h2><p>Use <code>tools</code> the same way you allowlist harness tools on the agent. When set, the connection serves only those names. Use <code>disallowedTools</code> to drop names instead. The two combine as deny-wins. The model and <code>host.mcp</code> only see what remains. A model-visible filter requires <code>advertiseTools: true</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.example.com/inventory&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tools: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;search_skus&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;get_stock&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.example.com/inventory&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  disallowedTools: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;place_order&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;delete_sku&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Names are the server&#39;s <code>tools/list</code> names. Unknown names are omitted. A filter that matches nothing on the server fails the turn unless <code>optional: true</code>. Combine with <code>effects: &quot;read&quot;</code> to keep only the listed tools the server classifies as reads.</p><p>A list of names is an allowlist. An object of handlers authors TypeScript tools. On <code>host-connections/</code>, a name list restricts <code>host.mcp</code> without advertising.</p><h2 id="local-stdio-mcp-server" tabindex="-1">Local stdio MCP server <a class="header-anchor" href="#local-stdio-mcp-server" aria-label="Permalink to &quot;Local stdio MCP server&quot;">​</a></h2><p>Run a local MCP server as a child process with <code>command</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  command: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;node&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  args: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--import&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;tsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;mcp/units-server.ts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // env, cwd</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>This suits small purpose-built servers, like a <code>units</code> converter shipped next to the agent.</p><p>To run TypeScript in the agent environment, author the tools on the connection instead. BDK packages authored tools as stdio MCP, so you write only <code>execute</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tools: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    probe_agent_tool: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Prove the tool ran in the agent environment.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">label</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { ok: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, label };</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="cursor-account-mcp-connection" tabindex="-1">Cursor account MCP connection <a class="header-anchor" href="#cursor-account-mcp-connection" aria-label="Permalink to &quot;Cursor account MCP connection&quot;">​</a></h2><p><code>{ cursorAccount: true }</code> forwards the MCP connectors the signed-in Cursor account already authorized (dashboard → MCP), such as Linear, Notion, and Slack. You don&#39;t configure tokens. Every tool runs on the Cursor backend with the account&#39;s stored OAuth credentials, so raw tokens never reach the serving host, session workspaces, or traces.</p><p>By default the agent gets every connected HTTP/SSE connector on the account. Pass <code>servers: &quot;*&quot;</code> (or <code>[&quot;*&quot;]</code>) for the same all-connectors behavior in an explicit form. Pass a name list when you want a smaller set.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/mcp-connections/account.ts: every connected connector</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cursorAccount: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// only Linear:</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cursorAccount: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  servers: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Name the file <code>account.ts</code>. <code>cursor.ts</code> collides with the IDE <code>cursor</code> MCP namespace. <code>advertiseTools: true</code> puts connector tools on local turns by name.</p><p>The host must be signed in (<code>bdk login</code>, <code>CURSOR_API_KEY</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>). <code>serve</code> fails at startup otherwise.</p><p>Use a <code>{ command }</code> connection for stdio servers.</p><div class="caution custom-block github-alert"><p class="custom-block-title">CAUTION</p><p>Whoever can talk to the agent can drive these connectors, because they are ordinary agent tools. <code>serve</code> refuses to start when <code>--allow-anonymous</code> is combined with account MCP connections unless you also pass <code>--allow-anonymous-cursor-account-mcp</code> (trusted boundary only; for example an SSO proxy or the hosted alias token). Prefer <code>--bearer-token</code> on shared hosts.</p></div><h2 id="peer-mcp-connection" tabindex="-1">Peer MCP connection <a class="header-anchor" href="#peer-mcp-connection" aria-label="Permalink to &quot;Peer MCP connection {#peer-mcp-connection}&quot;">​</a></h2><p><code>{ agent: &quot;&lt;slug&gt;&quot; }</code> addresses another agent mounted on the same serve host. The model gets the peer&#39;s <code>ask</code> and <code>check</code> tools, plus <code>call_tool</code> when the peer has server tools, and can delegate work to it:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  agent: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;weather-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Delegate weather questions to the weather agent.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Unknown slugs and self-references fail <code>serve</code> at startup. Walkthrough: <a href="./../guides/agent-to-agent.html#delegate-a-question-to-a-specialist">Peer agents</a>.</p><h2 id="call-mcp-from-host-code" tabindex="-1">Call MCP from host code <a class="header-anchor" href="#call-mcp-from-host-code" aria-label="Permalink to &quot;Call MCP from host code&quot;">​</a></h2><p>A file under <code>bot/mcp-connections/</code> is available to the Cursor agent, to server tools through <code>ctx.host.mcp</code>, and to channel and schedule handlers through <code>args.host.mcp</code>. Host connections skip the model.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/tools/search_linear.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Search Linear issues.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ query: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">query</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.mcp.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;list_issues&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { query });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>host.mcp.names()</code> lists connection names. <code>listTools(name)</code> / <code>callTool(name, tool, args)</code> call into a named connection.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>: <code>mcp oauth</code>, Connect, <code>--store</code></li><li><a href="./tools.html">Tools</a>: authored tools that wrap MCP connections</li><li><a href="./../guides/webhooks.html">Webhooks</a>: calling MCP connections from handlers</li><li><a href="./../guides/agent-to-agent.html">Peer agents</a>: when a specialist is its own agent</li></ul>`,55)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};

package/dist/docs/assets/reference_connections.md._XpKiOaF.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse(`{"title":"MCP connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),n={name:"reference/connections.md"};function l(h,s,o,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t("",55)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};