--- name: native-builds description: Use when working with Capgo Cloud native iOS and Android build requests, onboarding, credential storage, credential updates, and build output upload settings. --- # Capgo CLI Native Builds Use this skill for Capgo Cloud native iOS and Android build workflows. ## Build prescan overrides Before `build request` uploads, Capgo runs a local/remote **prescan**. Prefer per-check overrides over disabling the whole scan: - `--prescan-skip <checkId>` — do not run that check (repeatable / comma-separated) - `--prescan-warn <checkId>` — still run it, but downgrade findings to warning - `--no-prescan` / `--prescan-ignore-fatal` — global escapes; use only when necessary Example (intentional Capacitor `server.url` / Next.js shell): ```bash npx @capgo/cli@latest build request <appId> --platform ios --prescan-skip ios/capacitor-server-url-shipped ``` Standalone: `build prescan` accepts `--skip` / `--warn`. Full catalog: `webdocs/prescan-checks.mdx`. ## Onboarding (automated iOS setup) ### `build init` (alias: `build onboarding`) - Interactive command that automates iOS certificate and provisioning profile creation. - Reduces iOS setup from ~10 manual steps to 1 manual step (creating an API key) + 1 command. - Example: `npx @capgo/cli@latest build init` - Backward compatibility: `npx @capgo/cli@latest build onboarding` still works. - Options: - `-a, --apikey <apikey>` — Capgo API key to authenticate with (alternative to the `CAPGO_TOKEN` env var or `~/.capgo` / local `.capgo` file). Takes precedence over a saved key when both are present. Lets the SaaS onboarding wizard render a single copy-pasteable command across bash, zsh, fish, PowerShell, and cmd.exe. - `--no-analytics` — Disable build onboarding analytics and terminal replay for this run. - Example: `npx @capgo/cli@latest build init -a cap_xxx` - Notes: - Uses Ink (React for terminal) for the interactive UI, alongside the main `init` onboarding flow. - Requires running inside a Capacitor project directory with an `ios/` folder. - The user creates ONE App Store Connect API key (.p8 file), then the CLI handles everything else. - On macOS, offers a native file picker dialog for .p8 selection. - Auto-detects Key ID from .p8 filename (e.g. `AuthKey_XXXX.p8`). - For apps assigned only the supported Builder checklist, the saved platform is used when `--platform` is omitted; an explicit platform takes precedence. Generic `init` also hands these apps to this wizard. `app todo` shows both platforms independently, including backend-reported build failures. Finishing credential setup or requesting a build does not complete the checklist; Capgo must report a successful cloud build. Generic `init` behavior for OTA-only and dual-assigned apps is unchanged. To inspect dual-assigned progress, `app todo` has interactive OTA/Builder tabs; scripts and AI agents must pass `--list builder` or `--list ota`. An explicit selector prints one list and exits. - Progress persists in `~/.capgo-credentials/onboarding/<appId>.json` — safe to interrupt and resume. - Saves credentials to the same `~/.capgo-credentials/credentials.json` used by `build request`. - Optionally kicks off the first build at the end. - If the native `ios/` folder is missing, onboarding can offer to run `cap add ios` automatically instead of exiting immediately. - Unexpected failures now keep the user inside the recovery screen, show package-manager-aware commands, and save a support bundle under `~/.capgo-credentials/support/`. - The recovery screen offers an "Email Capgo support" action: it writes a redacted diagnostics bundle as both `.log` and `.log.gz` under `~/.capgo-credentials/support/`, copies the `.log.gz` path to the clipboard, reveals it in Finder on macOS, and opens a pre-filled `mailto:support@capgo.app` for the user to attach the file and send (no logs are uploaded automatically). An "Ask AI for help" option is also offered when a build log exists. #### What it automates (iOS) 1. Verifies the API key with Apple 2. Generates CSR + creates an `IOS_DISTRIBUTION` certificate via the App Store Connect API 3. Registers or reuses the bundle ID 4. Creates an `IOS_APP_STORE` provisioning profile 5. Saves all credentials (certificate as .p12, profile, API key, team ID) 6. Requests the first cloud build #### Conflict resolution - **Certificate limit reached**: lists existing certs, tags ones created by Capgo onboarding, lets the user pick one to revoke, then retries. - **Duplicate provisioning profiles**: detects profiles matching the `Capgo <appId> AppStore` naming pattern, deletes them, and retries. - **Existing credentials**: offers to backup existing credentials before proceeding, or exit onboarding. #### Architecture - `src/build/onboarding/command.ts` — entry point, launches Ink - `src/build/onboarding/apple-api.ts` — JWT auth + App Store Connect API (verify, create cert, create profile, revoke, delete) - `src/build/onboarding/csr.ts` — CSR generation + P12 creation via `node-forge` - `src/build/onboarding/progress.ts` — per-app progress persistence - `src/build/onboarding/file-picker.ts` — macOS native file picker via `osascript` - `src/build/onboarding/ui/app.tsx` — Ink app (state machine) - `src/build/onboarding/ui/components.tsx` — reusable UI components #### BuildLogger callback interface `requestBuildInternal` accepts an optional `BuildLogger` to receive log output via callbacks instead of writing directly to stdout. This enables clean integration with the Ink UI: ```typescript interface BuildLogger { info: (msg: string) => void error: (msg: string) => void warn: (msg: string) => void success: (msg: string) => void buildLog: (msg: string) => void uploadProgress: (percent: number) => void } ``` --- ## Core build request ### `build needed [appId]` - Example: `npx @capgo/cli@latest build needed com.example.app --channel production --verbose` - Prints `yes` or `no` and exits with code `1` only when local native dependency metadata requires a new native build. - If `--channel` is omitted, it uses `plugins.CapacitorUpdater.defaultChannel` from local config, then the public default channel in Capgo Cloud. - Key options: - `-c, --channel <channel>` - `--verbose` - `--package-json <packageJson>` - `--node-modules <nodeModules>` ### `build request [appId]` - Example: `npx @capgo/cli@latest build request com.example.app --platform ios --path .` - Notes: - Zips the current project directory and uploads it to Capgo for building. - Builds are processed for store distribution. - Credentials are never stored permanently on Capgo servers. - Build outputs can be uploaded for time-limited download links. - Before requesting a build, save credentials with `build credentials save`. - Core options: - `--path <path>` - `--node-modules <nodeModules>`: paths to `node_modules` directories for monorepos, comma-separated. - `--platform <platform>`: `ios` or `android`. If omitted in an interactive terminal, the CLI prompts for the platform; non-interactive runs must pass it explicitly. - `--build-mode <buildMode>`: `debug` or `release`. - `-a, --apikey <apikey>` - `--verbose` #### iOS request options - `--build-certificate-base64 <cert>` - `--p12-password <password>` - `--apple-id <email>` - `--apple-app-specific-password <password>` - `--apple-key-id <id>` - `--apple-issuer-id <id>` - `--apple-key-content <content>` - `--app-store-connect-team-id <id>` - `--ios-scheme <scheme>` - `--ios-target <target>` - `--xcode-version <version>`: build on a machine with this Xcode (e.g. `26`, `26.0.1`, `27`; a major accepts any minor). Env `CAPGO_IOS_XCODE_VERSION`. Fails fast with the available versions when no machine matches. - `--ios-distribution <mode>`: `app_store` (default, uploads to TestFlight) or `ad_hoc` (skips store upload; use with `--output-upload` for IPA-only when the App Store app does not exist yet) - `--ios-provisioning-profile <mapping>`: repeatable path or `bundleId=path` #### Android request options - `--android-keystore-file <keystore>` - `--keystore-key-alias <alias>` - `--keystore-key-password <password>` - `--keystore-store-password <password>` - `--play-config-json <json>` - `--android-flavor <flavor>` - `--sync-android-version`: before upload, replace a standalone quoted `versionName` literal in `android/app/build.gradle` with the `package.json` version. The request fails before submission if the file is missing or `versionName` is computed, interpolated, concatenated, or otherwise not a standalone quoted string literal. - `--in-app-update-priority <0-5>`: Google Play in-app update priority (higher = more urgent) #### Output behavior options - `--output-upload`: upload the finished IPA/APK/AAB to Capgo storage and print a time-limited download link (and QR). Pair with `--no-playstore-upload` (Android) or `--ios-distribution ad_hoc` (iOS) for artifact-only builds - `--no-output-upload`: skip Capgo storage upload (no download link); store upload can still happen when store credentials are set - `--no-playstore-upload`: Android — skip Google Play upload for this build (ignores saved Play credentials). Requires `--output-upload`. Use when the Play app does not exist yet or you only need the AAB download - `--submit-to-store-review`: submit after upload instead of leaving a draft/inactive store release. Android completes the Google Play release; iOS submits to TestFlight external review. - `--store-release-name <name>`: Android Google Play version_name/release label. - `--store-release-notes <notes>`: Google Play changelog and iOS TestFlight What to Test text. - `--ios-testflight-groups <groups>`: comma-separated external TestFlight group names or IDs required with `--submit-to-store-review` on iOS. - `--output-retention <duration>`: `1h` to `7d` - `--skip-build-number-bump` - `--no-skip-build-number-bump` - `--no-cache`: disable Xcode compilation cache for this build (default: cache enabled). Example: `npx @capgo/cli@latest build request com.example.app --platform ios --no-cache` - `--cache-key <key>`: custom compilation cache namespace for this build (e.g. `rc`, `prod`, `feature/my-branch`). Use to share cache within an environment or isolate cache between RC and production. Ignored when `--no-cache` is set. Example RC vs PROD: - RC: `npx @capgo/cli@latest build request com.example.app --platform ios --cache-key rc` - PROD: `npx @capgo/cli@latest build request com.example.app --platform ios --cache-key prod` ### `build zip [appId]` - Example: `npx @capgo/cli@latest build zip com.example.app --platform ios --json` - Writes the exact native project archive `build request` uploads (same file filter, path rewriting, `--sync-ios-version` / `--sync-android-version`, config resolution) without uploading it. Use it when an agent uploads the archive through a Capgo MCP signed URL. - Offline: no API key, no calls to Capgo. - JSON output: `app_id`, `platform`, `filename`, `size_bytes`, `sha256`, optional `ios_dependency_manager` (`cocoapods` or `spm`), and `build_options` (non-secret options derived from the project: `platform`, `iosSourceDir`/`iosAppDir`/`iosProjectDir` or `androidSourceDir`/`androidAppDir`/`androidProjectDir`). - Options: `--platform <platform>`, `--path <path>`, `--node-modules <nodeModules>`, `--sync-ios-version`, `--sync-android-version`, `--output <file>` (default `<appId>_<platform>_native.zip`), `-j, --json`. ## Local credential management Credentials are stored locally, either globally in `~/.capgo-credentials/credentials.json` or locally in `.capgo-credentials.json`. ### `build credentials save` - Required before build requests. - Supports global storage by default and local storage with `--local`. - Example iOS flow: ```bash npx @capgo/cli@latest 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" ``` - Example multi-target iOS flow: ```bash npx @capgo/cli@latest build credentials save --platform ios \ --ios-provisioning-profile ./App.mobileprovision \ --ios-provisioning-profile com.example.widget=./Widget.mobileprovision ``` - Example Android flow: ```bash npx @capgo/cli@latest build credentials save --platform android \ --keystore ./release.keystore --keystore-alias "my-key" \ --keystore-key-password "key-pass" \ --play-config ./service-account.json ``` - Core options: - `--appId <appId>` - `--platform <platform>` - `--local` - `--output-upload`, `--no-output-upload` - `--output-retention <duration>` - `--skip-build-number-bump`, `--no-skip-build-number-bump` #### iOS credential save options - `--certificate <path>` - `--ios-provisioning-profile <mapping>` - `--p12-password <password>` - `--apple-key <path>` - `--apple-key-id <id>` - `--apple-issuer-id <id>` - `--apple-team-id <id>` - `--ios-distribution <mode>` - `--apple-id <email>` - `--apple-app-password <password>` #### Android credential save options - `--keystore <path>` - `--keystore-alias <alias>` - `--keystore-key-password <password>` - `--keystore-store-password <password>` - `--play-config <path>` - `--android-flavor <flavor>` ### `build credentials list` - Examples: - `npx @capgo/cli@latest build credentials list` - `npx @capgo/cli@latest build credentials list --appId com.example.app` - Options: - `--appId <appId>` - `--local` ### `build credentials clear` - Examples: - `npx @capgo/cli@latest build credentials clear` - `npx @capgo/cli@latest build credentials clear --local` - `npx @capgo/cli@latest build credentials clear --appId com.example.app --platform ios` - Options: - `--appId <appId>` - `--platform <platform>` - `--local` ### `build credentials push` / `remote-status` / `remote-delete` Store the locally saved credentials for one platform on Capgo, encrypted (AES-256-GCM, bound to the app and platform), so builds can use them without sending secrets each time (for example from the hosted Capgo MCP). Writing or deleting requires app settings permission (app admin), and so does building with them (`build request --use-stored-credentials` or the MCP `capgo_request_build`), because build scripts can read the secrets; reading the summary requires native build permission. Env names that load code into every build (`NODE_OPTIONS`, `JAVA_TOOL_OPTIONS`, `GRADLE_OPTS`, `LD_PRELOAD`, `DYLD_*`, `PATH`, ...) cannot be stored; pass them per build with `--build-env`. Only key names and non-secret facts (iOS distribution, team id, provisioning profile names and expiry, what is still missing) are ever shown. - Examples: - `npx @capgo/cli@latest build credentials push com.example.app --platform ios` - `npx @capgo/cli@latest build credentials push --platform android --mode merge` - `npx @capgo/cli@latest build credentials remote-status com.example.app` - `npx @capgo/cli@latest build credentials remote-delete com.example.app --platform ios --yes` - `push` options: `--platform <platform>` (required), `--mode replace|merge` (default `replace`), `--local`, `--global`, `-a, --apikey`, `--api-host` - `remote-status` options: `--platform <platform>`, `-a, --apikey`, `--api-host` - `remote-delete` options: `--platform <platform>` (required), `-y, --yes`, `-a, --apikey`, `--api-host` - Agents with a shell can also upload a credentials file without the secrets entering the chat: `POST /build/credentials/upload-url` returns a 10-minute `PUT` URL that accepts the raw `credentials.json` file. ### `build credentials update` - Use to update specific credential fields without re-entering all data. - Platform is auto-detected from the supplied options. - Examples: - `npx @capgo/cli@latest build credentials update --ios-provisioning-profile ./new-profile.mobileprovision` - `npx @capgo/cli@latest build credentials update --local --keystore ./new-keystore.jks` - Core options: - `--appId <appId>` - `--platform <platform>` - `--local` - `--overwrite-ios-provisioning-map` - `--output-upload`, `--no-output-upload` - `--output-retention <duration>` - `--skip-build-number-bump`, `--no-skip-build-number-bump` - Supports the same iOS and Android credential fields as `build credentials save`. ### `build credentials ios-provisioning` - Repairs missing App Store provisioning-profile entries for every signable target in the current Capacitor iOS project. - Reuses a compatible wildcard profile only after confirmation; otherwise uses saved App Store Connect API-key credentials to create target-specific profiles. - Use `--local` or `--global` to select the credential store. If both stores contain credentials for the app and neither option is passed, the command exits and asks you to choose one. ```bash npx @capgo/cli@latest build credentials ios-provisioning --local ``` ### `build credentials export <VARIABLE>` - Exports one value from saved Builder credentials only; environment variables are never used. - Requires `--app-id <APP_ID>`. - Requires exactly one output mode: - `--raw` writes only the exact stored value to stdout, with no trailing newline. Failures go to stderr and exit with status `1`. - `--file <PATH>` creates a new `0600` file and never overwrites an existing path. Interactive runs prompt before decoding values that look like Base64; `--decode-base64` forces decoding. A negative response or non-interactive run preserves the stored text. - Use `--local` or `--global` when the app has saved credentials in both stores. Use `--platform ios|android` when the value is ambiguous across platforms. ```bash # Exact value for a CI secret or pipe: no newline is added. npx @capgo/cli@latest build credentials export P12_PASSWORD \ --app-id com.example.app --platform ios --raw # Create a new decoded keystore file; existing paths are refused. npx @capgo/cli@latest build credentials export ANDROID_KEYSTORE_FILE \ --app-id com.example.app --platform android --file ./release.keystore --decode-base64 ``` ### `build credentials migrate` - Example: `npx @capgo/cli@latest build credentials migrate --platform ios` - Notes: - Converts `BUILD_PROVISION_PROFILE_BASE64` to `CAPGO_IOS_PROVISIONING_MAP`. - Discovers the main bundle ID from the Xcode project automatically. - Options: - `--appId <appId>` - `--platform <platform>`: only `ios` - `--local` ## Supporting docs - iOS setup: `https://capgo.app/docs/cli/cloud-build/ios/` - Android setup: `https://capgo.app/docs/cli/cloud-build/android/`