# Agent SDK CLI

The CLI needs Node 22.13 or newer. Run `agent-sdk <command> --help` to see
every flag for that command.

```text
agent-sdk <command>
```

`agent-sdk help --all` prints every command, and
`agent-sdk help <command> --json` prints one command's flags as JSON.

Commands are named `agent-sdk <resource> <verb>`, such as
`agent-sdk deployment list`, apart from workflow verbs such as `init`, `dev`,
and `deploy`. Older names, such as `agent-sdk deployments` or
`agent-sdk secrets set`, still run and print the new form on stderr. The `bdk`
command remains available.

## Command catalog

### Development commands

| Command | Contract |
| --- | --- |
| `help`, `--help`, `-h` | Print the command index, or one command's help |
| [`serve`](#serve) | Serve one or more agents over HTTP |
| [`dev`](#dev) | Serve agents with local-development behavior |
| [`docs`](#docs) | Serve the bundled documentation |
| [`init`](#init) | Scaffold a project, or convert an Automation |
| [`migrate`](#migrate) | Open a pull request that migrates an early-alpha project |
| [`skills list`, `skills install`](#skills-install) | List or refresh the bundled coding-agent skills |
| [`info`](#info) | Print a project's discovered parts or deployment manifest |
| [`validate`](#validate) | Check project diagnostics and set the exit status |
| [`version`](#version) | Print the installed package version |
| [`update`](#update) | Upgrade the installed CLI |
| [`login`, `logout`, `whoami`](#login-logout-whoami) | Store, remove, or show the Cursor credential |

### Session and eval commands

| Command | Contract |
| --- | --- |
| [`chat`](#chat) | Talk to a running agent, or reattach a session |
| [`run`](#run) | Run turns on a local or running agent |
| [`tool call`](#tool-call) | Call a server tool without a model turn |
| [`logs`](#logs) | Follow or dump agent logs |
| [`session list`](#session-list) | List sessions, or their costs |
| [`session get`](#session-get) | Inspect a session or a saved trace |
| [`session create`](#session-create) | Start or continue a hosted session |
| [`eval`](#eval) | Run evals, or list, get, and cancel remote eval batches |

### Managed hosting commands

| Command | Contract |
| --- | --- |
| [`deploy`](#deploy) | Deploy an agent |
| [`deployment list`, `deployment get`](#deployment-list) | List deployments, or inspect one |
| [`deployment stop`, `start`, `kill`, `unlock`, `cancel-runs`, `upgrade`, `rollback`, `delete`, `rotate-token`](#deployment-lifecycle) | Change a deployment's state, release, or alias token |
| [`deployment update`](#deployment-update) | Replace a deployment's event repositories |
| [`secret`](#secret) | Set, list, or delete deployment secrets |

### Connection and channel commands

| Command | Contract |
| --- | --- |
| [`mcp serve`, `mcp install`](#mcp) | Connect an MCP client to an agent |
| [`mcp oauth`](#mcp-oauth) | Authorize an MCP connection |
| [`slack`](#slack) | Provision and check Slack channel apps |
| [`teams`](#teams) | Connect, check, and package a Microsoft Teams bot |
| [`github`](#github) | Forward, replay, and inspect GitHub webhooks |
| [`gitlab`, `bitbucket`, `pagerduty`](#replay-other-webhooks) | Replay and inspect GitLab, Bitbucket, or PagerDuty webhooks |

## Targets {#choose-a-target}

| Target | Selection | Commands |
| --- | --- | --- |
| Ephemeral local server | Omit `--url` and `--prod` | `run`, `tool call`, `eval` |
| Running server | Pass `--url <baseUrl>` | `chat`, `run`, `tool call`, `eval`, `logs`, `session list`, `session get`, `mcp serve` |
| Default local server | Omit `--url` and `--prod` to use `http://127.0.0.1:3000` | `chat`, `logs`, `session list`, `session get` |
| Hosted deployment | Pass `--prod` | `session list`, `session get`, `logs`. `session create` is always hosted. |

A hosted deployment supports only the commands in its row. `chat`, `run`,
`tool call`, `eval`, `mcp serve`, and `mcp install` exit with a usage error
when you pass `--prod`. To test a hosted agent, start a turn with
[`session create`](#session-create) and inspect it with
[`session get`](#session-get).

`--url` and `--prod` are mutually exclusive. An explicit `--url` must include
the slug for a multi-agent server, such as `http://127.0.0.1:3000/pr-approver`.
Otherwise `--slug` picks the agent, and under `--prod` it defaults to the
`--dir` basename. `--json` prints one JSON document on stdout, including
errors. Without it, output is text, even when piped.

## Local servers

### Serve agents {#serve}

`serve` mounts every project discovered under `--dir`:

```text
agent-sdk serve [--dir <path>] [--port <n>] [--host <host>]
  [--mode multi|single] [--dev] [--api-key <key>]
  [--state-root <path>]
  [--bearer-token <secret> | --allow-anonymous]
  [--allow-anonymous-cursor-github]
  [--allow-anonymous-cursor-account-mcp]
  [--public-url <url>]
  [--peers-url <url>]
  [--no-schedules] [--no-playground] [--no-docs]
  [--cursor-events --repo <owner/name>]...
```

`serve` listens on `127.0.0.1:3000`, or the next free port when that one is
taken. `--mode multi`, the default, mounts each project at `/<slug>/v1/*`, and
`--mode single` mounts one project at `/v1/*`. `--dev` turns off schedule and
reminder firing and admits unsigned loopback GitHub deliveries.

`--bearer-token` requires a token on routes that don't declare their own
authentication. `--allow-anonymous` admits every caller as one principal, so
use it only behind a trusted network boundary. The slugs `v1`, `channels`,
`playground`, and `docs` are reserved.

### Develop locally {#dev}

`dev` is `serve --dev` with an optional project path:

```text
agent-sdk dev
agent-sdk dev ./agent-sdk-pr-reviewer --port 3000
```

It accepts every `serve` option. Don't combine the path with a different
`--dir`.

When an agent has a Microsoft Teams channel, `dev` also opens a cloudflared
quick tunnel and prints that channel's messaging endpoint. Pass
`--tunnel devtunnel` for an endpoint that stays the same across restarts, and
`--tunnel-id <id>` to pick the dev tunnel. See
[Configure Microsoft Teams](#teams).

### Serve the docs {#docs}

```text
agent-sdk docs [--port <n>] [--host 127.0.0.1] [--print]
```

`docs` serves the bundled documentation on a loopback port until you press
Ctrl-C. `--print` prints the URL without opening a browser.

## Sessions and turns

### Chat with an agent {#chat}

```text
agent-sdk chat [--url <baseUrl>] [--message <text>]
  [--session <id> | --resume] [--continuation-token <token>]
  [--slug <slug>] [--json] [--text] [--no-color]
```

On a TTY, `chat` opens a REPL and sends any `--message` first. Without a TTY, it
sends `--message` as one turn, or reads newline-delimited messages until EOF.
`--session <id>` reattaches a stored session, and `--resume` picks the most
recent one.

### Run turns {#run}

```text
agent-sdk run [--dir <path>] [--message <text>]...
  [--messages-file <path>] [--url <baseUrl>]
  [--session <id>] [--continuation-token <token>]
  [--trace <file> | --no-trace] [--json]
  [--timeout-ms <n>] [--no-stream] [--slug <slug>] [--dry-run]
```

Repeat `--message` for a multi-turn run. `run` prints the compact trajectory,
writes an NDJSON trace unless you pass `--no-trace`, and exits `1` when the
trajectory fails. It has no default timeout.

### Call a tool {#tool-call}

```text
agent-sdk tool call <tool> [--input <json>]
  [--dir <path> | --url <baseUrl>]
  [--session <id>] [--slug <slug>] [--json]
```

`--input` takes JSON and defaults to `{}`. `--session` runs the tool in that
session's workspace and records the call. The command exits `1` unless the
response has `ok: true`. See
[Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn) for error codes.

### List sessions {#session-list}

```text
agent-sdk session list [--url <baseUrl> | --prod] [--since <duration|instant>]
  [--view sessions|cost] [--slug <slug>] [--team <id>]
  [--bearer-token <token>] [--limit <n>] [--page-token <token>] [--json]
```

`--limit` sets the page size, 20 by default and at most 100. With `--prod`,
it lists the most recently active hosted sessions, and `--since` reads back
to a cutoff such as `24h` or an ISO-8601 instant.
`--view cost` works only against a running server.

### Inspect a session {#session-get}

```text
agent-sdk session get <sessionId> [--url <baseUrl> | --prod]
  [--slug <slug>] [--team <id>]
  [--view trajectory|events|cost] [--json [--fields <a,b.c>]]
  [--trace <file.ndjson>] [--web [--print]]

agent-sdk session get --file <file.ndjson> [--json]
```

`session get` prints a compact trajectory, or raw [events](/docs/reference/sessions.md#stream-events) with `--view events`. `--view cost` and `--trace` work only locally. `--file` reads a saved trace and exits `1` when that trajectory failed, and `--web` opens the session in the playground. For a hosted deployment:

```bash
agent-sdk session list --prod
agent-sdk session get <sessionId> --prod --slug <slug> --view events
```

### Start a hosted session {#session-create}

```text
agent-sdk session create --message <text> [--session <ses_...>]
  [--slug <slug>] [--team <id>] [--wait [--timeout-ms <n>]]
  [--read-only] [--as-of <instant>] [--component <key>] [--dry-run] [--json]
```

`session create` sends one `--message` to the hosted deployment. Without
`--wait`, it exits `0` once the deployment accepts the turn, before a new
session has an ID. `--wait` polls until the session starts. It exits `3` when
`--timeout-ms` passes first and `1` when the delivery is skipped or fails.

`--session` continues a session that `session create` started. `--read-only`
stubs write tools, and `--as-of` freezes the session's clock at an ISO-8601
instant. See [Verify a hosted turn](/docs/deployment.md#verify-a-hosted-turn).

### Follow logs {#logs}

```text
agent-sdk logs [sessionId] [--url <baseUrl> | --prod]
  [--session <sessionId>] [--slug <slug>] [--team <id>] [--once] [--json]
```

`logs` follows output until Ctrl-C, and `--once` prints the current buffer and
exits. With `--prod`, it follows the hosted deployment's recent sessions and
prints a `==> <sessionId> (<channel>) <==` header when the output switches
sessions. A session ID follows one hosted session and requires `--prod`.

## Evals

### Run evals {#eval}

`eval` discovers `evals/**/*.eval.{ts,js}` and runs the selected cases:

```text
agent-sdk eval [--dir <path>] [evalId...]
  [--list] [--tag <tag>]... [--json] [--verbose]
  [--timeout-ms <n>] [--strict] [--max-concurrency <n>]
  [--junit <path>] [--artifacts <dir> | --no-artifacts]
  [--skip-report] [--no-stream]
  [--url <baseUrl>] [--no-wait] [--slug <slug>]
```

Select an exact case such as `weather/nyc`, a file prefix such as `weather`,
several IDs, or none for every case. Put an ID that is also a subcommand word
after `--`, as in `agent-sdk eval -- list`. The project needs an
[eval configuration](/docs/reference/evals.md#eval-configuration).

`--strict` fails a scored case below its soft threshold. The command exits `1`
for failed cases and `2` for invalid options or no matching cases. A running
server prints an Eval ID when it accepts the batch, and `--no-wait` returns at
that point. These commands require `--url`:

```text
agent-sdk eval list --url <baseUrl> [--limit <n>] [--page-token <token>]
agent-sdk eval get <evalId> --url <baseUrl>
agent-sdk eval cancel <evalId> --url <baseUrl>
```

`eval get` exits `3` while the batch runs and `1` when it failed or was
cancelled.

## Projects

### Scaffold a project {#init}

```text
agent-sdk init [directory] [--template <name>] [--var id=value]... [--json] [--dry-run]
agent-sdk init [directory] --from automation:<url-or-uuid> [--dry-run] [--json]
```

Without a directory, `init` prints the setup guide. With one, it adds missing
scaffold files, installs dependencies, and tries to put `agent-sdk` on `PATH`.
On a TTY, it also asks the template's questions and starts login when needed.

`--template` takes `agentic-owners`, `agents-md`, `code-wiki`, `demo`,
`security-help`, `security-reviewer`, `thermo-quality-review`, `thermo-review`,
`triage-jira`, or `triage-linear`. `triage` selects `triage-linear`.
`--var id=value` answers a template question without a prompt. `--dry-run`
lists the files without writing them.

#### Convert an Automation {#convert-automation}

`--from automation:` takes a Cursor Automation dashboard URL or UUID and
writes to `./<automation-name>` unless you name a directory. Generated files
don't overwrite existing paths, but the `npm install` that follows can run
lifecycle scripts from an existing `package.json`. See
[Convert a Cursor Automation](/docs/guides/convert-automation.md).

### Migrate an early-alpha project {#migrate}

```text
agent-sdk migrate [--dir <path>] [--repo <https-url>] [--ref <git-ref>]
  [--path <agent-path>] [--no-wait] [--json] [--api-key <key>]
```

`migrate` applies only to projects that deployed with `architecture: "v1"`
during the early alpha. It starts a Cursor cloud agent on a pushed Git ref
with the bundled `agent-sdk-migrate-v2` skill, and the agent opens a pull request
with the source changes. The command never deploys or changes secrets.

With nothing to change, it prints `Nothing to migrate.` and exits `0`, and it exits `1` if the run ends without a pull request. `deploy` refuses a project that sets `architecture: "v1"` and points to `migrate`. See [Migrate an early-alpha project](/docs/guides/migrate.md).

### Install and list coding-agent skills {#skills-install}

```text
agent-sdk skills install [--dry-run] [--json]
agent-sdk skills list [--json [--fields <a,b.c>]] [--limit <n>] [--page-token <token>]
```

Package installation copies the bundled skills, `skills install` replaces the installed copies and removes stale ones, and `skills list` prints each skill's bundled and installed versions. The `agent-sdk-cli` skill teaches agents to run `agent-sdk` safely.

### Inspect a project {#info}

```text
agent-sdk info [--dir <path>] [--view info|manifest] [--json [--fields <a,b.c>]]
```

Text output lists what discovery found, such as tools, channels, and
diagnostics. `--view manifest` summarizes one project's deployment metadata
without a network request.

### Validate a project {#validate}

```text
agent-sdk validate [--dir <path>]
```

`validate` prints every discovered project's diagnostics and exits `1` when
any diagnostic has error severity. `validate` fails when an SCM webhook secret
or GitHub credential is a literal or a getter, and the error message shows the
`{ secretName }` form to use. A project that still sets `architecture: "v1"`
gets the same finding as a warning.

## Credentials and versions

### Manage credentials {#login-logout-whoami}

```text
agent-sdk login [--api-key <key>] [--key-name <name>]
agent-sdk whoami [--json]
agent-sdk logout
```

`login` stores a supplied API key, or opens browser sign-in and stores the key
it creates. `whoami` shows the active credential and its source. `logout`
removes the stored credential but doesn't revoke the key, so revoke it in the
Cursor dashboard.

### Print the version {#version}

```text
agent-sdk version [--json]
agent-sdk --version
```

### Update the CLI {#update}

```text
agent-sdk update
```

`update` upgrades a recognized global or project install to npm's `latest`
tag, or prints a manual upgrade command. Published installs check for updates
daily unless an [update-check variable](#environment-variables) is set.

## Managed hosting

Every command here that changes a deployment takes `--dry-run`, which runs
the reads, stops at the first change, prints that request with secrets
redacted, and exits `0`.

`secret delete`, `image delete`, `slack destroy`, and the `deployment`
commands marked No in the [lifecycle table](#deployment-lifecycle) can't be
undone. On a terminal they ask you to type the slug or name, and a mismatch
exits `1`. Without a terminal, they exit `2` unless you pass `--yes`.

### Deploy agents {#deploy}

```text
agent-sdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
  [--repo <https-url>] [--ref <git-ref>] [--path <agent-path>]
  [--cursor-events-repo <repo>]... [--no-wait] [--json]
```

Deploying needs a team with agent hosting turned on, and a team service-account key with agent access can deploy. The CLI infers `--repo`, `--ref`, and `--path` from the current checkout, and the repository must use HTTPS.

`deploy` deploys one agent. On a folder of several agents, pass `--slug` to
pick one. `--all`, or picking several agents, prints one
`agent-sdk deploy --dir` command per agent and exits `1`.

`--cursor-events-repo` sets the repositories whose Cursor events the
deployment receives. Write `owner/name` for GitHub,
`gitlab.com/<group>/<project>` for GitLab, or
`bitbucket.org/<workspace>/<repo>` for Bitbucket. A GitLab path can include
subgroups. Repeat the flag once per repository. Each deploy replaces the whole list. Without the flag, the deployment watches its GitHub
source repository.

`deploy` waits until the deployment runs and exits nonzero if it fails, unless
you pass `--no-wait`. The first deploy of a slug can print an alias token
once. Slugs use lowercase letters, digits, `_`, and `-`, start with a letter
or digit, and have at most 64 characters. See [Deployment](/docs/deployment.md)
for egress hosts and the alias token.

### Inspect deployments {#deployment-list}

```text
agent-sdk deployment list [--team <id>] [--limit <n>] [--page-token <token>]
  [--json [--fields <a,b.c>]]
agent-sdk deployment get <slug> [--team <id>] [--json [--fields <a,b.c>]] [--web]
```

`deployment list` shows each deployment's slug, status, and update time, and `deployment get` adds the release, watched repositories, routes, secret names, and latest error. `--web` opens the deployment in [Deployed Agents](https://cursor.com/dashboard/deployed-agents), and an early-alpha deployment shows the steps to migrate it.

### Change a deployment {#deployment-lifecycle}

```text
agent-sdk deployment <command> <slug> [--team <id>] [--json] [--dry-run]
```

| Command | What it does | Undoable? |
| --- | --- | --- |
| `stop` | Stop the deployment. `--cancel-runs` also cancels active runs and reminder wakes. | Yes |
| `start` | Resume a stopped deployment. A kill lock stays. | Yes |
| `kill` | Lock deploys, stop the deployment, and cancel its runs and reminder wakes. To recover, run `unlock` and then `start`. | No |
| `unlock` | Remove the kill lock so deploys, upgrades, and rollbacks work again. Traffic stays stopped. | Yes |
| `cancel-runs` | Cancel active runs and reminder wakes. | No |
| `update` | Replace the [event repositories](#deployment-update). | Yes |
| `upgrade` | Move to a ready release, the newest unless you pass `--release`. | Yes |
| `rollback` | Move to an earlier ready release, the previous one unless you pass `--release`. | Yes |
| `delete` | Remove the deployment and free its slug. | No |
| `rotate-token` | Replace the alias token. The old one stops working at once. | No |

### Replace event repositories {#deployment-update}

```text
agent-sdk deployment update <slug> (--event-repo <owner/name>... | --no-event-repos)
  [--team <id>] [--dry-run] [--json]
```

The repositories you pass replace the deployment's whole event repository
list, and `--no-event-repos` clears it.

### Manage deployment secrets {#secret}

```text
agent-sdk secret set <slug> NAME [NAME2 ...]
  [--team <id>] [--from-argv] [--json]
agent-sdk secret list <slug> [--team <id>] [--limit <n>] [--page-token <token>] [--json]
agent-sdk secret delete <slug> NAME [--team <id>] [--yes] [--dry-run] [--json]
```

On a TTY, `secret set` prompts for each hidden value. With one name,
redirected stdin is the whole value minus one trailing newline, so a PEM key
keeps its line breaks:

```bash
agent-sdk secret set my-bot GITHUB_APP_PRIVATE_KEY < ./app.private-key.pem
```

With several names, give one line per name. `set` rejects `NAME=VALUE` arguments unless you pass `--from-argv`, because shell history keeps them. Names use `UPPER_SNAKE_CASE`, and the `CURSOR_` prefix is reserved. `secret list` returns names, never values.

## MCP connections

### Connect an MCP client {#mcp}

```text
agent-sdk mcp serve --url <baseUrl> [--bearer-token <token>]

agent-sdk mcp install --url <baseUrl> [--bearer-token <token>]
  [--name <server-name>] [--dry-run] [--json]
```

`mcp serve` proxies newline-delimited JSON-RPC from stdin to the agent's MCP
endpoint and reserves stdout for MCP messages. `mcp install` adds the agent to
`~/.cursor/mcp.json`. An entry made with `--bearer-token` contains that token,
so treat every printed or written copy as a credential.

### Authorize MCP OAuth {#mcp-oauth}

```text
agent-sdk mcp oauth <connection> [--dir <path>]
  [--slug <slug>] [--team <id>]
```

`<connection>` is the basename under `bot/mcp-connections/` or
`bot/host-connections/`. A `url` connection with `oauth: true` opens a browser
PKCE flow and saves tokens bound to that URL, so authorize again after you
change it. A `cursorAccount` connection exits nonzero and points to the
cursor.com dashboard. See [Host MCP OAuth](/docs/guides/mcp-oauth.md).

## Channel helpers

### Configure Slack {#slack}

```text
agent-sdk slack setup
agent-sdk slack create [--dir <path>] [--name <name>] [--env prod]
  [--slack-team <id>] [--team <id>] [--icon <url-or-file>]
  [--prefix <prefix> | --no-prefix] [--channel-posts] [--json]
agent-sdk slack destroy [--dir <path>] [--env prod] [--yes] [--dry-run]
  [--slack-team <id>] [--team <id>] [--json]
agent-sdk slack icon <url-or-file> [--dir <path>] [--env prod]
  [--slack-team <id>] [--team <id>] [--json]
agent-sdk slack init --manual [--dir <path>] [--name <name>]
  [--prefix <prefix> | --no-prefix] [--channel-posts]
  [--install | --no-install] [--slack-team <id>] [--env dev|prod]
agent-sdk slack manifest [--dir <path>] [--name <name>]
  [--env dev|prod|both] [--channel-posts] [--dry-run]
agent-sdk slack doctor [--dir <path>]
  [--prefix <prefix> | --no-prefix] [--channel <id>]... [--json]
```

`slack create` opens the
[Deployed Agents](https://cursor.com/dashboard/deployed-agents) wizard, writes
the token pair to `.env.local`, and runs `doctor`, which checks both tokens and
Socket Mode. It makes the development app unless you pass `--env prod`. The
token prefix defaults to the project directory name in upper snake case.
`--channel-posts` adds the message events that `engagement.channelPosts`
needs. See [Slack](/docs/guides/slack.md) for manual setup.

### Configure Microsoft Teams {#teams}

```text
agent-sdk channels teams setup
agent-sdk channels teams init --app-id <guid> --tenant-id <guid> [--dir <path>]
  [--prefix <prefix>] [--dry-run] [--json]
agent-sdk channels teams doctor [--dir <path>] [--slug <slug>] [--channel <id>]
  [--endpoint <url>] [--json]
agent-sdk channels teams package [--dir <path>] [--slug <slug>] [--channel <id>]
  [--name <name>] [--icon <png>] [--app-version <x.y.z>] [--endpoint <url>]
  [--out <file>] [--dry-run] [--json]
agent-sdk channels teams forward [--dir <path>] [--slug <slug>] [--channel <id>]
  [--host <host>] [--port <n>] [--tunnel cloudflared|devtunnel]
  [--tunnel-id <id>] [--json]
```

| Subcommand | Contract |
| --- | --- |
| `setup` | Print the Azure Bot setup steps without changing files. |
| `init` | Read the bot's client secret from a hidden prompt or stdin, never from an argument. Write `bot/channels/teams.ts` when it's missing, and write the app id, secret, and tenant id to `.env.local`. A second `init` keeps the channel file and replaces the secret. |
| `doctor` | Run the checks below and exit `1` when one fails. A check it can't run is skipped and says why. |
| `package` | Write the Teams app package: `manifest.json`, a 192 by 192 color icon, and a 32 by 32 outline icon. By default it writes `<slug>-teams-app.zip` in the agent folder and adds `*-teams-app.zip` to `.gitignore`. `--out <file>` writes it to that path instead. Upload it in Teams under **Apps** > **Manage your apps** > **Upload an app**. |
| `forward` | Open a tunnel to a running `agent-sdk serve` and print the messaging endpoint of each Teams channel. It runs until you stop it. |

`agent-sdk dev` opens the same tunnel by itself. The endpoint is the tunnel
origin plus `/<slug>/v1/channels/<channel>`, such as
`https://<random>.trycloudflare.com/helm/v1/channels/teams`. Set it as the
Azure Bot's messaging endpoint. The tunnel forwards only `POST` requests to
the Teams messaging paths, so the rest of the agent's API stays local. Every
other request on the tunnel host gets a `404`.

`--tunnel` picks the tunnel for `dev` and `channels teams forward`:

| `--tunnel` | Needs | Endpoint |
| --- | --- | --- |
| `cloudflared` (default) | `cloudflared` on `PATH`. No account. | A new `trycloudflare.com` URL on every start. Set it on the bot again after each restart. |
| `devtunnel` | The `devtunnel` CLI on `PATH`, logged in with `devtunnel user login`. | The same `devtunnels.ms` URL on every start. Set it on the bot once. |

With `devtunnel`, the first start creates a dev tunnel that allows anonymous
access, adds port `3978`, and saves the tunnel id as `TEAMS_DEVTUNNEL_ID` in
`.env.local`. Later starts reuse that tunnel. `--tunnel-id <id>` picks the id.
Microsoft deletes a dev tunnel after 30 days without use, and the next start
creates it again under the same id. Port `3978` belongs to the tunnel, so
`--port 3978` with `--tunnel devtunnel` stops with a usage error. Run the agent
on another port. `devtunnel host` publishes every port on the tunnel, so the
tunnel stops when it reports a port other than `3978`. Remove that port with
`devtunnel port delete <id> -p <port>`, or pass another `--tunnel-id`.

The package manifest uses Teams manifest version 1.25. It names the bot by
its app id and lists the scopes the channel answers in: mentions add `team`
and `groupChat`, and personal chats add `personal`. With
`engagement.channelPosts`, it also asks for `ChannelMessage.Read.Group`
consent. `--endpoint` adds the messaging endpoint's host to `validDomains`.
`--app-version` sets the app version. It defaults to `1.<YYYYMMDD>.<second of
the day>` in UTC, so each new zip is higher than the last, and Teams and the
Teams admin center accept it as an update. Teams refuses an update whose
version is not higher than the installed one. After you set
`--app-version 2.0.0`, a later default `1.x` version is lower, so keep passing
a higher `--app-version`. The default's middle part has 8 digits, which is fine
for a bot-only app. An app that adds an Office Add-in limits each part to 5
digits.

`doctor` runs these checks in order:

| Check | Passes when |
| --- | --- |
| `env` | The app id, password, and tenant id variables are set. |
| `token` | Microsoft Entra issues a Bot Framework token for the app within 10 seconds. |
| `bot-tenant` | The Azure Bot is **Single Tenant** and its tenant is the one in the channel's tenant id variable. |
| `bot-endpoint` | The Azure Bot's messaging endpoint is `--endpoint`. Without `--endpoint`, it reports the bot's endpoint. |
| `teams-channel` | The Azure Bot's Microsoft Teams channel is added and on. |
| `endpoint` | The endpoint's path names this channel, and an unsigned `POST` to it gets `401`. |

The three Azure checks need the Azure CLI, logged in with `az login`, on any
operating system. Without it they are skipped. When no Azure Bot in the
current subscription has the app id, they fail. Each `az` call has a time
limit. The endpoint's path must end in `/v1/channels/<channel>` plus the
channel's `path` after nothing, the agent's slug, or the legacy `/engine` alias,
or `/channels/<channel>` plus the channel's `path` after
`/v1/agent-sdk/<applicationId>` (optionally followed by `/<slug>`) on
Cursor-managed hosting. CLI `0.7.1` and older fail this check on
`/v1/agent-sdk/...` URLs (`deploy` and running bots are unaffected; `0.7.2`
adds support). A URL for another channel or agent fails without a
probe. The `endpoint` answers mean:

| Answer | Meaning |
| --- | --- |
| `401` with `invalid_token` | The Teams channel serves this URL and its credentials resolve. Teams signs its requests, so the channel refuses the unsigned probe. |
| `401` with `Unauthorized` | Cursor-managed hosting serves this URL and refuses the unsigned probe before the agent. |
| `503` with `teams_not_configured` | The server has no app id or password for this channel. Check `envPrefix` and the secrets. |
| `404` | No Teams channel at this path. Check the slug, the channel name, and the route path. |
| A redirect | A dev tunnel that needs sign-in. Run `devtunnel access create <id> --anonymous`. |

`--endpoint` must be the public `https` URL that `dev` or `channels teams forward`
prints. `agent-sdk dev` admits unsigned requests from loopback, so a loopback
probe proves nothing. Without `--endpoint`, `doctor` probes the Azure Bot's
messaging endpoint.

The channel's `envPrefix` owns the variable names. A new channel file reads
`TEAMS_APP_ID`, `TEAMS_APP_PASSWORD`, and `TEAMS_TENANT_ID`. `init --prefix
HELM` writes `envPrefix: "HELM"` into the new file and the names
`HELM_TEAMS_APP_ID`, `HELM_TEAMS_APP_PASSWORD`, and `HELM_TEAMS_TENANT_ID`. The
prefix must start with a letter, and each name must be a valid deployment
secret name. When the agent already has a Teams channel, under any file name,
`init` keeps it and writes the names it reads; a `--prefix` that disagrees with
it stops with an error. `doctor` and `package` read the names from the loaded
channel. Multi-agent servers need one Azure Bot per agent.

A channel that sets `credentials` in code has no env names for the CLI to
read. `doctor` then skips the `env`, `token`, and Azure checks and says why,
`package` and `init` stop with an error, and `doctor` still probes
`--endpoint`.

### Test GitHub webhooks {#github}

```text
agent-sdk github forward [--dir <path>] [--slug <slug>] [--channel <id>]
  [--repo owner/repo | --org <org>] [--events a,b,c]
  [--url <url>] [--host <host>] [--port <n>]
  [--secret <secret>] [--install]
agent-sdk github replay <pr-url-or-owner/repo#N>
  [--events a,b,c | '*'] [--action <action>] [--conclusion <result>]
  [--comment <body>] [--context <name>] [--dir <path>]
  [--slug <slug>] [--channel <id>] [--url <url>]
  [--secret <secret>] [--dry-run] [--fixtures-dir <dir>] [--json]
agent-sdk github events [--dir <path>] [--host <host>] [--port <n>] [--json]
agent-sdk github doctor [--install] [--json]
```

`forward` sends live deliveries to discovered channels through `gh webhook forward`. It needs repository admin access, or organization owner access for `--org`, and it uses the GitHub CLI's own login, so unset `GITHUB_TOKEN` and `GH_TOKEN` first. `doctor` checks the GitHub CLI and its webhook extension.

`replay` reads a pull request with read access, builds webhook payloads, and
posts them to matching channels. Its events are `pull_request`, the default,
`issue_comment`, `pull_request_review_comment`, `check_run`, `check_suite`,
`workflow_run`, and `status`. `--dry-run` prints the payloads without posting,
and `--fixtures-dir` also writes them as fixtures. See
[GitHub](/docs/guides/github.md) for channel setup.

### Test GitLab, Bitbucket, and PagerDuty webhooks {#replay-other-webhooks}

```text
agent-sdk gitlab replay <mr-url-or-group/project!N> [replay flags]
agent-sdk bitbucket replay <pr-url-or-workspace/repo#N> [replay flags]
agent-sdk pagerduty replay [incident-id] [replay flags]
agent-sdk <gitlab|bitbucket|pagerduty> events [--dir <path>] [--json]
agent-sdk <gitlab|bitbucket> forward [--dir <path>]
```

Replay takes the same flags as `github replay`, including `--fixtures-dir`. `events` lists the discovered channels, and `forward` prints the webhook and tunnel recipe for live deliveries.

| Command | Replay events | Default event | Read credential | `--secret` default |
| --- | --- | --- | --- | --- |
| `gitlab replay` | `merge_request`, `note`, `pipeline`, `push` | `merge_request` | `GITLAB_TOKEN` | `GITLAB_WEBHOOK_SECRET` |
| `bitbucket replay` | `pullrequest:created`, `pullrequest:updated`, `pullrequest:comment_created`, `repo:push`, in Cloud or Data Center format | `pullrequest:created` | `BITBUCKET_TOKEN` | `BITBUCKET_WEBHOOK_SECRET` |
| `pagerduty replay` | `incident.triggered`, `.acknowledged`, `.annotated`, `.escalated`, `.resolved`, `.reopened` | `incident.triggered` | None | `PAGERDUTY_WEBHOOK_SECRET` |

PagerDuty replay's incident ID defaults to `PREPLAY1`, and `--comment` is the
note body for `annotated`. Without a secret, its deliveries are unsigned, and
`agent-sdk dev` admits them from loopback. See [GitLab](/docs/guides/gitlab.md),
[Bitbucket](/docs/guides/bitbucket.md), and [PagerDuty](/docs/guides/pagerduty.md)
for channel setup.

## Environment variables {#environment-variables}

The CLI tries `--api-key`, `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
`CURSOR_SERVICE_ACCOUNT_KEY`, then the stored `agent-sdk login` credential, in
that order.

| Variable | Contract |
| --- | --- |
| `CURSOR_API_KEY` | Cursor credential. |
| `CURSOR_API_KEY_FILE` | Path to a Cursor credential file. |
| `CURSOR_SERVICE_ACCOUNT_KEY` | Team service-account credential. |
| `CURSOR_API_BASE_URL` | Backend for login, account, deployment, and event commands. |
| `CURSOR_BACKEND_URL` | Backend for agent turns. Set it with `CURSOR_API_BASE_URL` for a non-default backend. |
| `AGENT_SERVE_CONFIG_DIR` | CLI config directory for stored credentials and update state. |
| `AGENT_SERVE_NO_UPDATE_CHECK`, `NO_UPDATE_NOTIFIER`, `CI` | Turn off update checks when set to a value other than `0`. |
| `GITHUB_WEBHOOK_SECRET` | Default secret for GitHub forwarding and replay. |
| `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_INSTALLATION_ID` | GitHub App credentials for outbound API calls. |
| `GITHUB_TOKEN`, `GH_TOKEN` | Tokens for outbound GitHub calls. |
| `GITLAB_TOKEN`, `GITLAB_WEBHOOK_SECRET` | GitLab API token and default webhook token. |
| `GITLAB_API_BASE_URL` | GitLab REST base URL for self-managed hosts. |
| `BITBUCKET_TOKEN`, `BITBUCKET_WEBHOOK_SECRET` | Bitbucket API token and default signing secret. |
| `BITBUCKET_API_BASE_URL` | Bitbucket Data Center REST base URL. |
| `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | Slack tokens for one agent. Multi-agent servers use `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN`. |

## Exit status

Every command uses these exit codes, and `agent-sdk help --json` lists them
as `exitCodes`.

| Code | Meaning |
| --- | --- |
| `0` | `ok` |
| `1` | `failed`, `aborted`, `invalid_argument`, `rate_limited`, or `unavailable` |
| `2` | `usage`, for a bad command, flag, or argument |
| `3` | `pending`, while the work still runs |
| `4` | `not_found` |
| `5` | `unauthenticated` or `permission_denied` |
| `6` | `conflict` or `failed_precondition` |

## Related

- [Project layout](/docs/reference/project-layout.md)
- [Sessions, events, and streaming](/docs/reference/sessions.md)
- [Deployment](/docs/deployment.md)
- [Early-alpha migration](/docs/guides/migrate.md)
