@capgo/cli

Capgo CLI

Check out: Capgo — Instant updates for capacitor

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/

Usage

Before use 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/

📑 Capgo CLI Commands

📋 Table of Contents

• 🚀 Init
• 👨‍⚕️ Doctor
• 🔑 Login
• 📦 Bundle
  • Upload
  • Compatibility
  • Delete
  • List
  • Cleanup
  • Encrypt
  • Decrypt
  • Zip
• 📱 App
  • Add
  • Delete
  • List
  • Debug
  • Setting
  • Set
• 📢 Channel
  • Add
  • Delete
  • List
  • CurrentBundle
  • Set
• 🔐 Key
  • Save
  • Create
  • Delete_old
• 👤 Account
  • Id

🚀 Init

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

Options

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	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

👨‍⚕️ Doctor

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

Options

Param	Type	Description
--package-json	string	A list of paths to package.json. Useful for monorepos (comma separated ex: ../../package.json,./package.json)

🔑 Login

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

Options

Param	Type	Description
--local	boolean	Only save in local folder, git ignored for security.
--supa-host	string	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

📦 Bundle

📦 Manage app bundles for deployment in Capgo Cloud, including upload, compatibility checks, and encryption.

⬆️ Upload

Alias: u

npx @capgo/cli@latest bundle upload

⬆️ Upload a new app bundle to Capgo Cloud for distribution, optionally linking to a channel or external URL. External option supports privacy concerns or large apps (>200MB) by storing only the link. Capgo never inspects external content. Encryption adds a trustless security layer. Version must be > 0.0.0 and unique.

ℹ️ External option helps with corporate privacy concerns and apps larger than 200MB by storing only the link.

ℹ️ Capgo Cloud never looks at the content in the link for external options or in the code when stored.

ℹ️ You can add a second layer of security with encryption, making Capgo trustless.

ℹ️ Version should be greater than "0.0.0" and cannot be overridden or reused after deletion for security reasons.

Example:

npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production

