🔹 build

🏗️ Manage native iOS/Android builds through Capgo Cloud.

Build access and output

Native cloud build requests are currently in limited beta and access is restricted. Build credentials are never stored on Capgo servers: they are used only for the build and then deleted. Build outputs can optionally be uploaded with time-limited download links.

Save credentials first

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

Capture an output URL in CI

Pass --output-record to persist the download URL and QR code, then use build last-output to read it:

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

🔹 Needed

npx @capgo/cli@latest build needed

🧭 Print “yes” and exit with code 1 if a native build is required; otherwise print “no” and exit with code 0. Command failures exit with code 2.

Example:

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

Options:

Param	Type	Description
-a	string	API key to link to your account
-c	string	Channel to compare against. Defaults to CapacitorUpdater.defaultChannel or the public default channel
—package-json	string	Paths to package.json files for monorepos (comma-separated)
—node-modules	string	Paths to node_modules directories for monorepos (comma-separated)
—verbose	boolean	Enable verbose output with detailed logging
—supa-host	string	Custom Supabase host URL (for self-hosting or Capgo development)
—supa-anon	string	Custom Supabase anon key (for self-hosting)

🚀 Init

Alias: onboarding

npx @capgo/cli@latest build init

Set up build credentials interactively (iOS: certificates + profiles automated; Android: keystore + Google OAuth provisions GCP service account and Play Console invite)

Options:

Param	Type	Description
-a	string	API key to link to your account
-p	string	Platform to onboard (ios or android). If omitted, auto-detects when only one native folder exists; prompts otherwise.
—supa-host	string	Custom Supabase host URL (for self-hosting or Capgo development)
—no-analytics	boolean	Disable build onboarding analytics and terminal replay for this run

🔹 Request

npx @capgo/cli@latest build request

Request a native build from Capgo Cloud. This command will zip your project directory and upload it to Capgo for building. The build will be processed and sent directly to app stores. Credentials are never stored on Capgo servers; they are deleted after the build. Save them before requesting a build:

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

Example:

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

Options:

