🔹 Build

🏗️ 通过 Capgo Cloud 管理 iOS/Android Native Build。

构建权限与输出

所有 Capgo 方案均支持云端 Native Build。构建凭据绝不会存储在 Capgo 服务器上：它们仅用于构建过程，完成后即被删除。构建输出可以选择上传，并提供有时效性的下载链接。

优先保存凭据

npx @capgo/cli build credentials save --appId YOUR_APP_ID --platform ios
npx @capgo/cli build credentials save --appId YOUR_APP_ID --platform android

在 CI 中获取输出 URL

传入 --output-record 以持久化下载 URL 和 QR code，然后使用 build last-output 来读取它：

npx @capgo/cli build request APP_ID --platform android --output-upload --output-record /tmp/build.json
npx @capgo/cli build last-output --path /tmp/build.json --field outputUrl

🔹 必需

npx @capgo/cli@latest build needed

🧭 如果需要 Native Build，则打印 “yes” 并以 code 1 退出；否则打印 “no” 并以 code 0 退出。命令失败则以 code 2 退出。

示例：

npx @capgo/cli@latest build needed com.example.app --channel production --verbose

选项：

参数	类型	描述
-a	string	API 用于关联您的账户的密钥
-c	string	用于对比的 Channel。默认为 CapacitorUpdater.defaultChannel 或公共默认 Channel
—package-json	string	Monorepo 中 package.json 文件的路径（以逗号分隔）
—node-modules	string	Monorepo 中 node_modules 目录的路径（以逗号分隔）
—verbose	boolean	启用详细日志输出
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase anon key（用于自托管）

🚀 Init

别名： onboarding

npx @capgo/cli@latest build init

以交互方式设置 build 凭据（iOS：自动配置证书和描述文件；Android：keystore + Google OAuth，用于配置 GCP 服务账号并发送 Play Console 邀请）

选项：

参数	类型	描述
-a	string	API 用于关联您的账户的密钥
-p	string	要进行 onboarding 的平台 (ios 或 android)。如果省略，当仅存在一个原生文件夹时会自动检测；否则会进行 prompt。
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—no-analytics	boolean	在此次运行中禁用 build onboarding analytics 和 terminal replay

🔹 请求

npx @capgo/cli@latest build request

向 Capgo Cloud 请求 Native Build。 该命令会将您的项目目录压缩并 upload 到 Capgo 进行构建。 构建完成后将直接发送至应用商店。 凭据绝不会存储在 Capgo 服务器上；构建完成后即会被删除。请在请求构建前保存好凭据：

npx @capgo/cli build credentials save --appId APP_ID --platform ios

示例：

npx @capgo/cli@latest build request com.example.app --platform ios --path .

选项：