Options:

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-endoint	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	Uses multipart protocol to upload data to S3, Deprecated, use tus instead
--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 for the TUS upload
--partial	boolean	Upload partial files to Capgo cloud (deprecated, use --delta instead)
--partial-only	boolean	Upload only partial files to Capgo cloud, skip the zipped file, useful for big bundle (deprecated, use --delta-only instead)
--delta	boolean	Upload delta update to Capgo cloud (old name: --partial)
--delta-only	boolean	Upload only delta update to Capgo cloud, skip the zipped file, useful for big bundle (old name: --partial-only)
--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	A list of paths to package.json. Useful for monorepos (comma separated ex: ../../package.json,./package.json)
--node-modules	string	A list of paths to node_modules. Useful for monorepos (comma separated ex: ../../node_modules,./node_modules)
--encrypt-partial	boolean	Encrypt the partial update files (automatically applied 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	Glob patterns for files to exclude from brotli compression (comma-separated)
--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 device to self-assign to this channel, this will update the channel, if not provided it will leave the channel as is
--supa-host	string	Supabase host URL, for self-hosted Capgo or testing
--supa-anon	string	Supabase anon token, for self-hosted Capgo or testing

🧪 Compatibility

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 production

Options:

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	A list of paths to package.json. Useful for monorepos (comma separated ex: ../../package.json,./package.json)
--node-modules	string	A list of paths to node_modules. Useful for monorepos (comma separated ex: ../../node_modules,./node_modules)
--supa-host	string	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

🗑️ Delete

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

Options:

Param	Type	Description
-a,	string	API key to link to your account
--supa-host	string	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

📋 List

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

Options:

Param	Type	Description
-a,	string	API key to link to your account
--supa-host	string	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

🧹 Cleanup

Alias: c

npx @capgo/cli@latest bundle cleanup

🧹 Cleanup old bundles in Capgo Cloud, keeping a specified number of recent versions or those linked to channels. Ignores bundles in use.

Example:

npx @capgo/cli@latest bundle cleanup com.example.app --bundle=1.0 --keep=3

Options:

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 all versions even if linked to a channel, this will delete channel as well
--supa-host	string	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

🔒 Encrypt

npx @capgo/cli@latest bundle encrypt

🔒 Encrypt a zip bundle using the new encryption method for secure external storage or testing. Used with external sources or for testing, prints ivSessionKey for upload or decryption. The command will return the ivSessionKey for upload or decryption. The checksum is the checksum of the zip file, you can get it with the --json option of the zip command.

Example:

npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM

Options:

Param	Type	Description
--key	string	Custom path for private signing key
--key-data	string	Private signing key
-j,	string	Output in JSON

🔓 Decrypt

npx @capgo/cli@latest bundle decrypt

🔓 Decrypt a zip bundle using the new encryption method, mainly for testing purposes. Prints the base64 decrypted session key for verification.

Example:

npx @capgo/cli@latest bundle decrypt ./myapp_encrypted.zip CHECKSUM

Options:

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

🔹 Zip

npx @capgo/cli@latest bundle zip

🗜️ Create a zip file of your app bundle for upload or local storage. Useful for preparing bundles before encryption or upload. The command will return the checksum of the zip file, you can use it to encrypt the zip file with the --key-v2 option.

Example:

npx @capgo/cli@latest bundle zip com.example.app --path ./dist

Options:

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	A list of paths to package.json. Useful for monorepos (comma separated ex: ../../package.json,./package.json)

📱 App

📱 Manage your Capgo app settings and configurations in Capgo Cloud.

➕ Add

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

Options:

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	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

🗑️ Delete

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

Options:

Param	Type	Description
-a,	string	API key to link to your account
--supa-host	string	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

📋 List

Alias: l

npx @capgo/cli@latest app list

📋 List all apps registered under your account in Capgo Cloud.

Example:

npx @capgo/cli@latest app list

Options:

Param	Type	Description
-a,	string	API key to link to your account
--supa-host	string	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

🐞 Debug

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_ID

Options:

Param	Type	Description
-a,	string	API key to link to your account
-d,	string	The specific device ID to debug
--supa-host	string	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

⚙️ Setting

npx @capgo/cli@latest app setting

⚙️ Modify Capacitor configuration programmatically by specifying the path to the setting. (e.g., plugins.CapacitorUpdater.defaultChannel). You MUST provide either --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"

⚙️ Set

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 30

Options:

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	Retention period of app bundle in days, 0 by default = infinite
--supa-host	string	Supabase host URL for custom setups
--supa-anon	string	Supabase anon token for custom setups

📢 Channel

📢 Manage distribution channels for app updates in Capgo Cloud, controlling how updates are delivered to devices.

➕ Add

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 --default

Options:

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	Supabase host URL, for self-hosted Capgo or testing
--supa-anon	string	Supabase anon token, for self-hosted Capgo or testing

🗑️ Delete

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

Options:

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	Supabase host URL, for self-hosted Capgo or testing
--supa-anon	string	Supabase anon token, for self-hosted Capgo or testing

📋 List

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

Options:

Param	Type	Description
-a,	string	API key to link to your account
--supa-host	string	Supabase host URL, for self-hosted Capgo or testing
--supa-anon	string	Supabase anon token, for self-hosted Capgo or testing

📦 CurrentBundle

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

Options:

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	Supabase host URL, for self-hosted Capgo or testing
--supa-anon	string	Supabase anon token, for self-hosted Capgo or testing

⚙️ Set

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 default

Options:

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	Disable auto update strategy for this channel. The possible options are: major, minor, metadata, patch, none
--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	A list of paths to package.json. Useful for monorepos (comma separated ex: ../../package.json,./package.json)
--ignore-metadata-check	boolean	Ignore checking node_modules compatibility if present in the bundle
--supa-host	string	Supabase host URL, for self-hosted Capgo or testing
--supa-anon	string	Supabase anon token, for self-hosted Capgo or testing

🔐 Key

🔐 Manage encryption keys for secure bundle distribution in Capgo Cloud, supporting end-to-end encryption with RSA and AES combination.

🔹 Save

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

Options:

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

🔨 Create

npx @capgo/cli@latest key create

🔨 Create a new encryption key pair for end-to-end encryption in Capgo Cloud. Do not commit or share the private key; save it securely. This command will create a new key pair with the name .capgo_key_v2 and .capgo_key_v2.pub in the root of the project. The public key is used to decrypt the zip file in the mobile app. The public key will also be stored in the capacitor config. This is the one used in the mobile app. The file is just a backup. The private key is used to encrypt the zip file in the CLI.

Example:

npx @capgo/cli@latest key create

Options:

Param	Type	Description
-f,	string	Force generate a new one

🗑️ Delete_old

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

👤 Account

👤 Manage your Capgo account details and retrieve information for support or collaboration.

🔹 Id

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 id

Options:

Param	Type	Description
-a,	string	API key to link to your account