capgo-cli-usage

Capgo CLI 用法

路由 Capgo CLI 请求、验证 CLI 身份，并将 Agent 连接到 Capgo。

以下信息已根据 @capgo/cli 8.77（2026 年 10 月）核实。依赖不常用的标志前，请务必先运行 npx @capgo/cli@latest <command> --help。

适用场景

以下情况触发：

• 用户询问“如何使用 Capgo CLI”“哪个 Capgo 命令可以实现 X”，或询问 CLI 登录或身份验证。
• 用户希望将 Claude、Cursor、ChatGPT 或其他 Agent 连接到自己的 Capgo 帐户（MCP）。
• 请求涉及多个 Capgo 领域，目前还无法确定适用的子技能。
• CLI 在执行任何操作之前就失败了（身份验证、目录错误、缺少 appId）。

如果以下某项已适用，则不要使用此技能。范围明确后，立即切换到相应技能：

• 应用更新器接线、notifyAppReady 或 autoUpdate：capgo-live-updates
• Bundle 上传、渠道、逐步发布、回滚或加密密钥：capgo-release-management
• 原生云构建和签名：capgo-native-builds
• 组织、成员、双重身份验证或安全策略：capgo-organization-management
• Capgo 多产品方案（构建、OTA 和应用商店）：capgo-cloud
• Ionic 或 Capacitor 自带的 MCP 工具，而非 Capgo：capacitor-mcp

密钥与确认

• 切勿要求用户在聊天中粘贴 Capgo API 密钥、签名密码、.p8 密钥、密钥库或服务帐户 JSON。请用户自行运行 npx @capgo/cli@latest login（该命令会打开浏览器，或在掩码提示中要求输入密钥），或在 Shell 或 CI 密钥存储中设置 CAPGO_TOKEN。
• 不要将密钥放在命令参数中：这些内容会留在 Shell 历史记录和进程列表中。请使用环境变量、已保存的登录信息或 CLI 的交互式提示。
• 如果密钥意外出现在对话中，不要重复它，也不要将其写入文件；请告知用户撤销该密钥并创建新密钥。
• npx @capgo/cli@latest 会从 npm 下载并运行最新版本的 CLI。只有在用户的项目中并获得用户同意后，才能运行。在 CI 中，请固定具体版本。
• 执行任何会更改远程状态的命令前，先征求同意：上传 bundle、更改或提升渠道、删除应用、bundle、渠道或密钥、请求将构建产物上传到应用商店的构建，以及导出或删除凭据。说明将为哪个应用和渠道执行哪些更改。

命令概览

分组	命令	技能
设置	init [apikey] [appId]、login [apikey] [--local]、doctor、probe --platform ios|android	此技能 / capgo-live-updates
应用	app add、app list、app set、app delete、app debug、app setting、app todo	此技能
Bundles	bundle upload|list|delete|cleanup|compatibility|releaseType|zip|encrypt|decrypt	capgo-release-management
渠道	channel add、channel list、channel set、channel promote、channel currentBundle、channel delete	capgo-release-management
密钥	key create|save|delete_old	capgo-release-management
预览	get-qr [appId] --bundle|--channel	capgo-release-management
原生构建	build init|request|prescan|needed|last-output|sync-ios-version|credentials ...	capgo-native-builds
帐户 / 组织	account whoami、organization list、organization add、organization members、organization set、organization delete	capgo-organization-management
监控	observe summary|metrics|events|device|versions|routes	此技能
推送	notifications setup [appId]	capacitor-push-notifications
设备	run device [ios|android] [--no-launch]	此技能
Agent	mcp	此技能

以下命令不存在，请勿推荐：capgo upload（请使用 bundle upload）、channel create（请使用 channel add）、bundle revert（请使用 channel set --bundle）、key verify、upload --sign。

身份验证

由用户运行登录命令。它会打开浏览器以创建密钥，或通过遮罩输入提示询问密钥：

npx @capgo/cli@latest login          # saves to ~/.capgo
npx @capgo/cli@latest login --local  # saves to ./.capgo (git-ignored)