参数	类型	描述
—path	string	要构建的项目目录路径（默认：当前目录）
—node-modules	string	Monorepo 模式下 node_modules 的路径（以逗号分隔）
—platform	string	目标平台：ios 或 android（必填）
—build-mode	string	构建模式：debug 或 release（默认：release）
—build-certificate-base64	string	iOS：Base64 编码的 .p12 证书
—p12-password	string	iOS: P12 证书密码（若证书无密码则可选）
—apple-id	string	iOS: 用于上传 App-specific password 的 Apple ID 邮箱（可作为 App Store Connect API key 的替代方案）
—apple-app-specific-password	string	iOS: 用于 TestFlight 上传的 App-specific password (xxxx-xxxx-xxxx-xxxx)
—apple-app-id	string	iOS: App Store Connect 数字 App ID（需配合 —apple-id 和 —apple-app-specific-password 使用）
—apple-key-id	string	iOS: App Store Connect API Key ID
—apple-issuer-id	string	iOS：App Store Connect Issuer ID
—apple-key-content	string	iOS: Base64 编码的 App Store Connect API 密钥 (.p8)
—app-store-connect-team-id	string	iOS：App Store Connect Team ID
—ios-scheme	string	iOS: 用于构建的 Xcode scheme (默认值: App)
—ios-target	string	iOS: 用于读取构建设置的 Xcode target (默认值: 与 scheme 相同)
—xcode-version	string	iOS: 在指定 Xcode 版本的机器上进行构建 (例如 26, 26.0.1, 27)。主版本号可匹配任何次版本号。默认值: 任意机器。优先级: CLI > 环境变量 (CAPGO_IOS_XCODE_VERSION) > 已保存的凭据
—ios-distribution	string	iOS: 分发模式
—ios-provisioning-profile	string	iOS: Provisioning profile 路径或 bundleId=path 映射 (可重复使用)
—android-keystore-file	string	Android: Base64 编码的 keystore 文件
—keystore-key-alias	string	Android：Keystore 密钥别名
—keystore-key-password	string	Android: Keystore key 密码
—keystore-store-password	string	Android: Keystore store 密码
—play-config-json	string	Android: Base64 编码的 Google Play 服务账号 JSON
—android-flavor	string	Android: 要构建的 Product flavor（例如 production）。如果项目包含多个 flavor，则此项必填。
—android-track	string	Android: 本次上传对应的 Google Play track（internal, alpha, beta, production）。若未指定 —submit-to-store-review，默认值为 internal；若指定了 —submit-to-store-review 且未设置 track，则为 production。优先级：CLI > env > 已保存的凭据
—android-release-status	string	Android: Google Play 发布状态（draft, completed, inProgress, halted）。若未指定 —submit-to-store-review，默认值为 draft；若指定了 —submit-to-store-review 且未设置 status，则为 completed。优先级：CLI > env > 已保存的凭据
—in-app-update-priority	string	Android: 本次发布的 Google Play 应用内更新优先级（整数 0–5；数值越高越紧急）。详见 https://developer.android.com/guide/playcore/in-app-updates。优先级：CLI > env > 已保存的凭据
—no-playstore-upload	boolean	跳过本次构建的 Play Store 上传（会将已保存的 Play 配置置空）。需要配合 —output-upload 使用。
—submit-to-store-review	boolean	上传完成后，将商店版本提交审核，而不是将其保持为草稿或未激活状态。在 Android 上，这默认提交到 production 轨道且 release_status 为 completed（可通过 —android-track / PLAY_STORE_TRACK 和 —android-release-status / PLAY_STORE_RELEASE_STATUS 进行覆盖）。在 iOS 上，这会将处理好的 TestFlight build 提交至 App Store 审核。
—store-release-name	string	商店发布名称/版本标签。Android 会将其作为 Google Play 的 version_name 发送；iOS 在创建或复用可编辑版本时，将其作为 App Store 版本号使用。
—store-release-notes	string	默认的商店发布说明。Android 将其作为 Play 的更新日志；iOS 则将其作为 App Store “新功能”文本的备选内容。
—store-release-notes-locale	string	本地化的商店发布说明（可多次使用），例如 —store-release-notes-locale en-US=“Bug fixes” —store-release-notes-locale fr-FR=“Corrections”。
—ios-testflight-groups	string	iOS：可选参数，使用逗号分隔的 TestFlight 外部测试组名称或 ID，用于外部 Beta 测试分发。
—ios-automatic-release	boolean	iOS：在 Apple 审核通过后自动发布 App Store 版本。默认设置为手动发布。
—no-ios-automatic-release	boolean	iOS：Apple 审核通过后，让 App Store 版本保持待手动发布状态。
—output-upload	boolean	仅针对本次 build 覆盖输出上传行为（启用）。优先级：CLI > 环境变量 > 已保存的凭据
—no-output-upload	boolean	仅针对本次 build 覆盖输出上传行为（禁用）。优先级：CLI > 环境变量 > 已保存的凭据
—output-retention	string	仅针对本次 build 覆盖输出链接的 TTL（1h 至 7d）。示例：1h、6h、2d。优先级：CLI > 环境变量 > 已保存的凭据
—output-record	string	build 成功后，将 JSON 记录（jobId、status、outputUrl、qrCodeAscii、qrCodePngPath、finishedAt）写入指定路径。同时会在该路径旁写入一个 PNG QR code，并带有 .qr.png 后缀。读回字段请使用 build last-output.
—no-cache	boolean	跳过构建缓存恢复 以及 本次构建不保存新的缓存条目。每个 App 默认启用构建缓存。
—cache-key	string	按环境、分支或 Android flavor 划分构建缓存（例如 prod, staging）。省略则每个 App 共用一个默认缓存。
—no-skip-build-number-bump	boolean	覆盖已保存的凭据，仅本次构建重新启用 build number 自动递增。
—skip-marketing-version-bump	boolean	当 App 已发布时，跳过自动递增营销版本号（CFBundleShortVersionString / versionName）。
—sync-ios-version	boolean	iOS：上传项目前，从 package.json 同步 Xcode 的 MARKETING_VERSION。
—ai-analytics	boolean	构建失败时，将 logs 发送至 Capgo AI 进行诊断。在交互式终端中，此选项会跳过前置确认；在 CI 环境中，则会自动上传并将分析结果打印到 stderr。
—no-prescan	boolean	跳过自动构建前扫描 (pre-build scan)
—prescan-ignore-fatal	boolean	运行构建前扫描，但即使出错也不阻塞构建（仅报告）
—prescan-skip	string	通过 ID 跳过特定的 prescan 检查（可多次使用或用逗号分隔）。其他检查仍会运行。
—prescan-warn	string	通过 ID 将特定的 prescan 检查降级为警告（可多次使用或用逗号分隔）。检查仍会运行。
—fail-on-warnings	boolean	将 prescan 警告视为致命错误
—send-logs-to-support	boolean	若 CI/CD 构建失败，自动将构建日志上传至 Capgo 支持团队（无需通过邮件）。Capgo 支持团队会收到通知并随后通过邮件跟进。此功能与 —ai-analytics 叠加使用。
—send-logs	boolean	—send-logs-to-support 的弃用别名
-a	string	API 用于关联您的账户的密钥
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase anon key（用于自托管）
—verbose	boolean	启用详细日志输出

