Capgo CLI Usage
Route Capgo CLI requests, authenticate the CLI, and connect agents to Capgo.
Facts below were checked against @capgo/cli 8.77 (October 2026). Always run npx @capgo/cli@latest <command> --help before you rely on a rarely used flag.
When to Use
TRIGGER when:
- The user asks "how do I use the Capgo CLI", "which Capgo command does X", or asks about CLI login or auth.
- The user wants Claude, Cursor, ChatGPT, or another agent connected to their Capgo account (MCP).
- The request spans several Capgo areas and the right sub-skill is not clear yet.
- The CLI fails before doing any work (auth, wrong directory, missing
appId).
Do not use when one of these already fits. Switch to it as soon as the scope is clear:
- App updater wiring,
notifyAppReady, or autoUpdate: capgo-live-updates
- Bundle uploads, channels, rollouts, rollback, or encryption keys:
capgo-release-management
- Native cloud builds and signing:
capgo-native-builds
- Organizations, members, 2FA, or security policy:
capgo-organization-management
- Multi-product Capgo plans (builds, OTA, and store):
capgo-cloud
- Ionic or Capacitor's own MCP tooling, not Capgo:
capacitor-mcp
Secrets and Confirmation
- Never ask the user to paste a Capgo API key, signing password,
.p8 key, keystore, or service-account JSON into the chat. Ask them to run npx @capgo/cli@latest login themselves (it opens the browser or asks for the key in a masked prompt), or to set CAPGO_TOKEN in their shell or CI secret store.
- Do not put secrets in command arguments: they end up in shell history and process lists. Use environment variables, the saved login, or the CLI's interactive prompts.
- If a secret appears in the conversation anyway, do not repeat it, do not write it to a file, and tell the user to revoke it and create a new one.
npx @capgo/cli@latest downloads and runs the newest CLI from npm. Run it only inside the user's project and with their go-ahead. In CI, pin an exact version.
- Ask before any command that changes remote state: uploading a bundle, changing or promoting a channel, deleting apps, bundles, channels, or keys, requesting a build that uploads to a store, and exporting or deleting credentials. Say what will change and for which app and channel.
Command Surface
| Group |
Commands |
Skill |
| Setup |
init [apikey] [appId], login [apikey] [--local], doctor, probe --platform ios|android |
this skill / capgo-live-updates |
| App |
app add, app list, app set, app delete, app debug, app setting, app todo |
this skill |
| Bundles |
bundle upload|list|delete|cleanup|compatibility|releaseType|zip|encrypt|decrypt |
capgo-release-management |
| Channels |
channel add, channel list, channel set, channel promote, channel currentBundle, channel delete |
capgo-release-management |
| Keys |
key create|save|delete_old |
capgo-release-management |
| Previews |
get-qr [appId] --bundle|--channel |
capgo-release-management |
| Native builds |
build init|request|prescan|needed|last-output|sync-ios-version|credentials ... |
capgo-native-builds |
| Account / orgs |
account whoami, organization list, organization add, organization members, organization set, organization delete |
capgo-organization-management |
| Observe |
observe summary|metrics|events|device|versions|routes |
this skill |
| Push |
notifications setup [appId] |
capacitor-push-notifications |
| Devices |
run device [ios|android] [--no-launch] |
this skill |
| Agents |
mcp |
this skill |
These commands do not exist. Do not suggest them: capgo upload (use bundle upload), channel create (use channel add), bundle revert (use channel set --bundle), key verify, upload --sign.
Authentication
The user runs the login. It opens the browser to create a key, or asks for the key in a masked prompt:
npx @capgo/cli@latest login # saves to ~/.capgo
npx @capgo/cli@latest login --local # saves to ./.capgo (git-ignored)
The CLI picks the key in this order:
-a, --apikey <key> on the command
- The
CAPGO_TOKEN environment variable (use this in CI)
~/.capgo (global)
./.capgo (project)
Trap: the global key wins over the project key. Set the CAPGO_TOKEN environment variable to force a different account. Keys are created at https://console.capgo.app/dashboard/apikeys.
Self-hosted backends: add --supa-host <url> --supa-anon <key> on supported commands.
Connect the Agent to Capgo (MCP)
Capgo has two MCP servers. Use both when available.
- Hosted MCP:
https://api.capgo.app/mcp (streamable HTTP). Nothing to install. The client signs in with OAuth, or sends Authorization: Bearer <Capgo API key>. The hosted MCP includes destructive tools, so use an API key with the smallest role the task needs (read-only for reporting). It covers apps, bundles, channels, progressive rollouts, devices, stats, Observe update health, native build status and logs, webhooks, and push notifications. Example for Claude Code: claude mcp add --transport http capgo https://api.capgo.app/mcp, then /mcp to sign in. Each OAuth client gets its own MCP · <client name> API key, which expires after at most 90 days. Revoke a client by deleting that key in the console.
- Local CLI MCP:
npx @capgo/cli@latest mcp (stdio, authenticated by login). Use it to upload a bundle from the build folder, request a native build, or run doctor, probe, or compatibility checks against local project files. The hosted MCP cannot read local files.
Claude Desktop config for the local server:
{ "mcpServers": { "capgo": { "command": "npx", "args": ["@capgo/cli@latest", "mcp"] } } }
Setup guide for both servers: https://capgo.app/mcp (a page, not an MCP endpoint).
No Capgo account yet: sign up at https://console.capgo.app (14-day free trial, no credit card). Docs: https://capgo.app/docs/ai/mcp/
Diagnostics Quick Path
npx @capgo/cli@latest doctor # versions + setup problems (add --package-json for monorepos)
npx @capgo/cli@latest app todo com.example.app # onboarding checklist: done, skipped, pending
npx @capgo/cli@latest probe --platform android # would the backend serve an update to this config?
npx @capgo/cli@latest app debug com.example.app # live update events from a device
npx @capgo/cli@latest observe summary --days 7 # launch, crash, WebView findings, each with a next view
observe has no session ID. Use observe device DEVICE_ID --json to get one device's timeline.
Monorepos
Use --package-json, --node-modules, and, for dynamic root configs, --capacitor-config <path>. Keep the env selector active, for example CAP_APP=web npx @capgo/cli@latest init --capacitor-config ./env-configs/capacitor.config.web.ts.
Verification
npx @capgo/cli@latest account whoami prints the expected account ID and email, which proves auth works.
npx @capgo/cli@latest app list shows the app. If it is missing, run app add.
- MCP: in Claude Code,
/mcp lists capgo as connected, and a read-only prompt ("list my Capgo apps") returns data.
Error Handling
| String |
Fix |
No Capgo API key found. Run \...` first, then retry this command.` |
The user runs npx @capgo/cli@latest login, or sets the CAPGO_TOKEN environment variable |
Missing argument, you need to provide a appId, or be in a capacitor project |
Pass the appId positionally or run from the folder containing capacitor.config.* |
Insufficient permissions for <key> |
The key's role is too low for this app or org. Use a key with the needed role |
🔐 Access Denied: Two-Factor Authentication Required |
The org enforces 2FA. See capgo-organization-management |
App <id> not found in database |
Run npx @capgo/cli@latest app add <id> or check the active account |
| Wrong account used |
A global ~/.capgo overrides a local .capgo. Set CAPGO_TOKEN |
Resources
1---2name: capgo-cli-usage3description: Entry point for the Capgo CLI (`npx @capgo/cli@latest`). Maps the full command surface (init, login, doctor, probe, app, bundle, channel, key, account, organization, build, observe, get-qr, notifications, run device, mcp), explains API-key precedence (--apikey, CAPGO_TOKEN, ~/.capgo, ./.capgo), connects agents to Capgo through the hosted MCP (https://api.capgo.app/mcp) or the local CLI MCP, and routes to the narrower Capgo skill. Use when the user asks generally how to use the Capgo CLI, which command to run, how to authenticate it, how to connect Claude or another agent to Capgo, or gets "No Capgo API key found". Do not use when a specific Capgo skill already matches (capgo-live-updates, capgo-release-management, capgo-native-builds, capgo-organization-management).4metadata:5 source: https://skillmd.com/skills/tuyv/capgo-cli-usage6---78# Capgo CLI Usage910Route Capgo CLI requests, authenticate the CLI, and connect agents to Capgo.1112Facts below were checked against `@capgo/cli` 8.77 (October 2026). Always run `npx @capgo/cli@latest <command> --help` before you rely on a rarely used flag.1314## When to Use1516TRIGGER when:1718- The user asks "how do I use the Capgo CLI", "which Capgo command does X", or asks about CLI login or auth.19- The user wants Claude, Cursor, ChatGPT, or another agent connected to their Capgo account (MCP).20- The request spans several Capgo areas and the right sub-skill is not clear yet.21- The CLI fails before doing any work (auth, wrong directory, missing `appId`).2223Do not use when one of these already fits. Switch to it as soon as the scope is clear:2425- App updater wiring, `notifyAppReady`, or `autoUpdate`: `capgo-live-updates`26- Bundle uploads, channels, rollouts, rollback, or encryption keys: `capgo-release-management`27- Native cloud builds and signing: `capgo-native-builds`28- Organizations, members, 2FA, or security policy: `capgo-organization-management`29- Multi-product Capgo plans (builds, OTA, and store): `capgo-cloud`30- Ionic or Capacitor's own MCP tooling, not Capgo: `capacitor-mcp`3132## Secrets and Confirmation3334- Never ask the user to paste a Capgo API key, signing password, `.p8` key, keystore, or service-account JSON into the chat. Ask them to run `npx @capgo/cli@latest login` themselves (it opens the browser or asks for the key in a masked prompt), or to set `CAPGO_TOKEN` in their shell or CI secret store.35- Do not put secrets in command arguments: they end up in shell history and process lists. Use environment variables, the saved login, or the CLI's interactive prompts.36- If a secret appears in the conversation anyway, do not repeat it, do not write it to a file, and tell the user to revoke it and create a new one.37- `npx @capgo/cli@latest` downloads and runs the newest CLI from npm. Run it only inside the user's project and with their go-ahead. In CI, pin an exact version.38- Ask before any command that changes remote state: uploading a bundle, changing or promoting a channel, deleting apps, bundles, channels, or keys, requesting a build that uploads to a store, and exporting or deleting credentials. Say what will change and for which app and channel.3940## Command Surface4142| Group | Commands | Skill |43| --- | --- | --- |44| Setup | `init [apikey] [appId]`, `login [apikey] [--local]`, `doctor`, `probe --platform ios\|android` | this skill / `capgo-live-updates` |45| App | `app add`, `app list`, `app set`, `app delete`, `app debug`, `app setting`, `app todo` | this skill |46| Bundles | `bundle upload\|list\|delete\|cleanup\|compatibility\|releaseType\|zip\|encrypt\|decrypt` | `capgo-release-management` |47| Channels | `channel add`, `channel list`, `channel set`, `channel promote`, `channel currentBundle`, `channel delete` | `capgo-release-management` |48| Keys | `key create\|save\|delete_old` | `capgo-release-management` |49| Previews | `get-qr [appId] --bundle\|--channel` | `capgo-release-management` |50| Native builds | `build init\|request\|prescan\|needed\|last-output\|sync-ios-version\|credentials ...` | `capgo-native-builds` |51| Account / orgs | `account whoami`, `organization list`, `organization add`, `organization members`, `organization set`, `organization delete` | `capgo-organization-management` |52| Observe | `observe summary\|metrics\|events\|device\|versions\|routes` | this skill |53| Push | `notifications setup [appId]` | `capacitor-push-notifications` |54| Devices | `run device [ios\|android] [--no-launch]` | this skill |55| Agents | `mcp` | this skill |5657These commands do not exist. Do not suggest them: `capgo upload` (use `bundle upload`), `channel create` (use `channel add`), `bundle revert` (use `channel set --bundle`), `key verify`, `upload --sign`.5859## Authentication6061The user runs the login. It opens the browser to create a key, or asks for the key in a masked prompt:6263```bash64npx @capgo/cli@latest login # saves to ~/.capgo65npx @capgo/cli@latest login --local # saves to ./.capgo (git-ignored)66```6768The CLI picks the key in this order:69701. `-a, --apikey <key>` on the command712. The `CAPGO_TOKEN` environment variable (use this in CI)723. `~/.capgo` (global)734. `./.capgo` (project)7475Trap: the global key wins over the project key. Set the `CAPGO_TOKEN` environment variable to force a different account. Keys are created at https://console.capgo.app/dashboard/apikeys.7677Self-hosted backends: add `--supa-host <url> --supa-anon <key>` on supported commands.7879## Connect the Agent to Capgo (MCP)8081Capgo has two MCP servers. Use both when available.8283- Hosted MCP: `https://api.capgo.app/mcp` (streamable HTTP). Nothing to install. The client signs in with OAuth, or sends `Authorization: Bearer <Capgo API key>`. The hosted MCP includes destructive tools, so use an API key with the smallest role the task needs (read-only for reporting). It covers apps, bundles, channels, progressive rollouts, devices, stats, Observe update health, native build status and logs, webhooks, and push notifications. Example for Claude Code: `claude mcp add --transport http capgo https://api.capgo.app/mcp`, then `/mcp` to sign in. Each OAuth client gets its own `MCP · <client name>` API key, which expires after at most 90 days. Revoke a client by deleting that key in the console.84- Local CLI MCP: `npx @capgo/cli@latest mcp` (stdio, authenticated by `login`). Use it to upload a bundle from the build folder, request a native build, or run `doctor`, `probe`, or compatibility checks against local project files. The hosted MCP cannot read local files.8586Claude Desktop config for the local server:8788```json89{ "mcpServers": { "capgo": { "command": "npx", "args": ["@capgo/cli@latest", "mcp"] } } }90```9192Setup guide for both servers: https://capgo.app/mcp (a page, not an MCP endpoint).9394No Capgo account yet: sign up at https://console.capgo.app (14-day free trial, no credit card). Docs: https://capgo.app/docs/ai/mcp/9596## Diagnostics Quick Path9798```bash99npx @capgo/cli@latest doctor # versions + setup problems (add --package-json for monorepos)100npx @capgo/cli@latest app todo com.example.app # onboarding checklist: done, skipped, pending101npx @capgo/cli@latest probe --platform android # would the backend serve an update to this config?102npx @capgo/cli@latest app debug com.example.app # live update events from a device103npx @capgo/cli@latest observe summary --days 7 # launch, crash, WebView findings, each with a next view104```105106`observe` has no session ID. Use `observe device DEVICE_ID --json` to get one device's timeline.107108## Monorepos109110Use `--package-json`, `--node-modules`, and, for dynamic root configs, `--capacitor-config <path>`. Keep the env selector active, for example `CAP_APP=web npx @capgo/cli@latest init --capacitor-config ./env-configs/capacitor.config.web.ts`.111112## Verification113114- `npx @capgo/cli@latest account whoami` prints the expected account ID and email, which proves auth works.115- `npx @capgo/cli@latest app list` shows the app. If it is missing, run `app add`.116- MCP: in Claude Code, `/mcp` lists `capgo` as connected, and a read-only prompt ("list my Capgo apps") returns data.117118## Error Handling119120| String | Fix |121| --- | --- |122| `No Capgo API key found. Run \`...\` first, then retry this command.` | The user runs `npx @capgo/cli@latest login`, or sets the `CAPGO_TOKEN` environment variable |123| `Missing argument, you need to provide a appId, or be in a capacitor project` | Pass the `appId` positionally or run from the folder containing `capacitor.config.*` |124| `Insufficient permissions for <key>` | The key's role is too low for this app or org. Use a key with the needed role |125| `🔐 Access Denied: Two-Factor Authentication Required` | The org enforces 2FA. See `capgo-organization-management` |126| `App <id> not found in database` | Run `npx @capgo/cli@latest app add <id>` or check the active account |127| Wrong account used | A global `~/.capgo` overrides a local `.capgo`. Set `CAPGO_TOKEN` |128129## Resources130131- CLI commands: https://capgo.app/docs/cli/commands/132- Hosted MCP: https://capgo.app/docs/ai/mcp/133- Local MCP: https://capgo.app/docs/cli/reference/mcp/