---
name: release-management
description: Use when working on Capgo OTA release workflows including bundle uploads, compatibility checks, channel management, cleanup, and encryption key setup.
---

# 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.

## 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`
- 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.
- Important options:
  - `-p, --path <path>`
  - `-c, --channel <channel[,channel...]>`
  - `-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`)
  - `--ignore-checksum-check`
  - `--force-crc32-checksum`
  - `--timeout <timeout>`
  - `--zip`
  - `--tus`
  - `--tus-chunk-size <tusChunkSize>`
  - `--delta`
  - `--delta-only`
  - `--no-delta`
  - `--encrypted-checksum <encryptedChecksum>`
  - `--auto-set-bundle`
  - `--dry-upload`
  - `--package-json <packageJson>`
  - `--node-modules <nodeModules>`
  - `--encrypt-partial`
  - `--delete-linked-bundle-on-upload`
  - `--no-brotli-patterns <patterns>`
  - `--disable-brotli`
  - `--version-exists-ok`
  - `--self-assign`
  - `--qr-preview`
  - 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`

### `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.
- 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`
- Notes:
  - Produces a checksum for encryption workflows.
  - Use `--json` for machine-readable output.
- Key options:
  - `-p, --path <path>`
  - `-b, --bundle <bundle>`
  - `-n, --name <name>`
  - `-j, --json`
  - `--no-code-check`
  - `--key-v2`
  - `--package-json <packageJson>`

### `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`

### `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 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.
- Key options:
  - `-b, --bundle <bundle>`
  - `-s, --state <state>`
  - `--latest-remote`
  - `--latest`
  - `--downgrade`, `--no-downgrade`
  - `--ios`, `--no-ios`
  - `--android`, `--no-android`
  - `--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`
  - `--qr-preview`

## 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`