构建缓存： 默认情况下，Capgo 会按应用恢复并保存编译后的 Native 产物（CocoaPods、Gradle 及相关输出）。使用 --cache-key 可将 RC 和生产环境缓存分开；使用 --no-cache 进行一次性全新构建。API 集成可以通过 cache_key 或 cache_enabled: false 在构建请求的 payload 中传递参数。详见 构建缓存 以及 故障排除：缓存恢复错误.

🔹 Sync-ios-version

npx @capgo/cli@latest build sync-ios-version

根据 package.json 同步本地 iOS Xcode 的 MARKETING_VERSION。

示例：

npx @capgo/cli@latest build sync-ios-version --path .

选项：

参数	类型	描述
—path	string	项目目录路径 (默认：当前目录)
—check	boolean	仅进行检查；若 MARKETING_VERSION 不同步则返回非零退出码

🔹 预扫描

npx @capgo/cli@latest build prescan

Scan your project and saved credentials for problems that would fail a cloud build — before uploading anything. Checks credentials (expiry, passwords, profile pairing), project state (cap sync, node_modules layout), and platform config. Runs automatically inside build request; 此命令可独立运行（例如在 CI 中）。 请参阅 预扫描检查 以获取完整的检查目录以及如何 --skip / --warn 单个规则。

选项：

参数	类型	描述
—platform	string	目标平台：ios 或 android（必填）
—path	string	项目目录路径（默认：当前目录）
-a	string	API 用于关联您的账户的密钥
—android-flavor	string	Android：构建时使用的 product flavor
—ios-dist	string	iOS：用于校验的 distribution mode
—json	boolean	输出机器可读的 JSON 报告
—fail-on-warnings	boolean	发现警告时以非零状态码退出 (适用于 CI)
—ignore-fatal	boolean	诊断模式：报告所有问题但始终以状态码 0 退出
—skip	string	通过 ID 跳过特定的检查 (可多次使用或用逗号分隔)
—warn	string	通过 ID 将特定检查降级为警告 (可多次使用或用逗号分隔)
—verbose	boolean	启用详细日志输出
—supa-host	string	自定义 Supabase host URL（用于自托管或 Capgo 开发）
—supa-anon	string	自定义 Supabase anon key（用于自托管）

