@wular/coder 0.4.11 → 0.4.13

package/docs/agents/index.md

@@ -1,6 +1,6 @@
 # Agents
 
-An agent is a reusable teammate. Its `system.md` holds the standing instructions every task starts from: who it is, what it knows, how it answers. Its definition adds engine, model, effort and permissions defaults, the MCP servers it attaches and the [flows](../flows.md) it may run. Run it from the CLI with `coder task run --agent <id> "…"`, where flags override the defaults, from the [dashboard](../dash.md), or from platform events like a Slack DM or a GitHub pull request. [Prompt](prompt.md) shows everything its engine gets, per task kind.
+An agent is a reusable teammate. Its `system.md` holds the standing instructions every task starts from: who it is, what it knows, how it answers. Its definition adds engine, model, effort and permissions defaults, the MCP servers it attaches and the [flows](../flows.md) it may run. Run it from the CLI with `coder task run --agent <id> "…"`, where flags override the defaults, from the [dashboard](../dash.md), or from platform events like a Slack DM or a GitHub pull request.
 
 Connected to a platform, an agent listens for the events it names. Each event runs as a task with the agent's instructions, the event as its request, and the platform tools of every installation of the agent's apps; a GitHub event also checks out its repository, and any task can clone the agent's GitHub repositories. The reply goes back to the thread. Later messages in that conversation, from anyone, steer its task while it runs and resume it once it has finished. A bigger task can run a flow instead, with the event as its `args`.
 
@@ -8,7 +8,7 @@ On each platform an agent is its own app, a GitHub App or a Slack app for exampl
 
 ## Connections
 
-A connection gives tasks access to an MCP service, your own account on an integration, or an API key passed as one environment variable, such as `GROQ_API_KEY`. Add one under Settings → Connections or with `coder connection add`; an API key is kept as a credential, so rotating the credential rotates the connection. Tasks started by members receive workspace connections and that member’s own connections, narrowed by the agent’s Connections setting and `coder task run --connections`; outsider events receive none. A connection's access is Default, which follows the agent's, Read-only or Read-write.
+A connection gives tasks access to an MCP service, your own account on an integration, or an API key passed as one environment variable, such as `GROQ_API_KEY`. Add one under Settings → Connections or with `coder connection add`; an API key is kept as a credential, so rotating the credential rotates the connection. Tasks started by members receive workspace connections and that member’s own connections, narrowed by the agent’s Connections setting and `coder task run --connections`; outsider events receive none. A connection's access is Default, which follows the agent's, Read-only or Read-write. Read-only gives the engine only the tools the server marks read-only.
 
 ## Built-in agent
 
@@ -51,7 +51,7 @@ From there:
 2. On the dashboard, the agent's Platforms tab creates its app on each platform it uses and installs it; the app's credentials go straight to the server. An app is private, installable only by its owner, or public where the platform allows it (GitHub, Linear), installable by any account. An install started on the platform signs the installer in to Coder and binds to the app's workspace when they are a member.
 3. Events now reach the server, a task runs on its runner, and the reply is posted back. `coder agent run helper <event.json> --server --wait` fires one by hand; without `--server` it runs offline, platform tools off, reply printed. `--server` means `CODER_SERVER`, else the hosted service; give it a URL to pick another.
 
-Only pushes to the agents repo's configured branch are imported. An app created before push events existed needs the `push` event enabled once in its GitHub App settings.
+Only pushes to the agents repo's configured branch are imported, and each changed definition becomes a new version. An app created before push events existed needs the `push` event enabled once in its GitHub App settings.
 
 ### Definition
 
@@ -61,13 +61,11 @@ Only pushes to the agents repo's configured branch are imported. An app created
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `name`, `description`       | Text                                                                                                                                                                                                    | App name and handle; the description is added to the prompt                                                                                                                                                                |
 | `engine`, `model`, `effort` | As in `coder task run`                                                                                                                                                                                  | Engine defaults                                                                                                                                                                                                            |
