@wular/coder 0.4.10 → 0.4.12

package/docs/cli/index.md

@@ -0,0 +1,139 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# coder CLI
+
+Delegate a coding task to the best available engine and steer it while it runs.
+
+- [task](task.md): run, follow and steer coding tasks
+- [flow](flow.md): orchestrate many coder tasks from one TypeScript file
+- [agent](agent.md): define and run agents
+- [credentials](credentials.md): engine credentials: subscriptions and API keys
+- [server](server.md): self-host Coder: the server, its dashboard and sign-in
+- [runner](runner.md): run your server's tasks on this machine
+- [auth](auth.md): sign in to Coder and manage saved server sessions
+- [model](model.md): manage models: built-ins, aliases, custom endpoints
+- [connection](connection.md): platform accounts, API keys and MCP servers tasks use
+
+## `review [--base <base>] [--head <head>] [--pr <pr>] [--since <since>] [--path <path>] [--exclude <exclude>] [--post] [--md] [--engine <engine>] [--model <model>] [--effort <effort>] [--json] [--cwd <cwd>]`
+
+review changed code with a built-in flow
+
+Review changed code with a read-only agent. Every reported finding is checked
+against the repository. Runs the built-in `review` flow. A local review covers
+everything since the merge-base with the origin default branch, including
+uncommitted and untracked files. Changed submodules are reviewed file by file.
+PR reviews can post deduplicated inline comments.
+
+Related: `coder flow watch`, `coder docs review`.
+
+- `--base <base>` local comparison base (default: merge-base with origin default)
+- `--head <head>` review commits through this ref only (default: the working tree)
+- `--pr <pr>` review a pull request by number (origin repo) or URL; GitHub via gh for now
+- `--since <since>` keep only PR files and hunks changed since this commit
+- `--path <path>` review only this path, relative to cwd (repeatable)
+- `--exclude <exclude>` leave this path out, relative to cwd (repeatable)
+- `--post` post deduplicated inline comments and sticky PR summary
+- `--md` markdown output (the default)
+- `--engine <engine>` codex, claude, or custom
+- `--model <model>` model for the review task
+- `--effort <effort>` reasoning effort and review depth (default: medium depth)
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+```sh
+coder review  # review the branch plus uncommitted work
+coder review --base main  # review everything since main locally
+coder review --path src --exclude src/gen  # review src without generated code
+coder review --pr 42 --post  # review and post to pull request 42
+```
+
+## `config [action] [key] [value] [--workspace] [--json] [--cwd <cwd>]`
+
+read or write config
+
+Read or write configuration. `list` prints the effective config; get/set/unset
+target a dotted key (e.g. engines.codex.model). Writes go to ~/.coder/config.json.
+
+- `<action>` list, get, set or unset
+- `<key>` a dotted key, such as engines.codex.model
+- `<value>` with set: the value; JSON, or a comma list
+- `--workspace` target <repo>/.coder/config.json instead of the user file
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+```sh
+coder config list  # print the effective config
+coder config set chain codex,claude  # set the engine fallback chain
+coder config get engines.codex.model  # read one value
+```
+
+## `setup-host [hosts] [--json] [--cwd <cwd>]`
+
+check engines and install the host plugin or skill
+
+Set up coder in your host: check engines and auth, seed the config, and
+install the host plugin/skill for the named host(s). Claude Code gets its
+marketplace plugin; "agents" installs a skill into ~/.agents/skills for
+every host that reads the Agent Skills standard dir (Codex, Pi, OpenCode,
+...). Codex and Cursor also get the MCP server; the Claude plugin includes it.
+With no host, checks, seeds and registers available Codex and Cursor hosts.
+
+To add the MCP server by hand: claude mcp add coder -- coder mcp, codex mcp
+add coder -- coder mcp, or for Cursor "coder": { "command": "coder", "args":
+["mcp"] } under mcpServers in ~/.cursor/mcp.json. Restart running sessions after.
+
+- `<hosts>` claude, agents, codex, cursor (one or more)
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+```sh
+coder setup-host claude  # install the Claude Code plugin
+coder setup-host agents  # install the shared skill and register MCP with available Codex
+coder setup-host codex cursor  # install the skill and register MCP with both hosts
+```
+
+## `docs [topic] [--claude] [--json]`
+
+print bundled documentation (for agents to read)
+
+Print bundled documentation. With no topic, list the available topics; with a
+topic, print that doc's raw markdown to stdout (unstyled, for an agent to
+consume). Topics with sub-pages list them as `<topic>/<page>` (also accepted as
+`<topic>-<page>`). `coder docs skill` prints the host skill so an engine can
+load it once per session (--claude for the Claude Code flavor).
+
+- `<topic>` the doc to print (default: list the topics)
+- `--claude` with the skill topic: print the Claude Code flavor
+- `--json` JSON output
+
+```sh
+coder docs  # list the available topics
+coder docs flows  # print the Flows doc
+coder docs review  # print the Review doc
+```
+
+## `upgrade [--cli-only] [--plugins-only] [--codex] [--claude] [--pm <pm>]`
+
+update the CLI and host plugins
+
+Update the coder CLI through whichever package manager installed it, then refresh
+the host plugins to match.
+
+- `--cli-only` update just the CLI
+- `--plugins-only` refresh just the host plugins
+- `--codex` limit the refresh to the Agent Skills copy (Codex, Pi, ...)
+- `--claude` limit the refresh to the Claude Code plugin
+- `--pm <pm>` force a package manager instead of auto-detecting
+
+## `mcp`
+
+serve Coder's commands as MCP tools over stdio
+
+Serve Coder's commands as MCP tools over stdio, so a harness can run them.
+
+Commands return their JSON payloads and next steps. Load guides with load_skill;
+blocking commands keep their CLI flags and behavior, subject to the client's tool timeout.
+
+```sh
+claude mcp add coder -- coder mcp  # run Coder from Claude Code
+```