🔹 Last-output

npx @capgo/cli@latest build last-output

读取上一次写入的构建输出记录 build request --output-record. 默认输出完整 JSON，使用 —field 输出单个字段，或使用 —qr 输出 ASCII QR code。在 CI 中很方便，可抓取下载 URL 或 QR 码，回帖到 PR 或 issue。 示例： npx @capgo/cli build last-output —path /tmp/build.json npx @capgo/cli build last-output —path /tmp/build.json —field outputUrl npx @capgo/cli build last-output —path /tmp/build.json —qr

选项：

参数	类型	描述
—path	string	由 —output-record 写入的 JSON 记录路径（必填）
—field	string	打印单个字段（可选值：jobId, appId, platform, buildMode, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt, schemaVersion）
—qr	boolean	打印渲染后的 ASCII QR code（—field qrCodeAscii 的快捷方式）

🔹 凭据

管理存储在本机的 build 凭据。 🔒 安全：

• 凭据已保存到 ~/.capgo-credentials/credentials.json（全局）或 .capgo-credentials.json（本地）
• 构建时会发送至 Capgo，但绝不会永久存储
• 构建完成后会立即从 Capgo 中删除
• 构建输出可选择上传，以获取限时下载链接 📚 文档： iOS 配置： https://capgo.app/docs/cli/cloud-build/ios/ Android 配置： https://capgo.app/docs/cli/cloud-build/android/

🔹 Apple-key

别名： asc-key

npx @capgo/cli@latest build credentials apple-key

通过 macOS 引导助手创建 App Store Connect 团队 API 密钥（仅限 macOS）。 它会打开一个原生窗口，在嵌入式浏览器中引导你完成 Apple App Store Connect 的 UI 操作，自动获取 Issuer ID + Key ID，拦截一次性的 .p8 文件，向 Apple 进行验证，并将其保存至 ~/.appstoreconnect/private_keys。 进度统计数据会发送至 Capgo 进行分析（可通过 CAPGO_DISABLE_TELEMETRY 禁用）。 npx @capgo/cli build credentials apple-key —appId com.example.app

示例：

Example:

选项：

参数	类型	描述
-a	string	API 用于关联您的账户的密钥
—appId	string	将捕获的密钥保存到此应用的 iOS 构建凭据中
—local	boolean	将凭据保存至项目专属的 .capgo-credentials.json，而非全局文件
—json	boolean	以 JSON 格式打印获取到的 Key ID / Issuer ID / .p8 路径

🔹 保存

npx @capgo/cli@latest build credentials save

在本地保存 iOS 或 Android 的构建凭据。 凭据存储在：

• ~/.capgo-credentials/credentials.json (默认，全局)
• 项目根目录下的 .capgo-credentials.json (使用 —local 标志) ⚠️ 构建前必做：在请求构建之前，必须先保存凭据。 🔒 这些凭据绝不会永久存储在 Capgo 服务器上。 构建完成后会立即删除。 📚 配置指南： iOS: https://capgo.app/docs/cli/cloud-build/ios/ Android: https://capgo.app/docs/cli/cloud-build/android/ npx @capgo/cli build credentials save —platform ios
  —certificate ./cert.p12 —p12-password “password”
  —ios-provisioning-profile ./profile.mobileprovision
  —apple-key ./AuthKey.p8 —apple-key-id “KEY123”
  —apple-issuer-id “issuer-uuid” —apple-team-id “team-id” 多 Target 示例 (app + widget extension): npx @capgo/cli build credentials save —platform ios
  —ios-provisioning-profile ./App.mobileprovision
  —ios-provisioning-profile com.example.widget=./Widget.mobileprovision
  … npx @capgo/cli build credentials save —平台 android
  —keystore ./release.keystore —keystore-alias “my-key”
  —keystore-key-password “key-pass”
  —play-config ./service-account.json 本地存储 (按项目): npx @capgo/cli build credentials save —local —platform ios …

示例：

iOS Example:

选项：

