Capgo CLI Release Management#

Use this skill for OTA update workflows in Capgo Cloud.

Shared notes#

• Prefer npx @capgo/cli@latest ... examples.
• appId can often be inferred from the current Capacitor project.
• Shared public flags often include -a, --apikey.
• Preview QR workflows require app preview to be enabled before the QR code can be printed.
• --capacitor-config <path> is global. With a dynamic root config selector such as CAP_APP, it keeps loading the root config and writes config changes to the selected app-specific source.

Preview QR workflows#

get-qr [appId] [target]#

• Example: npx @capgo/cli@latest get-qr com.example.app --bundle 1.2.3
• Example: npx @capgo/cli@latest get-qr com.example.app --channel production
• Example: npx @capgo/cli@latest get-qr com.example.app production --type channel
• Use to print a terminal QR code for a bundle or channel preview.
• The target can be a bundle name, bundle id, channel name, or channel id.
• If a positional target matches both a bundle and a channel, add --type bundle or --type channel.
• Preview must already be enabled for the app; enable it with npx @capgo/cli@latest app set com.example.app --preview.
• Key options:
  • --bundle <bundle>
  • --channel <channel>
  • --type <bundle|channel>
  • -a, --apikey <apikey>

Bundle workflows#

bundle upload [appId]#

• Alias: u
• Example: npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production,beta
• Cordova example: npx @capgo/cli@latest bundle upload com.example.app --mode cordova --path www --channel production
• Progressive rollout example: npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production --rollout 10
• Advance an existing rollout: npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production --rollout-advance
• Key behavior:
  • Bundle version must be greater than 0.0.0 and unique.
  • Deleted versions cannot be reused.
  • External URL mode is useful for very large or privacy-sensitive bundles.
  • Encryption is recommended for trustless distribution.
  • Interactive prompts are disabled automatically in CI and other non-interactive sessions so uploads do not block automation.
  • Optional upload prompts can remember the user's answer on the current machine so future uploads can skip the same question.
  • --channel accepts a single channel or a comma-separated list such as production,beta.
  • When multiple channels are provided, channels that already have the uploaded checksum are skipped and the remaining channels are assigned.
  • Use --qr-preview to print a terminal QR code for the uploaded bundle after a successful upload. App preview must be enabled first.
  • Use --send-update-notification to queue native update-check notifications for channels whose linked bundle changed. Native notifications and push update notifications must be enabled for the app.
