A CLI to upload and download files from the Capgo Cloud.
You can find the most up to date version of this doc in our web doc: https://capgo.app/docs/cli/overview/
Before using the CLI, you should register here: https://capgo.app/
Then go to your account in apikey section and click in the all key to copy it.
Follow the documentation here: https://capacitorjs.com/docs/getting-started/
Alias: i
npx @capgo/cli@latest init🚀 Initialize a new app in Capgo Cloud with step-by-step guidance. This includes adding code for updates, building, uploading your app, and verifying update functionality.
Example:
npx @capgo/cli@latest init YOUR_API_KEY com.example.app| Param | Type | Description |
|---|---|---|
| -n, | string |
App name for display in Capgo Cloud |
| -i, | string |
App icon path for display in Capgo Cloud |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
npx @capgo/cli@latest doctor👨⚕️ Check if your Capgo app installation is up-to-date and gather information useful for bug reports. This command helps diagnose issues with your setup.
Example:
npx @capgo/cli@latest doctor| Param | Type | Description |
|---|---|---|
| --package-json | string |
Paths to package.json files for monorepos (comma-separated) |
Alias: l
npx @capgo/cli@latest login🔑 Save your Capgo API key to your machine or local folder for easier access to Capgo Cloud services. Use --apikey=******** in any command to override it.
Example:
npx @capgo/cli@latest login YOUR_API_KEY| Param | Type | Description |
|---|---|---|
| --local | boolean |
Only save in local folder, git ignored for security. |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
📦 Manage app bundles for deployment in Capgo Cloud, including upload, compatibility checks, and encryption.
Alias: u
npx @capgo/cli@latest bundle upload⬆️ Upload a new app bundle to Capgo Cloud for distribution. Version must be > 0.0.0 and unique. Deleted versions cannot be reused for security. External option: Store only a URL link (useful for apps >200MB or privacy requirements). Capgo never inspects external content. Add encryption for trustless security.
Example:
npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel productionOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| -p, | string |
Path of the folder to upload, if not provided it will use the webDir set in capacitor.config |
| -c, | string |
Channel to link to |
| -e, | string |
Link to external URL instead of upload to Capgo Cloud |
| --iv-session-key | string |
Set the IV and session key for bundle URL external |
| --s3-region | string |
Region for your S3 bucket |
| --s3-apikey | string |
API key for your S3 endpoint |
| --s3-apisecret | string |
API secret for your S3 endpoint |
| --s3-endpoint | string |
URL of S3 endpoint |
| --s3-bucket-name | string |
Name for your AWS S3 bucket |
| --s3-port | string |
Port for your S3 endpoint |
| --no-s3-ssl | boolean |
Disable SSL for S3 upload |
| --key-v2 | string |
Custom path for private signing key (v2 system) |
| --key-data-v2 | string |
Private signing key (v2 system) |
| --bundle-url | boolean |
Prints bundle URL into stdout |
| --no-key | boolean |
Ignore signing key and send clear update |
| --no-code-check | boolean |
Ignore checking if notifyAppReady() is called in source code and index present in root folder |
| --display-iv-session | boolean |
Show in the console the IV and session key used to encrypt the update |
| -b, | string |
Bundle version number of the bundle to upload |
| --link | string |
Link to external resource (e.g. GitHub release) |
| --comment | string |
Comment about this version, could be a release note, a commit hash, a commit message, etc. |
| --min-update-version | string |
Minimal version required to update to this version. Used only if the disable auto update is set to metadata in channel |
| --auto-min-update-version | boolean |
Set the min update version based on native packages |
| --ignore-metadata-check | boolean |
Ignores the metadata (node_modules) check when uploading |
| --ignore-checksum-check | boolean |
Ignores the checksum check when uploading |
| --timeout | string |
Timeout for the upload process in seconds |
| --multipart | boolean |
[DEPRECATED] Use --tus instead. Uses multipart protocol for S3 uploads |
| --zip | boolean |
Upload the bundle using zip to Capgo cloud (legacy) |
| --tus | boolean |
Upload the bundle using TUS to Capgo cloud |
| --tus-chunk-size | string |
Chunk size in bytes for TUS resumable uploads (default: auto) |
| --partial | boolean |
[DEPRECATED] Use --delta instead. Upload incremental updates |
| --partial-only | boolean |
[DEPRECATED] Use --delta-only instead. Upload only incremental updates, skip full bundle |
| --delta | boolean |
Upload incremental/differential updates to reduce bandwidth |
| --delta-only | boolean |
Upload only delta updates without full bundle (useful for large apps) |
| --encrypted-checksum | string |
An encrypted checksum (signature). Used only when uploading an external bundle. |
| --auto-set-bundle | boolean |
Set the bundle in capacitor.config.json |
| --dry-upload | boolean |
Dry upload the bundle process, mean it will not upload the files but add the row in database (Used by Capgo for internal testing) |
| --package-json | string |
Paths to package.json files for monorepos (comma-separated) |
| --node-modules | string |
Paths to node_modules directories for monorepos (comma-separated) |
| --encrypt-partial | boolean |
Encrypt delta update files (auto-enabled for updater > 6.14.4) |
| --delete-linked-bundle-on-upload | boolean |
Locates the currently linked bundle in the channel you are trying to upload to, and deletes it |
| --no-brotli-patterns | string |
Files to exclude from Brotli compression (comma-separated globs, e.g., ".jpg,.png") |
| --disable-brotli | boolean |
Completely disable brotli compression even if updater version supports it |
| --version-exists-ok | boolean |
Exit successfully if bundle version already exists, useful for CI/CD workflows with monorepos |
| --self-assign | boolean |
Allow devices to auto-join this channel (updates channel setting) |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
npx @capgo/cli@latest bundle compatibility🧪 Check compatibility of a bundle with a specific channel in Capgo Cloud to ensure updates are safe.
Example:
npx @capgo/cli@latest bundle compatibility com.example.app --channel productionOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| -c, | string |
Channel to check the compatibility with |
| --text | boolean |
Output text instead of emojis |
| --package-json | string |
Paths to package.json files for monorepos (comma-separated) |
| --node-modules | string |
Paths to node_modules directories for monorepos (comma-separated) |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: d
npx @capgo/cli@latest bundle delete🗑️ Delete a specific bundle from Capgo Cloud, optionally targeting a single version.
Example:
npx @capgo/cli@latest bundle delete BUNDLE_ID com.example.appOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: l
npx @capgo/cli@latest bundle list📋 List all bundles uploaded for an app in Capgo Cloud.
Example:
npx @capgo/cli@latest bundle list com.example.appOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: c
npx @capgo/cli@latest bundle cleanup🧹 Delete old bundles in Capgo Cloud, keeping specified number of recent versions. Bundles linked to channels are preserved unless --ignore-channel is used.
Example:
npx @capgo/cli@latest bundle cleanup com.example.app --bundle=1.0 --keep=3Options:
| Param | Type | Description |
|---|---|---|
| -b, | string |
Bundle version number of the app to delete |
| -a, | string |
API key to link to your account |
| -k, | string |
Number of versions to keep |
| -f, | string |
Force removal |
| --ignore-channel | boolean |
Delete bundles even if linked to channels (WARNING: deletes channels too) |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
npx @capgo/cli@latest bundle encrypt🔒 Encrypt a zip bundle for secure external storage. Returns ivSessionKey for upload/decryption. Get checksum using 'bundle zip --json'.
Example:
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUMOptions:
| Param | Type | Description |
|---|---|---|
| --key | string |
Custom path for private signing key |
| --key-data | string |
Private signing key |
| -j, | string |
Output in JSON |
npx @capgo/cli@latest bundle decrypt🔓 Decrypt an encrypted bundle (mainly for testing). Prints base64 session key for verification.
Example:
npx @capgo/cli@latest bundle decrypt ./myapp_encrypted.zip CHECKSUMOptions:
| Param | Type | Description |
|---|---|---|
| --key | string |
Custom path for private signing key |
| --key-data | string |
Private signing key |
| --checksum | string |
Checksum of the bundle, to verify the integrity of the bundle |
npx @capgo/cli@latest bundle zip🗜️ Create a zip file of your app bundle. Returns checksum for use with encryption. Use --json for machine-readable output.
Example:
npx @capgo/cli@latest bundle zip com.example.app --path ./distOptions:
| Param | Type | Description |
|---|---|---|
| -p, | string |
Path of the folder to upload, if not provided it will use the webDir set in capacitor.config |
| -b, | string |
Bundle version number to name the zip file |
| -n, | string |
Name of the zip file |
| -j, | string |
Output in JSON |
| --no-code-check | boolean |
Ignore checking if notifyAppReady() is called in source code and index present in root folder |
| --key-v2 | boolean |
Use encryption v2 |
| --package-json | string |
Paths to package.json files for monorepos (comma-separated) |
📱 Manage your Capgo app settings and configurations in Capgo Cloud.
Alias: a
npx @capgo/cli@latest app add➕ Add a new app to Capgo Cloud with a unique app ID in the format com.test.app. All options can be guessed from config if not provided.
Example:
npx @capgo/cli@latest app add com.example.app --name "My App" --icon ./icon.pngOptions:
| Param | Type | Description |
|---|---|---|
| -n, | string |
App name for display in Capgo Cloud |
| -i, | string |
App icon path for display in Capgo Cloud |
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
npx @capgo/cli@latest app delete🗑️ Delete an app from Capgo Cloud, optionally specifying a version to delete only that bundle.
Example:
npx @capgo/cli@latest app delete com.example.appOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: l
npx @capgo/cli@latest app list📋 List all apps registered under your account in Capgo Cloud.
Example:
npx @capgo/cli@latest app listOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
npx @capgo/cli@latest app debug🐞 Listen for live update events in Capgo Cloud to debug your app. Optionally target a specific device for detailed diagnostics.
Example:
npx @capgo/cli@latest app debug com.example.app --device DEVICE_IDOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| -d, | string |
The specific device ID to debug |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
npx @capgo/cli@latest app setting⚙️ Modify Capacitor configuration programmatically. Specify setting path (e.g., plugins.CapacitorUpdater.defaultChannel) with --string or --bool.
Example:
npx @capgo/cli@latest app setting plugins.CapacitorUpdater.defaultChannel --string "Production"Options:
| Param | Type | Description |
|---|---|---|
| --bool | string |
A value for the setting to modify as a boolean, ex: --bool true |
| --string | string |
A value for the setting to modify as a string, ex: --string "Production" |
Alias: s
npx @capgo/cli@latest app set⚙️ Update settings for an existing app in Capgo Cloud, such as name, icon, or retention period for bundles. Retention of 0 means infinite storage.
Example:
npx @capgo/cli@latest app set com.example.app --name "Updated App" --retention 30Options:
| Param | Type | Description |
|---|---|---|
| -n, | string |
App name for display in Capgo Cloud |
| -i, | string |
App icon path for display in Capgo Cloud |
| -a, | string |
API key to link to your account |
| -r, | string |
Days to keep old bundles (0 = infinite, default: 0) |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
📢 Manage distribution channels for app updates in Capgo Cloud, controlling how updates are delivered to devices.
Alias: a
npx @capgo/cli@latest channel add➕ Create a new channel for app distribution in Capgo Cloud to manage update delivery.
Example:
npx @capgo/cli@latest channel add production com.example.app --defaultOptions:
| Param | Type | Description |
|---|---|---|
| -d, | string |
Set the channel as default |
| --self-assign | boolean |
Allow device to self-assign to this channel |
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: d
npx @capgo/cli@latest channel delete🗑️ Delete a channel from Capgo Cloud, optionally removing associated bundles to free up resources.
Example:
npx @capgo/cli@latest channel delete production com.example.appOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| --delete-bundle | boolean |
Delete the bundle associated with the channel |
| --success-if-not-found | boolean |
Success if the channel is not found |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: l
npx @capgo/cli@latest channel list📋 List all channels configured for an app in Capgo Cloud to review distribution settings.
Example:
npx @capgo/cli@latest channel list com.example.appOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
npx @capgo/cli@latest channel currentBundle📦 Get the current bundle linked to a specific channel in Capgo Cloud for update tracking.
Example:
npx @capgo/cli@latest channel currentBundle production com.example.appOptions:
| Param | Type | Description |
|---|---|---|
| -c, | string |
Channel to get the current bundle from |
| -a, | string |
API key to link to your account |
| --quiet | boolean |
Only print the bundle version |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: s
npx @capgo/cli@latest channel set⚙️ Configure settings for a channel, such as linking a bundle, setting update strategies (major, minor, metadata, patch, none), or device targeting (iOS, Android, dev, emulator). One channel must be default.
Example:
npx @capgo/cli@latest channel set production com.example.app --bundle 1.0.0 --state defaultOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| -b, | string |
Bundle version number of the file to set |
| -s, | string |
Set the state of the channel, default or normal |
| --latest-remote | boolean |
Get the latest bundle uploaded in capgo cloud and set it to the channel |
| --latest | boolean |
Get the latest version key in the package.json to set it to the channel |
| --downgrade | boolean |
Allow to downgrade to version under native one |
| --no-downgrade | boolean |
Disable downgrade to version under native one |
| --ios | boolean |
Allow sending update to iOS devices |
| --no-ios | boolean |
Disable sending update to iOS devices |
| --android | boolean |
Allow sending update to Android devices |
| --no-android | boolean |
Disable sending update to Android devices |
| --self-assign | boolean |
Allow device to self-assign to this channel |
| --no-self-assign | boolean |
Disable devices to self-assign to this channel |
| --disable-auto-update | string |
Block updates by type: major, minor, metadata, patch, or none (allows all) |
| --dev | boolean |
Allow sending update to development devices |
| --no-dev | boolean |
Disable sending update to development devices |
| --emulator | boolean |
Allow sending update to emulator devices |
| --no-emulator | boolean |
Disable sending update to emulator devices |
| --package-json | string |
Paths to package.json files for monorepos (comma-separated) |
| --ignore-metadata-check | boolean |
Ignore checking node_modules compatibility if present in the bundle |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
🔐 Manage encryption keys for secure bundle distribution in Capgo Cloud, supporting end-to-end encryption with RSA and AES combination.
npx @capgo/cli@latest key save💾 Save the public key in the Capacitor config, useful for CI environments. Recommended not to commit the key for security.
Example:
npx @capgo/cli@latest key save --key ./path/to/key.pubOptions:
| Param | Type | Description |
|---|---|---|
| -f, | string |
Force generate a new one |
| --key | string |
Key path to save in Capacitor config |
| --key-data | string |
Key data to save in Capacitor config |
npx @capgo/cli@latest key create🔨 Create RSA key pair for end-to-end encryption. Creates .capgo_key_v2 (private) and .capgo_key_v2.pub (public) in project root. Public key is saved to capacitor.config for mobile app decryption. NEVER commit the private key - store it securely!
Example:
npx @capgo/cli@latest key createOptions:
| Param | Type | Description |
|---|---|---|
| -f, | string |
Force generate a new one |
npx @capgo/cli@latest key delete_old🧹 Delete the old encryption key from the Capacitor config to ensure only the current key is used.
Example:
npx @capgo/cli@latest key delete_old👤 Manage your Capgo account details and retrieve information for support or collaboration.
npx @capgo/cli@latest account id🪪 Retrieve your account ID, safe to share for collaboration or support purposes in Discord or other platforms.
Example:
npx @capgo/cli@latest account idOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
🏢 Manage your organizations in Capgo Cloud for team collaboration and app management.
Alias: l
npx @capgo/cli@latest organisation list📋 List all organizations you have access to in Capgo Cloud.
Example:
npx @capgo/cli@latest organisation listOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: a
npx @capgo/cli@latest organisation add➕ Create a new organization in Capgo Cloud for team collaboration.
Example:
npx @capgo/cli@latest organisation add --name "My Company" --email [email protected]Options:
| Param | Type | Description |
|---|---|---|
| -n, | string |
Organization name |
| -e, | string |
Management email for the organization |
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: s
npx @capgo/cli@latest organisation set⚙️ Update organization settings such as name and management email.
Example:
npx @capgo/cli@latest organisation set ORG_ID --name "Updated Company Name"Options:
| Param | Type | Description |
|---|---|---|
| -n, | string |
Organization name |
| -e, | string |
Management email for the organization |
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
Alias: d
npx @capgo/cli@latest organisation delete🗑️ Delete an organization from Capgo Cloud. This action cannot be undone. Only organization owners can delete organizations.
Example:
npx @capgo/cli@latest organisation delete ORG_IDOptions:
| Param | Type | Description |
|---|---|---|
| -a, | string |
API key to link to your account |
| --supa-host | string |
Custom Supabase host URL (for self-hosting or Capgo development) |
| --supa-anon | string |
Custom Supabase anon key (for self-hosting) |
You can use the Capgo CLI programmatically in your Node.js/TypeScript projects for automation and CI/CD pipelines.
npm install @capgo/cliimport { CapgoSDK } from '@capgo/cli/sdk'
const sdk = new CapgoSDK({
apikey: 'your-api-key'
})
await sdk.uploadBundle({
appId: 'com.example.app',
bundle: '1.0.0',
path: './dist',
channel: 'production'
})import { CapgoSDK } from '@capgo/cli/sdk'
const sdk = new CapgoSDK({
apikey: process.env.CAPGO_API_KEY
})
// Upload new version
await sdk.uploadBundle({
appId: 'com.example.app',
bundle: process.env.VERSION,
path: './dist',
channel: 'production'
})
// Cleanup old bundles
await sdk.cleanupBundles({
appId: 'com.example.app',
keep: 10
})All CLI features are available as SDK methods. See the TypeScript types for the complete API reference.