参数	类型	描述
—appId	string	App ID (例如: com.example.app) (必填)
—platform	string	Platform: ios 或 android (必填)
—certificate	string	iOS: .p12 证书文件路径
—ios-provisioning-profile	string	iOS: Provisioning profile 路径或 bundleId=path (可重复)
—p12-password	string	iOS: 证书密码 (若证书无密码则可选)
—apple-key	string	iOS: App Store Connect API .p8 密钥路径
—apple-key-id	string	iOS: App Store Connect API Key ID
—apple-issuer-id	string	iOS：App Store Connect Issuer ID
—apple-team-id	string	iOS：App Store Connect Team ID
—ios-distribution	string	iOS: 发行模式
—apple-id	string	iOS: 用于上传 App 专用密码的 Apple ID 邮箱 (作为 App Store Connect API 密钥的替代方案)
—apple-app-specific-password	string	iOS: 用于 TestFlight 上传的 App 专用密码 (xxxx-xxxx-xxxx-xxxx)
—apple-app-id	string	iOS: App Store Connect App ID 数字 ID (需配合 —apple-id 和 —apple-app-specific-password 使用)
—keystore	string	Android: Keystore 文件路径 (.keystore 或 .jks)
—keystore-alias	string	Android: Keystore 密钥别名
—keystore-key-password	string	Android: Keystore 密钥密码
—keystore-store-password	string	Android: Keystore 存储库密码
—play-config	string	Android: Play Store 服务账号 JSON 路径
—android-flavor	string	Android: 要构建的 Product flavor（例如 production）。如果项目包含多个 flavor，则此项必填。
—in-app-update-priority	string	Android: Google Play 应用内更新优先级（整数 0–5；数值越高越紧急）。若省略则保持 Play Store 原有值不变。
—local	boolean	保存到项目根目录下的 .capgo-credentials.json，而不是全局的 ~/.capgo-credentials/
—output-upload	boolean	将构建产物 (IPA/APK/AAB) 上传至 Capgo 存储并打印下载链接
—no-output-upload	boolean	不要将构建产物 (IPA/APK/AAB) 上传至 Capgo 存储
—output-retention	string	输出链接 TTL：1h 至 7d（默认：1h）。示例：1h、6h、2d
—skip-build-number-bump	boolean	在后续构建中跳过 build number/version code 的自动递增
—no-skip-build-number-bump	boolean	重新启用 build number 自动递增（默认行为）
—skip-marketing-version-bump	boolean	当应用已发布时，在后续构建中跳过自动营销版本号更新
—no-skip-marketing-version-bump	boolean	重新启用自动营销版本号更新（默认行为）

📋 列出

npx @capgo/cli@latest build credentials list

列出已保存的构建凭据（密码已脱敏）。 显示当前保存的凭据（包括全局和本地凭据）。 示例： npx @capgo/cli build credentials list # 列出所有应用 npx @capgo/cli build credentials list —appId com.example.app # 列出特定应用

选项：

参数	类型	描述
—appId	string	要列出的 App ID（可选，若省略则列出所有）
—local	boolean	仅列出本地 .capgo-credentials.json 中的凭据

🔹 Clear

npx @capgo/cli@latest build credentials clear

清除已保存的 build 凭据。 从存储中移除凭据。 使用 —appId 和 —platform 来指定特定的凭据。 示例： npx @capgo/cli build credentials clear # 清除所有 App（全局） npx @capgo/cli build credentials clear —local # 清除本地凭据 npx @capgo/cli build credentials clear —appId com.example.app —platform ios

选项：

参数	类型	描述
—appId	string	要清除的 App ID（可选，若省略则清除所有 App）
—platform	string	要清除的平台：ios 或 android（可选，若省略则清除所有平台）
—local	boolean	从本地 .capgo-credentials.json 而非全局配置中清除

🔹 更新

npx @capgo/cli@latest build credentials update

无需重新提供所有信息即可更新特定凭据。 仅需提供想要更改的字段即可更新现有凭据。 平台将根据你提供的选项自动检测。 示例： npx @capgo/cli build credentials update —ios-provisioning-profile ./new-profile.mobileprovision npx @capgo/cli build credentials update —local —keystore ./new-keystore.jks