package/docs/cli/model.md

@@ -0,0 +1,116 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# model
+
+manage models: built-ins, aliases, custom endpoints
+
+Manage the models coder can dispatch to. `add` connects any OpenAI-compatible
+endpoint (Ollama, vLLM, OpenRouter, ...) as the custom engine, alongside the
+built-in codex/claude models. Name your own shortcuts with `alias`
+(e.g. fast -> codex:luna); disable/enable turns any model off and on.
+
+## `model list [--json] [--cwd <cwd>]`
+
+list built-ins, custom models, and aliases
+
+List built-in aliases, configured custom models, and user aliases. Only custom
+models are probed.
+
+Use luna or sonnet for mechanical work; sol or opus is the default.
+Use astra or fable for the hardest work; they cost the most.
+
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+## `model add [name] [--base-url <base-url>] [--model <model>] [--env-key <env-key>] [--workspace] [--json] [--cwd <cwd>]`
+
+connect a model
+
+Connect a custom model behind an OpenAI-compatible endpoint (Ollama, LM Studio,
+vLLM, OpenRouter, ...). It currently runs on the codex engine pointed at your
+URL and is usable anywhere a model is: --model <name>, --engine custom, or as an
+agent default in config. Alias: `coder model setup`.
+
+- `<name>` the name to dispatch it by
+- `--base-url <base-url>` OpenAI-compatible API base (e.g. http://localhost:11434/v1)
+- `--model <model>` the provider's model id (e.g. qwen2.5-coder:32b)
+- `--env-key <env-key>` env var holding the API key (omit for keyless local endpoints)
+- `--workspace` write to <repo>/.coder/config.json instead of the user file
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+```sh
+coder model add qwen --base-url http://localhost:11434/v1 --model qwen2.5-coder:32b  # local Ollama model, no key
+coder model add kimi --base-url https://openrouter.ai/api/v1 --model moonshotai/kimi-k2 --env-key OPENROUTER_API_KEY  # third-party provider via OpenRouter
+coder run --model qwen "explain this repo"  # dispatch a task on it
+```
+
+## `model update [name] [--base-url <base-url>] [--model <model>] [--env-key <env-key>] [--workspace] [--json] [--cwd <cwd>]`
+
+change a model in place
+
+Update a configured custom model. Only the flags you pass change; the endpoint
+is re-probed and the wire protocol re-detected.
+
+- `<name>` the custom model
+- `--base-url <base-url>` new API base
+- `--model <model>` new provider model id
+- `--env-key <env-key>` new API-key env var
+- `--workspace` write to <repo>/.coder/config.json instead of the user file
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+## `model remove [name] [--workspace] [--json] [--cwd <cwd>]`
+
+delete a custom model
+
+Remove a configured custom model.
+
+- `<name>` the custom model
+- `--workspace` target <repo>/.coder/config.json instead of the user file
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+## `model disable [name] [--workspace] [--json] [--cwd <cwd>]`
+
+turn off a model (built-in, custom, or alias)
+
+Disable a model - built-in, custom, or alias. Requests for it fail until re-enabled.
+
+- `<name>` a built-in, custom model, or alias
+- `--workspace` target <repo>/.coder/config.json instead of the user file
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+## `model enable [name] [--workspace] [--json] [--cwd <cwd>]`
+
+re-enable a disabled model
+
+- `<name>` a built-in, custom model, or alias
+- `--workspace` target <repo>/.coder/config.json instead of the user file
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+## `model alias [name] [spec] [--workspace] [--json] [--cwd <cwd>]`
+
+name a spec, e.g. fast codex:luna
+
+Save an alias for an engine spec, e.g. fast -> codex:luna. An alias may reuse a
+built-in name to override it.
+
+- `<name>` the alias
+- `<spec>` the engine spec, such as codex:luna
+- `--workspace` target <repo>/.coder/config.json instead of the user file
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+## `model unalias [name] [--workspace] [--json] [--cwd <cwd>]`
+
+remove an alias
+
+Remove a user-defined alias.
+
+- `<name>` the alias
+- `--workspace` target <repo>/.coder/config.json instead of the user file
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)

