cap-go/capgo/release-management

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]