选项：

参数	类型	描述
—appId	string	App ID（若省略，则从 capacitor.config 自动检测）
—platform	string	平台：ios 或 android（根据选项自动检测）
—local	boolean	更新本地 .capgo-credentials.json 而非全局文件
—certificate	string	P12 证书文件的路径
—ios-provisioning-profile	string	Provisioning profile 路径或 bundleId=path（可重复使用，默认采用增量合并方式）
—overwrite-ios-provisioning-map	boolean	替换整个 provisioning map 而不是进行合并（默认：merge）
—p12-password	string	P12 证书密码
—apple-key	string	App Store Connect API 密钥路径 (.p8 文件)
—apple-key-id	string	App Store Connect API Key ID
—apple-issuer-id	string	App Store Connect Issuer ID
—apple-team-id	string	App Store Connect 团队 ID
—apple-id	string	iOS: 用于上传 app-specific password 的 Apple ID 邮箱（作为 App Store Connect API 密钥的替代方案）
—apple-app-specific-password	string	iOS: 用于 TestFlight 上传的 App-specific password (xxxx-xxxx-xxxx-xxxx)
—apple-app-id	string	iOS: App Store Connect 的数字 App ID（需配合 —apple-id 和 —apple-app-specific-password 使用）
—ios-distribution	string	iOS: 发行模式
—keystore	string	Keystore 文件路径 (.keystore 或 .jks)
—keystore-alias	string	Keystore 密钥别名
—keystore-key-password	string	Keystore 密钥密码
—keystore-store-password	string	Keystore 存储库密码
—play-config	string	Google Play 服务账号 JSON 文件的路径
—android-flavor	string	Android: 要构建的 Product flavor（例如 production）。如果项目包含多个 flavor，则此项必填。
—in-app-update-priority	string	Android：后续发布的 Google Play 应用内更新优先级（整数 0–5；数值越高越紧急）。
—output-upload	boolean	将构建产物 (IPA/APK/AAB) 上传至 Capgo 存储并打印下载链接
—no-output-upload	boolean	不要将构建产物 (IPA/APK/AAB) 上传至 Capgo 存储
—output-retention	string	输出链接 TTL：1h 至 7d。示例：1h, 6h, 2d
—skip-build-number-bump	boolean	在后续构建中跳过 build number/version code 的自动递增
—no-skip-build-number-bump	boolean	重新启用 build number 自动递增（默认行为）
—skip-marketing-version-bump	boolean	当 App 已发布时，跳过后续构建中自动递增 marketing version
—no-skip-marketing-version-bump	boolean	重新启用自动营销版本号递增（默认行为）

🔹 管理

npx @capgo/cli@latest build credentials manage

交互式管理已保存的构建凭据。 浏览存储的凭据、查看配置详情、导出适用于 CI/CD 的 .env 文件，或删除特定平台的凭据。复用了与以下相同的 TUI： capgo init。 示例： npx @capgo/cli build credentials manage npx @capgo/cli build credentials manage —appId com.example.app npx @capgo/cli build credentials manage —appId com.example.app —platform ios npx @capgo/cli build credentials manage —local

选项：

参数	类型	描述
—appId	string	要管理的 App ID（可选，若省略则会提示选择）
—platform	string	要管理的平台：ios 或 android（可选，若省略则会提示选择）
—local	boolean	仅浏览本地的 .capgo-credentials.json

🔹 迁移

npx @capgo/cli@latest build credentials migrate

将旧版 provisioning profile 迁移至新的多目标格式。 将 BUILD_PROVISION_PROFILE_BASE64 转换为 CAPGO_IOS_PROVISIONING_MAP。 自动从您的 Xcode 项目中获取主 bundle ID。 npx @capgo/cli build credentials migrate —platform ios

示例：

Example:

选项：

参数	类型	描述
—appId	string	App ID（若未提供，将从 capacitor.config 自动检测）
—platform	string	平台（仅支持 ios）
—local	boolean	从本地 .capgo-credentials.json 迁移，而非全局配置