Skip to content
TanStackIntent
TanStack Intent/Registry/@capgo/cli

@capgo/cli

A CLI to upload to capgo servers

native-builds

340 linesSource

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):

shell
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:

ts
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
  • --symbols-upload: keep the debug symbols (iOS dSYMs zip, Android mapping.txt) and print a time-limited download link for crash reporters (Crashlytics, Sentry). If output upload is enabled by a flag, environment variable, or saved credentials, also pass --no-output-upload to avoid keeping the IPA/APK/AAB. Use with store builds. Off by default: Capgo keeps nothing unless you opt in. TTL follows --output-retention
  • --no-symbols-upload: do not keep debug symbols unless output upload is enabled. --output-upload still includes debug symbols
  • --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:
shell
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:
shell
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:
shell
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>
    • --symbols-upload, --no-symbols-upload
    • --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>
    • --symbols-upload, --no-symbols-upload
    • --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.
shell
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.
shell
# 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/