@cursor/july 0.1.5 → 0.1.7

package/docs/reference/cli.md

@@ -1,68 +1,123 @@
 ---
 title: "CLI"
-description: "Every agentkit command and the flags that matter, from serve and run to the slack and github packs."
+description: "Commands and common flags for local development, running servers, and Cursor-managed hosting."
 ---
 
 # CLI reference
 
-Run the CLI with Node 22.13+. `agentkit help` prints the
-built-in summary, and most commands print their own usage when a
-required argument is missing.
-
-| Command                                                 | Description                                           |
-| ------------------------------------------------------- | ----------------------------------------------------- |
-| [`serve`](#serve)                                       | Serve agents over HTTP (multi-agent by default)       |
-| [`dev`](#dev)                                           | Local development: same as `serve --dev`              |
-| [`chat`](#chat)                                         | Talk to a running server from the terminal            |
-| [`resume`](#resume)                                     | Reattach chat to an existing session id               |
-| [`run`](#run)                                           | One-shot turn on an ephemeral server; JSON trajectory |
-| [`call`](#call)                                         | Call a server tool directly, no model turn            |
-| [`eval`](#eval)                                         | Run filesystem evals                                  |
-| [`trajectory`](#trajectory)                             | Summarize a saved events.ndjson                       |
-| [`init`](#init)                                         | Scaffold a project (or print the setup guide)         |
-| [`info`](#info)                                         | Print the discovered agent surface                    |
-| [`validate`](#validate)                                 | Check the project; non-zero exit on errors            |
-| [`login` / `logout` / `whoami`](#login--logout--whoami) | Manage the host's Cursor credential                   |
-| [`slack …`](#slack)                                     | Slack pack: init, manifests, doctor                   |
-| [`github …`](#github)                                   | GitHub pack: forward, replay, events, doctor          |
-
-The flags shared across commands: `--dir <path>` (project root, default
-`.`), `--json` (machine output where supported), `--url <baseUrl>`
-(target a running server instead of starting one), `--bearer-token`
-(require it on `serve`; send it from `chat`, `run`, `eval`, and `call`),
-and `--state-root <path>` (durable state directory, default
-`<dir>/.agentkit`).
+`@cursor/july` installs `agentkit` and the legacy `agent-serve` alias.
+The examples on this page use `agentkit`. Run the CLI with Node 22.13
+or newer. Don't run it with Bun; Bun corrupts tool-result streams from
+the Cursor SDK.
+
+The current release still uses `.agent-serve` for on-disk state. See the
+[rename table](../README.md#run-the-cli) for identifiers still moving to
+agentkit names.
+
+`agentkit help` prints the built-in summary. The Slack and GitHub packs
+also provide `agentkit slack help` and `agentkit github help`.
+
+| Command                                                 | Description                                                    |
+| ------------------------------------------------------- | -------------------------------------------------------------- |
+| [`serve`](#serve)                                       | Serve agents over HTTP                                         |
+| [`dev`](#dev)                                           | Start local development with `serve --dev`                     |
+| [`chat`](#chat)                                         | Talk to a running agent                                        |
+| [`resume`](#resume)                                     | Reattach chat to a previous session                            |
+| [`logs`](#logs)                                         | Follow local or hosted logs                                    |
+| [`sessions`](#sessions)                                 | List sessions on a running agent                               |
+| [`session`](#session)                                   | Inspect one session                                            |
+| [`playground`](#playground)                             | Open the local or hosted playground                            |
+| [`run`](#run)                                           | Run one or more turns locally, remotely, or on a hosted agent  |
+| [`call`](#call)                                         | Call a server tool without a model turn                        |
+| [`eval`](#eval)                                         | Run filesystem evals                                           |
+| [`trajectory`](#trajectory)                             | Summarize a saved `events.ndjson` file                         |
+| [`init`](#init)                                         | Scaffold a project, or print the setup guide                   |
+| [`info`](#info)                                         | Print the discovered agent surface                             |
+| [`validate`](#validate)                                 | Check a project and fail on errors                             |
+| [`login` / `logout` / `whoami`](#login--logout--whoami) | Manage the host's Cursor credential                            |
+| [`update`](#update)                                     | Upgrade the installed CLI                                      |
+| [`deploy`](#deploy)                                     | Deploy one or more agents to Cursor managed hosting            |
+| [`deployments`](#deployments)                           | List hosted deployments                                        |
+| [`deployment`](#deployment)                             | Inspect one hosted deployment                                  |
+| [`stop`](#stop)                                         | Stop a hosted deployment                                       |
+| [`rotate-token`](#rotate-token)                         | Replace a deployment's alias token                             |
+| [`rotate-pod-credential`](#rotate-pod-credential)       | Replace a deployment's pod credential                          |
+| [`secrets`](#secrets)                                   | Manage deployment secrets                                      |
+| [`slack ...`](#slack)                                   | Set up and check Slack channels                                |
+| [`github ...`](#github)                                 | Forward, replay, and inspect GitHub webhook channels           |
+
+## Choose a target
+
+Request-sending commands support three target types.
+
+| Target | How to select it | Commands |
+| --- | --- | --- |
+| Ephemeral local server | Omit `--url` and `--prod` | `run`, `call`, `eval` |
+| Running server | Pass `--url <baseUrl>`, unless the command uses the localhost default described next | `chat`, `resume`, `logs`, `sessions`, `session`, `playground`, `run`, `call`, `eval` |
+| Cursor managed hosting | Pass `--prod` | `chat`, `resume`, `logs`, `sessions`, `session`, `playground`, `run`, `call`, `eval` |
+
+`chat`, `logs`, `sessions`, `session`, and `playground` default to
+`http://127.0.0.1:3000`. A `--url` must include the agent slug for a
+multi-agent server, such as `http://127.0.0.1:3000/pr-approver`.
+`--slug` doesn't change an explicit URL.
+
+With `--prod`, `--slug` selects the deployment and `--team` selects the
+Cursor team. The slug defaults to the `--dir` basename. The team
+defaults to the signed-in account's team. `--url` and `--prod` are
+mutually exclusive.
+
+Use `--bearer-token <token>` when a running server requires bearer
+authentication. Hosted commands use your Cursor credential to request
+short-lived engine access. `--api-key` overrides the Cursor credential
+for `login`, `serve`, hosted targets, and managed-hosting commands.
+`--state-root` applies to `serve` and ephemeral `run`, `call`, and
+`eval` servers. Running and hosted targets ignore it.
+
+For ephemeral `run`, `call`, and `eval` commands, omitting `--slug`
+selects an unslugged root mount when one exists. Otherwise, agentkit
+selects the first discovered agent.
 
 ## serve
 
-`serve` hosts every agent under a directory, multi-agent by default.
+`serve` hosts every agent under `--dir` in multi-agent mode by default.
 
 ```bash
 agentkit serve [--dir <path>] [--port 3000] [--host 127.0.0.1] [--dev]
                   [--mode multi|single] [--api-key <key>]
                   [--state-root <path>] [--bearer-token <secret> | --allow-anonymous]
+                  [--allow-anonymous-cursor-github]
                   [--public-url <url>] [--no-schedules] [--no-playground]
-                  [--no-docs] [--cursor-events --repo owner/name]
+                  [--no-docs] [--cursor-events --repo owner/name]...
 ```
 
-Serves every agent under `--dir`. A directory that is itself an agent
-project mounts under its directory name; a directory of projects mounts
-each child. The index lives at `/`, each agent at `/<slug>/v1/*` and
-`/<slug>/playground`. On a TTY, press Enter to restart; it reloads
-agent code.
-
-| Flag                | Meaning                                                                                                                                                                                                                                    |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `--dev`             | Dev mode. Schedules and reminders never auto-fire (dispatch through `/v1/dev/...`), the playground session list widens (loopback), GitHub channels accept unsigned loopback deliveries, and Vite HMR starts when the toolchain is present. |
-| `--mode`            | `multi` (default: slugged routes plus an index) or `single` (one agent at the unslugged `/v1/*`).                                                                                                                                          |
-| `--api-key`         | Cursor API key. Falls back to `CURSOR_API_KEY`, then the stored `login` credential.                                                                                                                                                        |
-| `--bearer-token`    | Require this bearer token on API routes; replaces the loopback-only default on channels without authored auth. Mutually exclusive with `--allow-anonymous`.                                                                                |
-| `--allow-anonymous` | Admit every HTTP caller as one `anonymous` principal. Trusted networks only.                                                                                                                                                               |
-| `--public-url`      | The base URL where this host is reachable from outside. Required for peer MCP connections on cloud-runtime turns.                                                                                                                          |
-| `--no-schedules`    | Disable the cron runner outside dev mode.                                                                                                                                                                                                  |
-| `--no-playground`   | Skip the web playground (and its auto-build / HMR).                                                                                                                                                                                        |
-| `--no-docs`         | Skip the documentation site at `/docs` (and its auto-build).                                                                                                                                                                               |
-| `--cursor-events`   | Pull SCM webhook events from Cursor's `/v0/scm-events` instead of receiving webhooks. Requires a signed-in host and `--repo` (repeatable). Offset state lives under `<state-root>/cursor-events/`.                                         |
+If `--dir` is an agent project, it mounts under its directory name. If
+it contains agent projects, each child mounts separately. The index
+lives at `/`. Each agent is available at `/<slug>/v1/*` and
+`/<slug>/playground`. On a TTY, press Enter to reload agent code.
+Unless `--state-root` is set, each mount uses
+`<agent-project>/.agent-serve`; slugged mounts use
+`<agent-project>/.agent-serve/<slug>`.
+
+| Flag | Meaning |
+| --- | --- |
+| `--port` | Listen on this port. `0` selects an available port. The default is `3000`. |
+| `--host` | Bind this host. The default is loopback-only `127.0.0.1`. |
+| `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, widen playground session access on loopback, and start Vite HMR when available. |
+| `--mode` | Use `multi` for slugged routes and an index, or `single` for one agent at the unslugged `/v1/*`. The default is `multi`. |
+| `--api-key` | Use this Cursor API key. The command falls back to `CURSOR_API_KEY`, then the stored login. |
+| `--state-root` | Store sessions, streams, workspaces, and channel state here. Keep durable production state outside the agent repository. |
+| `--bearer-token` | Require this bearer token on routes without authored auth. Mutually exclusive with `--allow-anonymous`. |
+| `--allow-anonymous` | Admit every caller as one `anonymous` principal. Use only behind a trusted network boundary. |
+| `--allow-anonymous-cursor-github` | Allow anonymous callers to drive sessions holding a Cursor account's repo-scoped GitHub credential. Use only behind an authenticating proxy. |
+| `--public-url` | Set the externally reachable host URL. Cloud-runtime peer connections need it to call back into this server. |
+| `--no-schedules` | Disable the cron runner outside dev mode. |
+| `--no-playground` | Skip the web playground and its build or HMR process. |
+| `--no-docs` | Skip the documentation site at `/docs` and its build. |
+| `--cursor-events` | Pull SCM events from Cursor's `/v0/scm-events` in addition to authored webhook routes. Requires a signed-in host. Pass repeatable `--repo owner/name` values; repos declared by `githubChannel({ cursorAccount })` also enable the relay. State lives under `<state-root>/cursor-events/`. |
+
+Multi-agent slugs must start with a letter or digit, then contain only
+letters, digits, `_`, or `-`. The reserved slugs are `v1`, `playground`,
+and `docs`.
 
 ## dev
 
@@ -75,69 +130,154 @@ agentkit dev ./pr-approver
 agentkit dev ./pr-approver --port 3000
 ```
 
-Same flags as [`serve`](#serve) (`--dir` still works if you prefer it).
+`dev` accepts the same flags as [`serve`](#serve). You can use `--dir`
+instead of the positional path.
 Dev mode is always on: schedules and reminders wait for manual dispatch,
 GitHub accepts unsigned loopback deliveries, and Vite HMR starts when
 the toolchain is present. Prefer this over `serve --dev` while
-iterating.
+iterating. Pass at most one positional path. Don't combine a positional
+path with a different `--dir`.
 
 ## chat
 
-`chat` talks to a running server from the terminal.
+`chat` talks to a running agent from the terminal. It never starts a
+server.
 
 ```bash
-agentkit chat --url http://127.0.0.1:3000/<slug>            # interactive REPL
-agentkit chat --url … --message "Is the PR ready to approve?"       # one-shot
-agentkit chat --url … --message "hello" --json              # JSON trajectory
-agentkit chat --url https://host --bearer-token "$TOKEN"    # authed server
+agentkit chat --url http://127.0.0.1:3000/pr-approver
+agentkit chat --message "Is the PR ready to approve?"
+agentkit chat --message "Inspect PR 42" --json
+agentkit chat --prod --slug pr-approver --team 123
 ```
 
-Streams the reply live: text, tool calls, and a per-turn usage footer.
-`--json` requires `--message` and prints
+`chat` streams text, tool calls, and a per-turn usage footer.
+On a TTY, `--message` seeds the interactive REPL. With non-TTY input,
+`--message` runs one turn and exits; without it, `chat` reads
+newline-delimited messages until EOF. `--json` requires `--message`,
+runs one turn, and prints
 `{ ok, sessionId, continuationToken, trajectory }`. `--text` prints a
-compact dump, and `--no-color` forces plain output.
+compact trajectory when combined with `--json`. `--no-color` forces
+plain interactive output.
+
+Use `--session <id>` to reattach a stored session. The command looks up
+its continuation token when you omit `--continuation-token`. Use
+`--resume` to select the most recently updated session with a
+continuation token.
 
 ## resume
 
-`resume` reattaches the chat REPL to an existing session.
+`resume` is the direct way to reattach the chat REPL.
+
+```bash
+agentkit resume ses_123 --url http://127.0.0.1:3000/pr-approver
+agentkit resume --url http://127.0.0.1:3000/pr-approver
+agentkit resume ses_123 --prod --team 123 --slug pr-approver
+agentkit resume ses_123 --message "Continue the review" --json
+```
+
+Pass a session ID to select it. Omit the ID to select the most recently
+updated followable session from `/v1/sessions`. The command looks up a
+missing continuation token, replays the transcript, and accepts
+follow-ups. `resume --json` requires `--message`. The same operation is
+available as `chat --session <id>` or `chat --resume`.
+
+## logs
+
+`logs` follows the local or hosted log buffer.
+
+```bash
+agentkit logs [--url http://127.0.0.1:3000] [--once] [--json]
+agentkit logs --prod [--slug <slug>] [--team <id>] [--once] [--json]
+```
+
+Local mode reads `/v1/logs` from the running server. Hosted mode reports
+deploy progress until the deployment is running or degraded, then
+follows reachable runtime logs.
+The command follows until Ctrl-C by default. `--once` prints the current
+buffer and exits. `--json` emits newline-delimited JSON events.
+
+## sessions
+
+`sessions` lists sessions on a running or hosted agent.
 
 ```bash
-agentkit resume ses_… --url http://127.0.0.1:3000/<slug>
-agentkit resume ses_… --prod --team 1 --slug approval-buddy
-agentkit resume ses_… --prod --message "continue from here"
+agentkit sessions [--url <baseUrl> | --prod] [--slug <slug>]
+                  [--team <id>] [--bearer-token <token>] [--json]
 ```
 
-Same as `chat --session <id>`: looks up the continuation token via
-`/v1/sessions` when `--continuation-token` is omitted, replays the
-transcript, then accepts follow-ups. Accepts the same output flags as
-[`chat`](#chat) (`--json`, `--text`, `--no-color`).
+Text output shows session ID, channel, mode, turn count, running status,
+and update time. `--json` prints full session summaries in
+`{ sessions }`, including continuation tokens.
+
+## session
+
+`session` inspects the event stream for one session.
+
+```bash
+agentkit session <sessionId> [--url <baseUrl> | --prod]
+                 [--slug <slug>] [--team <id>]
+                 [--json | --text | --events]
+```
+
+By default, `session` prints a compact trajectory. `--text` selects the
+same format. `--json` prints the trajectory object. `--events` prints
+`{ sessionId, events }` with the raw event list. You can't combine
+`--events` and `--json`. Use
+[`resume`](#resume) to continue the conversation.
+
+## playground
+
+`playground` opens an agent's web playground.
+
+```bash
+agentkit playground [--url <baseUrl> | --prod] [--session <id>]
+                    [--slug <slug>] [--team <id>]
+                    [--bearer-token <token>] [--print]
+```
+
+`--session` opens a deep link to one session. `--print` prints the URL
+without opening a browser.
+
+For an unauthenticated local URL, `playground` opens the browser and
+exits. `--prod` and `--bearer-token` start a loopback proxy to inject
+browser-inaccessible credentials. The proxy stays open until Ctrl-C,
+including when you pass `--print`.
 
 ## run
 
-`run` executes one turn on an ephemeral server and prints a JSON trajectory.
+`run` sends one or more turns and prints a JSON result.
 
 ```bash
 agentkit run --dir . --message "Is https://github.com/acme/checkout/pull/42 ready?"
-agentkit run --dir . --message "first" --message "then this"   # multi-turn
-agentkit run --url http://127.0.0.1:3000/<slug> --message "…"  # running server
-agentkit run --dir . --message "…" --events /tmp/run.ndjson    # custom trace path
+agentkit run --dir . --message "Inspect PR 42" --message "Summarize the risks"
+agentkit run --url http://127.0.0.1:3000/pr-approver --message "Inspect PR 42"
+agentkit run --prod --slug pr-approver --team 123 --message "Inspect PR 42"
+agentkit run --dir . --messages-file ./prompts.json
 ```
 
-The create-and-test loop in one command: start an ephemeral server
-(port 0, temp state root outside the project), send the message(s), print a
-JSON trajectory, and write an NDJSON trace (default
-`<dir>/.agentkit/traces/<sessionId>.ndjson`). Progress streams to
-stderr on a TTY.
-
-| Flag                                 | Meaning                                                                                       |
-| ------------------------------------ | --------------------------------------------------------------------------------------------- |
-| `--message`                          | The user message; repeatable for multi-turn. `--messages-file` takes a JSON array of strings. |
-| `--session` / `--continuation-token` | Follow up an existing session on a running server.                                            |
-| `--events <file>` / `--no-events`    | Override the trace path, or skip the trace.                                                   |
-| `--text`                             | Compact text output instead of JSON.                                                          |
-| `--timeout-ms`                       | Abort a hung turn.                                                                            |
-| `--no-stream`                        | Silence live progress on stderr.                                                              |
-| `--slug`                             | Pick one agent when `--dir` mounts several.                                                   |
+Without `--url` or `--prod`, the command starts an ephemeral server on
+an available port. Its state root is a temporary directory outside the
+project unless you pass `--state-root`. The command closes the server
+after the turns finish.
+
+| Flag | Meaning |
+| --- | --- |
+| `--message <text>` | Send a user message. Repeat the flag for a multi-turn run. |
+| `--messages-file <path>` | Read a JSON array of strings. File messages run before repeated `--message` values. |
+| `--session <id>` | Follow up an existing session. Unlike `chat`, `run` doesn't look up a missing continuation token. |
+| `--continuation-token <token>` | Continue the existing session selected by `--session`. |
+| `--events <file>` | Write the raw NDJSON event stream to this path. |
+| `--no-events` | Don't write an event stream. |
+| `--text` | Print a compact trajectory instead of the JSON result. |
+| `--timeout-ms <n>` | Abort the turn after a positive number of milliseconds. There is no default timeout. |
+| `--no-stream` | Hide live tool and reply progress on stderr. Progress is on by default when stderr is a TTY. |
+| `--slug <slug>` | Pick one agent when local discovery mounts several agents. With `--prod`, select the hosted deployment. |
+
+The default trace path is
+`<dir>/.agent-serve/traces/<sessionId>.ndjson`. JSON output contains
+`ok`, `sessionId`, `continuationToken`, `trace`, `playgroundUrl`,
+`playgroundHint`, `visualize`, and `trajectory`. The command exits
+non-zero when the trajectory fails.
 
 ## call
 
@@ -146,14 +286,24 @@ stderr on a TTY.
 ```bash
 agentkit call inspect_pr --dir . \
   --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
-agentkit call inspect_pr --url http://127.0.0.1:3000/<slug> --input '{…}'
-agentkit call inspect_pr --dir . --input '{…}' --session ses_…
+agentkit call inspect_pr --url http://127.0.0.1:3000/pr-approver \
+  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
+agentkit call refresh_cache --url http://127.0.0.1:3000/pr-approver \
+  --session ses_123
+agentkit call inspect_pr --prod --slug pr-approver --team 123 --input '{}'
 ```
 
-Deterministic server-tool invocation through `POST /v1/tools/:toolName`:
-schema-validated, in-process, no model turn, no API key. `--session`
-runs it inside an existing session and records it on that session's
-stream (serializing with model turns). See
+`call` sends `POST /v1/tools/:toolName` and runs the tool in the serving
+process without a model turn. `--input` accepts any valid JSON and
+defaults to `{}`. Tools with a Zod input schema validate and transform
+the value before execution. A local call needs no inference credential.
+A hosted call still needs Cursor credentials to reach the deployment.
+
+`--session` runs the tool inside an existing session and records it on
+the event stream. If a model turn is active or pending, the server
+returns `session_busy`; retry after the turn finishes. The command
+prints the server's JSON response and exits non-zero unless the HTTP
+response succeeds with `ok: true`. See
 [Tools](./tools.md#call-a-tool-without-a-model-turn).
 
 ## eval
@@ -168,11 +318,22 @@ agentkit eval --dir . builds          # every datapoint in the file
 agentkit eval --dir . --tag smoke     # by tag (repeatable)
 agentkit eval --dir . --json          # machine-readable results
 agentkit eval --dir . --verbose       # stream t.log lines + reply snippets
+agentkit eval --prod --slug pr-approver --team 123
 ```
 
-Runs `evals/**/*.eval.{ts,js}` on an ephemeral server, or against `--url`.
-Select by exact case id, file id (a prefix), several of either, tags, or
-nothing for all. See [Evals](../evals.md).
+`eval` runs `evals/**/*.eval.{ts,js}` on an ephemeral server or against
+`--url`. Select one or more exact case IDs, file ID prefixes, or tags.
+Omit selectors to run all cases. Repeated `--tag` flags use OR matching.
+
+An eval run requires `evals/evals.config.{ts,js}` with `maxConcurrency`
+between 1 and 200. Timeout priority is the case's `timeoutMs`, the CLI's
+`--timeout-ms`, the config's `timeoutMs`, then 180 seconds. Use
+`--no-stream` to hide live progress or `--verbose` to include `t.log`
+lines and reply snippets.
+
+`--list --json` prints an array of discovered cases. A run with `--json`
+prints `{ ok, passed, failed, results }`. Failed cases exit `1`; no
+matching cases exit `2`. See [Evals](../evals.md).
 
 ## trajectory
 
@@ -182,8 +343,9 @@ nothing for all. See [Evals](../evals.md).
 agentkit trajectory --events /tmp/run.ndjson [--text]
 ```
 
-Turns any saved NDJSON event stream into the same trajectory JSON `run`
-prints.
+`trajectory` converts a saved NDJSON stream into the trajectory JSON
+returned by `run`. `--text` prints the compact view. The command exits
+non-zero when the reconstructed trajectory failed.
 
 ## init
 
@@ -195,18 +357,21 @@ agentkit init ./my-agent --json   # machine-readable summary for tooling
 agentkit init                     # no directory: print the setup guide
 ```
 
-The scaffold summary lists each file as `create` or `exist` (existing
-files are left alone) and the project folder path, then runs
-`npm install` so `@cursor/july` resolves for `dev` / `run`. On a TTY,
-on a TTY, `init` asks before installing (or updating) the package
-coding-agent skills into `~/.cursor/skills/agentkit/`, always overwriting
-with the version from the installed package (skipped for `--json` /
-non-interactive hosts). When the host has no Cursor credential yet,
-`init` runs `agentkit login` and waits for the browser sign-in to
-finish, then prints next steps: `cd` into the project (when needed),
-`agentkit login` (when still unsigned), and `agentkit dev`. `--json`
-still installs dependencies but never blocks on login or skill install;
-it prints
+`init` leaves existing files unchanged and labels each one `create` or
+`exist`. It prints the project path, then runs `npm install` so
+`@cursor/july` resolves for `dev` and `run`.
+
+On a TTY, `init` asks whether to install or update the coding-agent
+skills in `~/.cursor/skills/agentkit/`. If accepted, it overwrites them
+with the version bundled in the installed package. The prompt is skipped
+for `--json` and non-interactive hosts.
+
+If the host isn't signed in, `init` runs `agentkit login` and waits for
+the browser flow. It then prints the `cd`, `agentkit login`, and
+`agentkit dev` steps still needed.
+
+With `--json`, `init` still installs dependencies but never blocks on
+login or skill installation. It prints
 `{ ok, directory, created, skipped, installed, installError, next }`
 (with `login` in `next` when unsigned).
 
@@ -218,10 +383,12 @@ it prints
 agentkit info --dir . [--json]
 ```
 
-The discovered surface: model, instructions size, tools, skills, MCP
-connections, subagents, channels and their routes, schedules, hooks, and
-diagnostics. `--json` matches `GET /v1/info`; with multiple agents it
-prints one entry per slug.
+`info` reports the model, instruction size, tools, skills, MCP
+connections, subagents, channel routes, schedules, hooks, and
+diagnostics. Text output summarizes each mounted agent. `--json` prints
+`{ agents: [{ slug, ...projectInfo }] }`, with one entry per mounted
+slug. Use `validate`, not `info --json`, when a script needs an error
+exit status.
 
 ## validate
 
@@ -231,10 +398,9 @@ prints one entry per slug.
 agentkit validate --dir .
 ```
 
-Prints diagnostics per agent and exits non-zero when any has
-error-severity diagnostics (`serve` refuses to start in that state).
-Warnings (cloud runtime combined with local-only capabilities, say) print
-without failing it.
+`validate` prints diagnostics for each agent and exits non-zero when any
+diagnostic has error severity. `serve` also refuses to start when errors
+are present. Warnings don't change the exit status.
 
 ## login / logout / whoami
 
@@ -248,58 +414,291 @@ agentkit logout
 
 `login` 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 `agentkit (<hostname>)`). It powers inference, the cloud
-runtime, and Cursor account MCP connections. `whoami` shows which credential
-is active and why: explicit flag, then `CURSOR_API_KEY`, then the
-stored login. `logout` removes the stored key.
+name is `<invoked command> (<hostname>)`). It powers inference, the cloud
+runtime, and Cursor account MCP connections. `--key-name` changes the
+name of a browser-minted key. `login --api-key` validates and stores a
+key you already created.
+
+`whoami` shows which credential is active and why. `CURSOR_API_KEY`
+takes precedence over the stored login. `logout` removes the local
+credential file but doesn't revoke the API key. Revoke it in the Cursor
+dashboard when it should stop working.
 
 Non-production backends: login and account RPCs honor
 `CURSOR_API_BASE_URL` while the SDK harness honors `CURSOR_BACKEND_URL`.
 Set both to the same URL, or keys minted on one backend are rejected by
 the other.
 
+## update
+
+`update` upgrades an installed copy to the latest published version.
+
+```bash
+agentkit update
+```
+
+The command checks npm's `latest` tag, detects how agentkit was installed,
+and runs the matching npm, pnpm, Yarn, or Bun upgrade command. It handles
+global installs and project dependencies. It doesn't prompt before
+running the package-manager command.
+
+Source checkouts, `npx` or `pnpm dlx` caches, and unknown install layouts
+aren't changed. The command prints a manual upgrade hint instead.
+
+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 `--json` flag skip this automatic check.
+
+## deploy
+
+`deploy` sends one or more agents to Cursor managed hosting.
+
+```bash
+agentkit deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
+                [--repo <https-url>] [--ref <git-ref>] [--path <agent-path>]
+                [--cursor-events-repo owner/name]...
+                [--allow-domain <domain>]... [--no-wait] [--json]
+```
+
+Managed hosting requires team-admin permission and the team's
+cloud-agent entitlement. `--team` defaults to the signed-in account's
+team.
+
+For a single project, the slug defaults to a normalized version of the
+directory name. Deployment slugs contain lowercase letters, digits, `_`,
+or `-`, with a maximum of 64 characters. For a directory with several
+agents, select one with `--slug`, deploy all with `--all`, or choose from
+the TTY prompt. Non-interactive callers must pass `--slug` or `--all`.
+If `--dir` contains no agent project or child agents, `deploy` creates a
+static placeholder using `--slug` or a slug derived from the directory
+name. In this case, `--all` fails.
+
+The command infers `--repo`, `--ref`, and `--path` from the current Git
+checkout when possible. Explicit flags take precedence. `--repo` must
+use HTTPS. Repeat `--cursor-events-repo` to select SCM event sources.
+Repeat `--allow-domain` to add engine egress domains; these values are
+combined with `hosting.egressDomains` 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 `*.` wildcard is allowed. A deployment
+can declare at most 20 domains.
+
+By default, the command polls every three seconds for up to ten minutes
+and succeeds only when the deployment reaches `running`. `--no-wait`
+returns after the deployment request is accepted. Multi-agent deploys
+run sequentially. When several agents are selected, `--path` is ignored
+and each project infers its own path. A single-target `--json` run
+prints one object; a multi-target run prints an array.
+
+The first deployment can return an alias token. It appears once in text
+or JSON output and can't be retrieved later. Store it as a secret. Send
+it as `X-Agent-Alias-Token` when calling the stable alias URL, or use it
+to sign in to the hosted playground.
+
+See [Deployment](../deployment.md) for the hosting security model and
+state layout.
+
+## deployments
+
+`deployments` lists the selected team's deployments.
+
+```bash
+agentkit deployments [--team <id>] [--json]
+```
+
+Text output shows each slug, status, generation, deployment kind, and
+update time. `--json` prints `{ deployments }`.
+
+## deployment
+
+`deployment` prints the full status of one deployment.
+
+```bash
+agentkit deployment <slug> [--team <id>] [--json]
+```
+
+Text output includes status, generation, kind, alias, source, egress
+domains, secret names, engine state, and the last error when present.
+`--json` returns the full API response. It can include short-lived
+`engineAccess.headers`, so handle JSON output as a credential.
+
+## stop
+
+`stop` shuts down a deployment.
+
+```bash
+agentkit stop <slug> [--team <id>] [--no-wait] [--json]
+```
+
+The command polls for up to ten minutes until the status reaches
+`stopped`. `--no-wait` returns after the stop request is accepted.
+
+## rotate-token
+
+`rotate-token` replaces the alias token used by callers and the hosted
+playground.
+
+```bash
+agentkit rotate-token <slug> [--team <id>] [--json]
+```
+
+The old token stops working immediately. The replacement is shown once.
+`--json` prints `{ aliasToken }`.
+
+## rotate-pod-credential
+
+`rotate-pod-credential` replaces the credential used by the running
+engine pod.
+
+```bash
+agentkit rotate-pod-credential <slug> [--team <id>] [--json]
+```
+
+The command returns only the masked key and revokes the old credential
+immediately. Redeploy at once to inject the replacement; the current
+pod can't authenticate to Cursor in between.
+
+## secrets
+
+`secrets` manages environment secrets for a deployment.
+
+```bash
+agentkit secrets set <slug> NAME[=VALUE]... [--team <id>] [--json]
+agentkit secrets list <slug> [--team <id>] [--json]
+agentkit secrets unset <slug> NAME [--team <id>] [--json]
+```
+
+Omit `=VALUE` from `secrets set` to enter the value at a hidden TTY
+prompt. With piped stdin, provide one line for each missing value. Avoid
+values in command arguments because shells can record them in history.
+
+Secret names use `UPPER_SNAKE_CASE`, start with a letter, and contain at
+most 64 characters. Names beginning with `CURSOR_` are reserved. Values
+can contain at most 4096 bytes, and one deployment can hold 32 secrets.
+
+`secrets list` returns names and creation times, never values. Secret
+changes reach the engine on its next deploy. `secrets set` upserts the
+named secrets without deleting others.
+
+JSON output is `{ secretNames }` for `set`, `{ secrets }` for `list`,
+and `{ removed }` for `unset`.
+
 ## slack
 
-The `slack` subcommands generate and verify the Slack side of a channel.
+The `slack` pack generates and checks Socket Mode channel setup.
 
 ```bash
-agentkit slack setup                              # guided checklist
-agentkit slack init --dir . --name "My Agent"     # channel + manifests + env.example
-agentkit slack init --dir . --no-prefix           # shared SLACK_* vars
-agentkit slack init --dir . --channel-posts       # + message.channels/groups events
-agentkit slack manifest --env dev|prod|both       # regenerate manifests
-agentkit slack doctor --prefix MY_AGENT           # token / connectivity checks
+agentkit slack setup
+agentkit slack init [--dir <path>] [--name <name>]
+                    [--prefix <prefix> | --no-prefix] [--channel-posts]
+agentkit slack manifest [--dir <path>] [--name <name>]
+                        [--env dev|prod|both] [--channel-posts] [--print]
+agentkit slack doctor [--prefix <prefix>] [--json]
 ```
 
+`slack setup` prints a guided checklist and doesn't change files.
+
+`slack init` creates the channel file, development and production
+manifests, `env.example`, and setup status under the project. It refuses
+to overwrite a target file. If a collision occurs, it exits non-zero;
+files created earlier in the run remain. The token prefix defaults to
+the directory basename normalized to uppercase snake case. Explicit
+`--prefix` values use the same normalization when agentkit builds token
+variable names. For example, `pr-approver` becomes
+`PR_APPROVER_SLACK_BOT_TOKEN`. `--no-prefix` uses shared
+`SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`. `--channel-posts` subscribes
+the manifests to channel-post events. The command always prints a JSON
+summary.
+
+`slack manifest` regenerates selected manifest files. `--env` defaults
+to `both`, and `--name` defaults to the directory name. `--print` writes
+the manifest JSON to stdout instead of changing files. With the default
+`--env both`, it prints development JSON, a `--- prod ---` separator,
+then production JSON.
+
+`slack doctor` checks both tokens, Socket Mode connectivity, and
+Slack's `auth.test`. It exits non-zero when any check fails.
+
 See the [Slack guide](../guides/slack.md).
 
 ## github
 
-The `github` subcommands test webhook channels against real repositories.
+The `github` pack discovers `githubChannel()` definitions and sends live
+or synthesized deliveries to them.
 
 ```bash
-agentkit github doctor [--install]                # gh + cli/gh-webhook extension
-agentkit github events --dir . [--json]           # per-agent URL + event list
-agentkit github forward --dir . [--repo owner/repo | --org ORG]
+agentkit github doctor [--install] [--json]
+agentkit github events [--dir <path>] [--host <host>] [--port <n>] [--json]
+agentkit 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]
 agentkit github replay <pr-url|owner/repo#N> --dir .
-    [--events a,b,c|'*'] [--action …] [--conclusion …] [--comment …]
-    [--context …] [--secret …] [--dry-run] [--out DIR]
+    [--events a,b,c|'*'] [--action <action>] [--conclusion <result>]
+    [--comment <body>] [--context <name>] [--slug <slug>] [--channel <id>]
+    [--host <host>] [--port <n>] [--url <url>] [--secret <secret>]
+    [--dry-run] [--out <dir>] [--json]
 ```
 
-`forward` wraps `gh webhook forward`: repo admin required, and blank
-any env `GITHUB_TOKEN` / `GH_TOKEN` or deliveries 401. `replay`
-synthesizes GitHub-shaped payloads from read access only, the
-deterministic tier. `--slug` and `--channel` target one agent among
-several. See the [GitHub guide](../guides/github.md).
+`github events` prints each discovered channel's delivery URL and event
+set. When it finds no channels, it returns an empty result and exits
+successfully.
+
+`github forward` wraps `gh webhook forward`. It infers the repository
+from the Git remote when you omit `--repo` and `--org`. URLs and events
+come from the discovered channels; `--events` overrides the event set.
+Use `--slug` or `--channel` to narrow discovery when several channels
+match. Otherwise, one local proxy fans deliveries out to every match.
+`--url` targets one channel. For `forward`, pass `--events` when no
+matched channel can supply the event set.
+
+Repository forwarding needs repo-admin access. Organization forwarding
+needs org-owner access. The relay authenticates with the GitHub CLI's
+stored login. A `GITHUB_TOKEN` or `GH_TOKEN` environment override can
+make delivery requests return `401`, even when hook creation succeeds.
+Unset those variables before forwarding.
+
+Pass `--secret` or set `GITHUB_WEBHOOK_SECRET` to sign deliveries.
+`serve --dev` accepts unsigned loopback deliveries. A non-dev target
+requires the same secret on both sides.
+
+`github replay` needs read access, not admin access. It reads the pull
+request through `gh api`, builds GitHub webhook payloads, and posts them
+to the selected channels. Supported events are `pull_request`,
+`issue_comment`, `pull_request_review_comment`, `check_run`,
+`check_suite`, `workflow_run`, and `status`. The default is
+`pull_request` with action `synchronize`. Comment events need
+`--comment`.
+
+Use `--events '*'` to replay every supported event declared by the
+channel. `--dry-run` prints payloads without posting them. `--out`
+writes fixture files but still posts unless you also pass `--dry-run`.
+
+`github doctor` checks `gh`, its login, and the pinned
+`cli/gh-webhook` extension. `--install` installs or repairs the
+extension. An environment-token override is a warning and doesn't make
+`github doctor` fail.
+
+See the [GitHub guide](../guides/github.md).
 
 ## Environment variables
 
-These are the most common environment variables the CLI and the
-channel packs read.
-
-| Variable                                                                  | Meaning                                                                      |
-| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `CURSOR_API_KEY`                                                          | The Cursor credential, checked after `--api-key` and before the stored login |
-| `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` / `GITHUB_APP_INSTALLATION_ID` | GitHub App auth for outbound API calls                                       |
-| `GITHUB_TOKEN` / `GH_TOKEN`                                               | Token auth for outbound API calls; must be blank for `github forward`        |
-| `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN`                                     | Slack tokens (single-agent); `<PREFIX>_SLACK_*` per agent otherwise          |
+These environment variables affect the CLI and its channel packs.
+
+| Variable | Meaning |
+| --- | --- |
+| `CURSOR_API_KEY` | Cursor credential. It takes precedence over the stored login. |
+| `CURSOR_API_BASE_URL` | Backend used by login, account, deployment, and event-relay RPCs in non-production environments. |
+| `CURSOR_BACKEND_URL` | Backend used by the Cursor SDK harness in non-production environments. |
+| `AGENT_SERVE_CONFIG_DIR` | Directory for stored credentials and update-check state. The default is `~/.config/agent-serve`. |
+| `AGENT_SERVE_NO_UPDATE_CHECK` / `NO_UPDATE_NOTIFIER` | Disable the automatic published-version check when set to a non-empty value other than `0`. |
+| `CI` | Disable the automatic published-version check when set. |
+| `GITHUB_WEBHOOK_SECRET` | Default signing secret for GitHub forwarding and replay. |
+| `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` / `GITHUB_APP_INSTALLATION_ID` | GitHub App authentication for outbound API calls. |
+| `GITHUB_TOKEN` / `GH_TOKEN` | Token authentication for outbound API calls. Unset both for `github forward`. |
+| `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` | Slack tokens for one agent. Use `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` for each agent on a multi-agent host. |
+
+## What's next
+
+- [Project layout](./project-layout.md): files the CLI discovers
+- [HTTP API](./http-api.md): routes used by `chat`, `call`, and other clients
+- [Deployment](../deployment.md): production auth, state, and operations