@cursor/july 0.1.97 → 0.1.99

package/dist/docs/assets/{reference_cli.md.RyZf5OTE.js → reference_cli.md.DfoeyvL0.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h1><p><code>@cursor/july</code> installs <code>july</code> (so <code>npx @cursor/july docs</code> works) and <code>agent-sdk</code>. The examples on this page use <code>agent-sdk</code>. Run the CLI with Node 22.13 or newer. Don&#39;t run it with Bun; Bun corrupts tool-result streams from the Cursor SDK.</p><p><code>agent-sdk help</code> prints the built-in summary. The Slack and GitHub packs also provide <code>agent-sdk slack help</code> and <code>agent-sdk github help</code>.</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Start local development with <code>serve --dev</code></td></tr><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="#logs"><code>logs</code></a></td><td>Follow local or hosted logs</td></tr><tr><td><a href="#sessions"><code>sessions</code></a></td><td>List sessions on a running agent</td></tr><tr><td><a href="#session"><code>session</code></a></td><td>Inspect one session</td></tr><tr><td><a href="#cost"><code>cost</code></a></td><td>Report per-session token usage and estimated cost</td></tr><tr><td><a href="#playground"><code>playground</code></a></td><td>Open the local or hosted playground</td></tr><tr><td><a href="#docs"><code>docs</code></a></td><td>Serve the shipped documentation site locally</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run one or more turns locally, remotely, or on a 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="#eval"><code>eval</code></a></td><td>Run filesystem evals</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved event stream</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or print the setup guide</td></tr><tr><td><a href="#convert-automation"><code>convert-automation</code></a></td><td>Export a Cursor Automation into an agent project</td></tr><tr><td><a href="#install-skills"><code>install-skills</code></a></td><td>Refresh coding-agent skills (<code>npm install</code> already copies them)</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered agent surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check a project and fail on errors</td></tr><tr><td><a href="#login-logout-whoami"><code>login</code> / <code>logout</code> / <code>whoami</code></a></td><td>Manage the host&#39;s Cursor credential</td></tr><tr><td><code>version</code></td><td>Print the installed version and exit (also <code>--version</code> / <code>-V</code>)</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy one or more agents to Cursor managed hosting</td></tr><tr><td><a href="#deployments"><code>deployments</code></a></td><td>List hosted deployments</td></tr><tr><td><a href="#deployment"><code>deployment</code></a></td><td>Inspect one hosted deployment</td></tr><tr><td><a href="#stop"><code>stop</code></a></td><td>Stop a hosted deployment</td></tr><tr><td><a href="#delete"><code>delete</code></a></td><td>Delete a hosted 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="#rotate-pod-credential"><code>rotate-pod-credential</code></a></td><td>Replace a deployment&#39;s pod credential</td></tr><tr><td><a href="#secrets"><code>secrets</code></a></td><td>Manage deployment secrets</td></tr><tr><td><a href="#mcp"><code>mcp</code></a></td><td>Proxy the agent&#39;s MCP endpoint over stdio; <code>mcp install</code> writes <code>~/.cursor/mcp.json</code></td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize host MCP OAuth; optional <code>--store</code> to deployment secrets</td></tr><tr><td><a href="#slack"><code>slack ...</code></a></td><td>Provision, set up, and check Slack channels</td></tr><tr><td><a href="#github"><code>github ...</code></a></td><td>Forward, replay, and inspect GitHub webhook channels</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Choose a target <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Choose a target&quot;">​</a></h2><p>Request-sending commands support three target types.</p><table tabindex="0"><thead><tr><th>Target</th><th>How to select it</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>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code>, unless the command uses the localhost default described next</td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr><tr><td>Cursor managed hosting</td><td>Pass <code>--prod</code></td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr></tbody></table><p><code>chat</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, and <code>playground</code> default to <code>http://127.0.0.1:3000</code>. A <code>--url</code> must include the agent slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. <code>--slug</code> doesn&#39;t change an explicit URL. <code>mcp</code> has no default target; pass <code>--url</code> or <code>--prod</code>.</p><p>With <code>--prod</code>, <code>--slug</code> selects the deployment and <code>--team</code> selects the Cursor team. The slug defaults to the <code>--dir</code> basename. The team defaults to the signed-in account&#39;s team. <code>--url</code> and <code>--prod</code> are mutually exclusive.</p><p>Use <code>--bearer-token &lt;token&gt;</code> when a running server requires bearer authentication. Hosted commands use your Cursor credential to request short-lived engine access. <code>--api-key</code> overrides the Cursor credential for <code>login</code>, <code>serve</code>, hosted targets, and managed-hosting commands. <code>--state-root</code> applies to <code>serve</code> and ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> servers. Running and hosted targets ignore it.</p><p>For ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> commands, omitting <code>--slug</code> selects an unslugged root mount when one exists. Otherwise, the Agent SDK selects the first discovered agent.</p><h2 id="serve" tabindex="-1">serve <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;serve&quot;">​</a></h2><p><code>serve</code> hosts every agent under <code>--dir</code> in multi-agent mode by default.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3000]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">127.0.0.1]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dev]</span></span>
+import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,k){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h1><p><code>@cursor/july</code> installs <code>july</code> (so <code>npx @cursor/july docs</code> works) and <code>agent-sdk</code>. The examples on this page use <code>agent-sdk</code>. Run the CLI with Node 22.13 or newer. Don&#39;t run it with Bun; Bun corrupts tool-result streams from the Cursor SDK.</p><p><code>agent-sdk help</code> prints the built-in summary. The Slack and GitHub packs also provide <code>agent-sdk slack help</code> and <code>agent-sdk github help</code>.</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Start local development with <code>serve --dev</code></td></tr><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="#logs"><code>logs</code></a></td><td>Follow local or hosted logs</td></tr><tr><td><a href="#sessions"><code>sessions</code></a></td><td>List sessions on a running agent</td></tr><tr><td><a href="#session"><code>session</code></a></td><td>Inspect one session</td></tr><tr><td><a href="#cost"><code>cost</code></a></td><td>Report per-session token usage and estimated cost</td></tr><tr><td><a href="#playground"><code>playground</code></a></td><td>Open the local or hosted playground</td></tr><tr><td><a href="#docs"><code>docs</code></a></td><td>Serve the shipped documentation site locally</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run one or more turns locally, remotely, or on a 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="#eval"><code>eval</code></a></td><td>Run filesystem evals</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved event stream</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or print the setup guide</td></tr><tr><td><a href="#convert-automation"><code>convert-automation</code></a></td><td>Export a Cursor Automation into an agent project</td></tr><tr><td><a href="#install-skills"><code>install-skills</code></a></td><td>Refresh coding-agent skills (<code>npm install</code> already copies them)</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered agent surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check a project and fail on errors</td></tr><tr><td><a href="#login-logout-whoami"><code>login</code> / <code>logout</code> / <code>whoami</code></a></td><td>Manage the host&#39;s Cursor credential</td></tr><tr><td><code>version</code></td><td>Print the installed version and exit (also <code>--version</code> / <code>-V</code>)</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy one or more agents to Cursor managed hosting</td></tr><tr><td><a href="#deployments"><code>deployments</code></a></td><td>List hosted deployments</td></tr><tr><td><a href="#deployment"><code>deployment</code></a></td><td>Inspect one hosted deployment</td></tr><tr><td><a href="#stop"><code>stop</code></a></td><td>Stop a hosted deployment</td></tr><tr><td><a href="#delete"><code>delete</code></a></td><td>Delete a hosted 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="#rotate-pod-credential"><code>rotate-pod-credential</code></a></td><td>Replace a deployment&#39;s pod credential</td></tr><tr><td><a href="#secrets"><code>secrets</code></a></td><td>Manage deployment secrets</td></tr><tr><td><a href="#mcp"><code>mcp</code></a></td><td>Proxy the agent&#39;s MCP endpoint over stdio; <code>mcp install</code> writes <code>~/.cursor/mcp.json</code></td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize host MCP OAuth; optional <code>--store</code> to deployment secrets</td></tr><tr><td><a href="#slack"><code>slack ...</code></a></td><td>Provision, set up, and check Slack channels</td></tr><tr><td><a href="#github"><code>github ...</code></a></td><td>Forward, replay, and inspect GitHub webhook channels</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Choose a target <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Choose a target&quot;">​</a></h2><p>Request-sending commands support three target types.</p><table tabindex="0"><thead><tr><th>Target</th><th>How to select it</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>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code>, unless the command uses the localhost default described next</td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr><tr><td>Cursor managed hosting</td><td>Pass <code>--prod</code></td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr></tbody></table><p><code>chat</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, and <code>playground</code> default to <code>http://127.0.0.1:3000</code>. A <code>--url</code> must include the agent slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. <code>--slug</code> doesn&#39;t change an explicit URL. <code>mcp</code> has no default target; pass <code>--url</code> or <code>--prod</code>.</p><p>With <code>--prod</code>, <code>--slug</code> selects the deployment and <code>--team</code> selects the Cursor team. The slug defaults to the <code>--dir</code> basename. The team defaults to the signed-in account&#39;s team. <code>--url</code> and <code>--prod</code> are mutually exclusive.</p><p>Use <code>--bearer-token &lt;token&gt;</code> when a running server requires bearer authentication. Hosted commands use your Cursor credential to request short-lived engine access. <code>--api-key</code> overrides the Cursor credential for <code>login</code>, <code>serve</code>, hosted targets, and managed-hosting commands. <code>--state-root</code> applies to <code>serve</code> and ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> servers. Running and hosted targets ignore it.</p><p>For ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> commands, omitting <code>--slug</code> selects an unslugged root mount when one exists. Otherwise, the Agent SDK selects the first discovered agent.</p><h2 id="serve" tabindex="-1">serve <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;serve&quot;">​</a></h2><p><code>serve</code> hosts every agent under <code>--dir</code> in multi-agent mode by default.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3000]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">127.0.0.1]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dev]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--mode multi</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">single] [--api-key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">key</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;">                  [--state-root </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--bearer-token </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">secret</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> --allow-anonymous]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--allow-anonymous-cursor-github]</span></span>
@@ -59,8 +59,8 @@ import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> logout</span></span></code></pre></div><p><code>login</code> signs the host in to Cursor: browser sign-in mints a named, dashboard-revocable API key, and only the key is stored (the default name is <code>&lt;invoked command&gt; (&lt;hostname&gt;)</code>). It powers inference, the cloud runtime, and Cursor account MCP connections. <code>--key-name</code> changes the name of a browser-minted key. <code>login --api-key</code> validates and stores a key you already created.</p><p><code>whoami</code> shows which credential is active and why. <code>CURSOR_API_KEY</code> takes precedence over the stored login. <code>logout</code> removes the local credential file but doesn&#39;t revoke the API key. Revoke it in the Cursor dashboard when it should stop working.</p><p>Login and account RPCs honor <code>CURSOR_API_BASE_URL</code>. The SDK harness honors <code>CURSOR_BACKEND_URL</code>. Set both to the same URL, or keys minted on one host are rejected by the other.</p><h2 id="update" tabindex="-1">update <a class="header-anchor" href="#update" aria-label="Permalink to &quot;update&quot;">​</a></h2><p><code>update</code> upgrades an installed copy to the latest published version.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> update</span></span></code></pre></div><p>The command checks npm&#39;s <code>latest</code> tag, detects how the Agent SDK was installed, and runs the matching npm, pnpm, Yarn, or Bun upgrade command. It handles global installs and project dependencies. It doesn&#39;t prompt before running the package-manager command.</p><p>Source checkouts, <code>npx</code> or <code>pnpm dlx</code> caches, and unknown install layouts aren&#39;t changed. The command prints a manual upgrade hint instead.</p><p>Published installs also check for a newer version at most once every 24 hours and print an update warning on stderr. Source checkouts, CI, and commands with an explicit <code>--json</code> flag skip this automatic check.</p><h2 id="deploy" tabindex="-1">deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to &quot;deploy&quot;">​</a></h2><p><code>deploy</code> sends one or more agents to Cursor managed hosting.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> --all]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--repo </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https-url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--ref </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">git-ref</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--path </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">agent-path</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;">                [--cursor-events-repo owner/name]</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">...</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--allow-domain </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">domain</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--multi-tenant]</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--no-wait] [--json]</span></span></code></pre></div><p>Managed hosting requires team-admin permission and the team&#39;s cloud-agent entitlement. <code>--team</code> defaults to the signed-in account&#39;s team.</p><p>For a single project, the slug defaults to a normalized version of the directory name. Deployment slugs contain lowercase letters, digits, <code>_</code>, or <code>-</code>, with a maximum of 64 characters. For a directory with several agents, select one with <code>--slug</code>, deploy all with <code>--all</code>, or choose from the TTY prompt. Non-interactive callers must pass <code>--slug</code> or <code>--all</code>. If <code>--dir</code> contains no agent project or child agents, <code>deploy</code> requires <code>--slug</code> (or a slug derived from the directory name) and an https git repository URL (<code>--repo</code>, or inferred from <code>origin</code> when <code>--dir</code> is an agent project). <code>--all</code> fails when there is no agent project.</p><p>The command infers <code>--repo</code>, <code>--ref</code>, and <code>--path</code> from the current Git checkout when possible. Explicit flags take precedence. <code>--repo</code> must use HTTPS. Repeat <code>--cursor-events-repo</code> to select SCM event sources. Repeat <code>--allow-domain</code> to add engine egress domains; these values are combined with <code>hosting.egressDomains</code> from the agent config. Egress domains apply only to repository-backed deployments. Each domain must be a lowercase hostname with at least two labels and an alphabetic top-level domain. One leading <code>*.</code> wildcard is allowed. A deployment can declare at most 20 domains.</p><p><code>--multi-tenant</code> adds a release to an existing Cursor-managed (multi-tenant) product such as <code>security-reviewer</code>. It is valid only for <code>architecture: &quot;v2&quot;</code> and cannot create a new multi-tenant application — those stay on the operator seed path. Without the flag, HTTP deploy stays single-tenant and a managed slug 409s.</p><p>By default, the command polls every three seconds for up to ten minutes and succeeds only when the deployment reaches <code>running</code>. <code>--no-wait</code> returns after the deployment request is accepted. Multi-agent deploys run sequentially. When several agents are selected, <code>--path</code> is ignored and each project infers its own path. A single-target <code>--json</code> run prints one object; a multi-target run prints an array.</p><p>The first deployment can return an alias token. It appears once in text or JSON output and can&#39;t be retrieved later. Store it as a secret. Send it as <code>X-Agent-Alias-Token</code> when calling the stable alias URL, or use it to sign in to the hosted playground.</p><p>See <a href="./../deployment.html">Deployment</a> for the hosting security model and state layout.</p><h2 id="deployments" tabindex="-1">deployments <a class="header-anchor" href="#deployments" aria-label="Permalink to &quot;deployments&quot;">​</a></h2><p><code>deployments</code> lists the selected team&#39;s deployments.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployments</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Text output shows each slug, status, deployment kind, and update time. <code>--json</code> prints <code>{ deployments }</code>.</p><h2 id="deployment" tabindex="-1">deployment <a class="header-anchor" href="#deployment" aria-label="Permalink to &quot;deployment&quot;">​</a></h2><p><code>deployment</code> prints the full status of one deployment.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployment</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Text output includes status, kind, alias, source, egress domains, secret names, engine state, and the last error when present. <code>--json</code> returns the full API response. It can include short-lived <code>engineAccess.headers</code>, so handle JSON output as a credential.</p><h2 id="stop" tabindex="-1">stop <a class="header-anchor" href="#stop" aria-label="Permalink to &quot;stop&quot;">​</a></h2><p><code>stop</code> shuts down a deployment.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> stop</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--no-wait] [--json]</span></span></code></pre></div><p>The command polls for up to ten minutes until the status reaches <code>stopped</code>. <code>--no-wait</code> returns after the stop request is accepted.</p><h2 id="delete" tabindex="-1">delete <a class="header-anchor" href="#delete" aria-label="Permalink to &quot;delete&quot;">​</a></h2><p><code>delete</code> removes a deployment.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> delete</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--no-wait] [--json]</span></span></code></pre></div><p>The command waits until the deployment is gone. <code>--no-wait</code> returns after the delete request is accepted.</p><h2 id="rotate-token" tabindex="-1">rotate-token <a class="header-anchor" href="#rotate-token" aria-label="Permalink to &quot;rotate-token&quot;">​</a></h2><p><code>rotate-token</code> replaces the alias token used by callers and the hosted playground.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rotate-token</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>The old token stops working immediately. The replacement is shown once. <code>--json</code> prints <code>{ aliasToken }</code>.</p><h2 id="rotate-pod-credential" tabindex="-1">rotate-pod-credential <a class="header-anchor" href="#rotate-pod-credential" aria-label="Permalink to &quot;rotate-pod-credential&quot;">​</a></h2><p><code>rotate-pod-credential</code> replaces the credential used by the running engine pod.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rotate-pod-credential</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>The command prints only the masked key (<code>--json</code> prints <code>{ podCredentialMaskedKey }</code>). The running pod keeps the old credential until the next deploy, so nothing breaks in between. Run <code>agent-sdk deploy --slug &lt;slug&gt;</code> to inject the replacement and retire the old credential.</p><h2 id="mcp" tabindex="-1">mcp <a class="header-anchor" href="#mcp" aria-label="Permalink to &quot;mcp&quot;">​</a></h2><p><code>mcp</code> proxies an agent&#39;s MCP endpoint over stdio for MCP clients that spawn local servers, such as Cursor.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--allow-domain </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">domain</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">...</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--no-wait] [--json]</span></span></code></pre></div><p>Managed hosting requires team-admin permission and the team&#39;s cloud-agent entitlement. <code>--team</code> defaults to the signed-in account&#39;s team.</p><p>For a single project, the slug defaults to a normalized version of the directory name. Deployment slugs contain lowercase letters, digits, <code>_</code>, or <code>-</code>, with a maximum of 64 characters. For a directory with several agents, select one with <code>--slug</code>, deploy all with <code>--all</code>, or choose from the TTY prompt. Non-interactive callers must pass <code>--slug</code> or <code>--all</code>. If <code>--dir</code> contains no agent project or child agents, <code>deploy</code> requires <code>--slug</code> (or a slug derived from the directory name) and an https git repository URL (<code>--repo</code>, or inferred from <code>origin</code> when <code>--dir</code> is an agent project). <code>--all</code> fails when there is no agent project.</p><p>The command infers <code>--repo</code>, <code>--ref</code>, and <code>--path</code> from the current Git checkout when possible. Explicit flags take precedence. <code>--repo</code> must use HTTPS. Repeat <code>--cursor-events-repo</code> to select SCM event sources. Repeat <code>--allow-domain</code> to add engine egress domains; these values are combined with <code>hosting.egressDomains</code> from the agent config. Egress domains apply only to repository-backed deployments. Each domain must be a lowercase hostname with at least two labels and an alphabetic top-level domain. One leading <code>*.</code> wildcard is allowed. A deployment can declare at most 20 domains.</p><p>By default, the command polls every three seconds for up to ten minutes and succeeds only when the deployment reaches <code>running</code>. <code>--no-wait</code> returns after the deployment request is accepted. Multi-agent deploys run sequentially. When several agents are selected, <code>--path</code> is ignored and each project infers its own path. A single-target <code>--json</code> run prints one object; a multi-target run prints an array.</p><p>The first deployment can return an alias token. It appears once in text or JSON output and can&#39;t be retrieved later. Store it as a secret. Send it as <code>X-Agent-Alias-Token</code> when calling the stable alias URL, or use it to sign in to the hosted playground.</p><p>See <a href="./../deployment.html">Deployment</a> for the hosting security model and state layout.</p><h2 id="deployments" tabindex="-1">deployments <a class="header-anchor" href="#deployments" aria-label="Permalink to &quot;deployments&quot;">​</a></h2><p><code>deployments</code> lists the selected team&#39;s deployments.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployments</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Text output shows each slug, status, deployment kind, and update time. <code>--json</code> prints <code>{ deployments }</code>.</p><h2 id="deployment" tabindex="-1">deployment <a class="header-anchor" href="#deployment" aria-label="Permalink to &quot;deployment&quot;">​</a></h2><p><code>deployment</code> prints the full status of one deployment.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployment</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Text output includes status, kind, alias, source, egress domains, secret names, engine state, and the last error when present. <code>--json</code> returns the full API response. It can include short-lived <code>engineAccess.headers</code>, so handle JSON output as a credential.</p><h2 id="stop" tabindex="-1">stop <a class="header-anchor" href="#stop" aria-label="Permalink to &quot;stop&quot;">​</a></h2><p><code>stop</code> shuts down a deployment.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> stop</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--no-wait] [--json]</span></span></code></pre></div><p>The command polls for up to ten minutes until the status reaches <code>stopped</code>. <code>--no-wait</code> returns after the stop request is accepted.</p><h2 id="delete" tabindex="-1">delete <a class="header-anchor" href="#delete" aria-label="Permalink to &quot;delete&quot;">​</a></h2><p><code>delete</code> removes a deployment.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> delete</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--no-wait] [--json]</span></span></code></pre></div><p>The command waits until the deployment is gone. <code>--no-wait</code> returns after the delete request is accepted.</p><h2 id="rotate-token" tabindex="-1">rotate-token <a class="header-anchor" href="#rotate-token" aria-label="Permalink to &quot;rotate-token&quot;">​</a></h2><p><code>rotate-token</code> replaces the alias token used by callers and the hosted playground.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rotate-token</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>The old token stops working immediately. The replacement is shown once. <code>--json</code> prints <code>{ aliasToken }</code>.</p><h2 id="rotate-pod-credential" tabindex="-1">rotate-pod-credential <a class="header-anchor" href="#rotate-pod-credential" aria-label="Permalink to &quot;rotate-pod-credential&quot;">​</a></h2><p><code>rotate-pod-credential</code> replaces the credential used by the running engine pod.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rotate-pod-credential</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>The command prints only the masked key (<code>--json</code> prints <code>{ podCredentialMaskedKey }</code>). The running pod keeps the old credential until the next deploy, so nothing breaks in between. Run <code>agent-sdk deploy --slug &lt;slug&gt;</code> to inject the replacement and retire the old credential.</p><h2 id="mcp" tabindex="-1">mcp <a class="header-anchor" href="#mcp" aria-label="Permalink to &quot;mcp&quot;">​</a></h2><p><code>mcp</code> proxies an agent&#39;s MCP endpoint over stdio for MCP clients that spawn local servers, such as Cursor.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">baseUr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">l</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--bearer-token </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">toke</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--prod </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> --url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">baseUr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">l</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">serverNam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                     [--print] [--json] [--remote]</span></span></code></pre></div><p>The bare command reads newline-delimited JSON-RPC on stdin and forwards one POST per message to <code>&lt;target&gt;/v1/mcp</code>. It requires <code>--prod</code> or <code>--url</code>. With <code>--prod</code>, it resolves the hosted deployment through the signed-in Cursor account and re-mints short-lived engine credentials as they expire, so no durable secret lands in a config file. stdout is reserved for the MCP wire; logging goes to stderr.</p><p><code>mcp install</code> writes the matching entry into <code>~/.cursor/mcp.json</code> so the agent shows up as an MCP server in Cursor. <code>--name</code> overrides the server name (the default is the slug, or a name derived from <code>--url</code>). <code>--print</code> prints the entry instead of writing the file, and <code>--json</code> prints a machine-readable result. <code>--remote</code> (with <code>--prod</code>) writes a remote HTTP entry pointing at the stable Cursor MCP gateway instead of the local stdio proxy, for MCP hosts that can&#39;t spawn stdio servers. The remote entry carries your API key in plain text, so treat the file as a credential.</p><h2 id="mcp-oauth" tabindex="-1">mcp oauth <a class="header-anchor" href="#mcp-oauth" aria-label="Permalink to &quot;mcp oauth&quot;">​</a></h2><p><code>mcp oauth</code> authorizes a <code>defineConnection({ url, oauth: true })</code> or <code>defineConnection({ cursorAccount: true })</code> connection.</p><p>URL connections run a browser PKCE flow. Tokens are written to <code>mcp-auth.json</code> under the CLI config directory (override with <code>AGENT_SERVE_CONFIG_DIR</code>). Pass <code>--store</code> to upsert matching <code>MCP_OAUTH_&lt;CONNECTION&gt;_*</code> secrets on the hosted deployment. <code>--store</code> is the path for the next deploy. Hosted Connect lets the current process retry.</p><p>Cursor-account connections authorize the hosted deployment&#39;s service account through the Cursor backend&#39;s connector consent flow. Those tokens live on the Cursor backend, so <code>--store</code> isn&#39;t needed; the command prints a note when you pass it anyway.</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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> oauth</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">connectio</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--store] [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">slug</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><p><code>&lt;connection&gt;</code> is the basename under <code>agent/mcp-connections/</code> or <code>agent/host-connections/</code>. <code>--slug</code> defaults to the <code>--dir</code> basename. <code>--team</code> defaults to the signed-in account&#39;s team. You need <code>agent-sdk login</code> (or <code>--api-key</code>) before <code>--store</code>.</p><p>Secret names are <code>MCP_OAUTH_&lt;NAME&gt;_ACCESS_TOKEN</code>, <code>_REFRESH_TOKEN</code>, and <code>_CLIENT_ID</code> (<code>&lt;NAME&gt;</code> is the connection id in upper snake case). Declare them in <code>hosting.secretNames</code> so deploy validation expects them. Secrets apply on the next deploy.</p><p>Tokens are bound to the connection&#39;s resource URL. Changing the URL invalidates the local entry; run <code>mcp oauth</code> again.</p><p>See the <a href="./../guides/mcp-oauth.html">Host MCP OAuth guide</a>.</p><h2 id="secrets" tabindex="-1">secrets <a class="header-anchor" href="#secrets" aria-label="Permalink to &quot;secrets&quot;">​</a></h2><p><code>secrets</code> manages environment secrets for a deployment.</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;">agent-sdk</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:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> NAME</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [NAME2 </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">...]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span>
@@ -89,4 +89,4 @@ import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--events a,b,c</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;*&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">action</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--conclusion </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">result</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;">    [--comment </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--context </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">slug</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--channel </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</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;">    [--host </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">host</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--port </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--url </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--secret </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">secret</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;">    [--dry-run] [--out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</span></span></code></pre></div><p><code>github events</code> prints each discovered channel&#39;s delivery URL and event set. When it finds no channels, it returns an empty result and exits successfully.</p><p><code>github forward</code> wraps <code>gh webhook forward</code>. It infers the repository from the Git remote when you omit <code>--repo</code> and <code>--org</code>. URLs and events come from the discovered channels; <code>--events</code> overrides the event set. Use <code>--slug</code> or <code>--channel</code> to narrow discovery when several channels match. Otherwise, one local proxy fans deliveries out to every match. <code>--url</code> targets one channel. For <code>forward</code>, pass <code>--events</code> when no matched channel can supply the event set.</p><p>Repository forwarding needs repo-admin access. Organization forwarding needs org-owner access. The relay authenticates with the GitHub CLI&#39;s stored login. A <code>GITHUB_TOKEN</code> or <code>GH_TOKEN</code> environment override can make delivery requests return <code>401</code>, even when hook creation succeeds. Unset those variables before forwarding.</p><p>Pass <code>--secret</code> or set <code>GITHUB_WEBHOOK_SECRET</code> to sign deliveries. <code>serve --dev</code> accepts unsigned loopback deliveries. A non-dev target requires the same secret on both sides.</p><p><code>github replay</code> needs read access, not admin access. It reads the pull request through <code>gh api</code>, builds GitHub webhook payloads, and posts them to the selected channels. Supported events are <code>pull_request</code>, <code>issue_comment</code>, <code>pull_request_review_comment</code>, <code>check_run</code>, <code>check_suite</code>, <code>workflow_run</code>, and <code>status</code>. The default is <code>pull_request</code> with action <code>synchronize</code>. Comment events need <code>--comment</code>.</p><p>Use <code>--events &#39;*&#39;</code> to replay every supported event declared by the channel. <code>--dry-run</code> prints payloads without posting them. <code>--out</code> writes fixture files but still posts unless you also pass <code>--dry-run</code>.</p><p><code>github doctor</code> checks <code>gh</code>, its login, and the pinned <code>cli/gh-webhook</code> extension. <code>--install</code> installs or repairs the extension. An environment-token override is a warning and doesn&#39;t make <code>github doctor</code> fail.</p><p>See the <a href="./../guides/github.html">GitHub guide</a>.</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>These environment variables affect the CLI and its channel packs.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Meaning</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential. It takes precedence over the stored login.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend used by login, account, deployment, and event-relay RPCs.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend used by the Cursor SDK harness.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>Directory for stored credentials and update-check state. Defaults to the CLI config directory under <code>~/.config</code>.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code> / <code>NO_UPDATE_NOTIFIER</code></td><td>Disable the automatic published-version check when set to a non-empty value other than <code>0</code>.</td></tr><tr><td><code>CI</code></td><td>Disable the automatic published-version check when set.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default signing 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 authentication for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code></td><td>Token authentication for outbound API calls. Unset both for <code>github forward</code>.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code> / <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> for each agent on a multi-agent host.</td></tr></tbody></table><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./project-layout.html">Project layout</a>: files the CLI discovers</li><li><a href="./http-api.html">HTTP API</a>: routes used by <code>chat</code>, <code>call</code>, and other clients</li><li><a href="./../deployment.html">Deployment</a>: production auth, state, and operations</li></ul>`,202)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--dry-run] [--out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</span></span></code></pre></div><p><code>github events</code> prints each discovered channel&#39;s delivery URL and event set. When it finds no channels, it returns an empty result and exits successfully.</p><p><code>github forward</code> wraps <code>gh webhook forward</code>. It infers the repository from the Git remote when you omit <code>--repo</code> and <code>--org</code>. URLs and events come from the discovered channels; <code>--events</code> overrides the event set. Use <code>--slug</code> or <code>--channel</code> to narrow discovery when several channels match. Otherwise, one local proxy fans deliveries out to every match. <code>--url</code> targets one channel. For <code>forward</code>, pass <code>--events</code> when no matched channel can supply the event set.</p><p>Repository forwarding needs repo-admin access. Organization forwarding needs org-owner access. The relay authenticates with the GitHub CLI&#39;s stored login. A <code>GITHUB_TOKEN</code> or <code>GH_TOKEN</code> environment override can make delivery requests return <code>401</code>, even when hook creation succeeds. Unset those variables before forwarding.</p><p>Pass <code>--secret</code> or set <code>GITHUB_WEBHOOK_SECRET</code> to sign deliveries. <code>serve --dev</code> accepts unsigned loopback deliveries. A non-dev target requires the same secret on both sides.</p><p><code>github replay</code> needs read access, not admin access. It reads the pull request through <code>gh api</code>, builds GitHub webhook payloads, and posts them to the selected channels. Supported events are <code>pull_request</code>, <code>issue_comment</code>, <code>pull_request_review_comment</code>, <code>check_run</code>, <code>check_suite</code>, <code>workflow_run</code>, and <code>status</code>. The default is <code>pull_request</code> with action <code>synchronize</code>. Comment events need <code>--comment</code>.</p><p>Use <code>--events &#39;*&#39;</code> to replay every supported event declared by the channel. <code>--dry-run</code> prints payloads without posting them. <code>--out</code> writes fixture files but still posts unless you also pass <code>--dry-run</code>.</p><p><code>github doctor</code> checks <code>gh</code>, its login, and the pinned <code>cli/gh-webhook</code> extension. <code>--install</code> installs or repairs the extension. An environment-token override is a warning and doesn&#39;t make <code>github doctor</code> fail.</p><p>See the <a href="./../guides/github.html">GitHub guide</a>.</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>These environment variables affect the CLI and its channel packs.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Meaning</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential. It takes precedence over the stored login.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend used by login, account, deployment, and event-relay RPCs.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend used by the Cursor SDK harness.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>Directory for stored credentials and update-check state. Defaults to the CLI config directory under <code>~/.config</code>.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code> / <code>NO_UPDATE_NOTIFIER</code></td><td>Disable the automatic published-version check when set to a non-empty value other than <code>0</code>.</td></tr><tr><td><code>CI</code></td><td>Disable the automatic published-version check when set.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default signing 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 authentication for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code></td><td>Token authentication for outbound API calls. Unset both for <code>github forward</code>.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code> / <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> for each agent on a multi-agent host.</td></tr></tbody></table><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./project-layout.html">Project layout</a>: files the CLI discovers</li><li><a href="./http-api.html">HTTP API</a>: routes used by <code>chat</code>, <code>call</code>, and other clients</li><li><a href="./../deployment.html">Deployment</a>: production auth, state, and operations</li></ul>`,201)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_cli.md.RyZf5OTE.lean.js → reference_cli.md.DfoeyvL0.lean.js}

@@ -1 +1 @@
-import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t("",202)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};
+import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,k){return a(),e("div",null,[...s[0]||(s[0]=[t("",201)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_http-api.md.5zOAbV86.js → reference_http-api.md.BEJx9XVj.js}

@@ -2,7 +2,7 @@ import{_ as t,c as s,o,ag as a}from"./chunks/framework.BCISBCiQ.js";const p=JSON
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;What can you do?&quot;}&#39;</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;sessionId&quot;:&quot;ses_…&quot;,&quot;continuationToken&quot;:&quot;http:…&quot;,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>The response returns as soon as the message is accepted; follow the stream for progress. The continuation token is the follow-up credential, and <code>playgroundUrl</code> deep-links the session in the playground.</p><table tabindex="0"><thead><tr><th>Body field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>message</code></td><td>Required user message</td></tr><tr><td><code>title</code></td><td>Session title</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools</td></tr><tr><td><code>workspaceFiles</code></td><td>UTF-8 files written into the session workspace</td></tr><tr><td><code>cloud</code></td><td>Per-session cloud options merged over the agent defaults</td></tr></tbody></table><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</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;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session/ses_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>The response returns as soon as the message is accepted; follow the stream for progress. The continuation token is the follow-up credential, and <code>playgroundUrl</code> deep-links the session in the playground.</p><table tabindex="0"><thead><tr><th>Body field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>message</code></td><td>Required user message</td></tr><tr><td><code>title</code></td><td>Session title</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools</td></tr><tr><td><code>asOf</code></td><td>ISO-8601 instant with a timezone, frozen at create; the prompt states it, <code>ctx.now()</code> returns it, and tools declaring <code>timeArgs</code> refuse calls not bounded at or before it. <code>400</code> when unusable</td></tr><tr><td><code>workspaceFiles</code></td><td>UTF-8 files written into the session workspace</td></tr><tr><td><code>cloud</code></td><td>Per-session cloud options merged over the agent defaults</td></tr></tbody></table><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</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;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session/ses_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;continuationToken&quot;:&quot;http:…&quot;,&quot;message&quot;:&quot;Make it shorter.&quot;}&#39;</span></span></code></pre></div><p>Works for any chat session, including ones created by custom channels. Each accepted follow-up rotates the token, and the response carries the new one. Sending to a busy session interrupts the in-flight turn, waits for it to settle, then sends.</p><p>Expect <code>409</code> on a stale token or a task session. Task sessions do not accept follow-ups. Expect <code>403</code> when the caller is not the session owner.</p><h2 id="stream-a-session" tabindex="-1">Stream a session <a class="header-anchor" href="#stream-a-session" aria-label="Permalink to &quot;Stream a session&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/stream</code> is the live NDJSON feed.</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;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;http://127.0.0.1:3000/&lt;slug&gt;/v1/session/ses_…/stream?startIndex=0&#39;</span></span></code></pre></div><p>One NDJSON event per line, from <code>startIndex</code>, then following live. The default is <code>0</code>: omitting the parameter replays the entire recorded stream before following. Pass the last index you&#39;ve seen plus one to resume without duplicates. The stream is durable and reconnectable. For the vocabulary, see <a href="./sessions.html#which-events-can-i-stream">Sessions</a>.</p><p><code>GET /v1/session/:sessionId/events</code> returns a one-shot NDJSON dump. Pass <code>?format=json</code> for <code>{ sessionId, events, playgroundUrl }</code>.</p><h2 id="stop-and-list" tabindex="-1">Stop and list <a class="header-anchor" href="#stop-and-list" aria-label="Permalink to &quot;Stop and list&quot;">​</a></h2><p><code>POST /v1/session/:sessionId/stop</code> interrupts the in-flight turn without sending a new message. <code>GET /v1/sessions</code> lists sessions owned by the calling principal. Under <code>serve --dev</code> on loopback it includes all sessions, which is how webhook and schedule sessions show up in the playground.</p><h2 id="session-cost" tabindex="-1">Session cost <a class="header-anchor" href="#session-cost" aria-label="Permalink to &quot;Session cost&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/cost</code> returns the session&#39;s cost report: per-turn token usage and the engine&#39;s estimated cost, folded from <code>turn.completed</code> events. It runs the same owner check as the other session routes and returns <code>404</code> for an unknown session. The <a href="./cli.html#cost"><code>agent-sdk cost</code></a> command reports the same data.</p><h2 id="approvals" tabindex="-1">Approvals <a class="header-anchor" href="#approvals" aria-label="Permalink to &quot;Approvals&quot;">​</a></h2><p>Two routes list and resolve parked tool calls.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/session/:sessionId/approvals</code></td><td>Pending human-in-the-loop tool approvals</td></tr><tr><td><code>POST /v1/session/:sessionId/approvals/:callId</code></td><td>Resolve one: <code>{&quot;decision&quot;:&quot;approve&quot;}</code> or <code>{&quot;decision&quot;:&quot;deny&quot;}</code></td></tr></tbody></table><p>For the lifecycle, see <a href="./../guides/human-in-the-loop.html">Human-in-the-loop</a>.</p><h2 id="call-a-tool-directly" tabindex="-1">Call a tool directly <a class="header-anchor" href="#call-a-tool-directly" aria-label="Permalink to &quot;Call a tool directly&quot;">​</a></h2><p><code>POST /v1/tools/:toolName</code> runs a server tool with no model turn.</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;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/tools/inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>

package/dist/docs/assets/{reference_tools.md.B84gw9Ii.js → reference_tools.md.CvAHsdSp.js}

@@ -42,7 +42,15 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.BCISBCiQ.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;">version</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:#6F42C1;--shiki-dark:#B392F0;"> publishRelease</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(version);</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>dryRunResult</code> keeps the result shape stable. Without it, a stubbed write returns <code>&quot;Operation acknowledged.&quot;</code>. Traces mark the result as stubbed.</p><h2 id="define-an-agent-tool" tabindex="-1">Define an agent tool <a class="header-anchor" href="#define-an-agent-tool" aria-label="Permalink to &quot;Define an agent tool&quot;">​</a></h2><p>Set <code>execution: &quot;agent&quot;</code> and the tool materializes as a shell script that runs where the Cursor agent runs: the local harness workspace or the cloud VM. The script receives JSON arguments on stdin and prints its result on stdout. Use this flavor when the tool must run next to the checkout the agent works in; on cloud, server tools stay available too through the host&#39;s HTTP MCP endpoint.</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;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&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><code>dryRunResult</code> keeps the result shape stable. Without it, a stubbed write returns <code>&quot;Operation acknowledged.&quot;</code>. Traces mark the result as stubbed.</p><h3 id="bound-time-arguments-under-asof" tabindex="-1">Bound time arguments under <code>asOf</code> <a class="header-anchor" href="#bound-time-arguments-under-asof" aria-label="Permalink to &quot;Bound time arguments under \`asOf\`&quot;">​</a></h3><p>Declare <code>timeArgs</code> with the input properties that carry time bounds. In a session created with <code>asOf</code>, every named argument must be an absolute ISO-8601 instant with a timezone, no later than the session&#39;s frozen instant. A call that omits one, or supplies a relative or later value, is refused with an error telling the model to retry with absolute bounds. Sessions without <code>asOf</code> ignore the declaration.</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;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Query telemetry between two instants.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ since: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), until: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  effect: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;read&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  timeArgs: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;since&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;until&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">since</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">until</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:#6F42C1;--shiki-dark:#B392F0;"> queryTelemetry</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(since, until);</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>Every name in <code>timeArgs</code> must exist in the input schema; a session with <code>asOf</code> refuses to start otherwise, because a misspelled name would silently check nothing.</p><h2 id="define-an-agent-tool" tabindex="-1">Define an agent tool <a class="header-anchor" href="#define-an-agent-tool" aria-label="Permalink to &quot;Define an agent tool&quot;">​</a></h2><p>Set <code>execution: &quot;agent&quot;</code> and the tool materializes as a shell script that runs where the Cursor agent runs: the local harness workspace or the cloud VM. The script receives JSON arguments on stdin and prints its result on stdout. Use this flavor when the tool must run next to the checkout the agent works in; on cloud, server tools stay available too through the host&#39;s HTTP MCP endpoint.</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;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -76,4 +84,4 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}&#39;</span></span></code></pre></div><p>Programmatically, <code>callTool(toolName, input, options?)</code> is available on the serve handle, on channel route handlers and <code>onStart</code> args, and on schedule <code>run</code> handlers, so a channel can mix deterministic calls with model turns, fetching PR metadata deterministically and then <code>send()</code>ing the review prompt:</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;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> outcome</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> handle.</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;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;">  prUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/acme/checkout/pull/42&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>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// { toolName, callId, isError, result, durationMs }</span></span></code></pre></div><p>By default the call runs against an ephemeral workspace and is removed when the call returns. Pass a <code>sessionId</code> (a body field over HTTP, <code>--session</code> on the CLI, <code>options.sessionId</code> programmatically) to run inside an existing session instead: the tool sees that session&#39;s workspace, and the call is recorded on the session&#39;s event stream. While a model turn is running, a session-bound call is admitted by its effect: a read-effect call (a declared <code>effect: &quot;read&quot;</code>, or an advertised MCP tool whose server annotates it read-only) runs alongside the turn, reading the workspace as the turn has left it, and is recorded under its own per-call <code>turnId</code> so trajectories keep it apart from the turn&#39;s own calls; a write-effect call — including an undeclared tool, which counts as a write — returns <code>409 session_busy</code> until the turn finishes, because a running turn owns the workspace. When the session&#39;s harness cwd cannot be materialized, a read-effect call runs in a scratch workspace instead and the outcome carries <code>scratchWorkspace: true</code>; a write-effect call fails with <code>workspace_unavailable</code>.</p><p>A session can also be addressed by its continuation token: an optional <code>continuationToken</code> (<code>&lt;channelId&gt;:&lt;key&gt;</code>, as <code>/v1/sessions</code> lists it; mutually exclusive with <code>sessionId</code>). A token that maps to a live session behaves exactly like passing that session&#39;s id — same ownership check, same busy semantics, same event recording. A token with no session behind it runs the call scratch-bound with the token&#39;s channel id and continuation key as the call&#39;s session identity, so a deployment whose tools resolve state from the continuation key can serve it with no live session. Malformed tokens are rejected with <code>400 invalid_continuation_token</code>.</p><p>The error semantics match the model path. Unknown tools are rejected with the available names, agent-execution tools cannot be called on the host (<code>400</code>), schema-invalid input is a <code>400</code> before the tool body runs (Zod validates; plain JSON Schema passes through unvalidated), and a tool body that throws reports <code>isError: true</code> in the same envelope the model would see.</p><h2 id="design-habits" tabindex="-1">Design habits <a class="header-anchor" href="#design-habits" aria-label="Permalink to &quot;Design habits&quot;">​</a></h2><p>Keep one decision per tool. Small tools with crisp descriptions beat multi-purpose tools with mode flags. The model chooses better and evals gate cleaner.</p><p>Put deterministic policy in tool code, not model judgment. A PR-approval tool should re-read the live PR inside the tool before acting, so a spoofed payload can&#39;t steer it.</p><p>Test tools with <code>call</code> before blaming prompts. If the tool&#39;s output is wrong, no instruction change fixes it.</p><p>Gate side effects with <code>needsApproval</code>. Declare each tool&#39;s <code>effect</code> so dry-run sessions can execute reads and stub writes.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./../guides/human-in-the-loop.html">Human-in-the-loop</a>: the approval lifecycle in full</li><li><a href="./connections.html">MCP connections</a>: tools that come from MCP servers instead</li><li><a href="./../evals.html">Evals</a>: gating tool decisions with <code>calledTool</code></li></ul>`,53)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// { toolName, callId, isError, result, durationMs }</span></span></code></pre></div><p>By default the call runs against an ephemeral workspace and is removed when the call returns. Pass a <code>sessionId</code> (a body field over HTTP, <code>--session</code> on the CLI, <code>options.sessionId</code> programmatically) to run inside an existing session instead: the tool sees that session&#39;s workspace, and the call is recorded on the session&#39;s event stream. While a model turn is running, a session-bound call is admitted by its effect: a read-effect call (a declared <code>effect: &quot;read&quot;</code>, or an advertised MCP tool whose server annotates it read-only) runs alongside the turn, reading the workspace as the turn has left it, and is recorded under its own per-call <code>turnId</code> so trajectories keep it apart from the turn&#39;s own calls; a write-effect call — including an undeclared tool, which counts as a write — returns <code>409 session_busy</code> until the turn finishes, because a running turn owns the workspace. When the session&#39;s harness cwd cannot be materialized, a read-effect call runs in a scratch workspace instead and the outcome carries <code>scratchWorkspace: true</code>; a write-effect call fails with <code>workspace_unavailable</code>.</p><p>A session can also be addressed by its continuation token: an optional <code>continuationToken</code> (<code>&lt;channelId&gt;:&lt;key&gt;</code>, as <code>/v1/sessions</code> lists it; mutually exclusive with <code>sessionId</code>). A token that maps to a live session behaves exactly like passing that session&#39;s id — same ownership check, same busy semantics, same event recording. A token with no session behind it runs the call scratch-bound with the token&#39;s channel id and continuation key as the call&#39;s session identity, so a deployment whose tools resolve state from the continuation key can serve it with no live session. Malformed tokens are rejected with <code>400 invalid_continuation_token</code>.</p><p>The error semantics match the model path. Unknown tools are rejected with the available names, agent-execution tools cannot be called on the host (<code>400</code>), schema-invalid input is a <code>400</code> before the tool body runs (Zod validates; plain JSON Schema passes through unvalidated), and a tool body that throws reports <code>isError: true</code> in the same envelope the model would see.</p><h2 id="design-habits" tabindex="-1">Design habits <a class="header-anchor" href="#design-habits" aria-label="Permalink to &quot;Design habits&quot;">​</a></h2><p>Keep one decision per tool. Small tools with crisp descriptions beat multi-purpose tools with mode flags. The model chooses better and evals gate cleaner.</p><p>Put deterministic policy in tool code, not model judgment. A PR-approval tool should re-read the live PR inside the tool before acting, so a spoofed payload can&#39;t steer it.</p><p>Test tools with <code>call</code> before blaming prompts. If the tool&#39;s output is wrong, no instruction change fixes it.</p><p>Gate side effects with <code>needsApproval</code>. Declare each tool&#39;s <code>effect</code> so dry-run sessions can execute reads and stub writes.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./../guides/human-in-the-loop.html">Human-in-the-loop</a>: the approval lifecycle in full</li><li><a href="./connections.html">MCP connections</a>: tools that come from MCP servers instead</li><li><a href="./../evals.html">Evals</a>: gating tool decisions with <code>calledTool</code></li></ul>`,57)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_tools.md.B84gw9Ii.lean.js → reference_tools.md.CvAHsdSp.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,p,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t("",53)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
+import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,p,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t("",57)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};