SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场capgo-cli-usage

capgo-cli-usage

部署与运维

查看项目

更新于 10-14 22:45

技能介绍

用途

本技能是 Capgo CLI（npx @capgo/cli@latest）的入口，用于：路由 Capgo CLI 相关请求、对 CLI 进行认证、把智能体连接到 Capgo 账户。

适用触发场景：

  • 用户询问“如何使用 Capgo CLI”“某个功能对应哪条 Capgo 命令”，或询问 CLI 登录与认证。
  • 用户希望把 Claude、Cursor、ChatGPT 或其他智能体连接到自己的 Capgo 账户（MCP）。
  • 请求横跨多个 Capgo 领域，尚不清楚应使用哪个子技能。
  • CLI 在开始工作前就失败（认证、目录错误、缺少 appId）。

当范围明确后，应切换到对应子技能：应用更新接线、notifyAppReady、autoUpdate 用 capgo-live-updates；Bundle 上传、渠道、灰度发布、回滚、加密密钥用 capgo-release-management；原生云构建与签名用 capgo-native-builds；组织、成员、2FA、安全策略用 capgo-organization-management；多产品 Capgo 套餐（构建、OTA、商店）用 capgo-cloud；Ionic 或 Capacitor 自带的 MCP 工具用 capacitor-mcp。

命令总览

  • 安装/初始化：init [apikey] [appId]、login [apikey] [--local]、doctor、probe --platform ios|android
  • 应用：app add、app list、app set、app delete、app debug、app setting、app todo
  • Bundle：bundle upload|list|delete|cleanup|compatibility|releaseType|zip|encrypt|decrypt
  • 渠道：channel add、channel list、channel set、channel promote、channel currentBundle、channel delete
  • 密钥：key create|save|delete_old
  • 预览：get-qr [appId] --bundle|--channel
  • 原生构建：build init|request|prescan|needed|last-output|sync-ios-version|credentials ...
  • 账户/组织：account whoami、organization list、organization add、organization members、organization set、organization delete
  • 观测：observe summary|metrics|events|device|versions|routes
  • 推送：notifications setup [appId]
  • 设备：run device [ios|android] [--no-launch]
  • 智能体：mcp

以下命令不存在，不要建议：capgo upload（用 bundle upload）、channel create（用 channel add）、bundle revert（用 channel set --bundle）、key verify、upload --sign。

认证

npx @capgo/cli@latest login YOUR_API_KEY          # 保存到 ~/.capgo
npx @capgo/cli@latest login YOUR_API_KEY --local  # 保存到 ./.capgo（已被 git 忽略）

CLI 按以下顺序选取密钥：

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

注意：全局密钥优先于项目密钥。要强制使用其他账户，请传 -a 或使用 CAPGO_TOKEN 环境变量。密钥在 https://console.capgo.app/dashboard/apikeys 创建。如果用户已提供密钥，直接使用，不要回显。

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

将智能体连接到 Capgo（MCP）

Capgo 有两个 MCP 服务器，可用时两者都用。

托管 MCP：https://api.capgo.app/mcp（streamable HTTP），无需安装。客户端通过 OAuth 登录，或发送 Authorization: Bearer <Capgo API key>。托管 MCP 包含破坏性工具，因此请使用满足任务所需的最小角色密钥（只读用于报表）。它覆盖应用、Bundle、渠道、渐进式发布、设备、统计、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 认证）。用于从构建文件夹上传 Bundle、请求原生构建，或针对本地项目文件运行 doctor、probe、兼容性检查。托管 MCP 无法读取本地文件。

本地服务器的 Claude Desktop 配置：

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

https://capgo.app/mcp 是另一个服务器：仅用于公开文档发现，无账户访问权限。

尚无 Capgo 账户：在 https://console.capgo.app 注册（14 天免费试用，无需信用卡）。文档：https://capgo.app/docs/ai/mcp/

诊断快速路径

npx @capgo/cli@latest doctor                         # 版本 + 安装问题（monorepo 加 --package-json）
npx @capgo/cli@latest app todo com.example.app       # 上手清单：已完成、已跳过、待处理
npx @capgo/cli@latest probe --platform android       # 后端是否会向此配置下发更新？
npx @capgo/cli@latest app debug com.example.app      # 来自设备的实时更新事件
npx @capgo/cli@latest observe summary --days 7       # 启动、崩溃、WebView 发现，各带下一步视图

observe 没有 session 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 <key>、设置 CAPGO_TOKEN 环境变量，或使用 -a。
  • 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，使用 -a 或 CAPGO_TOKEN。

资源

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

限制

资料基于 @capgo/cli 8.77（2026 年 10 月）核对。依赖不常用参数前，始终先运行 npx @capgo/cli@latest <command> --help。