@cursor/bdk 0.2.13 → 0.2.15

package/dist/docs/assets/{reference_cli.md.dYCAL2lB.js → reference_cli.md.BYNIHwbi.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as a,o,a3 as s}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(r,e,c,i,l,p){return o(),a("div",null,[...e[0]||(e[0]=[s(`<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><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 from <code>@cursor/bdk</code>. Run it 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>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="#migrate"><code>migrate</code></a></td><td>Move an early-alpha project to architecture v2 through a pull request</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 hosted 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 hosted 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 deployment&#39;s event repositories</td></tr><tr><td><a href="#upgrade"><code>upgrade</code></a></td><td>Move a deployment 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>run</code>, <code>session</code>, <code>playground</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 the hosted deployment. Only <code>run</code>, <code>session</code>, and <code>playground</code> accept it.</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>
+import{_ as t,c as a,o,a3 as s}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,i,l,p){return o(),a("div",null,[...e[0]||(e[0]=[s(`<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><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 from <code>@cursor/bdk</code>. Run it 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>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="#migrate"><code>migrate</code></a></td><td>Move an early-alpha project to architecture v2 through a pull request</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 hosted 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 hosted 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="#start"><code>start</code></a></td><td>Start a stopped deployment</td></tr><tr><td><a href="#kill"><code>kill</code></a></td><td>Stop a deployment, cancel its runs, and lock deploys</td></tr><tr><td><a href="#unlock-deploys"><code>unlock-deploys</code></a></td><td>Let a killed deployment deploy again</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 deployment&#39;s event repositories</td></tr><tr><td><a href="#upgrade"><code>upgrade</code></a></td><td>Move a deployment to a release</td></tr><tr><td><a href="#rollback"><code>rollback</code></a></td><td>Move a deployment to an earlier 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><tr><td><a href="#images"><code>images</code></a></td><td>Push, list, or remove container images for persistent agents</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>run</code>, <code>session</code>, <code>logs</code>, <code>playground</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 the hosted deployment. Only <code>run</code>, <code>session</code>, <code>logs</code>, and <code>playground</code> accept it; <code>chat</code>, <code>resume</code>, <code>call</code>, <code>skill</code>, <code>sessions</code>, <code>cost</code>, and <code>mcp</code> report that the deployment doesn&#39;t support the command, and <code>eval</code> rejects the flag.</td></tr><tr><td><code>--slug &lt;slug&gt;</code></td><td>Select an agent from a multi-agent project or a hosted deployment. 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>
@@ -17,19 +17,19 @@ import{_ as t,c as a,o,a3 as s}from"./chunks/framework.BNw1pucY.js";const u=JSON
 <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. <code>--prod</code> 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. With <code>--prod</code>, pass 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. <code>--prod</code> 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 <code>--prod</code> turn as non-mutating.</td></tr><tr><td><code>--as-of &lt;instant&gt;</code></td><td>Freeze a <code>--prod</code> 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 hosted deployment&#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. With <code>--prod</code>, <code>run</code> prints a <code>deliveryId</code> when the deployment accepts the turn and returns before the turn finishes. A fresh start has no <code>sessionId</code> yet, even with <code>--dry-run</code>; a continuation includes it. <code>--prod</code> starts ignore <code>--events</code>, <code>--no-events</code>, <code>--text</code>, <code>--timeout-ms</code>, and <code>--no-stream</code>, and a successful start exits <code>0</code> before the turn outcome is known. See <a href="./../deployment.html#verify-a-hosted-turn">Verify a hosted turn</a>.</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>  [--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. A <code>--prod</code> run takes exactly 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. With <code>--prod</code>, pass a hosted <code>ses_...</code> ID from a session that <code>run --prod</code> or <code>session --prod</code> started; Slack, SCM, and custom-route sessions can&#39;t be continued this way.</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. <code>--prod</code> doesn&#39;t accept it.</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>Start a <code>--prod</code> session that runs read tools and stubs write tools.</td></tr><tr><td><code>--as-of &lt;instant&gt;</code></td><td>Freeze a <code>--prod</code> session&#39;s clock at an ISO-8601 instant with a timezone, such as <code>2026-08-31T12:00:00Z</code>.</td></tr><tr><td><code>--component &lt;key&gt;</code></td><td>Wake a named component of a <code>--prod</code> deployment instead of its default. A continued session must belong to that component.</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.</p><p>With <code>--prod</code>, <code>run</code> returns as soon as the deployment accepts the turn and exits <code>0</code> before the turn outcome is known. It prints <code>deliveryId</code>, <code>workflowId</code>, and <code>sessionMode</code>, plus <code>dryRun</code> and <code>asOf</code> when set. A fresh start has no <code>sessionId</code> yet; a continuation echoes the <code>--session</code> value. <code>--events</code>, <code>--no-events</code>, <code>--text</code>, <code>--timeout-ms</code>, and <code>--no-stream</code> have no effect. See <a href="./../deployment.html#verify-a-hosted-turn">Verify a hosted turn</a> for finding and following the new session.</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;]</span></span>
 <span class="line"><span>  [--session &lt;id&gt;] [--slug &lt;slug&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>Hosted deployments don&#39;t support <code>call</code>. Start a model turn with <code>run --prod</code> and check it with <a href="#session"><code>session</code></a>.</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;]</span></span>
 <span class="line"><span>  [--slug &lt;slug&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;]</span></span>
-<span class="line"><span>  [--slug &lt;slug&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><p>Hosted deployments don&#39;t support <code>sessions</code>. Find a hosted session in the deployment&#39;s <strong>Sessions</strong> list in the dashboard, then check it with <a href="#session"><code>session &lt;sessionId&gt; --prod</code></a>.</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;] [--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><p>Hosted deployments don&#39;t support <code>sessions</code>. Find a hosted session ID in the <a href="#logs"><code>logs --prod</code></a> headers or the deployment&#39;s <strong>Sessions</strong> list in the dashboard, then check it with <a href="#session"><code>session &lt;sessionId&gt; --prod</code></a>.</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 hosted session or continue the supplied hosted session ID.</td></tr></tbody></table><p><code>--events</code> and <code>--json</code> are mutually exclusive. With <code>--prod</code>, the command prints the session&#39;s runs and logs in text or JSON, and <code>--events</code> and <code>--out</code> aren&#39;t available. While a hosted turn is running, text output also reports the event count so far and prints <code>Turn running; runs may lag behind events.</code> 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 [sessionId] [--url &lt;baseUrl&gt; | --prod]</span></span>
-<span class="line"><span>  [--session &lt;sessionId&gt;] [--slug &lt;slug&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. With <code>--prod</code>, it follows the output of the hosted deployment&#39;s most recent sessions and prints a <code>==&gt; &lt;sessionId&gt; (&lt;channel&gt;) &lt;==</code> header each time the output switches sessions. Pass a session ID, as an argument or with <code>--session</code>, to follow only that session. Hosted log events carry <code>sessionId</code> and <code>line</code> rather than <code>index</code> and <code>at</code>.</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;]</span></span>
+<span class="line"><span>  [--team &lt;id&gt;] [--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 hosted session, or continue the supplied hosted session ID, with the same contract as <a href="#run"><code>run --prod</code></a>.</td></tr></tbody></table><p><code>--events</code> and <code>--json</code> are mutually exclusive. Use <a href="#resume"><code>resume</code></a> to continue a conversational session on a local or running server.</p><p>With <code>--prod</code>, the command prints the session&#39;s hosted executions: one line per run with its status, duration, and time, followed by that run&#39;s log lines. <code>--json</code> prints <code>{ sessionId, executions, startLog, ... }</code>. <code>--events</code> and <code>--out</code> aren&#39;t available. While a turn is running, text output also reports the event count and latest event type and prints <code>Turn running; runs may lag behind events.</code> A run can show <code>running</code> with no logs until the turn ends, so a growing event count is the progress signal.</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 [sessionId] [--url &lt;baseUrl&gt; | --prod]</span></span>
+<span class="line"><span>  [--session &lt;sessionId&gt;] [--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. With <code>--prod</code>, it follows the output of the hosted deployment&#39;s most recent sessions on every channel and prints a <code>==&gt; &lt;sessionId&gt; (&lt;channel&gt;) &lt;==</code> header each time the output switches sessions. Pass a session ID, as an argument or with <code>--session</code>, to follow only that session; a session ID requires <code>--prod</code>. Hosted log events carry <code>sessionId</code> and <code>line</code> rather than <code>index</code> and <code>at</code>.</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;]</span></span>
 <span class="line"><span>  [--slug &lt;slug&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. <code>--session</code> links for a hosted deployment may not open yet; check that session with <a href="#session"><code>session &lt;sessionId&gt; --prod</code></a> instead.</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>  [--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. With <code>--prod</code>, the URL opens the deployment&#39;s playground under <strong>Deployed Agents</strong> in the dashboard.</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>
@@ -43,16 +43,19 @@ import{_ as t,c as a,o,a3 as s}from"./chunks/framework.BNw1pucY.js";const u=JSON
 <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>Watch a repository&#39;s Cursor events. Repeat the flag for each repository; the repositories you pass replace the previous list. Without the flag, the deployment watches its GitHub source repository.</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, or a trailing <code>:port</code> for a protocol that is not HTTPS, with at most 64 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>. 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.</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 deployment&#39;s active runs and reminder wakes. 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>  [--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>Watch a repository&#39;s Cursor events. Repeat the flag for each repository; the repositories you pass replace the previous list. Without the flag, the deployment watches its GitHub source repository.</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, or a trailing <code>:port</code> for a protocol that is not HTTPS, with at most 64 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>. 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.</p><h3 id="start" tabindex="-1">Start a deployment <a class="header-anchor" href="#start" aria-label="Permalink to &quot;Start a deployment {#start}&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 start &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p><code>start</code> resumes a stopped deployment. It doesn&#39;t remove the deploy lock that <a href="#kill"><code>kill</code></a> sets.</p><h3 id="kill" tabindex="-1">Kill a deployment <a class="header-anchor" href="#kill" aria-label="Permalink to &quot;Kill a deployment {#kill}&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 kill &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p>Use <code>kill</code> in an emergency. It locks deploys of the slug, stops the deployment, and requests cancellation of its active runs and reminder wakes. To bring the deployment back, run <a href="#unlock-deploys"><code>unlock-deploys</code></a> and then <a href="#start"><code>start</code></a>.</p><h3 id="unlock-deploys" tabindex="-1">Unlock deploys <a class="header-anchor" href="#unlock-deploys" aria-label="Permalink to &quot;Unlock deploys {#unlock-deploys}&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 unlock-deploys &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p><code>unlock-deploys</code> removes the lock that <code>kill</code> sets, so <code>deploy</code>, <code>upgrade</code>, and <code>rollback</code> work for the slug again. It doesn&#39;t resume traffic; run <code>start</code> for that.</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 deployment&#39;s active runs and reminder wakes. 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 deployment&#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 deployment <a class="header-anchor" href="#upgrade" aria-label="Permalink to &quot;Upgrade a deployment {#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;] [--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="rollback" tabindex="-1">Roll back a deployment <a class="header-anchor" href="#rollback" aria-label="Permalink to &quot;Roll back a deployment {#rollback}&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 rollback &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>rollback</code> moves the deployment to an earlier ready release without building a new one. Omit <code>--release</code> to select the release before the current one. <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 a hidden value and ends that value at the first newline. With one name, redirected stdin is the whole value and one trailing newline is removed, so a PEM private key keeps its line breaks:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> my-bot</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> GITHUB_APP_PRIVATE_KEY</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./app.private-key.pem</span></span></code></pre></div><p>With several names, provide one line per name. <code>set</code> rejects <code>NAME=VALUE</code> on the command line unless <code>--from-argv</code> is set, because those 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 --url &lt;baseUrl&gt; [--bearer-token &lt;token&gt;]</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 a hidden value and ends that value at the first newline. With one name, redirected stdin is the whole value and one trailing newline is removed, so a PEM private key keeps its line breaks:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> my-bot</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> GITHUB_APP_PRIVATE_KEY</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./app.private-key.pem</span></span></code></pre></div><p>With several names, provide one line per name. <code>set</code> rejects <code>NAME=VALUE</code> on the command line unless <code>--from-argv</code> is set, because those 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><h3 id="images" tabindex="-1">Manage container images <a class="header-anchor" href="#images" aria-label="Permalink to &quot;Manage container images {#images}&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 images push &lt;local-image&gt; --name &lt;name&gt; [--team &lt;id&gt;] [--json]</span></span>
+<span class="line"><span>bdk images list [--team &lt;id&gt;] [--json]</span></span>
+<span class="line"><span>bdk images rm &lt;name&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p>A persistent agent can run inside a container image that your team pushes and names in <code>hosting.image</code>. <code>push</code> needs Docker on your machine. It checks the local image first: the image must be <code>linux/amd64</code> and have <code>bash</code>, <code>git</code>, <code>node</code> 22.13 or newer, and <code>npm</code> on <code>PATH</code>. The command then compresses the image and uploads it under <code>--name</code>.</p><p><code>list</code> shows the team&#39;s images and how many the team can keep, and <code>rm</code> deletes one image. A deploy pins the image it uses, so after you push a new image under the same name, deploy again to pick it up.</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 --url &lt;baseUrl&gt; [--bearer-token &lt;token&gt;]</span></span>
 <span class="line"><span></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></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 hosted 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>  [--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></tbody></table><p>Hosted deployments don&#39;t support <code>mcp</code> or <code>mcp install</code>; both report that the deployment doesn&#39;t support the command when you pass <code>--prod</code>.</p><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;]</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.</td></tr><tr><td><code>defineConnection({ cursorAccount: true })</code></td><td>Authorize the hosted deployment&#39;s service account through Cursor.</td></tr></tbody></table><p>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>
@@ -89,4 +92,4 @@ import{_ as t,c as a,o,a3 as s}from"./chunks/framework.BNw1pucY.js";const u=JSON
 <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><code>migrate</code></td><td>Exit <code>0</code> after starting with <code>--no-wait</code> or after the agent opens a pull request. Exit <code>1</code> for invalid input, authentication or agent failure, or a completed run without a pull request.</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><li><a href="./../guides/migrate.html">Early-alpha migration</a></li></ul>`,204)])])}const g=t(d,[["render",n]]);export{u as __pageData,g as default};
+<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><code>migrate</code></td><td>Exit <code>0</code> after starting with <code>--no-wait</code> or after the agent opens a pull request. Exit <code>1</code> for invalid input, authentication or agent failure, or a completed run without a pull request.</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><li><a href="./../guides/migrate.html">Early-alpha migration</a></li></ul>`,223)])])}const g=t(d,[["render",n]]);export{u as __pageData,g as default};

package/dist/docs/assets/{reference_cli.md.dYCAL2lB.lean.js → reference_cli.md.BYNIHwbi.lean.js}

@@ -1 +1 @@
-import{_ as t,c as a,o,a3 as s}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(r,e,c,i,l,p){return o(),a("div",null,[...e[0]||(e[0]=[s("",204)])])}const g=t(d,[["render",n]]);export{u as __pageData,g as default};
+import{_ as t,c as a,o,a3 as s}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,i,l,p){return o(),a("div",null,[...e[0]||(e[0]=[s("",223)])])}const g=t(d,[["render",n]]);export{u as __pageData,g as default};

package/dist/docs/assets/{reference_connections.md.DLrgAd5f.js → reference_connections.md.CxbLpaaP.js}

@@ -1,4 +1,4 @@
-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><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>
+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 h(l,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><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>
@@ -7,11 +7,10 @@ import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  command: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;slack-mcp-server&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;--transport&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stdio&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  env: { SLACK_MCP_XOXB_TOKEN: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;\${SLACK_BOT_TOKEN}&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>That timing is the point of the template. Your connection file is imported once, when the project loads, and a hosted deployment has none of its secrets in the environment yet, because the platform passes them to the agent per request. So a <code>process.env.SLACK_BOT_TOKEN</code> read at the top of the file captures an empty string and keeps sending it for the life of the process, while the same file works locally because <code>.env.local</code> was read before the import. The template form is right in both places.</p><p><code>bdk validate</code> warns about a template the environment does not define and names the variable. It stays a warning rather than an error, since a hosted deployment resolves it later. An unset variable resolves to an empty value at connect time, which the server reports as an auth failure.</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;">});</span></span></code></pre></div><p>That timing is the point of the template. Your connection file is imported once, when the project loads, and a hosted deployment has none of its secrets in the environment yet, because the platform passes them to the agent per request. So a <code>process.env.SLACK_BOT_TOKEN</code> read at the top of the file captures an empty string and keeps sending it for the life of the process, while the same file works locally because <code>.env.local</code> was read before the import. The template form is right in both places.</p><p><code>bdk validate</code> warns about a template the environment does not define and names the variable. It stays a warning rather than an error, since a hosted deployment resolves it later. An unset variable resolves to an empty value at connect time, which the server reports as an auth failure.</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 of the machine that authorized them. A hosted agent reaches OAuth servers through a <a href="#cursor-account-mcp-connection">Cursor account connection</a> instead.</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;">});</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></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>
@@ -64,4 +63,4 @@ import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c
 <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>`,58)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
+<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, and hosted agents</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>`,58)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_connections.md.DLrgAd5f.lean.js → reference_connections.md.CxbLpaaP.lean.js}

@@ -1 +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("",58)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
+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 h(l,s,o,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t("",58)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_evals.md.D5i8PuXJ.js → reference_evals.md.if--BLd0.js}

@@ -22,7 +22,7 @@ import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  maxConcurrency: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  timeoutMs: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">180_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  judge: { model: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gpt-5.4-mini&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><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>maxConcurrency</code></td><td>Required; concurrent authored datapoints, from 1 to 200</td></tr><tr><td><code>timeoutMs</code></td><td>Per-case timeout; case/file, CLI, then config precedence</td></tr><tr><td><code>judge</code></td><td>Default model for <code>t.judge</code></td></tr><tr><td><code>reporters</code></td><td>Objects notified as cases and runs complete</td></tr><tr><td><code>maxPlaygroundRuns</code></td><td>Number of server-side batches kept in playground history; defaults to 20</td></tr></tbody></table><p>A case can override <code>description</code>, <code>tags</code>, <code>timeoutMs</code>, <code>iterations</code>, <code>judge</code>, <code>reporters</code>, and <code>metadata</code>. Case metadata merges over file-level metadata; case reporters add to the file&#39;s reporters.</p><h2 id="send-turns-in-a-case" tabindex="-1">Send turns in a case <a class="header-anchor" href="#send-turns-in-a-case" aria-label="Permalink to &quot;Send turns in a case&quot;">​</a></h2><p><code>await t.send(message, options?)</code> runs one turn and waits until it finishes, fails, or parks for approval. Several sends in one test share the session.</p><p>The returned turn exposes its assistant <code>message</code>, <code>sessionId</code>, <code>events</code>, ordered <code>toolCalls</code>, <code>ok</code>, and one-based <code>index</code>. Assertions on the turn inspect only that turn; assertions on <code>t</code> inspect the whole case. Run values include <code>t.reply</code>, <code>t.events</code>, <code>t.turns</code>, <code>t.sessionId</code>, <code>t.iteration</code>, <code>t.iterations</code>, and the timeout <code>t.signal</code>.</p><p>These options apply on the first send because they shape the session:</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>workspaceFiles</code></td><td>Relative path-to-content map seeded into the session workspace</td></tr><tr><td><code>workspaceDir</code></td><td>Absolute working directory for a new local session</td></tr></tbody></table><p>Use <code>turn.expectOk()</code> when later test steps depend on the turn succeeding. It throws when the turn failed.</p><h2 id="trajectory-assertions" tabindex="-1">Trajectory assertions <a class="header-anchor" href="#trajectory-assertions" aria-label="Permalink to &quot;Trajectory assertions&quot;">​</a></h2><p>Assertions record failures without stopping the test, so one case reports every violated contract.</p><table tabindex="0"><thead><tr><th>Assertion</th><th>Checks</th></tr></thead><tbody><tr><td><code>t.succeeded()</code></td><td>Run finished without failure or an unanswered approval</td></tr><tr><td><code>t.parked()</code></td><td>Run stopped on an unanswered approval</td></tr><tr><td><code>t.calledTool(name, matcher?)</code></td><td>Matching tool request occurred</td></tr><tr><td><code>t.notCalledTool(name)</code></td><td>No request for that tool occurred</td></tr><tr><td><code>t.loadedSkill(name)</code></td><td>Agent opened a named skill</td></tr><tr><td><code>t.toolOrder(names)</code></td><td>Tool requests appeared in relative order</td></tr><tr><td><code>t.usedNoTools()</code></td><td>No tool was requested</td></tr><tr><td><code>t.maxToolCalls(max)</code></td><td>Tool-call count stayed under the bound</td></tr><tr><td><code>t.noFailedActions()</code></td><td>No tool result failed</td></tr><tr><td><code>t.calledSubagent(name, matcher?)</code></td><td>Matching subagent call occurred</td></tr><tr><td><code>t.taggedArtifact(kind?, predicate?)</code></td><td>Matching durable artifact was tagged</td></tr><tr><td><code>t.event(type, matcher?)</code></td><td>Matching session event occurred</td></tr><tr><td><code>t.notEvent(type, matcher?)</code></td><td>Matching session event did not occur</td></tr><tr><td><code>t.eventOrder(matchers)</code></td><td>Event groups appeared in relative order</td></tr><tr><td><code>t.eventsSatisfy(label, predicate)</code></td><td>Predicate accepted the event stream</td></tr><tr><td><code>t.check(value, expectation)</code></td><td>Value met an expectation builder</td></tr><tr><td><code>t.score(name, value)</code></td><td>Recorded a numeric score from 0 to 1</td></tr></tbody></table><p><code>t.requireToolCall</code>, <code>t.requireInputRequest</code>, and <code>t.require</code> return the matched value and stop the remaining test body when no match exists.</p><h2 id="tool-and-event-matchers" tabindex="-1">Tool and event matchers <a class="header-anchor" href="#tool-and-event-matchers" aria-label="Permalink to &quot;Tool and event matchers&quot;">​</a></h2><p>Tool matchers can narrow by <code>input</code>, <code>output</code>, <code>status</code>, and <code>count</code>. Values accept literals, regular expressions, or predicates. Object literals partial-deep-match:</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:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;inspect_pr&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><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>maxConcurrency</code></td><td>Required; concurrent authored datapoints, from 1 to 200</td></tr><tr><td><code>timeoutMs</code></td><td>Per-case timeout; case/file, CLI, then config precedence</td></tr><tr><td><code>judge</code></td><td>Default model for <code>t.judge</code></td></tr><tr><td><code>reporters</code></td><td>Objects notified as cases and runs complete</td></tr><tr><td><code>maxPlaygroundRuns</code></td><td>Number of server-side batches kept in playground history; defaults to 20</td></tr></tbody></table><p>A case can override <code>description</code>, <code>tags</code>, <code>timeoutMs</code>, <code>iterations</code>, <code>judge</code>, <code>reporters</code>, and <code>metadata</code>. Case metadata merges over file-level metadata; case reporters add to the file&#39;s reporters.</p><h2 id="send-turns-in-a-case" tabindex="-1">Send turns in a case <a class="header-anchor" href="#send-turns-in-a-case" aria-label="Permalink to &quot;Send turns in a case&quot;">​</a></h2><p><code>await t.send(message, options?)</code> runs one turn and waits until it finishes or fails. Several sends in one test share the session.</p><p>The returned turn exposes its assistant <code>message</code>, <code>sessionId</code>, <code>events</code>, ordered <code>toolCalls</code>, <code>ok</code>, and one-based <code>index</code>. Assertions on the turn inspect only that turn; assertions on <code>t</code> inspect the whole case. Run values include <code>t.reply</code>, <code>t.events</code>, <code>t.turns</code>, <code>t.sessionId</code>, <code>t.iteration</code>, <code>t.iterations</code>, and the timeout <code>t.signal</code>.</p><p>These options apply on the first send because they shape the session:</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>workspaceFiles</code></td><td>Relative path-to-content map seeded into the session workspace</td></tr><tr><td><code>workspaceDir</code></td><td>Absolute working directory for a new local session</td></tr></tbody></table><p>Use <code>turn.expectOk()</code> when later test steps depend on the turn succeeding. It throws when the turn failed.</p><h2 id="trajectory-assertions" tabindex="-1">Trajectory assertions <a class="header-anchor" href="#trajectory-assertions" aria-label="Permalink to &quot;Trajectory assertions&quot;">​</a></h2><p>Assertions record failures without stopping the test, so one case reports every violated contract.</p><table tabindex="0"><thead><tr><th>Assertion</th><th>Checks</th></tr></thead><tbody><tr><td><code>t.succeeded()</code></td><td>Run finished without failure</td></tr><tr><td><code>t.calledTool(name, matcher?)</code></td><td>Matching tool request occurred</td></tr><tr><td><code>t.notCalledTool(name)</code></td><td>No request for that tool occurred</td></tr><tr><td><code>t.loadedSkill(name)</code></td><td>Agent opened a named skill</td></tr><tr><td><code>t.toolOrder(names)</code></td><td>Tool requests appeared in relative order</td></tr><tr><td><code>t.usedNoTools()</code></td><td>No tool was requested</td></tr><tr><td><code>t.maxToolCalls(max)</code></td><td>Tool-call count stayed under the bound</td></tr><tr><td><code>t.noFailedActions()</code></td><td>No tool result failed</td></tr><tr><td><code>t.calledSubagent(name, matcher?)</code></td><td>Matching subagent call occurred</td></tr><tr><td><code>t.taggedArtifact(kind?, predicate?)</code></td><td>Matching durable artifact was tagged</td></tr><tr><td><code>t.event(type, matcher?)</code></td><td>Matching session event occurred</td></tr><tr><td><code>t.notEvent(type, matcher?)</code></td><td>Matching session event did not occur</td></tr><tr><td><code>t.eventOrder(matchers)</code></td><td>Event groups appeared in relative order</td></tr><tr><td><code>t.eventsSatisfy(label, predicate)</code></td><td>Predicate accepted the event stream</td></tr><tr><td><code>t.check(value, expectation)</code></td><td>Value met an expectation builder</td></tr><tr><td><code>t.score(name, value)</code></td><td>Recorded a numeric score from 0 to 1</td></tr></tbody></table><p><code>t.requireToolCall</code>, <code>t.requireInputRequest</code>, and <code>t.require</code> return the matched value and stop the remaining test body when no match exists.</p><h2 id="tool-and-event-matchers" tabindex="-1">Tool and event matchers <a class="header-anchor" href="#tool-and-event-matchers" aria-label="Permalink to &quot;Tool and event matchers&quot;">​</a></h2><p>Tool matchers can narrow by <code>input</code>, <code>output</code>, <code>status</code>, and <code>count</code>. Values accept literals, regular expressions, or predicates. Object literals partial-deep-match:</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:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;inspect_pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  input: { verdict: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;review&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  status: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  count: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>

package/dist/docs/assets/{reference_hooks.md.B-eGa2km.js → reference_hooks.md.DbJC8mcZ.js}

@@ -42,4 +42,4 @@ import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k
 <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="hooks-vs-channels-vs-evals" tabindex="-1">Hooks vs channels vs evals <a class="header-anchor" href="#hooks-vs-channels-vs-evals" aria-label="Permalink to &quot;Hooks vs channels vs evals&quot;">​</a></h2><p>All three consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th></tr></thead><tbody><tr><td>Scope</td><td>every session of the agent</td><td>sessions the channel owns</td><td>one test turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td></tr><tr><td>Context</td><td><code>ctx.host</code>, <code>ctx.artifacts</code>, session info</td><td><code>channel.state</code>, <code>setContinuationToken</code>, <code>ctx.host</code>, session info</td><td>the <code>t</code> assertion helpers</td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td></tr><tr><td>Authored at</td><td><code>bot/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td></tr></tbody></table><h2 id="hook-boundaries" tabindex="-1">Hook boundaries <a class="header-anchor" href="#hook-boundaries" aria-label="Permalink to &quot;Hook boundaries&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel&#39;s <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel&#39;s <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>; see <a href="./../guides/github.html">GitHub agents</a></td></tr><tr><td>Block, approve, or rewrite a tool call</td><td><a href="./tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a> on the tool</td></tr><tr><td>Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn</td><td><code>defineResult</code></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><h2 id="test-a-hook" tabindex="-1">Test a hook <a class="header-anchor" href="#test-a-hook" aria-label="Permalink to &quot;Test a hook&quot;">​</a></h2><p>A hook definition is a plain object, so a unit test calls <code>hook.events[&quot;turn.completed&quot;]</code> directly with an event and a stub <code>HookContext</code>. Discovery skips <code>*.test.ts</code>, so the test can live next to the hook.</p><table tabindex="0"><thead><tr><th>Command</th><th>What it reports</th></tr></thead><tbody><tr><td><code>bdk validate --dir .</code></td><td>Discovery errors and the empty-handlers warning</td></tr><tr><td><code>bdk info --dir . --json</code></td><td>Loaded hooks under <code>agents[].hooks</code></td></tr><tr><td><code>bdk run --dir . --message &quot;…&quot;</code></td><td>Serve log on stderr, including <code>hook &quot;&lt;name&gt;&quot; handler for &lt;event&gt; threw: …</code></td></tr></tbody></table><p>On hosting, read the same log with <a href="./cli.html#logs"><code>bdk logs</code></a>.</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/hooks.html">Hooks guide</a>: meter usage and page on failure</li><li><a href="./sessions.html">Sessions and streaming</a>: the event vocabulary hooks observe</li><li><a href="./../guides/opentelemetry.html">OpenTelemetry</a>: OTLP traces and metrics from the same event stream</li><li><a href="./../deployment.html#observability">Deployment</a>: runtime logs and export paths</li><li><a href="./channels.html#events">Channels</a>: the delivery-side counterpart</li></ul>`,31)])])}const E=e(n,[["render",o]]);export{k as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="hooks-vs-channels-vs-evals" tabindex="-1">Hooks vs channels vs evals <a class="header-anchor" href="#hooks-vs-channels-vs-evals" aria-label="Permalink to &quot;Hooks vs channels vs evals&quot;">​</a></h2><p>All three consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th></tr></thead><tbody><tr><td>Scope</td><td>every session of the agent</td><td>sessions the channel owns</td><td>one test turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td></tr><tr><td>Context</td><td><code>ctx.host</code>, <code>ctx.artifacts</code>, session info</td><td><code>channel.state</code>, <code>setContinuationToken</code>, <code>ctx.host</code>, session info</td><td>the <code>t</code> assertion helpers</td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td></tr><tr><td>Authored at</td><td><code>bot/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td></tr></tbody></table><h2 id="hook-boundaries" tabindex="-1">Hook boundaries <a class="header-anchor" href="#hook-boundaries" aria-label="Permalink to &quot;Hook boundaries&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel&#39;s <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel&#39;s <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>; see <a href="./../guides/github.html">GitHub agents</a></td></tr><tr><td>Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn</td><td><code>defineResult</code></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><h2 id="test-a-hook" tabindex="-1">Test a hook <a class="header-anchor" href="#test-a-hook" aria-label="Permalink to &quot;Test a hook&quot;">​</a></h2><p>A hook definition is a plain object, so a unit test calls <code>hook.events[&quot;turn.completed&quot;]</code> directly with an event and a stub <code>HookContext</code>. Discovery skips <code>*.test.ts</code>, so the test can live next to the hook.</p><table tabindex="0"><thead><tr><th>Command</th><th>What it reports</th></tr></thead><tbody><tr><td><code>bdk validate --dir .</code></td><td>Discovery errors and the empty-handlers warning</td></tr><tr><td><code>bdk info --dir . --json</code></td><td>Loaded hooks under <code>agents[].hooks</code></td></tr><tr><td><code>bdk run --dir . --message &quot;…&quot;</code></td><td>Serve log on stderr, including <code>hook &quot;&lt;name&gt;&quot; handler for &lt;event&gt; threw: …</code></td></tr></tbody></table><p>On hosting, read the same log with <a href="./cli.html#logs"><code>bdk logs</code></a>.</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/hooks.html">Hooks guide</a>: meter usage and page on failure</li><li><a href="./sessions.html">Sessions and streaming</a>: the event vocabulary hooks observe</li><li><a href="./../guides/opentelemetry.html">OpenTelemetry</a>: OTLP traces and metrics from the same event stream</li><li><a href="./../deployment.html#observability">Deployment</a>: runtime logs and export paths</li><li><a href="./channels.html#events">Channels</a>: the delivery-side counterpart</li></ul>`,31)])])}const E=e(n,[["render",o]]);export{k as __pageData,E as default};