npm - @mcpcloud/cli - Versions diffs - 0.9.1 → 0.10.0-next-20260715004701 - Mend

@mcpcloud/cli 0.9.1 → 0.10.0-next-20260715004701

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,222 +1,429 @@
 # @mcpcloud/cli
-The official command-line interface for [MCPCloud](https://mcpcloud.sh) — manage projects, MCP servers, skills, and API keys from your terminal.
+The official command-line interface for [MCPCloud](https://mcpcloud.sh) — build, deploy, and operate MCP servers and Skills from your terminal. Everything the dashboard does, scriptable: ingest an OpenAPI/GraphQL spec into a typed MCP server, deploy it to the edge, watch metrics, manage custom domains, and wire skills into your coding agent.
 ```sh
 npm install -g @mcpcloud/cli
-export MCPCLOUD_BASE_URL=https://your-deployment.example.com   # ask your admin
-mcp login
-mcp whoami
+mcp login          # opens the browser sign-in — works out of the box
+mcp whoami         # confirm your identity, org, and active profile
 ```
-> **Note**
-> MCPCloud is in private beta. The CLI does **not** ship with a default API base URL — set `MCPCLOUD_BASE_URL` (or `mcp config set-url <url>`) using the URL provided by your MCPCloud admin. A built-in default will be added when the platform launches publicly.
-The package installs three equivalent binaries: `mcp` (primary), `mcpsh`, and `mcpcloud`. They all point at the same executable — use whichever you prefer.
+The package installs three equivalent binaries — `mcp` (primary), `mcpsh`, and `mcpcloud`. They all point at the same executable; use whichever you prefer.
 ## Requirements
 - Node.js 18 or newer
-- An MCPCloud account and API key (create one at https://mcpcloud.sh)
+- An MCPCloud account (sign up at https://mcpcloud.sh)
 ## Installation
 ```sh
 # global install
 npm install -g @mcpcloud/cli
-bun  add -g @mcpcloud/cli
+bun  add     -g @mcpcloud/cli
 # one-off invocation (no install)
-npx -y @mcpcloud/cli whoami
-bunx --bun @mcpcloud/cli whoami
+npx  -y      @mcpcloud/cli whoami
+bunx --bun   @mcpcloud/cli whoami
 ```
-## Configuration
-The CLI needs **two** values to talk to your MCPCloud deployment: an API base URL and an API key. Either or both can come from environment variables, the saved config file, or per-invocation flags.
-### 1. Set the API base URL
+## Quick start
-The CLI does not assume any default base URL. Use whichever method fits your environment:
+The CLI ships with the **MCPCloud production base URL baked in**, so a fresh machine works with zero configuration — just sign in:
 ```sh
-# environment variable (recommended for CI / scripts)
-export MCPCLOUD_BASE_URL=https://your-deployment.example.com
-# persist for your user account (writes to ~/.mcpcloud/config.json)
-mcp config set-url https://your-deployment.example.com
+mcp login                       # browser sign-in (recommended)
+mcp login --key mck_xxx         # non-interactive (writes to shell history — prefer the env var)
+export MCPCLOUD_API_KEY=mck_xxx # or use an env var for CI
-# one-off override
-mcp --base-url https://your-deployment.example.com whoami
+mcp whoami                      # identity, resolved base URL (marked "(production)"), active profile
+mcp servers list                # your deployed MCP servers
+mcp servers get srv_123         # detail view
+mcp tools list --server srv_123 # tools that server exposes
+mcp skills connect skl_123 --agent claude-code --apply
+                                #   auto-register a skill with Claude Code
 ```
-The lookup order is: `--base-url` flag → `MCPCLOUD_BASE_URL` env var → saved `baseUrl` in `~/.mcpcloud/config.json`. If none are set the CLI exits with code `3` and a clear message.
+Run `mcp <command> --help` for the full option list, or `mcp help <topic>` for guided walkthroughs.
-### 2. Authenticate
+### Pointing at staging or a self-host
-```sh
-# Save a key to ~/.mcpcloud/config.json (mode 0600)
-mcp login                       # interactive prompt (recommended)
-mcp login --key mck_xxx         # non-interactive (avoid: writes to shell history)
+The production default is only a default — override it per environment. Precedence is `--base-url` flag → `MCPCLOUD_BASE_URL` → the saved profile's `baseUrl` → the built-in production default:
-# Or use an environment variable (recommended for CI)
-export MCPCLOUD_API_KEY=mck_xxx
+```sh
+export MCPCLOUD_BASE_URL=https://staging.example.com   # env (CI / scripts)
+mcp config set-url https://staging.example.com         # persist to the active profile
+mcp --base-url https://staging.example.com whoami      # one-off override
 ```
-`mcp logout` removes the saved key. `mcp config show` prints the current resolved config (with the API key redacted).
+## Authentication & config
-## Quick start
+Credentials and settings live in `~/.mcpcloud/config.json` (mode `0600`; respects `XDG_CONFIG_HOME` on Linux):
 ```sh
-mcp whoami                      # show current key + organizations
-mcp projects list               # list projects in your default org
-mcp servers list                # list MCP servers
-mcp servers get srv_123         # detail view
-mcp servers logs srv_123        # recent deployment events
-mcp tools  list srv_123         # tools exposed by a server
-mcp skills list                 # list skills
-mcp skills connect skl_123 --agent claude-code --apply
-                                  # auto-register a skill with Claude Code
-mcp api-keys list               # personal API keys
-mcp api-keys create --name CI   # mint a new key (secret shown once)
-mcp api-keys revoke key_456
+mcp login                       # save an API key (interactive browser flow)
+mcp logout                      # remove the saved key
+mcp config show                 # print the resolved config (key redacted)
+mcp config current              # alias of `config show`
+mcp config set-org <name|id>    # persist a default organization (accepts name, slug, or id)
 ```
-Run `mcp <command> --help` on any command for the full option list.
+`MCPCLOUD_API_KEY` overrides the saved key; `MCPCLOUD_ORG_ID` overrides the saved default org.
-## Global flags
+## Profiles
-| Flag               | Description                                                                             |
-| ------------------ | --------------------------------------------------------------------------------------- |
-| `--json`           | Emit raw JSON on stdout. Errors come back as `{ "error": { "code", "message", ... } }`. |
-| `--base-url <url>` | Override the API base URL for one invocation (useful for staging).                      |
-| `-v, --version`    | Print the CLI version.                                                                  |
-| `-h, --help`       | Show help for any command.                                                              |
+Keep separate credentials + base URLs for prod, staging, and self-host, and always know which one you're about to mutate:
-## Environment variables
-| Variable            | Description                                                   |
-| ------------------- | ------------------------------------------------------------- |
-| `MCPCLOUD_API_KEY`  | API key used for authentication (overrides the saved config). |
-| `MCPCLOUD_BASE_URL` | API base URL. **Required** — there is no built-in default.    |
-| `MCPCLOUD_ORG_ID`   | Default organization ID for commands that require one.        |
+```sh
+mcp config profile add staging --url https://staging.example.com --key mck_stg
+mcp config profile list         # ✓ marks the active profile
+mcp config use staging          # switch the active profile
+mcp --profile prod servers list # one-off override
+export MCPCLOUD_PROFILE=staging # or select via env
+```
-The organization for each command is resolved in this order:
+`mcp whoami` prints the active profile and its source, and appends `(production)` to the base URL when it resolves to the production host — so a profile named "local" pointed at prod can't surprise you. `mcp doctor` runs the same resolution as an 8-point health check.
-1. The `--org` flag (when supported).
-2. `MCPCLOUD_ORG_ID`.
-3. `defaultOrganizationId` saved in `~/.mcpcloud/config.json`.
-4. The server-side default returned from `/api/v1/organizations`.
+## The dev loop
-## Commands
+`mcp dev` runs a deployed server **locally** with hot reload: it downloads the server's generated bundle, serves it on `localhost` (HTTP/SSE/stdio), watches your files (and optionally an OpenAPI spec) to regenerate on change, auto-wires the running instance into your coding agent (`--auto-connect claude-code`), and exposes an inspector UI at `/__inspect`. Pair it with the round-trip tool editors (`tools pull` / `tools edit` / `tools diff` / `tools reset-handler`) to iterate on tool metadata and handler source against the live bundle.
-### Authentication & config
+## Scripting & CI
-```sh
-mcp login [--key <secret>]      # save an API key locally
-mcp logout                      # remove the saved key
-mcp whoami                      # show current key, base URL, and accessible orgs
+Every command honors a machine-readable output contract, registered globally so it's uniform across the tree.
-mcp config show                 # print resolved config (key redacted)
-mcp config set-url <url>        # persist the API base URL
-mcp config clear-url            # remove the saved base URL
-mcp config set-org <orgId>      # persist a default organization
-mcp config clear-org            # remove the saved default organization
-```
+### Output formats
-### Projects
+| Flag                 | Effect                                                                              |
+| -------------------- | ----------------------------------------------------------------------------------- |
+| `--json`             | Emit a single JSON document on success; errors become a `{ "error": {…} }` envelope. No human text is mixed in. |
+| `--format <mode>`    | List output as `table` (default), `tsv`, `jsonl`, or `json`.                        |
+| `--no-table`         | Shorthand for `--format tsv` — tab-separated rows for `awk`/`cut`/`grep`.           |
+| `--field <names>`    | Comma-separated columns to include in list output (repeatable).                     |
+| `--filter <k=substr>`| Case-insensitive substring filter on list rows (repeatable).                        |
+| `--quiet`            | Suppress success/step/info chrome; data and errors still print. Pairs with exit codes for gates. |
+| `--non-interactive`  | Refuse prompts (fail fast on missing input) without the color/glyph changes of `--ci`. |
+| `--ci`               | Force CI mode (auto-detected when `CI=true`): no color, ASCII glyphs, no prompts, always surface request IDs. |
+| `--warnings-as-errors` | Exit non-zero if any warning is emitted.                                          |
 ```sh
-mcp projects list [--org <id>] [--limit <n>]
-mcp projects get  <projectId> [--org <id>]
+mcp --json servers list | jq '.servers[].id'
+mcp servers list --field id,name,status --format jsonl
+mcp servers list --filter status=active --no-table | cut -f1
 ```
-### Servers
-```sh
-mcp servers list [--org <id>] [--project <id>] [--limit <n>]
-mcp servers get  <serverId> [--org <id>]
-mcp servers logs <serverId> [--org <id>] [--limit <n>]
-```
+### Exit codes
-### Tools
+| Code | Meaning                                                                                  |
+| ---- | ---------------------------------------------------------------------------------------- |
+| `0`  | Success.                                                                                  |
+| `1`  | Generic failure (API error, validation error, network error).                            |
+| `2`  | No API key configured. Run `mcp login` or set `MCPCLOUD_API_KEY`.                         |
+| `3`  | No API base URL configured (only reachable if you clear the built-in default and set nothing). |
-```sh
-mcp tools list --project <projectId> [--org <id>]
-mcp tools list --server <serverId>  [--org <id>]   # looks up the project for you
-```
+### Error envelope
-### Skills
+Structured API errors are surfaced consistently. In `--json` mode:
-```sh
-mcp skills list [--org <id>] [--project <id>] [--limit <n>]
-mcp skills get  <skillId> [--org <id>]
-# Print or apply the MCP configuration that wires a skill into your coding agent.
-mcp skills connect <skillId>
-    [--org <id>]
-    [--agent claude-code|codex|claude-desktop|vscode|cursor|windsurf|antigravity]
-    [--name <connection-name>]
-    [--apply]                     # for claude-code only: runs `claude mcp add`
+```json
+{ "error": { "code": "server_not_found", "message": "Server not found", "requestId": "api_018f…", "docsUrl": "https://mcpcloud.sh/docs/errors#server_not_found" } }
 ```
-### API keys
+In human mode the same fields print as `code`, a one-line remediation, the `request id` (always shown under `--ci`, even when the upstream response omitted one), and an absolute `docs:` link.
-```sh
-mcp api-keys list
-mcp api-keys create --name <displayName>
-mcp api-keys revoke <apiKeyId>
-```
+### Idempotency
-The secret returned by `api-keys create` is shown **once**. Save it immediately — you cannot retrieve it again.
+Mutations accept `--idempotency-key <key>` (1–255 ASCII chars, no whitespace). When omitted, the CLI auto-generates a UUID per invocation so its own internal retries on transient failures stay safe. Pass a stable key from your pipeline to make a whole step re-runnable.
-## JSON mode
+### CI deploy gate
-Every command supports `--json` for piping into another tool. In JSON mode the CLI emits a single JSON document on success and a `{ "error": { ... } }` envelope on failure. No human-readable text is mixed in.
+The observability commands compose into a deploy gate that exits non-zero on failure — no output parsing required:
 ```sh
-mcp --json projects list | jq '.projects[].slug'
-mcp --json skills connect skl_123 --agent cursor \
-  | jq '.snippet'
+mcp servers deploy srv_123 --wait                        # block until the deploy is terminal
+mcp deployments health <deploymentId> --quiet            # exit non-zero unless healthy
+mcp metrics deployment <deploymentId> --since 15m --max-error-rate 0.02
+                                                         # exit non-zero if the error rate breaches the budget
 ```
-## Exit codes
-| Code | Meaning                                                                                  |
-| ---- | ---------------------------------------------------------------------------------------- |
-| `0`  | Success.                                                                                 |
-| `1`  | Generic failure (API error, validation error, network error).                            |
-| `2`  | No API key configured. Run `mcp login` or set `MCPCLOUD_API_KEY`.                      |
-| `3`  | No API base URL configured. Set `MCPCLOUD_BASE_URL` or run `mcp config set-url <url>`. |
-When an API call fails, the CLI prints the response code, status, and request id (when present) to make debugging easier:
-```
-Error: Server not found (code: not_found) (status: 404)
-  request id: api_018f...
-  docs:       https://mcpcloud.sh/docs/errors#not_found
-```
+Resolve the deployment id from `mcp servers get srv_123 --json` (or `mcp deployments list`) after the deploy completes.
+## Command reference
+Run `mcp <command> --help` for full options on any of these.
+<!-- BEGIN GENERATED COMMANDS -->
+_Generated from the live command tree by `bun run docs:readme` — do not edit by hand._
+### Top-level commands
+| Command | Description |
+| --- | --- |
+| `mcp completion <shell>` | Print a shell completion script (bash, zsh, or fish) |
+| `mcp doctor` | Diagnose the CLI environment: Node, config, base URL, API key, claude CLI, and updates |
+| `mcp help [topic]` | Show extended help for a topic (auth, profiles, agents, errors) |
+| `mcp init` | Guided onboarding: pick org → pick/create project → create a server (empty skeleton, or generated from an OpenAPI/GraphQL spec via --from-spec) |
+| `mcp invoke <serverId> <tool>` | Call a tool on a deployed MCP server. Exchanges runtime-auth if needed, sends JSON-RPC `tools/call`, and prints the response. |
+| `mcp login` | Sign in via browser (default) or paste an API key |
+| `mcp logout` | Remove the saved API key from ~/.mcpcloud/config.json |
+| `mcp ui` | Interactive terminal UI: browse orgs/servers/skills, tail deployment logs, and watch the live `mcp dev` inspector |
+| `mcp update` | Check for a newer @mcpcloud/cli release and re-install it via your package manager |
+| `mcp whoami` | Show the caller identity, API key, base URL, and organizations you can access |
+### `mcp api-keys` — Manage personal API keys
+| Command | Description |
+| --- | --- |
+| `mcp api-keys create` | Create a new API key (the secret is shown once) |
+| `mcp api-keys describe <apiKeyId>` | Show one API key (status, expiry, last used) — never the secret |
+| `mcp api-keys list` | List active API keys for the current user |
+| `mcp api-keys revoke <apiKeyId>` | Permanently revoke an API key |
+| `mcp api-keys rotate <apiKeyId>` | Mint a replacement key and grace-expire the old one (24h window). The new secret is shown once. |
+### `mcp audit` — Workspace audit log (admin/owner only)
+| Command | Description |
+| --- | --- |
+| `mcp audit list` | List recent audit events for an organization |
+### `mcp config` — Manage CLI configuration in ~/.mcpcloud/config.json
+| Command | Description |
+| --- | --- |
+| `mcp config clear-app-url` | Forget the saved dashboard URL (falls back to MCPCLOUD_APP_URL or auto-derive) |
+| `mcp config clear-editor` | Forget the editor open preference, the picked editor command, AND the saved target (mcp dev will re-detect and prompt next session) |
+| `mcp config clear-org` | Remove the saved default organization ID |
+| `mcp config clear-url` | Remove the saved base URL (falls back to MCPCLOUD_BASE_URL) |
+| `mcp config current` | Alias for `config show` — print the active profile |
+| `mcp config profile` | Manage named config profiles (apiKey + baseUrl + defaultOrganizationId) |
+| `mcp config profile add <name>` | Create a new profile (use --url / --key / --app / --org to seed values) |
+| `mcp config profile list` | List all configured profiles |
+| `mcp config profile remove <name>` | Delete a profile (cannot remove the active or only-remaining profile) |
+| `mcp config set-app-url <url>` | Save the dashboard origin used by `mcp login` browser flow |
+| `mcp config set-editor <pref>` | Save the dev-runner editor open preference: always \| never |
+| `mcp config set-editor-command <command>` | Override the editor launch command (default: code; e.g. cursor, code-insiders) |
+| `mcp config set-org <organization>` | Save a default organization (by name, slug, or id) |
+| `mcp config set-url <url>` | Save the API base URL to ~/.mcpcloud/config.json |
+| `mcp config show` | Print the active profile (API key is redacted) |
+| `mcp config use <name>` | Switch the active profile (e.g. staging, prod) |
+### `mcp connections` — Manage your per-server upstream API keys (BYOK) from the terminal
+| Command | Description |
+| --- | --- |
+| `mcp connections add <serverId>` | Save (or replace) your upstream API key for a server — rotation is just adding again |
+| `mcp connections list` | List your stored upstream keys across servers (hints only) |
+| `mcp connections remove <serverId>` | Revoke your stored upstream key for a server |
+### `mcp deployments` — Inspect deployments
+| Command | Description |
+| --- | --- |
+| `mcp deployments get <deploymentId>` | Show one deployment by id |
+| `mcp deployments health <deploymentId>` | Show a deployment's last health-check result (status, HTTP code, when it was checked) |
+| `mcp deployments list` | List deployments in an organization |
+| `mcp deployments logs <deploymentId>` | Show recent deployment events; pass --follow to tail new ones as they arrive |
+| `mcp deployments rollback <deploymentId>` | Roll back to a prior deployment — flips a paused/undeployed deployment back to active and demotes the current latest in one shot. |
+| `mcp deployments runtime-auth <deploymentId>` | Inspect a deployment's runtime-auth posture (access mode, exchange path, edge policy) |
+### `mcp dev` — Run a deployed MCP server locally with hot reload + agent auto-wire
+| Command | Description |
+| --- | --- |
+| `mcp dev init` | Interactively pick an organization + server and write .mcpcloud/state.json (forces the picker even if state already exists) |
+| `mcp dev invoke <tool>` | Call a tool against the running `mcp dev` session in this directory. No auth — local runtime accepts anonymous JSON-RPC. |
+| `mcp dev kill <pid>` | Stop a running mcp dev session by PID (or "all" to stop every session) |
+| `mcp dev list` | List running mcp dev sessions on this machine |
+| `mcp dev replay` | Replay one or more recorded calls against the running mcp dev server |
+| `mcp dev tail` | Stream new mcp dev inspector records to stdout as JSON lines (Ctrl+C to stop) |
+### `mcp domains` — Serve servers from custom domains you own (Pro+)
+| Command | Description |
+| --- | --- |
+| `mcp domains add <hostname>` | Attach a custom domain to a server (admin role required) |
+| `mcp domains list` | List the custom domains in an organization |
+| `mcp domains namespaces` | Verify a parent domain once, then attach subdomains to any server with no further DNS work |
+| `mcp domains namespaces add <parentDomain>` | Register a domain namespace and print its one-time DNS records (admin role required) |
+| `mcp domains namespaces list` | List the domain namespaces in an organization |
+| `mcp domains namespaces remove <parentDomain>` | Remove a domain namespace — existing attached hostnames keep working (admin role required) |
+| `mcp domains namespaces verify <parentDomain>` | Check the namespace verification records now |
+| `mcp domains remove <hostname>` | Remove a custom domain — traffic on it stops immediately (admin role required) |
+| `mcp domains status <hostname>` | Recheck a custom domain against Cloudflare and show status |
+| `mcp domains transfer <hostname>` | Move a custom domain to another server without certificate churn (admin role required) |
+### `mcp installation` — Manage your skill / artifact installations
+| Command | Description |
+| --- | --- |
+| `mcp installation disable <installationId>` | Disable an installation by id (replay-as-success on already-disabled rows) |
+| `mcp installation list` | List your active installations and their ids |
+| `mcp installation remove <installationId>` | Mark an installation as removed by id |
+### `mcp marketplace` — Browse the public registry of MCP servers and skills
+| Command | Description |
+| --- | --- |
+| `mcp marketplace fork <artifactId>` | Fork a registry artifact into one of your projects as an editable draft |
+| `mcp marketplace get <artifactId>` | Show full details for one registry artifact (readme, recent versions) |
+| `mcp marketplace install <artifactId>` | Install a published registry artifact (server or skill) into your organization |
+| `mcp marketplace list` | List published artifacts in the registry |
+| `mcp marketplace publish <serverId|skillId>` | Publish a deployed server or a versioned skill to the registry (requires org admin) |
+| `mcp marketplace version <artifactId> <versionId>` | Show details for one published version of a registry artifact |
+| `mcp marketplace versions <artifactId>` | List published versions of a registry artifact (paginated) |
+### `mcp metrics` — Aggregate deployment metrics (request volume, error rate)
+| Command | Description |
+| --- | --- |
+| `mcp metrics deployment <deploymentId>` | Show aggregate request metrics for a deployment over a window (CI deploy gate) |
+### `mcp oauth` — Manage OAuth provider connections
+| Command | Description |
+| --- | --- |
+| `mcp oauth connection` | Inspect or revoke individual OAuth connections |
+| `mcp oauth connection delete <connectionId>` | Revoke an OAuth connection (best-effort upstream revoke; replay-as-success on already-revoked rows) |
+| `mcp oauth connections` | List OAuth provider connections across the organization |
+### `mcp orgs` — List and inspect the organizations you belong to
+| Command | Description |
+| --- | --- |
+| `mcp orgs get [organizationId]` | Show one organization (defaults to your active org) |
+| `mcp orgs list` | List organizations you can access |
+| `mcp orgs members [organizationId]` | List members of an organization |
+| `mcp orgs usage [organizationId]` | Show request-volume usage for an organization |
+| `mcp orgs use <organizationId>` | Set the default organization for this profile (discoverable alias of `mcp config set-org`) |
+### `mcp plugin` — Manage @mcpcloud/cli plugins (third-party command extensions)
+| Command | Description |
+| --- | --- |
+| `mcp plugin install <package>` | Install a plugin from npm (uses npm under the hood) |
+| `mcp plugin list` | List installed plugins |
+| `mcp plugin remove <name>` | Remove an installed plugin |
+### `mcp projects` — Manage projects
+| Command | Description |
+| --- | --- |
+| `mcp projects api-source <apiSourceId>` | Show details for a single imported API spec |
+| `mcp projects api-sources <projectId>` | List imported API specs / source material for a project |
+| `mcp projects create` | Create a new project in an organization |
+| `mcp projects delete <projectId>` | Permanently delete a project. Requires --confirm "<exact name>" and that the project is empty of servers/skills. |
+| `mcp projects get <projectId>` | Get details for a single project |
+| `mcp projects list` | List projects in an organization |
+| `mcp projects update <projectId>` | Update a project (RFC 7396 merge patch — only listed fields change) |
+### `mcp servers` — Manage MCP servers
+| Command | Description |
+| --- | --- |
+| `mcp servers create` | Create an empty server skeleton in a project |
+| `mcp servers delete <serverId>` | Permanently delete a server and all its data. Requires --confirm "<exact name>". |
+| `mcp servers deploy <serverId>` | Deploy a server's generated bundle to Cloudflare Workers (closes the spec → deploy loop) |
+| `mcp servers deployments <serverId>` | List a server's deployment history |
+| `mcp servers env` | Manage server runtime environment bindings (encrypted secrets injected by the proxy). |
+| `mcp servers env get <serverId> <bindingName>` | Show metadata for one env binding. Plaintext is never returned — values are write-only. |
+| `mcp servers env list <serverId>` | List a server's env bindings (metadata only; values are never returned). |
+| `mcp servers env set <serverId> <bindingName> [value]` | Create or replace an env binding's value. Schedules a Cloudflare-runtime push when the server has an active deployment. |
+| `mcp servers env unset <serverId> <bindingName>` | Remove an env binding. Idempotent — succeeds even if the binding is already gone. |
+| `mcp servers export <serverId>` | Export a self-host bundle (Dockerfile + node entry + config) for a server |
+| `mcp servers generate <serverId>` | Generate the server's TypeScript bundle (the exact code `deploy` ships) and optionally write it to disk — a dry-run for the codegen path. Wraps POST /api/v1/server/generate. |
+| `mcp servers get <serverId>` | Get details for a single server |
+| `mcp servers ingest` | Create a server from an OpenAPI spec (file, URL, or @- stdin) or a GraphQL endpoint. Wraps POST /api/v1/server/ingest. |
+| `mcp servers list` | List servers |
+| `mcp servers logs <serverId>` | Show recent deployment events for a server's latest deployment |
+| `mcp servers oauth-connections <serverId>` | List OAuth provider connections bound to this server |
+| `mcp servers pause <serverId>` | Pause the server's latest active deployment (traffic stops; worker is preserved) |
+| `mcp servers push-spec <serverId>` | Push a local OpenAPI spec to the cloud (regenerates the bundle; optionally deploys) |
+| `mcp servers regenerate <serverId>` | Re-fetch a server's source spec and rebuild its tools with the current codegen (preserves customizations). Wraps POST /api/v1/server/regenerate. |
+| `mcp servers resume <serverId>` | Resume the server's paused deployment (flips dispatch routing back on; only platformWorker deployments support instant resume) |
+| `mcp servers test-runs` | Inspect and trigger server sandbox test runs |
+| `mcp servers test-runs get <testRunId>` | Show one server test run with assertions, trace, and the tool response |
+| `mcp servers test-runs list <serverId>` | List sandbox test runs for a server |
+| `mcp servers test-runs new <serverId>` | Trigger a sandbox test run against a server's latest deployment (synchronous) |
+| `mcp servers test-scenarios` | Inspect server sandbox test scenarios |
+| `mcp servers test-scenarios get <scenarioId>` | Show one server test scenario including its request and expected response |
+| `mcp servers test-scenarios list <serverId>` | List test scenarios bound to a server |
+| `mcp servers test-suites` | Inspect server sandbox test suites (groups of scenarios) |
+| `mcp servers test-suites get <suiteId>` | Show one server test suite including its scenario membership |
+| `mcp servers test-suites list <serverId>` | List test suites bound to a server |
+| `mcp servers update <serverId>` | Update a server (v1 PATCH only carries name and description) |
+| `mcp servers version <serverId> <versionId>` | Show details for a single server version |
+| `mcp servers versions <serverId>` | List published versions of a server |
+### `mcp skills` — Manage skills
+| Command | Description |
+| --- | --- |
+| `mcp skills archive <skillId>` | Archive a skill (replay-as-success on already-archived rows) |
+| `mcp skills connect <skillId>` | Print (or apply) the MCP configuration that connects this skill to your coding agent |
+| `mcp skills create` | Create an empty skill draft in a project |
+| `mcp skills delete <skillId>` | Permanently delete a draft skill. Requires --confirm "<exact name>". Published skills with versions/installs are rejected (archive instead). |
+| `mcp skills get <skillId>` | Get details for a single skill |
+| `mcp skills install <skillId>` | Install a skill into the caller's project |
+| `mcp skills installations <skillId>` | List the installation footprint of a skill (which orgs / users installed it) |
+| `mcp skills invoke <skillId>` | Run a deployed skill from the terminal. Resolves the skill’s MCP endpoint, auto-discovers its single tool, and calls it. |
+| `mcp skills list` | List skills in an organization |
+| `mcp skills test-runs` | Inspect and trigger skill sandbox test runs |
+| `mcp skills test-runs get <testRunId>` | Show one skill test run with assertions, trace, and output |
+| `mcp skills test-runs list <skillId>` | List sandbox test runs for a skill |
+| `mcp skills test-runs new <skillId>` | Trigger a sandbox test run against a skill (synchronous; returns terminal status) |
+| `mcp skills test-scenarios` | Inspect skill sandbox test scenarios |
+| `mcp skills test-scenarios get <scenarioId>` | Show one skill test scenario including its prompt and assertion body |
+| `mcp skills test-scenarios list <skillId>` | List test scenarios bound to a skill |
+| `mcp skills uninstall <skillId>` | Mark the caller's installation of this skill as removed |
+| `mcp skills update <skillId>` | Update skill metadata (name, description, visibility) |
+| `mcp skills version <skillId> <versionId>` | Show details for one published skill version (workflow summary, triggers, deps) |
+| `mcp skills versions <skillId>` | List published versions of a skill |
+### `mcp tools` — Inspect and edit tools on a project or server
+| Command | Description |
+| --- | --- |
+| `mcp tools diff <name>` | Compare a tool's local files (metadata .md + handler .ts) against the cloud version. |
+| `mcp tools edit <name>` | Open a tool's local .md in $EDITOR; pushes your changes to the cloud on save. Requires `mcp dev` to have materialized tools (run `mcp tools pull` first if needed). |
+| `mcp tools enrich <name>` | Run AI enrichment for a tool. Prints the suggested vs applied diff; pass --apply to push the suggestion to the cloud. |
+| `mcp tools handlers` | Inspect tool handler files (the per-tool .ts in src/tools/) |
+| `mcp tools handlers list` | List every tool with its handler override status (default / override / stale). |
+| `mcp tools list` | List tools for a project, or scope to a single server with --server |
+| `mcp tools pull [name]` | Refresh local tool files from the cloud, overwriting any unsaved local edits. Use after `409 conflict` to re-sync. |
+| `mcp tools pull-handler <name>` | Refresh a tool's handler source from the cloud, overwriting any local edits. Use after `409 conflict` to re-sync. |
+| `mcp tools reset-handler <name>` | Drop the cloud handler override for a tool and re-materialize the codegen default. Prompts to confirm unless --yes is passed. |
+| `mcp tools show <name>` | Show a tool's full applied metadata (and any pending AI suggestion). |
+### `mcp usage` — Show organization usage (tool-call volume) and credit balance from the terminal
+| Command | Description |
+| --- | --- |
+| `mcp usage ledger` | List organization credit ledger entries (most recent first) |
+<!-- END GENERATED COMMANDS -->
+## Plugins
+`mcp plugin install <spec>` extends the CLI with third-party commands. **A plugin runs in your CLI process with your credentials and the same filesystem access — install only plugins you trust.**
 ## Configuration file
-The CLI stores its config at `~/.mcpcloud/config.json` with mode `0600`. Recognised fields:
+`~/.mcpcloud/config.json` (mode `0600`). Environment variables take precedence over its contents. Recognised fields:
 ```jsonc
 {
-  "apiKey": "mck_...", // saved by `mcp login`
-  "baseUrl": "https://your-deployment...", // saved by `mcp config set-url`
-  "defaultOrganizationId": "org_...", // saved by `mcp config set-org`
+  "apiKey": "mck_...",                       // saved by `mcp login`
+  "baseUrl": "https://your-deployment...",   // saved by `mcp config set-url` (omit to use the production default)
+  "defaultOrganizationId": "org_...",        // saved by `mcp config set-org`
+  "profiles": { "staging": { /* apiKey + baseUrl + defaultOrganizationId */ } }
 }
 ```
-You can edit the file directly or replace it. Environment variables take precedence over its contents.
 ## Reliability
 - **Timeout:** every request is bounded by a 30-second `AbortController`.
 - **Retry:** transient failures (network errors, HTTP 502/503/504) are retried once with jittered backoff. 4xx responses are never retried.
-- **Error envelope:** server errors are surfaced with their `code`, `message`, `requestId`, and `docsUrl` so you can correlate with backend logs.
+- **Error envelope:** server errors carry their `code`, `message`, `requestId`, and `docsUrl` so you can correlate with backend logs.
 ## Development
@@ -229,9 +436,10 @@ bun run dev -- --help            # run from source
 bun run typecheck                # tsc --noEmit
 bun run test                     # vitest
 bun run build                    # bundle to dist/index.js
+bun run docs:readme              # regenerate the command reference above
 ```
-The bundled output is a single Node-compatible ESM file with a `#!/usr/bin/env node` shebang.
+The command reference between the markers is generated from the live Commander tree by `bun run docs:readme`; a conformance test fails if it drifts, so a new command can't ship with a stale README.
 ## Releasing