@mcpcloud/cli 0.0.0-next-20260525192206

package/README.md

@@ -0,0 +1,259 @@
+# @mcpcloud/cli
+
+The official command-line interface for [MCPCloud](https://mcpcloud.sh) — manage projects, MCP servers, skills, and API keys from your terminal.
+
+```sh
+npm install -g @mcpcloud/cli
+export MCPCLOUD_BASE_URL=https://your-deployment.example.com   # ask your admin
+mcp login
+mcp whoami
+```
+
+> **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.
+
+## Requirements
+
+- Node.js 18 or newer
+- An MCPCloud account and API key (create one at https://mcpcloud.sh)
+
+## Installation
+
+```sh
+# global install
+npm install -g @mcpcloud/cli
+bun  add -g @mcpcloud/cli
+
+# one-off invocation (no install)
+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
+
+The CLI does not assume any default base URL. Use whichever method fits your environment:
+
+```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
+
+# one-off override
+mcp --base-url https://your-deployment.example.com whoami
+```
+
+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.
+
+### 2. Authenticate
+
+```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)
+
+# Or use an environment variable (recommended for CI)
+export MCPCLOUD_API_KEY=mck_xxx
+```
+
+`mcp logout` removes the saved key. `mcp config show` prints the current resolved config (with the API key redacted).
+
+## Quick start
+
+```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
+```
+
+Run `mcp <command> --help` on any command for the full option list.
+
+## Global flags
+
+| 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.                                                              |
+
+## 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.        |
+
+The organization for each command is resolved in this order:
+
+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`.
+
+## Commands
+
+### Authentication & config
+
+```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
+
+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
+```
+
+### Projects
+
+```sh
+mcp projects list [--org <id>] [--limit <n>]
+mcp projects get  <projectId> [--org <id>]
+```
+
+### 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>]
+```
+
+### Tools
+
+```sh
+mcp tools list --project <projectId> [--org <id>]
+mcp tools list --server <serverId>  [--org <id>]   # looks up the project for you
+```
+
+### Skills
+
+```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`
+```
+
+### API keys
+
+```sh
+mcp api-keys list
+mcp api-keys create --name <displayName>
+mcp api-keys revoke <apiKeyId>
+```
+
+The secret returned by `api-keys create` is shown **once**. Save it immediately — you cannot retrieve it again.
+
+## JSON mode
+
+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.
+
+```sh
+mcp --json projects list | jq '.projects[].slug'
+
+mcp --json skills connect skl_123 --agent cursor \
+  | jq '.snippet'
+```
+
+## 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
+```
+
+## Configuration file
+
+The CLI stores its config at `~/.mcpcloud/config.json` with mode `0600`. 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`
+}
+```
+
+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.
+
+## Development
+
+```sh
+git clone https://github.com/MCPCloud-sh/mcp-hub
+cd mcp-hub/packages/cli
+
+bun install
+bun run dev -- --help            # run from source
+bun run typecheck                # tsc --noEmit
+bun run test                     # vitest
+bun run build                    # bundle to dist/index.js
+```
+
+The bundled output is a single Node-compatible ESM file with a `#!/usr/bin/env node` shebang.
+
+## Releasing
+
+The CLI is released independently of the dashboard via [Changesets](https://github.com/changesets/changesets). When you land a PR that changes anything under `packages/cli/src/`, the workflow's `pr-checks` job requires a changeset describing the bump:
+
+```sh
+# From the repo root, after staging your CLI changes:
+bunx changeset
+# → pick @mcpcloud/cli, choose patch | minor | major, write a one-line summary.
+# Commit the generated .changeset/<name>.md alongside your code change.
+```
+
+On merge to `main`, [`.github/workflows/cli-release.yml`](../../.github/workflows/cli-release.yml) opens (or updates) a "chore(cli): version packages" PR that bumps `packages/cli/package.json`, writes `CHANGELOG.md`, and consumes the pending changesets. Merging that PR publishes to npm (`prepublishOnly` re-runs typecheck + test + build as a gate) and creates a `@mcpcloud/cli@<version>` GitHub Release.
+
+A Homebrew distribution (`brew install mcpcloud` via a custom tap with standalone bottles) is tracked separately — see issue tracker.
+
+## Support
+
+- Documentation: https://mcpcloud.sh/docs
+- Issues: https://github.com/MCPCloud-sh/mcp-hub/issues
+- Email: support@mcpcloud.sh
+
+## License
+
+MIT © MCPCloud