Param	Type	Description
—path	string	Path to the project directory to build (default: current directory)
—node-modules	string	Paths to node_modules directories for monorepos (comma-separated)
—platform	string	Target platform: ios or android (required)
—build-mode	string	Build mode: debug or release (default: release)
—build-certificate-base64	string	iOS: Base64-encoded .p12 certificate
—p12-password	string	iOS: Certificate password (optional if cert has no password)
—apple-id	string	iOS: Apple ID email for app-specific password uploads (alternative to App Store Connect API key)
—apple-app-specific-password	string	iOS: App-specific password (xxxx-xxxx-xxxx-xxxx) for TestFlight uploads
—apple-app-id	string	iOS: Numeric App Store Connect app id (required together with —apple-id and —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-encoded App Store Connect API key (.p8)
—app-store-connect-team-id	string	iOS: App Store Connect Team ID
—ios-scheme	string	iOS: Xcode scheme to build (default: App)
—ios-target	string	iOS: Xcode target for reading build settings (default: same as scheme)
—ios-distribution	string	iOS: Distribution mode
—ios-provisioning-profile	string	iOS: Provisioning profile path or bundleId=path mapping (repeatable)
—android-keystore-file	string	Android: Base64-encoded keystore file
—keystore-key-alias	string	Android: Keystore key alias
—keystore-key-password	string	Android: Keystore key password
—keystore-store-password	string	Android: Keystore store password
—play-config-json	string	Android: Base64-encoded Google Play service account JSON
—android-flavor	string	Android: Product flavor to build (e.g. production). Required if your project has multiple flavors.
—in-app-update-priority	string	Android: Google Play in-app update priority for this release (integer 0–5; higher = more urgent). See https://developer.android.com/guide/playcore/in-app-updates. Precedence: CLI > env > saved credentials
—no-playstore-upload	boolean	Skip Play Store upload for this build (nulls out saved play config). Requires —output-upload.
—submit-to-store-review	boolean	After upload, submit the store release for review instead of leaving it as a draft/inactive build. Android marks the Play release completed; iOS submits the processed TestFlight build to App Store review.
—store-release-name	string	Store release name/version label. Android sends this as the Google Play version_name; iOS uses it as the App Store version when creating or reusing the editable version.
—store-release-notes	string	Default store release notes. Android uses this as the Play changelog; iOS uses it as the fallback App Store What’s New text.
—store-release-notes-locale	string	Localized store release notes (repeatable), for example —store-release-notes-locale en-US=“Bug fixes” —store-release-notes-locale fr-FR=“Corrections”.
—ios-testflight-groups	string	iOS: optional comma-separated TestFlight external group names or IDs for external beta distribution.
—ios-automatic-release	boolean	iOS: automatically release the App Store version after Apple approval. Default is manual release.
—no-ios-automatic-release	boolean	iOS: keep the App Store version waiting for manual release after Apple approval.
—output-upload	boolean	Override output upload behavior for this build only (enable). Precedence: CLI > env > saved credentials
—no-output-upload	boolean	Override output upload behavior for this build only (disable). Precedence: CLI > env > saved credentials
—output-retention	string	Override output link TTL for this build only (1h to 7d). Examples: 1h, 6h, 2d. Precedence: CLI > env > saved credentials
—output-record	string	After a successful build, write a JSON record (jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) to a path. A PNG QR code is also written next to that path with the .qr.png suffix. Read fields back with build last-output.
—no-skip-build-number-bump	boolean	Override saved credentials to re-enable automatic build number incrementing for this build only.
—skip-marketing-version-bump	boolean	Skip automatic marketing version (CFBundleShortVersionString / versionName) bump when the app is already released.
—sync-ios-version	boolean	iOS: sync Xcode MARKETING_VERSION from package.json before uploading the project.
—ai-analytics	boolean	On build failure, send logs to Capgo AI for diagnosis. In interactive terminals this skips the upfront confirmation; in CI this auto-uploads and prints the analysis to stderr.
—no-prescan	boolean	Skip the automatic pre-build scan
—prescan-ignore-fatal	boolean	Run the pre-build scan but never block the build (report only)
—fail-on-warnings	boolean	Treat prescan warnings as fatal
—send-logs-to-support	boolean	On a CI/CD build failure, automatically upload the build logs to Capgo support (no email required). Capgo support is notified and will follow up by email. Additive to —ai-analytics.
—send-logs	boolean	Deprecated alias for —send-logs-to-support
-a	string	API key to link to your account
—supa-host	string	Custom Supabase host URL (for self-hosting or Capgo development)
—supa-anon	string	Custom Supabase anon key (for self-hosting)
—verbose	boolean	Enable verbose output with detailed logging

🔹 Sync-ios-version

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

Sync the local iOS Xcode MARKETING_VERSION from package.json.

Example:

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

Options:

Param	Type	Description
—path	string	Path to the project directory (default: current directory)
—check	boolean	Check only; exit non-zero when MARKETING_VERSION is out of sync

🔹 Prescan

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; this command runs it standalone (e.g. in CI).

Options:

Param	Type	Description
—platform	string	Target platform: ios or android (required)
—path	string	Path to the project directory (default: current directory)
-a	string	API key to link to your account
—android-flavor	string	Android: product flavor the build will use
—ios-dist	string	iOS: distribution mode to validate against
—json	boolean	Output a machine-readable JSON report
—fail-on-warnings	boolean	Exit non-zero when warnings are found (CI)
—ignore-fatal	boolean	Diagnostic mode: report everything but always exit 0
—verbose	boolean	Enable verbose output with detailed logging
—supa-host	string	Custom Supabase host URL (for self-hosting or Capgo development)
—supa-anon	string	Custom Supabase anon key (for self-hosting)

🔹 Last-output

npx @capgo/cli@latest build last-output

Read the build output record written by a previous build request --output-record. Prints the full JSON by default, a single field with —field, or the ASCII QR code with —qr. Useful in CI to grab the download URL or QR for posting back to a PR or issue. Examples: 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

Options:

Param	Type	Description
—path	string	Path to the JSON record written by —output-record (required)
—field	string	Print a single field (one of: jobId, appId, platform, buildMode, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt, schemaVersion)
—qr	boolean	Print the rendered ASCII QR code (shortcut for —field qrCodeAscii)

🔹 Credentials

Manage build credentials stored locally on your machine. 🔒 SECURITY:

• Credentials saved to ~/.capgo-credentials/credentials.json (global) or .capgo-credentials.json (local)
• When building, sent to Capgo but NEVER stored permanently
• Deleted from Capgo immediately after build
• Build outputs may optionally be uploaded for time-limited download links 📚 DOCUMENTATION: iOS setup: https://capgo.app/docs/cli/cloud-build/ios/ Android setup: https://capgo.app/docs/cli/cloud-build/android/

🔹 Apple-key

Alias: asc-key

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

Create an App Store Connect team API key with a guided macOS helper (macOS only). Opens a native window that walks you through Apple’s App Store Connect UI in an embedded browser, auto-captures the Issuer ID + Key ID, intercepts the one-time .p8, validates it against Apple, and saves it to ~/.appstoreconnect/private_keys. Progress statistics are forwarded to Capgo analytics (disable with CAPGO_DISABLE_TELEMETRY). npx @capgo/cli build credentials apple-key —appId com.example.app

Example:

Example:

Options:

Param	Type	Description
-a	string	API key to link to your account
—appId	string	Save the captured key into this app iOS build credentials
—local	boolean	Save into the per-project .capgo-credentials.json instead of the global file
—json	boolean	Print the captured Key ID / Issuer ID / .p8 path as JSON

🔹 Save

npx @capgo/cli@latest build credentials save

Save build credentials locally for iOS or Android. Credentials are stored in:

• ~/.capgo-credentials/credentials.json (default, global)
• .capgo-credentials.json in project root (with —local flag) ⚠️ REQUIRED BEFORE BUILDING: You must save credentials before requesting a build. 🔒 These credentials are NEVER stored on Capgo servers permanently. They are deleted immediately after the build completes. 📚 Setup guides: 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” Multi-target Example (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 —platform android
  —keystore ./release.keystore —keystore-alias “my-key”
  —keystore-key-password “key-pass”
  —play-config ./service-account.json Local storage (per-project): npx @capgo/cli build credentials save —local —platform ios …

Example:

iOS Example:

Options:

Param	Type	Description
—appId	string	App ID (e.g., com.example.app) (required)
—platform	string	Platform: ios or android (required)
—certificate	string	iOS: Path to .p12 certificate file
—ios-provisioning-profile	string	iOS: Provisioning profile path or bundleId=path (repeatable)
—p12-password	string	iOS: Certificate password (optional if cert has no password)
—apple-key	string	iOS: Path to .p8 App Store Connect API key
—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: Distribution mode
—apple-id	string	iOS: Apple ID email for app-specific password uploads (alternative to App Store Connect API key)
—apple-app-specific-password	string	iOS: App-specific password (xxxx-xxxx-xxxx-xxxx) for TestFlight uploads
—apple-app-id	string	iOS: Numeric App Store Connect app id (required together with —apple-id and —apple-app-specific-password)
—keystore	string	Android: Path to keystore file (.keystore or .jks)
—keystore-alias	string	Android: Keystore key alias
—keystore-key-password	string	Android: Keystore key password
—keystore-store-password	string	Android: Keystore store password
—play-config	string	Android: Path to Play Store service account JSON
—android-flavor	string	Android: Product flavor to build (e.g. production). Required if your project has multiple flavors.
—in-app-update-priority	string	Android: Google Play in-app update priority for future releases (integer 0–5; higher = more urgent). Omit to leave Play’s existing value untouched.
—local	boolean	Save to .capgo-credentials.json in project root instead of global ~/.capgo-credentials/
—output-upload	boolean	Upload build outputs (IPA/APK/AAB) to Capgo storage and print download links
—no-output-upload	boolean	Do not upload build outputs (IPA/APK/AAB) to Capgo storage
—output-retention	string	Output link TTL: 1h to 7d (default: 1h). Examples: 1h, 6h, 2d
—skip-build-number-bump	boolean	Skip automatic build number/version code incrementing on future builds
—no-skip-build-number-bump	boolean	Re-enable automatic build number incrementing (default behavior)
—skip-marketing-version-bump	boolean	Skip automatic marketing version bump on future builds when the app is already released
—no-skip-marketing-version-bump	boolean	Re-enable automatic marketing version bump (default behavior)

📋 List

npx @capgo/cli@latest build credentials list

List saved build credentials (passwords masked). Shows what credentials are currently saved (both global and local). Examples: npx @capgo/cli build credentials list # List all apps npx @capgo/cli build credentials list —appId com.example.app # List specific app

Options:

Param	Type	Description
—appId	string	App ID to list (optional, lists all if omitted)
—local	boolean	List credentials from local .capgo-credentials.json only

🔹 Clear

npx @capgo/cli@latest build credentials clear

Clear saved build credentials. Remove credentials from storage. Use —appId and —platform to target specific credentials. Examples: npx @capgo/cli build credentials clear # Clear all apps (global) npx @capgo/cli build credentials clear —local # Clear local credentials npx @capgo/cli build credentials clear —appId com.example.app —platform ios

Options:

Param	Type	Description
—appId	string	App ID to clear (optional, clears all apps if omitted)
—platform	string	Platform to clear: ios or android (optional, clears all platforms if omitted)
—local	boolean	Clear from local .capgo-credentials.json instead of global

🔹 Update

npx @capgo/cli@latest build credentials update

Update specific credentials without providing all of them again. Update existing credentials by providing only the fields you want to change. Platform is auto-detected from the options you provide. Examples: npx @capgo/cli build credentials update —ios-provisioning-profile ./new-profile.mobileprovision npx @capgo/cli build credentials update —local —keystore ./new-keystore.jks

Options:

Param	Type	Description
—appId	string	App ID (auto-detected from capacitor.config if omitted)
—platform	string	Platform: ios or android (auto-detected from options)
—local	boolean	Update local .capgo-credentials.json instead of global
—certificate	string	Path to P12 certificate file
—ios-provisioning-profile	string	Provisioning profile path or bundleId=path (repeatable, additive by default)
—overwrite-ios-provisioning-map	boolean	Replace the entire provisioning map instead of merging (default: merge)
—p12-password	string	P12 certificate password
—apple-key	string	Path to App Store Connect API key (.p8 file)
—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 Team ID
—apple-id	string	iOS: Apple ID email for app-specific password uploads (alternative to App Store Connect API key)
—apple-app-specific-password	string	iOS: App-specific password (xxxx-xxxx-xxxx-xxxx) for TestFlight uploads
—apple-app-id	string	iOS: Numeric App Store Connect app id (required together with —apple-id and —apple-app-specific-password)
—ios-distribution	string	iOS: Distribution mode
—keystore	string	Path to keystore file (.keystore or .jks)
—keystore-alias	string	Keystore key alias
—keystore-key-password	string	Keystore key password
—keystore-store-password	string	Keystore store password
—play-config	string	Path to Google Play service account JSON
—android-flavor	string	Android: Product flavor to build (e.g. production). Required if your project has multiple flavors.
—in-app-update-priority	string	Android: Google Play in-app update priority for future releases (integer 0–5; higher = more urgent).
—output-upload	boolean	Upload build outputs (IPA/APK/AAB) to Capgo storage and print download links
—no-output-upload	boolean	Do not upload build outputs (IPA/APK/AAB) to Capgo storage
—output-retention	string	Output link TTL: 1h to 7d. Examples: 1h, 6h, 2d
—skip-build-number-bump	boolean	Skip automatic build number/version code incrementing on future builds
—no-skip-build-number-bump	boolean	Re-enable automatic build number incrementing (default behavior)
—skip-marketing-version-bump	boolean	Skip automatic marketing version bump on future builds when the app is already released
—no-skip-marketing-version-bump	boolean	Re-enable automatic marketing version bump (default behavior)

🔹 Manage

npx @capgo/cli@latest build credentials manage

Interactively manage saved build credentials. Browse stored credentials, view what’s configured, export a CI/CD-ready .env file, or delete a platform’s credentials. Reuses the same TUI as capgo init. Examples: 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

Options:

Param	Type	Description
—appId	string	App ID to manage (optional, prompts to pick if omitted)
—platform	string	Platform to manage: ios or android (optional, prompts to pick if omitted)
—local	boolean	Only browse local .capgo-credentials.json

🔹 Migrate

npx @capgo/cli@latest build credentials migrate

Migrate legacy provisioning profile to the new multi-target format. Converts BUILD_PROVISION_PROFILE_BASE64 to CAPGO_IOS_PROVISIONING_MAP. Discovers the main bundle ID from your Xcode project automatically. npx @capgo/cli build credentials migrate —platform ios

Example:

Example:

Options:

Param	Type	Description
—appId	string	App ID (auto-detected from capacitor.config if omitted)
—platform	string	Platform (only ios is supported)
—local	boolean	Migrate from local .capgo-credentials.json instead of global