• Important options:
  • --mode <framework> (cordova for Cordova apps without capacitor.config; webDir defaults to www)
  • -p, --path <path>
  • -c, --channel <channel[,channel...]>
  • --rollout <percentage>
  • --rollout-percentage-bps <basisPoints>
  • --rollout-advance (promote the current rollout target to stable, then set the uploaded bundle as the new rollout; reuses the previous percentage unless --rollout or --rollout-percentage-bps is also set)
  • --rollout-cache-ttl-seconds <seconds>
  • -e, --external <url>
  • --iv-session-key <key>
  • -b, --bundle <bundle>
  • --link <link>
  • --comment <comment>
  • --min-update-version <minUpdateVersion>
  • --auto-min-update-version
  • --ignore-metadata-check
  • --fail-on-incompatible (fail the upload instead of uploading when the bundle is incompatible with a target channel's current native packages; cannot be combined with --ignore-metadata-check or --accept-incompatible)
  • --accept-incompatible (mark native-package incompatibility as handled: still checks and warns, continues the upload, skips the crash-warning email; cannot be combined with --fail-on-incompatible or --ignore-metadata-check)
  • --ignore-checksum-check
  • --force-crc32-checksum
  • --timeout <timeout>
  • --zip
  • --tus
  • --tus-chunk-size <tusChunkSize>
  • --delta (refuses over 10,000 files — delta tracks each file; use --no-delta for a full zip, or reduce build files)
  • --delta-only
  • --no-delta
  • --encrypted-checksum <encryptedChecksum>
  • --auto-set-bundle
  • --dry-upload
  • --package-json <packageJson>
  • --node-modules <nodeModules>
  • --encrypt-delta
  • --delete-linked-bundle-on-upload
  • --no-brotli-patterns <patterns>
  • --disable-brotli
  • --version-exists-ok
  • --self-assign
  • --qr-preview
  • --send-update-notification
  • S3 options: --s3-region, --s3-apikey, --s3-apisecret, --s3-endpoint, --s3-bucket-name, --s3-port, --no-s3-ssl
  • Signing options: --key-v2, --key-data-v2, --bundle-url, --no-key, --display-iv-session
  • Deprecated options still supported: --multipart, --partial, --partial-only, --encrypt-partial

bundle compatibility [appId]#

• Example: npx @capgo/cli@latest bundle compatibility com.example.app --channel production
• Use to check whether a bundle is safe for a given channel.
• Key options:
  • -c, --channel <channel>
  • --text
  • --package-json <packageJson>
  • --node-modules <nodeModules>

bundle releaseType [appId]#

• Example: npx @capgo/cli@latest bundle releaseType com.example.app --channel production
• Prints native or OTA based on channel compatibility.
• Key options:
  • -c, --channel <channel>
  • --package-json <packageJson>
  • --node-modules <nodeModules>

bundle list [appId]#

• Alias: l
• Example: npx @capgo/cli@latest bundle list com.example.app

bundle delete [bundleId] [appId]#

• Alias: d
• Example: npx @capgo/cli@latest bundle delete BUNDLE_ID com.example.app

bundle cleanup [appId]#

• Alias: c
• Example: npx @capgo/cli@latest bundle cleanup com.example.app --bundle=1.0 --keep=3
• Notes:
  • Linked bundles are preserved unless --ignore-channel is used; with it, linked bundles are unlinked from their channels and deleted.
  • The Capgo API selects and deletes the bundles server-side (POST /bundle/cleanup). Without --force, the CLI first shows a preview (dry run), asks for confirmation, then deletes only the bundles shown as removable, even if new bundles are uploaded meanwhile.
  • With --force, selection and deletion happen in one request, with no preview.
  • Self-hosted Capgo: bundle cleanup needs a backend that serves POST /bundle/cleanup; against an older backend it stops with "This Capgo API does not support server-side bundle cleanup". bundle delete uses the capgo_api 2026-10-22 contract of DELETE /bundle; an older backend still deletes, but reports a missing bundle as a generic delete error. Update the backend or use an older CLI.
  • bundle delete sends one request to the Capgo API, which reports a missing bundle directly. If the bundle is still linked to a channel, the CLI offers to unlink it and then retries the delete.
• Key options:
  • -b, --bundle <bundle>
  • -k, --keep <keep>
  • -f, --force
  • --ignore-channel

bundle zip [appId]#

• Example: npx @capgo/cli@latest bundle zip com.example.app --path ./dist
• Offline packer example (for signed-URL uploads through the Capgo MCP): npx @capgo/cli@latest bundle zip com.example.app --for-upload --delta-pack ./delta.zip --json
• Notes:
  • Produces a checksum for encryption workflows.
  • Use --json for machine-readable output (JSON on stdout, logs on stderr).
  • Works offline: no API key, no calls to Capgo (no analytics either).
  • --for-upload produces exactly what bundle upload would send: same zip, checksum algorithm, v2 encryption (.capgo_key_v2 by default, --key-v2, --key-data-v2, --no-key), and adds session_key, key_id, native_packages to the JSON. Without it, the zip is never encrypted (keeps the bundle zip then bundle encrypt flow).
  • --delta-pack <file> (implies --for-upload) also writes a STORE zip with capgo-delta-manifest.json (protocol_version, file_hash_format, delta_encryption, entries[] with file_name, file_hash, compression = none or brotli, uploaded_bytes_sha256, uploaded_bytes_size, pack_path) and the uploaded bytes under files/<id>.
  • JSON keys: bundle, filename, checksum, app_id, updater_version, checksum_algorithm, size_bytes, cli_version; with --for-upload: encryption_method, session_key, key_id, native_packages; with --delta-pack: delta_pack, delta_pack_entries, delta_file_hash_format, delta_encryption.
• Key options:
  • -p, --path <path>
  • -b, --bundle <bundle>
  • -n, --name <name>
  • -j, --json
  • --no-code-check
  • --key-v2 [key]
  • --key-data-v2 <keyDataV2>
  • --no-key
  • --for-upload
  • --delta-pack <file>
  • --encrypt-delta
  • --disable-brotli
  • --force-crc32-checksum
  • --package-json <packageJson>
  • --node-modules <nodeModules>

bundle encrypt [zipPath] [checksum]#

• Example: npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM
• Notes:
  • Returns the ivSessionKey needed for upload and later decryption.
• Key options:
  • --key <key>
  • --key-data <keyData>
  • -j, --json
  • --package-json <packageJson>

bundle decrypt [zipPath] [checksum]#

• Example: npx @capgo/cli@latest bundle decrypt ./myapp_encrypted.zip CHECKSUM
• Notes:
  • Mainly for testing.
  • Prints the base64 session key for verification.
• Key options:
  • --key <key>
  • --key-data <keyData>
  • --checksum <checksum>
  • --package-json <packageJson>

Channel workflows#

channel add [channelId] [appId]#

• Alias: a
• Example: npx @capgo/cli@latest channel add production com.example.app --default
• Key options:
  • -d, --default
  • --self-assign

channel list [appId]#

• Alias: l
• Example: npx @capgo/cli@latest channel list com.example.app
• Requires a valid API key with app.read and app.read_channels permission for the app. Permission failures identify the required permission.
• Displays Yes/No settings and marks channels without a bundle as Unlinked. Narrow terminals show each channel as a Setting/Value table.

channel delete [channelId] [appId]#

• Alias: d
• Example: npx @capgo/cli@latest channel delete production com.example.app
• Key options:
  • --delete-bundle
  • --success-if-not-found

channel currentBundle [channel] [appId]#

• Example: npx @capgo/cli@latest channel currentBundle production com.example.app
• Key options:
  • -c, --channel <channel>
  • --quiet

channel promote [fromChannel] [toChannel] [appId]#

• Example: npx @capgo/cli@latest channel promote staging production com.example.app
• Use to ship what a channel already serves (for example a validated staging or preprod bundle) to another channel without looking up the bundle version.
• Notes:
  • Copies only the stable bundle linked to the source channel. Channel settings are not copied.
  • Like channel set --bundle, a new stable bundle stops any rollout in progress on the target channel; the CLI warns when that happens.
  • Runs the same native compatibility and RBAC checks as channel set --bundle on the target channel.
• Key options:
  • --ignore-metadata-check
  • --accept-incompatible (cannot be combined with --ignore-metadata-check)
  • --send-update-notification

channel set [channelId] [appId]#

• Alias: s
• Example: npx @capgo/cli@latest channel set production com.example.app --bundle 1.0.0 --state default
• Notes:
  • One channel must remain default.
  • Supports update policies major, minor, metadata, patch, and none.
  • Supports platform and device targeting.
  • Use --qr-preview to print a terminal QR code for the updated channel. App preview must be enabled first.
  • Use --send-update-notification with bundle, latest, latest remote, rollout target, or rollout promote changes to make matching devices check for updates.
• Key options:
  • -b, --bundle <bundle>
  • -s, --state <state>
  • --latest-remote
  • --latest
  • --downgrade, --no-downgrade
  • --ios, --no-ios
  • --android, --no-android
  • --electron, --no-electron
  • --pause, --resume (stop or restart every update on the channel)
  • --self-assign, --no-self-assign
  • --disable-auto-update <disableAutoUpdate>
  • --dev, --no-dev
  • --prod, --no-prod
  • --emulator, --no-emulator
  • --device, --no-device
  • --package-json <packageJson>
  • --ignore-metadata-check
  • --accept-incompatible (mark native-package incompatibility as handled: still checks and warns, sets the channel instead of failing; cannot be combined with --ignore-metadata-check)
  • --qr-preview
  • --send-update-notification

Encryption key workflows#

key save#

• Example: npx @capgo/cli@latest key save --key ./path/to/key.pub
• Notes:
  • Saves the public key in Capacitor config.
  • Useful for CI.
  • Recommended not to commit the key.
• Key options:
  • -f, --force
  • --key <key>
  • --key-data <keyData>

key create#

• Example: npx @capgo/cli@latest key create
• Notes:
  • Creates .capgo_key_v2 and .capgo_key_v2.pub.
  • Saves the public key to Capacitor config.
  • Never commit the private key.
• Key options:
  • -f, --force

key delete_old#

• Example: npx @capgo/cli@latest key delete_old