Guides the agent through Capgo OTA release workflows including bundle uploads, compatibility checks, channels, cleanup, and encryption key setup. Use when managing Capgo bundle and channel operations. Do not use for native build requests or organization administration.

Capgo Release Management Ship, promote, roll back, and clean up Capgo OTA bundles from the CLI. Facts below were checked against @capgo/cli 8.77 (October 2026). Every command accepts a, apikey . The appId can be omitted inside a Capacitor project. When to Use TRIGGER when: The user uploads, lists, deletes, or cleans up bundles, or asks which version a channel serves. The user creates or configures channels, promotes staging to production, starts, pauses, or rolls back a progressive rollout, or rolls back a bad release. The user asks whether a change is OTA safe ( bundle compatibility , bundle releaseType ). The user sets up bundle encryption ( key create , key save , key v2 ). Do not use when: The work is app side updater code or config ( notifyAppReady , autoUpdate , setChannel ). Use capgo live updates . A native binary is needed. Use capgo native builds . The user manages organizations, members, 2FA, or API key policy. Use capgo organization management . The user wants an end to end release pipeline design. Use capgo release workflows . Command Map Goal Command Upload and link bundle upload [appId] path ./dist channel production (comma separate several channels) Is it OTA safe? bundle releaseType [appId] channel production prints OTA or native Detailed native diff bundle compatibility [appId] channel production [ text] What is live channel currentBundle production [appId] quiet Promote channel promote staging production [appId] Roll back channel set production [appId] bundle <previous version Rollout bundle upload ... rollout 10 , then channel set ... rollout percentage 50 / rollout promote / rollout rollback Create channel channel add beta [appId] [ default] [ self assign] Channel policy channel set <ch disable auto update major\ minor\ patch\ metadata\ none plus ios/ android/ dev/ prod/ emulator/ device toggles List bundle list [appId] , channel list [appId] Clean up bundle cleanup [appId] bundle 1.0 keep 3 Delete bundle delete <version [appId] , channel delete <ch [appId] Preview QR app set [appId] preview once, then get qr [appId] channel beta or bundle upload ... qr preview Encryption keys key create , key save key ./.capgo key v2.pub , key delete old Custom zip / external bundle zip [appId] json , bundle encrypt <zip <checksum , bundle upload external <url All of these are npx @capgo/cli@latest <command . Commands that do not exist (they come from old docs or other tools): channel create , bundle revert , upload sign , key verify , and a top level capgo upload without bundle . Procedure 1. Inspect first Report the current live version and the OTA/native verdict before you change anything. If the verdict is native , stop and hand off to capgo native builds (or the user's native pipeline). 2. Upload The version comes from package.json unless you pass bundle <semver . It must be unique, greater than 0.0.0 , and never a previously deleted version. Use delta for instant apply apps. The CLI refuses delta uploads with more than 10,000 files. Use no delta in that case. Use fail on incompatible in CI. Use accept incompatible only when the JS guards missing plugins. These two flags and ignore metadata check cannot be combined. 3. Promote and roll out Promote: npx @capgo/cli@latest channel promote staging production com.example.app . It runs the same compatibility checks as channel set bundle . Gradual rollout: upload with rollout <pct , then watch the stats before you run rollout promote . Only change which channel is the default ( channel set <ch state default , or channel add default ) when the user explicitly wants to move production traffic. 4. Roll back Devices pick up the change on their next update check. 5. Encryption (optional, for sensitive apps) In CI, keep the private key in the CI secret store, write it to ./.capgo key v2 in the job, and pass the same key v2 ./.capgo key v2 . The private key never leaves the runner. Add .capgo key v2 to .gitignore and never commit it. A changed key needs a new native build: devices with the old publicKey fail with key id mismatch . Traps On a channel that has a rollout configured, a plain bundle upload channel production sets the rollout target , and stable is unchanged. Replace stable explicitly with channel set bundle . bundle cleanup ignore channel also deletes the linked channels. Never add it without asking. bundle delete is permanent, and the deleted version cannot be reused. Prefer relinking an older bundle to roll back. releaseType only sees native package metadata, not raw ios/ or android/ edits. self assign on upload changes the channel's settings, not just this bundle. Verification 1. npx @capgo/cli@latest channel currentBundle production com.example.app quiet prints the expected version. 2. npx @capgo/cli@latest probe platform ios (run in the project) reports whether an update would be served. 3. npx @capgo/cli@latest app debug com.example.app shows a test device downloading and setting the bundle. 4. For encrypted uploads, a device on the new native build applies the update with no key id mismatch error. Error Handling String Fix ❌ Version X already exists Bump bundle , use auto bump patch , or pass version exists ok in CI re runs Cannot upload the same bundle content The checksum is already on that channel. Rebuild with changes, or pass ignore checksum check Bundle NOT compatible with <channel channel Native packages differ. Do a native build first, or use accept incompatible if the code guards it notifyAppReady() is missing in the build folder (...) Fix the app entry point (see capgo live updates ) index.html is missing in the root folder of <dir Wrong path Cannot find channel <name Check channel list . Names are case sensitive Channel strategy <x is not known Use major , minor , patch , metadata , or none No Capgo API key found. Run ... first, then retry this command. npx @capgo/cli@latest login , set CAPGO TOKEN , or pass a Insufficient permissions for <key The API key role is too low for this app. Ask an admin for an upload capable key Cannot upload bundle ( try again with tus option) Retry with tus , and raise timeout for large bundles Resources Bundle reference: https://capgo.app/docs/cli/reference/bundle/ Channel reference: https://capgo.app/docs/cli/reference/channel/ Progressive rollouts: https://capgo.app/docs/live updates/progressive rollouts/ Encryption: https://capgo.app/docs/live updates/encryption/ Compatibility: https://capgo.app/docs/live updates/compatibility/

capgo-release-management