package/docs/cli/runner.md

@@ -0,0 +1,92 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# runner
+
+run your server's tasks on this machine
+
+Run your Coder server's tasks on your own machine, reached through any tunnel.
+
+## `runner add <kind> [--name <name>] [--scope <scope>] [--field <field>] [--server <server>] [--yes] [--json]`
+
+connect a runner
+
+Connect a runner. Secret fields read environment variables with key=env:VARIABLE. Adding local prints a pairing command.
+
+- `<kind>` the runner kind, such as local or http
+- `--name <name>` runner display name
+- `--scope <scope>` personal or workspace
+- `--field <field>` repeat for each field, use env:VARIABLE for secrets
+- `--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
+
+## `runner default <id> [--server <server>] [--yes] [--json]`
+
+set the default in its scope
+
+Use this runner by default within its scope.
+
+- `<id>` the runner
+- `--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
+
+## `runner test <id> [--server <server>] [--yes] [--json]`
+
+check a runner connection
+
+Check the runner connection.
+
+- `<id>` the runner
+- `--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
+
+## `runner serve [--url <url>] [--token <token>] [--runner-url <runner-url>] [--port <port>] [--name <name>] [--workspace] [--server <server>] [--yes] [--json] [--cwd <cwd>]`
+
+run your server's tasks on this machine
+
+Run tasks on this machine with its own claude and codex logins. Expose the port with any tunnel (cloudflared, ngrok, Tailscale Funnel or a public VS Code port) and pass the tunnel's URL; each start registers the current URL, so a changing tunnel URL is fine. Choose a default with coder runner default. Tasks use their named runner, the agent setting, your default, the workspace default, then the server default.
+
+- `--url <url>` the HTTPS address the server reaches this runner at
+- `--token <token>` one-use pairing token, --url is the Coder server
+- `--runner-url <runner-url>` public tunnel address when pairing, or CODER_RUNNER_URL
+- `--port <port>` local port the tunnel forwards to (default 4100)
+- `--name <name>` shown in the dashboard (default: this machine's hostname)
+- `--workspace` run every member's tasks, not only yours (owners and admins)
+- `--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
+- `--cwd <cwd>` workspace directory (default: current)
+
+```sh
+cloudflared tunnel --url http://localhost:4100  # expose the port in one terminal
+coder runner serve --url https://abc.trycloudflare.com  # then serve through it
+```
+
+## `runner list [--server <server>] [--yes] [--json]`
+
+list your runners and the workspace's
+
+- `--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
+
+## `runner rename <id> <name> [--server <server>] [--yes] [--json]`
+
+rename a runner
+
+- `<id>` the runner
+- `<name>` its new name
+- `--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
+
+## `runner remove <id> [--server <server>] [--yes] [--json]`
+
+remove a runner
+
+- `<id>` the runner
+- `--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/server.md

@@ -0,0 +1,89 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# server
+
+self-host Coder: the server, its dashboard and sign-in
+
+Self-host Coder: the server your agents and platform apps talk to, with a dashboard and sign-in. We run one as the hosted service; you can run your own.
+
+## `server serve [--port <port>] [--host <host>] [--memory] [--runner <runner>] [--json] [--cwd <cwd>]`
+
+run the server
+
+Run the Coder server on Bun: the address platforms deliver events to, the dashboard, and the worker that runs tasks. With DATABASE_URL it is a full server with sign-in and workspaces. Without one it is the dashboard for this machine's CLI: its config, agents, tasks and engine logins, on loopback only. --memory makes a throwaway test server that keeps everything in memory. Configured through the environment; every variable is in coder docs self-host.
+
+- `--port <port>` listen port (default: PORT, else the port in a localhost PUBLIC_URL, else 8787)
+- `--host <host>` listen address (default: HOST, else 127.0.0.1 without a database, else every interface)
+- `--memory` a throwaway test server: everything in memory, no sign-in, admin token only
+- `--runner <runner>` local, local-docker, vercel-sandbox, github-actions, or http
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory (default: current)
+
+Environment:
+
+- `PUBLIC_URL` the address platforms and browsers reach the server at (default http://localhost:<port>)
+- `PORT` listen port, as hosts set it (default 8787)
+- `HOST` listen address, as --host
+- `DATABASE_URL` Postgres, set up with drizzle-kit push; turns on sign-in and workspaces
+- `AUTH_WULAR_URL` the Wular Auth issuer people sign in with (default https://auth.wular.ai)
+- `SERVER_ENCRYPTION_KEY` encrypts stored secrets and derives the sign-in keys; required with DATABASE_URL (openssl rand -base64 32)
+- `RUNNER` where tasks run: local (default), local-docker, vercel-sandbox, github-actions, http
+- `MAX_TASKS, TASK_TIMEOUT, TASK_STALL, TASK_ATTEMPTS` runner capacity and lifecycle limits
+- `ADMIN_TOKEN` local and memory servers: the dashboard and CLI key; minted and shown when unset
+- `CODER_CACHE_HOME` archived tasks, flows and usage (default OS cache directory/wular-coder)
+- `WORK_DIR` where tasks check out repositories
+- `SERVER_NAME` what the dashboard calls this server (default Coder)
+
+```sh
+PUBLIC_URL=https://abc.ngrok.app coder server serve  # receive GitHub and Slack events through a tunnel; the tunnel serves only their webhooks and callbacks
+PUBLIC_URL=https://agents.example.com DATABASE_URL=postgres://... coder server serve  # on your own host, backed by Postgres
+```
+
+## `server rotate-key [--json]`
+
+re-seal secrets with SERVER_ENCRYPTION_KEY
+
+Re-seal stored app, installation, engine, and linked user secrets with the current key.
+
+- `--json` JSON output
+
+Environment:
+
+- `SERVER_ENCRYPTION_KEY` the new key
+- `SERVER_ENCRYPTION_KEY_PREVIOUS` the old key, still accepted while rotating
+
+## `server workflow`
+
+print the GitHub Actions workflow for RUNNER=github-actions
+
+Print the workflow the github-actions runner dispatches. Save it as .github/workflows/coder-agent.yml in every repo the agent runs on, and set RUNNER=github-actions on the server.
+
+```sh
+coder server workflow > .github/workflows/coder-agent.yml  # add it to a repo
+```
+
+## server app
+
+the built-in agent's public apps
+
+The built-in agent's apps, one per platform, shared by every workspace on this server.
+
+## `server app create <integration> [--org <org>] [--name <name>] [--json]`
+
+create the built-in agent's public app
+
+Open the page that creates the built-in agent's public app on a platform, once per server. Every workspace then connects it from its dashboard with one click. Run it where the server's environment is set.
+
+- `<integration>` the platform, such as github
+- `--org <org>` create it under this organization instead of your own account
+- `--name <name>` the app's name and handle (default Coder)
+- `--json` JSON output
+
+Environment:
+
+- `DATABASE_URL` the server's Postgres
+- `PUBLIC_URL` the server's address, which goes into the app
+
+```sh
+coder server app create github --name wular-coder  # the hosted GitHub App
+```