@mcpcloud/cli 0.1.0

package/README.md

@@ -0,0 +1,213 @@
+# @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
+mcpsh login
+mcpsh whoami
+```
+
+The package installs two equivalent binaries: `mcpsh` (short) and `mcpcloud` (full). 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
+```
+
+## Authentication
+
+You can authenticate two ways. The CLI prefers the environment variable when both are set.
+
+```sh
+# 1. Save a key to ~/.mcpcloud/config.json (mode 0600)
+mcpsh login                       # interactive prompt (recommended)
+mcpsh login --key mck_xxx         # non-interactive (avoid: writes to shell history)
+
+# 2. Use an environment variable (recommended for CI)
+export MCPCLOUD_API_KEY=mck_xxx
+```
+
+`mcpsh logout` removes the saved key.
+
+## Quick start
+
+```sh
+mcpsh whoami                      # show current key + organizations
+mcpsh projects list               # list projects in your default org
+mcpsh servers list                # list MCP servers
+mcpsh servers get srv_123         # detail view
+mcpsh servers logs srv_123        # recent deployment events
+mcpsh tools  list srv_123         # tools exposed by a server
+mcpsh skills list                 # list skills
+mcpsh skills connect skl_123 --agent claude-code --apply
+                                  # auto-register a skill with Claude Code
+mcpsh api-keys list               # personal API keys
+mcpsh api-keys create --name CI   # mint a new key (secret shown once)
+mcpsh api-keys revoke key_456
+```
+
+Run `mcpsh <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` | Override the API base URL. Default: `https://mcpcloud.sh`. |
+| `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
+
+```sh
+mcpsh login [--key <secret>]      # save an API key locally
+mcpsh logout                      # remove the saved key
+mcpsh whoami                      # show current key, base URL, and accessible orgs
+```
+
+### Projects
+
+```sh
+mcpsh projects list [--org <id>] [--limit <n>]
+mcpsh projects get  <projectId> [--org <id>]
+```
+
+### Servers
+
+```sh
+mcpsh servers list [--org <id>] [--project <id>] [--limit <n>]
+mcpsh servers get  <serverId> [--org <id>]
+mcpsh servers logs <serverId> [--org <id>] [--limit <n>]
+```
+
+### Tools
+
+```sh
+mcpsh tools list <serverId> [--org <id>]
+```
+
+### Skills
+
+```sh
+mcpsh skills list [--org <id>] [--project <id>] [--limit <n>]
+mcpsh skills get  <skillId> [--org <id>]
+
+# Print or apply the MCP configuration that wires a skill into your coding agent.
+mcpsh 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
+mcpsh api-keys list
+mcpsh api-keys create --name <displayName>
+mcpsh 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
+mcpsh --json projects list | jq '.projects[].slug'
+
+mcpsh --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 `mcpsh login` or set `MCPCLOUD_API_KEY`. |
+
+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 `mcpsh login`
+  "baseUrl": "https://staging.mcpcloud.sh", // overrides the default
+  "defaultOrganizationId": "org_..."        // used when --org is omitted
+}
+```
+
+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/your-org/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.
+
+## Support
+
+- Documentation: https://mcpcloud.sh/docs
+- Issues: https://github.com/your-org/mcp-hub/issues
+- Email: support@mcpcloud.sh
+
+## License
+
+MIT © MCPCloud