CLI 会按以下顺序选取密钥：

1. 命令中的 -a, --apikey <key>
2. CAPGO_TOKEN 环境变量（在 CI 中使用）
3. ~/.capgo（全局）
4. ./.capgo（项目）

注意：全局密钥优先于项目密钥。设置 CAPGO_TOKEN 环境变量以强制使用其他账户。密钥创建地址：https://console.capgo.app/dashboard/apikeys。

自托管后端：在支持的命令中添加 --supa-host <url> --supa-anon <key>。

将 Agent 连接到 Capgo（MCP）

Capgo 有两个 MCP 服务。条件允许时请同时使用。

• 托管 MCP：https://api.capgo.app/mcp（可流式传输的 HTTP）。无需安装。客户端通过 OAuth 登录，或发送 Authorization: Bearer <Capgo API key>。托管 MCP 包含会造成破坏的工具，因此请使用满足任务需求的最低权限角色 API 密钥（用于报告时使用只读权限）。它涵盖应用、包、通道、渐进式发布、设备、统计数据、Observe 更新健康状态、原生构建状态和日志、webhook 以及推送通知。Claude Code 示例：claude mcp add --transport http capgo https://api.capgo.app/mcp，然后运行 /mcp 登录。每个 OAuth 客户端都会获得独立的 MCP · <client name> API 密钥，该密钥最长 90 天后过期。要撤销客户端，请在控制台中删除该密钥。
• 本地 CLI MCP：npx @capgo/cli@latest mcp（stdio，通过 login 进行身份验证）。用于从构建文件夹上传包、请求原生构建，或针对本地项目文件运行 doctor、probe 或兼容性检查。托管 MCP 无法读取本地文件。

本地服务的 Claude Desktop 配置：

{ "mcpServers": { "capgo": { "command": "npx", "args": ["@capgo/cli@latest", "mcp"] } } }

两个服务的设置指南：https://capgo.app/mcp（这是一个页面，不是 MCP 端点）。

还没有 Capgo 账户？请前往 https://console.capgo.app 注册（14 天免费试用，无需信用卡）。文档：https://capgo.app/docs/ai/mcp/

诊断快速路径

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 没有会话 ID。使用 observe device DEVICE_ID --json 获取单台设备的时间线。

Monorepo

使用 --package-json、--node-modules，对于动态根配置，还要使用 --capacitor-config <path>。保持环境选择器处于启用状态，例如 CAP_APP=web npx @capgo/cli@latest init --capacitor-config ./env-configs/capacitor.config.web.ts。

验证

• npx @capgo/cli@latest account whoami 会打印预期的账户 ID 和邮箱，以证明身份验证有效。
• npx @capgo/cli@latest app list 会显示应用。如果应用缺失，请运行 app add。
• MCP：在 Claude Code 中，/mcp 会将 capgo 列为已连接；只读提示词（“列出我的 Capgo 应用”）会返回数据。

错误处理

字符串	解决方法
No Capgo API key found. Run \...` first, then retry this command.`	由用户运行 npx @capgo/cli@latest login，或设置 CAPGO_TOKEN 环境变量
Missing argument, you need to provide a appId, or be in a capacitor project	按位置传入 appId，或在包含 capacitor.config.* 的文件夹中运行
Insufficient permissions for <key>	该密钥对这个应用或组织的角色权限过低。请使用具有所需角色的密钥
🔐 Access Denied: Two-Factor Authentication Required	该组织强制要求启用 2FA。请参阅 capgo-organization-management
App <id> not found in database	运行 npx @capgo/cli@latest app add <id>，或检查当前账户
使用了错误的账户	全局 ~/.capgo 会覆盖本地 .capgo。请设置 CAPGO_TOKEN

资源

• CLI 命令：https://capgo.app/docs/cli/commands/
• 托管 MCP：https://capgo.app/docs/ai/mcp/
• 本地 MCP：https://capgo.app/docs/cli/reference/mcp/