-| `permissions`               | `read-only` (default), `workspace-write`, `auto`                                                                                                                                                        | Agent sandbox mode inside the checkout                                                                                                                                                                                     |
+| `permissions`               | `auto` (default), `workspace-write`, `read-only`                                                                                                                                                        | Sandbox mode inside the checkout, also for the tasks its [flows](../flows.md) start; only `auto` asks a person ([escalations](../access.md#escalations))                                                                   |
 | `integrations.<id>.events`  | Event names from the [integration](#integrations): a list, or a map of event → `true`, a flow name (repo `.coder/flows` or built-in such as `review`), or `{ "flow", "match", "permissions", "actAs" }` | A list or `true` runs the agent, a flow name runs that flow, `match` is a regex the event text must pass, `permissions` overrides the agent's for this event, `"actAs": "requester"` uses the requester's own GitHub token |
-| `access`                    | `read` (Read-only) or `write` (Read-write, default)                                                                                                            | What it may do on its platforms and connections; also its apps' permissions                                                                                                                                                |
+| `access`                    | `read` (Read-only) or `write` (Read-write, default)                                                                                                                                                     | What it may do on its platforms and connections; also its apps' permissions                                                                                                                                                |
 | `mcp`                       | A map of MCP servers in the `.mcp.json` entry shape, as in [MCP](../mcp.md)                                                                                                                             | Servers every task of the agent attaches                                                                                                                                                                                   |
 
-`permissions` is about the checkout, `access` is about platforms and connections. An agent can run any [flow](../flows.md#flows-run-by-an-agent), and the tasks it starts never exceed the agent's `permissions`. The server versions imported definitions and activates a new version when their content changes; recreate the app only when `events` or `access` change.
-
 ## Usage
 
 How a repo runs an agent goes under `agents` in its `.coder/config.json` ([Configuration](../config.md)), one entry per agent id. No entry or `true` runs the agent as defined, `false` disables it, an object overrides it:
@@ -81,13 +79,13 @@ How a repo runs an agent goes under `agents` in its `.coder/config.json` ([Confi
 }
 ```
 
-| Key                                        | Values              | Purpose                                                    |
-| ------------------------------------------ | ------------------- | ---------------------------------------------------------- |
-| `engine`, `model`, `effort`, `permissions` | As above            | Override the definition                                    |
-| `connections` | Connection id list | Narrow `agents.<id>.connections`; omit for all granted connections |
-| `access`                                   | `read`              | Lower the definition's access to Read-only                 |
-| `integrations.<id>.allowedEvents`          | Event names         | Cap the definition's events; omit to allow all it asks for |
-| `disabled`                                 | `true`              | Disable the agent and keep its other settings              |
+| Key                                        | Values             | Purpose                                                            |
+| ------------------------------------------ | ------------------ | ------------------------------------------------------------------ |
+| `engine`, `model`, `effort`, `permissions` | As above           | Override the definition                                            |
+| `connections`                              | Connection id list | Narrow `agents.<id>.connections`; omit for all granted connections |
+| `access`                                   | `read`             | Lower the definition's access to Read-only                         |
+| `integrations.<id>.allowedEvents`          | Event names        | Cap the definition's events; omit to allow all it asks for         |
+| `disabled`                                 | `true`             | Disable the agent and keep its other settings                      |
 
 Unknown ids, integrations, events, and keys fail validation. Usage is read from the repo the event came from.
 
@@ -111,13 +109,13 @@ Disable or Enable any agent, built-in ones included, in its Settings › Manage
 An integration gives an agent two things:
 
 1. **Chat.** The agent's own app on the platform. Its events start tasks, and the reply goes back to the same thread. Linked workspace members can address an agent, and so can anyone the platform lets write there (on GitHub, write access to the repository); they get the workspace's connections only.
-2. **Platform tools.** Actions beyond replying, through each platform's MCP server, one per installation of the agent's apps. They run outside the agent's sandbox, with a token for that installation in the agent's access mode, and the token never reaches the agent. Read-only exposes only tools the platform server marks read-only; Read-write exposes all its tools. The prompt lists the servers; the engine loads a server's tools when it needs them. Replies, reactions and history work in both modes.
+2. **Platform tools.** Actions beyond replying, through each platform's MCP server, one per installation of the agent's apps. They run outside the agent's sandbox, with a token for that installation in the agent's access mode; the agent can read that token during its turn. Read-only exposes only tools the platform server marks read-only; Read-write exposes all its tools. The prompt lists the servers; the engine loads a server's tools when it needs them. Replies, reactions and history work in both modes.
 
-| Platform        | App                                                                                                                                                                              | Events                                                     | Tools                                                                                                                  |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| GitHub          | A [GitHub App](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) per agent                                                           | `mention`, `pull_request`, `issue`, `comment`              | GitHub's [MCP server](https://github.com/github/github-mcp-server); `read` runs it read-only                        |
-| Slack           | A [Slack app](https://api.slack.com/reference/manifests) per agent                                                                                                               | `mention`, `dm`, `channel`, `command`                      | [Slack MCP server](https://github.com/korotovsky/slack-mcp-server), pinned to v1.3.0 with SHA256 verification |
-| Linear          | Your [Linear OAuth app](https://linear.app/developers/agents), with webhooks to `<PUBLIC_URL>/hooks/linear?app=<client id>`                                                      | `mention`: an agent session                                | [Official Linear MCP server](https://linear.app/docs/mcp) at `https://mcp.linear.app/mcp` |
+| Platform | App                                                                                                                         | Events                                        | Tools                                                                                                         |
+| -------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| GitHub   | A [GitHub App](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) per agent      | `mention`, `pull_request`, `issue`, `comment` | GitHub's [MCP server](https://github.com/github/github-mcp-server); `read` runs it read-only                  |
+| Slack    | A [Slack app](https://api.slack.com/reference/manifests) per agent                                                          | `mention`, `dm`, `channel`, `command`         | [Slack MCP server](https://github.com/korotovsky/slack-mcp-server), pinned to v1.3.0 with SHA256 verification |
+| Linear   | Your [Linear OAuth app](https://linear.app/developers/agents), with webhooks to `<PUBLIC_URL>/hooks/linear?app=<client id>` | `mention`: an agent session                   | [Official Linear MCP server](https://linear.app/docs/mcp) at `https://mcp.linear.app/mcp`                     |
 
 On Slack, `dm` takes every message in direct and group DMs with the agent, and `channel` every message in channels it is in, up to Slack's 30,000 events per workspace per app per hour. A Slack app's Home tab shows the agent and how to use it, and links to this server's tasks and agents unfurl into a short card.
 

package/docs/cli/agent.md

@@ -0,0 +1,137 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# agent
+
+define and run agents
+
+Define and run agents from the CLI, the dashboard, or on GitHub, Slack and other platforms.
+
+## `agent list [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+list local or server-owned agents
+
+Without --server, one row per built-in and workspace agent. With --server, list the agent records and current versions owned by that Coder server.
+
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `agent show [id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+one agent in full: settings, integrations, events, tools
+
+Describe one agent as it will run here, or its active version on a server: its settings, access and per-integration events.
+
+- `<id>` the agent
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder agent show coder  # what the built-in agent listens to and may do
+```
+
+## `agent init [id] [--integrations <integrations>] [--events <events>] [--access <access>] [--name <name>] [--description <description>] [--permissions <permissions>] [--match <match>] [--yes] [--json] [--cwd <cwd>]`
+
+scaffold an agent folder in .coder/agents
+
+Create .coder/agents/<id>/ with an agent.json built from the integration catalog, a system.md to write the prompt in, and one sample event per integration for `coder agent run`. Asks for the id, integrations, events, and access when run in a terminal without them.
+
+- `<id>` the agent id: its folder under .coder/agents
+- `--integrations <integrations>` platforms the agent listens to (see coder agent integrations list)
+- `--events <events>` events that start tasks, applied to each integration that has them (default: mention)
+- `--access <access>` read or write, on its platforms and connections (default: write)
+- `--name <name>` display name used in replies (default: the id)
+- `--description <description>` one line for agent list
+- `--permissions <permissions>` engine permission mode (default: auto)
+- `--match <match>` start tasks only for event text matching a regex, as event=regex pairs
+- `--yes` skip the questions and take the defaults
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder agent init  # answer the questions, id included
+coder agent init triage --integrations github --events issue,mention --access read  # no questions
+```
+
+## `agent push [id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+upload workspace agents to a Coder server
+
+Upload one workspace agent, or every agent in .coder/agents when no id is given. The server creates a new immutable version only when its definition, prompt, or files changed.
+
+- `<id>` the agent (default: every workspace agent)
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder agent push helper  # upload helper
+```
+
+## `agent run [agent] [file] [--server <server>] [--workspace <workspace>] [--yes] [--wait] [--flow <flow>] [--task <task>] [--json] [--cwd <cwd>]`
+
+run a recorded event through an agent, offline or on a server
+
+Run a recorded platform event (AgentEvent JSON) through an agent. With --server it goes through your Coder server exactly like a webhook: real app, tokens, runner, and the reply is posted. Without it the engine runs here on the agent's prompt and this checkout, platform tools off, and the reply is printed.
+
+- `<agent>` the agent id
+- `<file>` the event JSON file
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--wait` with --server: follow the task log here until it finishes, then print the reply
+- `--flow <flow>` override the matched flow
+- `--task <task>` a runner's form: run that server task here
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder agent run helper sample-slack-mention.json  # offline: print what the agent would reply
+coder agent run helper event.json --server  # for real, through the server
+```
+
+## `agent usage [--since <since>] [--by <by>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+aggregate usage by agent, installation, or engine
+
+- `--since <since>` period such as 7d or 24h, or milliseconds since epoch
+- `--by <by>` agent, installation, or engine
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## agent integrations
+
+the integration catalog: events and tool presets
+
+The platforms an agent can listen to and act on: their events and tool presets.
+
+## `agent integrations list [--json]`
+
+list integrations with their events and tools
+
+One row per integration: its id, the events an agent can wire, and every tool it offers; `show` splits the tools by preset.
+
+- `--json` JSON output
+
+## `agent integrations show [id] [--json]`
+
+events and tools of one integration
+
+Describe one integration: each event with what triggers it, and the tools each preset (read, write) allows.
+
+- `<id>` the integration
+- `--json` JSON output
+
+```sh
+coder agent integrations show github  # the GitHub integration in full
+```

package/docs/cli/auth.md

@@ -0,0 +1,48 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# auth
+
+sign in to Coder and manage saved server sessions
+
+## `auth login [--server <server>] [--workspace <workspace>] [--yes] [--device] [--json]`
+
+sign in through the browser
+
+Sign in with Wular Auth in your browser. The CLI keeps the tokens in ~/.coder/session.json, and commands that talk to a server then act as you.
+
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--device` show a code to approve on another device; the default without a local browser
+- `--json` JSON output
+
+Environment:
+
+- `CODER_SERVER` the server to use instead of https://coder.wular.ai
+
+```sh
+coder auth login  # sign in to the hosted service
+coder auth login --server https://agents.example.com  # sign in to a self-hosted server
+```
+
+## `auth logout [--server <server>] [--yes] [--json]`
+
+sign out and forget the saved session
+
+Revoke the saved session for that server at Wular Auth and forget its tokens.
+
+- `--server <server>` sign out of this Coder server (default: the hosted one)
+- `--yes` connect to a server used for the first time without asking
+- `--json` JSON output
+
+## `auth status [--json]`
+
+show where you are signed in
+
+List saved sessions with their server, user, and workspace.
+
+- `--json` JSON output
+
+Environment:
+
+- `CODER_SERVER` the server to use instead of https://coder.wular.ai

package/docs/cli/connection.md

@@ -0,0 +1,89 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# connection
+
+platform accounts, API keys and MCP servers tasks use
+
+Connections give tasks access to a service without a handle: a platform account, an API key tasks read from the environment, or an MCP server. They live in ~/.coder, or on your Coder server with --server, and every task of yours may use them unless its agent or `coder task run --connections` narrows the set.
+
+## `connection add <name> [--command <command>] [--env <env>] [--url <url>] [--header <header>] [--key] [--auth <auth>] [--access <access>] [--tools <tools>] [--credential <credential>] [--me] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+connect a platform account, an API key or an MCP server
+
+Connect a platform account by its name (OAuth in the browser), an API key that tasks read from --env, or an MCP server at --url or started by the command after `--`. An API key is kept as a credential. A credential already holding the variable is used, else the value comes from that variable here, or from stdin or a prompt. A remote MCP server is checked for OAuth, open access or a key; a needed key is read from stdin or a prompt. With --key, the key goes in --header (default Authorization) or --env. Signing in needs --server.
+
+- `<name>` the connection name; a platform name connects that account
+- `--command <command>` a stdio MCP server to start; on the command line, the words after `--`
+- `--env <env>` the API key variable, or where a stdio server reads its key
+- `--url <url>` a remote MCP server (streamable HTTP by default)
+- `--header <header>` the header a remote server reads its key from (default: Authorization)
+- `--key` read a key from stdin or a prompt, never from a flag value
+- `--auth <auth>` override MCP authentication (default: detected for --url, none for a command)
+- `--access <access>` read keeps only read-only tools (default: the agent's mode, write for API keys)
+- `--tools <tools>` tool allowlist; a read-only stdio server needs one
+- `--credential <credential>` the credential an API key connection reads
+- `--me` your own connection instead of the workspace's
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+GROQ_API_KEY=gsk_... coder connection add groq --env GROQ_API_KEY  # an API key from this shell
+pbpaste | coder connection add docs --key --env DOCS_TOKEN --access write -- npx -y docs-mcp  # a stdio server with its key from stdin
+coder connection add github --me --server  # your GitHub account on your Coder server
+```
+
+## `connection list [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+list connections and the MCP servers this repository declares
+
+Your connections, and the MCP servers this repository and its agents declare with whether each is approved on this machine.
+
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `connection rm <name> [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+remove a connection
+
+Remove a connection. The credential an API key connection reads stays.
+
+- `<name>` the connection
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `connection reconnect <name> [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+give a connection a new key, or sign in again
+
+Give a key connection its new key, read from stdin or a prompt, or sign in to an OAuth connection again in the browser. The credential an API key connection reads gets the new value, so every connection reading it rotates.
+
+- `<name>` the connection
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+pbpaste | coder connection reconnect groq  # the new key from the clipboard
+```
+
+## `connection approve <name> [--agent <agent>] [--json] [--cwd <cwd>]`
+
+approve a repository MCP server on this machine
+
+Approve an MCP server this repository or one of its agents declares, on this machine. A changed endpoint or command needs approval again.
+
+- `<name>` the MCP server
+- `--agent <agent>` select the agent when names have different definitions
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current

package/docs/cli/credentials.md

@@ -0,0 +1,58 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# credentials
+
+engine credentials: subscriptions and API keys
+
+Manage subscriptions and API keys, one per variable in each scope. Your personal ones are yours alone; workspace ones serve every member, and only owners and admins change them. A task runs on its requester's own, else the workspace's.
+
+## `credentials list [--server <server>] [--yes] [--json]`
+
+list your keys and the workspace keys, by variable
+
+- `--server <server>` act on your Coder server, in the saved workspace
+- `--yes` connect to a server used for the first time without asking
+- `--json` JSON output
+
+## `credentials add [--env <env>] [--value <value>] [--workspace] [--no-check] [--server <server>] [--yes] [--json]`
+
+store an API key or subscription for one variable
+
+Store the key of one environment variable, encrypted on the server, as your own or with --workspace for every member. A key saved for that variable in the same scope is replaced. Where the server has subscription sign-in on, CLAUDE_CODE_OAUTH_TOKEN takes your own claude setup-token output.
+
+- `--env <env>` the variable tasks read the key as (reads that variable by default)
+- `--value <value>` literal values land in shell history and are visible to other processes; use - for stdin or prefer environment variables
+- `--workspace` a workspace key; owners and admins only
+- `--no-check` skip the provider key check
+- `--server <server>` act on your Coder server, in the saved workspace
+- `--yes` connect to a server used for the first time without asking
+- `--json` JSON output
+
+```sh
+ANTHROPIC_API_KEY=sk-... coder credentials add --env ANTHROPIC_API_KEY  # your own Claude key, read from the environment
+OPENAI_API_KEY=sk-... coder credentials add --env OPENAI_API_KEY --workspace  # a workspace key every member's tasks can use
+pbpaste | coder credentials add --env OPENROUTER_API_KEY --value -  # a key for custom models, value from stdin
+```
+
+## `credentials login [engine] [--server <server>] [--yes] [--json]`
+
+sign in to a claude or codex subscription on the server
+
+Runs the official claude or codex sign-in on the server's runner, prints the sign-in link or device code, and waits. Claude asks you to paste the code the sign-in page shows. The result replaces your subscription for that engine. Needs CLAUDE_SUBSCRIPTIONS=1 or CODEX_SUBSCRIPTIONS=1 on the server.
+
+- `<engine>` claude or codex
+- `--server <server>` act on your Coder server, in the saved workspace
+- `--yes` connect to a server used for the first time without asking
+- `--json` JSON output
+
+## `credentials remove <NAME> [--workspace] [--server <server>] [--yes] [--json]`
+
+remove the key of one variable
+
+Remove the key of one environment variable.
+
+- `<NAME>` the variable
+- `--workspace` the workspace key of that variable
+- `--server <server>` act on your Coder server, in the saved workspace
+- `--yes` connect to a server used for the first time without asking
+- `--json` JSON output

package/docs/cli/flow.md

@@ -0,0 +1,158 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# flow
+
+orchestrate many coder tasks from one TypeScript file
+
+Orchestrate many coder tasks with a plain TypeScript file: dispatch, gates,
+concurrency, journaling, and resume. Flows live in .coder/flows/ (workspace)
+or ~/.coder/flows/ (global). See `coder docs flows`.
+
+## `flow run <flow> [inputs] [--wait] [--args <args>] [--concurrency <concurrency>] [--max-tasks <max-tasks>] [--dry-run] [--json] [--cwd <cwd>]`
+
+run a flow in the background (--wait to follow it live)
+
+Run a flow: a TypeScript file that orchestrates many coder tasks with gates,
+journaling, and resume. Prints the run id and orchestrates in the background;
+--wait follows the run in the foreground with live progress (Ctrl-C detaches;
+it keeps running), and `coder flow watch` shows the same lines any time.
+Stop a run with `coder flow stop`.
+
+- `<flow>` the flow: a discovered name or a path
+- `<inputs>` the flow's input as bare key=value pairs
+- `--wait` follow the run in the foreground (Ctrl-C detaches; it keeps running)
+- `--args <args>` the flow's input as a JSON value (or pass bare key=value pairs)
+- `--concurrency <concurrency>` tasks running at once (default: CPU count)
+- `--max-tasks <max-tasks>` total tasks the run may dispatch (default: CPU count x 10)
+- `--dry-run` print every resolved prompt and gate command without dispatching
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder flow run audit-routes --wait  # run a discovered flow
+coder flow run ./scratch/one-off.ts --wait  # run a flow by path
+coder flow run verify --args '{"clusters":["a","b"]}' --wait  # pass structured input
+```
+
+## `flow list [--archived] [--limit <limit>] [--json] [--cwd <cwd>]`
+
+recent flow runs (by default running + just stopped)
+
+List recent flow runs, most recent first: running runs plus ones that ended
+within the last 30 minutes. Older runs auto-archive and move to --archived.
+
+- `--archived` show archived runs (auto-archived or via flow archive)
+- `--limit <limit>` show at most n runs (default all)
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `flow discover [--json] [--cwd <cwd>]`
+
+list flows runnable here (workspace + global)
+
+List every flow discoverable from the current directory: workspace flows in
+.coder/flows/ (walking up to the repo root) and global flows in ~/.coder/flows/.
+
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `flow result [run-id] [--tail <tail>] [--json] [--cwd <cwd>]`
+
+progress and result of a run
+
+Show a flow run's status and result, with its tasks, gates, and token ledger.
+--tail <n> caps the step rows (0 for the result alone). Defaults to the most
+recent run. To watch a run live, prefer `coder flow watch`.
+
+- `<run-id>` the run (default: the most recent)
+- `--tail <tail>` show the last n step rows (default: all; 0 hides them)
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder flow result --tail 0  # the most recent run's result, no step rows
+```
+
+## `flow watch [run-id] [--tail <tail>] [--from <from>] [--json] [--cwd <cwd>]`
+
+watch a run live (replay + follow)
+
+Watch a flow run live: replay its progress lines from the start, then keep
+following while it runs (Ctrl-C detaches; it keeps running). Blocks until it
+finishes; exits 0 on success, 1 otherwise. Defaults to the most recent run.
+For the result alone, prefer `coder flow result`. Alias: stream.
+
+With --from <n>, or as a tool, it returns the events from event n on without
+following, and `next`: the command that continues them while the run goes on.
+
+- `<run-id>` the run (default: the most recent)
+- `--tail <tail>` replay only the last n events first (default: all)
+- `--from <from>` return the events from event n on instead of following them
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder flow watch  # follow the most recent run to completion
+coder flow watch <run-id> --from 0 --json  # the events so far, and the command that continues them
+```
+
+## `flow stop [run-id] [--keep-tasks] [--json] [--cwd <cwd>]`
+
+stop a run and its still-running tasks
+
+Stop a running flow: signal the orchestrator so it stops dispatching, stamp the
+run stopped, and stop its still-running tasks. Defaults to the most recent run;
+the journal stays ready for `coder flow resume`.
+
+- `<run-id>` the run (default: the most recent)
+- `--keep-tasks` leave the run's still-running tasks running
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `flow resume [run-id] [--wait] [--args <args>] [--concurrency <concurrency>] [--max-tasks <max-tasks>] [--dry-run] [--json] [--cwd <cwd>]`
+
+continue a stopped or edited run
+
+Re-run a flow from its journal: finished steps replay instantly, the first
+changed or new step onward runs live. Defaults to the most recent run.
+Accepts the same flags as flow run.
+
+- `<run-id>` the run (default: the most recent)
+- `--wait` follow the run in the foreground (Ctrl-C detaches; it keeps running)
+- `--args <args>` the flow's input as a JSON value (or pass bare key=value pairs)
+- `--concurrency <concurrency>` tasks running at once (default: CPU count)
+- `--max-tasks <max-tasks>` total tasks the run may dispatch (default: CPU count x 10)
+- `--dry-run` print every resolved prompt and gate command without dispatching
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder flow resume  # continue the most recent run
+```
+
+## `flow archive [run-id] [--all-stopped] [--json] [--cwd <cwd>]`
+
+hide a run (or all stopped) from the list
+
+Archive a flow run so it drops out of the default list (see it again with
+`coder flow list --archived [--limit N]`). Pass --all-stopped to archive every
+finished run. A running run must be stopped first.
+
+- `<run-id>` the run to archive
+- `--all-stopped` archive every stopped (finished) run
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `flow delete [run-id] [--all-archived] [--json] [--cwd <cwd>]`
+
+delete a run's record (or all archived)
+
+Delete a flow run's record from disk (its journal, events, and logs). This is
+permanent; the run's tasks are ordinary tasks and are not touched. Pass
+--all-archived to delete every archived run at once. A running run must be
+stopped first.
+
+- `<run-id>` the run to delete
+- `--all-archived` delete every archived run
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current