Skip to content

CLI

The Capawesome Cloud Command Line Interface (CLI) can be used to manage your apps and resources from the command line, including Live Updates, Native Builds, and App Submissions.

Installation

The Capawesome CLI can be installed globally via npm:

npm install -g @capawesome/cli@latest

Help

The Capawesome CLI ships with command documentation that is accessible with the --help flag.

npx @capawesome/cli --help

Usage

The Capawesome CLI uses the following syntax:

npx @capawesome/cli <command> [options]

Authentication

To use the Capawesome CLI, you need to authenticate with Capawesome Cloud. You can do this by running the following command:

npx @capawesome/cli login

For CI/CD environments, you can generate a token from the Capawesome Cloud Console and use it to log in non-interactively:

npx @capawesome/cli login --token <your_token>

Command Reference

apps:create

Create a new app in Capawesome Cloud.

npx @capawesome/cli apps:create [options]

Options:

  • --name: The name of the app.
  • --organization-id: The ID of the organization to create the app in.

apps:delete

Delete an app from Capawesome Cloud.

npx @capawesome/cli apps:delete [options]

Options:

  • --app-id: The ID of the app.
  • --yes, -y: Skip confirmation prompt.

apps:builds:cancel

Cancel an app build.

npx @capawesome/cli apps:builds:cancel [options]

Options:

  • --app-id: The ID of the app the build belongs to.
  • --build-id: The ID of the build to cancel.

apps:builds:create

Create a new app build.

npx @capawesome/cli apps:builds:create [options]

Options:

  • --aab: Download the generated AAB file (Android only). Optionally provide a file path.
  • --apk: Download the generated APK file (Android only). Optionally provide a file path.
  • --app-id: The ID of the app to create the build for.
  • --certificate: The name of the certificate to use for the build.
  • --channel: The name of the channel to deploy to (Web only).
  • --destination: The name of the destination to deploy to (Android/iOS only).
  • --detached: Exit immediately after creating the build without waiting for completion.
  • --environment: The name of the environment to use for the build.
  • --git-ref: The Git reference (branch, tag, or commit SHA) to build.
  • --ipa: Download the generated IPA file (iOS only). Optionally provide a file path.
  • --json: Output in JSON format. This will include additional information such as the build ID.
  • --platform: The platform for the build. Supported values are android, ios, and web.
  • --stack: The name of the stack to use for the build. Must be either macos-sequoia or macos-tahoe.
  • --type: The type of build. For Android, supported values are debug and release. For iOS, supported values are simulator, development, ad-hoc, app-store, and enterprise. For Web, no type is required.
  • --yes, -y: Skip confirmation prompts.
  • --zip: Download the generated zip file (Web only). Optionally provide a file path.

apps:builds:download

Download the build artifacts for an app build.

npx @capawesome/cli apps:builds:download [options]

Options: - --app-id: The ID of the app the build belongs to.
- --build-id: The ID of the build to download artifacts for.
- --aab: Download the generated AAB file (Android only). Optionally provide a file path.
- --apk: Download the generated APK file (Android only). Optionally provide a file path.
- --ipa: Download the generated IPA file (iOS only). Optionally provide a file path. - --zip: Download the generated zip file (Web only). Optionally provide a file path.

apps:builds:logs

Display the logs for a ongoing or completed app build.

npx @capawesome/cli apps:builds:logs [options]

Options: - --app-id: The ID of the app the build belongs to.
- --build-id: The ID of the build to display logs for.

apps:certificates:create

Create a new certificate for an app in Capawesome Cloud.

npx @capawesome/cli apps:certificates:create [options]

Options:

  • --app-id: The ID of the app.
  • --file: Path to the certificate file.
  • --key-alias: Key alias for the certificate.
  • --key-password: Key password for the certificate.
  • --name: The name of the certificate.
  • --password: Password for the certificate.
  • --platform: The platform of the certificate. Supported values are android, ios, and web.
  • --provisioning-profile: Paths to provisioning profile files to upload and link. Can be specified multiple times.
  • --type: The type of the certificate. Supported values are development and production.
  • --yes, -y: Skip optional prompts.

apps:certificates:delete

Delete a certificate from an app in Capawesome Cloud.

npx @capawesome/cli apps:certificates:delete [options]

Options:

  • --app-id: The ID of the app.
  • --certificate-id: The ID of the certificate.
  • --name: The name of the certificate.
  • --platform: The platform of the certificate (android, ios, web).
  • --yes, -y: Skip confirmation prompt.

apps:certificates:get

Get a certificate from an app in Capawesome Cloud.

npx @capawesome/cli apps:certificates:get [options]

Options:

  • --app-id: The ID of the app.
  • --certificate-id: The ID of the certificate.
  • --json: Output in JSON format.
  • --name: The name of the certificate.
  • --platform: The platform of the certificate (android, ios, web).

apps:certificates:list

List all certificates for an app in Capawesome Cloud.

npx @capawesome/cli apps:certificates:list [options]

Options:

  • --app-id: The ID of the app.
  • --json: Output in JSON format.
  • --limit: The maximum number of certificates to return.
  • --offset: The offset to start returning certificates from.
  • --platform: Filter by platform. Supported values are android, ios, and web.
  • --type: Filter by type. Supported values are development and production.

apps:certificates:update

Update an existing certificate from an app in Capawesome Cloud.

npx @capawesome/cli apps:certificates:update [options]

Options:

  • --app-id: The ID of the app.
  • --certificate-id: The ID of the certificate.
  • --key-alias: Key alias for the certificate.
  • --key-password: Key password for the certificate.
  • --name: The name of the certificate.
  • --password: Password for the certificate.
  • --type: The type of the certificate. Supported values are development and production.

apps:channels:create

Create a new channel for an app in Capawesome Cloud.

npx @capawesome/cli apps:channels:create [options]

Options:

  • --app-id: The ID of the app.
  • --ignore-errors: Ignore errors when creating the channel. This is useful for CI/CD pipelines where the channel may already exist. Defaults to false.
  • --name: The name of the channel.
  • --protected: Whether to protect the channel or not. Defaults to false.

apps:channels:delete

Delete a channel from an app in Capawesome Cloud.

npx @capawesome/cli apps:channels:delete [options]

Options:

  • --app-id: The ID of the app.
  • --channel-id: The ID of the channel. Either the ID or the name of the channel must be provided.
  • --name: The name of the channel. Either the ID or the name of the channel must be provided.
  • --yes, -y: Skip confirmation prompt.

apps:channels:get

Get a channel from an app in Capawesome Cloud.

npx @capawesome/cli apps:channels:get [options]

Options:

  • --app-id: The ID of the app.
  • --channel-id: The ID of the channel. Either the ID or the name of the channel must be provided.
  • --json: Output in JSON format.
  • --name: The name of the channel. Either the ID or the name of the channel must be provided.

apps:channels:list

List all channels for an app in Capawesome Cloud.

npx @capawesome/cli apps:channels:list [options]

Options:

  • --app-id: The ID of the app.
  • --json: Output in JSON format.
  • --limit: The maximum number of channels to return.
  • --offset: The offset to start returning channels from.

apps:channels:pause

Pause an app channel.

npx @capawesome/cli apps:channels:pause [options]

Options:

  • --app-id: The ID of the app.
  • --channel: The name of the channel to pause.

apps:channels:resume

Resume an app channel.

npx @capawesome/cli apps:channels:resume [options]

Options:

  • --app-id: The ID of the app.
  • --channel: The name of the channel to resume.

apps:channels:update

Update an existing channel from an app in Capawesome Cloud.

npx @capawesome/cli apps:channels:update [options]

Options:

  • --app-id: The ID of the app.
  • --channel-id: The ID of the channel.
  • --name: The name of the channel.
  • --protected: Whether to protect the channel or not.

apps:deployments:cancel

Cancel an ongoing app deployment.

npx @capawesome/cli apps:deployments:cancel [options]

Options:

  • --app-id: The ID of the app the deployment belongs to.
  • --deployment-id: The ID of the deployment to cancel.

apps:deployments:create

Create a new app deployment.

npx @capawesome/cli apps:deployments:create [options]

Options:

  • --app-id: The ID of the app to create the deployment for.
  • --build-id: The ID of the build to deploy. Alternative to --build-number.
  • --build-number: The build number to deploy (e.g., "1", "42"). Alternative to --build-id.
  • --channel: The name of the channel to deploy the build to (Web only).
  • --destination: The name of the destination to deploy to (Android/iOS only).
  • --detached: Exit immediately after creating the deployment without waiting for completion.

apps:deployments:logs

Display the logs for a ongoing or completed app deployment.

npx @capawesome/cli apps:deployments:logs [options]

Options: - --app-id: The ID of the app the deployment belongs to. - --deployment-id: The ID of the deployment to display logs for.

apps:destinations:create

Create a new destination for an app in Capawesome Cloud.

npx @capawesome/cli apps:destinations:create [options]

Options:

  • --app-id: The ID of the app.
  • --name: The name of the destination.
  • --platform: The platform of the destination. Supported values are android and ios.
  • --android-build-artifact-type: Android build artifact type. Supported values are aab and apk.
  • --android-package-name: Android package name.
  • --android-release-status: Android release status. Supported values are completed and draft.
  • --google-play-track: Google Play track.
  • --google-service-account-key-file: Path to the Google service account key JSON file.
  • --apple-api-key-file: Path to the Apple API key (.p8) file.
  • --apple-app-id: Apple App ID.
  • --apple-app-password: Apple app-specific password.
  • --apple-id: Apple ID.
  • --apple-issuer-id: Apple Issuer ID.
  • --apple-team-id: Apple Team ID.

apps:destinations:delete

Delete a destination from an app in Capawesome Cloud.

npx @capawesome/cli apps:destinations:delete [options]

Options:

  • --app-id: The ID of the app.
  • --destination-id: The ID of the destination.
  • --name: The name of the destination.
  • --platform: The platform of the destination (android, ios).
  • --yes, -y: Skip confirmation prompt.

apps:destinations:get

Get a destination from an app in Capawesome Cloud.

npx @capawesome/cli apps:destinations:get [options]

Options:

  • --app-id: The ID of the app.
  • --destination-id: The ID of the destination.
  • --json: Output in JSON format.
  • --name: The name of the destination.
  • --platform: The platform of the destination (android, ios).

apps:destinations:list

List all destinations for an app in Capawesome Cloud.

npx @capawesome/cli apps:destinations:list [options]

Options:

  • --app-id: The ID of the app.
  • --json: Output in JSON format.
  • --limit: The maximum number of destinations to return.
  • --offset: The offset to start returning destinations from.
  • --platform: Filter by platform. Supported values are android and ios.

apps:destinations:update

Update an existing destination from an app in Capawesome Cloud.

npx @capawesome/cli apps:destinations:update [options]

Options:

  • --app-id: The ID of the app.
  • --destination-id: The ID of the destination.
  • --name: The name of the destination.
  • --android-build-artifact-type: Android build artifact type. Supported values are aab and apk.
  • --android-package-name: Android package name.
  • --android-release-status: Android release status. Supported values are completed and draft.
  • --app-google-service-account-key-id: App Google Service Account Key ID.
  • --google-play-track: Google Play track.
  • --apple-api-key-id: Apple API Key ID.
  • --apple-app-id: Apple App ID.
  • --apple-app-password: Apple app-specific password.
  • --apple-id: Apple ID.
  • --apple-issuer-id: Apple Issuer ID.
  • --apple-team-id: Apple Team ID.
  • --app-apple-api-key-id: App Apple API Key ID.

apps:devices:delete

Delete a device from an app in Capawesome Cloud.

npx @capawesome/cli apps:devices:delete [options]

Options:

  • --app-id: The ID of the app.
  • --device-id: The ID of the device.
  • --yes, -y: Skip confirmation prompt.

apps:devices:forcechannel

Force a device to use a specific channel.

npx @capawesome/cli apps:devices:forcechannel [options]

Options:

  • --app-id: The ID of the app.
  • --device-id: The ID of the device.
  • --channel: The name of the channel to force.

apps:devices:probe

Check whether a device would receive a live update. This is useful for debugging and testing purposes, especially when setting up new devices or troubleshooting existing ones.

npx @capawesome/cli apps:devices:probe [options]

Options:

  • --app-id: The ID of the app.
  • --device-id: The ID of the device.
  • --json: Output in JSON format.

apps:devices:unforcechannel

Remove the forced channel from a device.

npx @capawesome/cli apps:devices:unforcechannel [options]

Options:

  • --app-id: The ID of the app.
  • --device-id: The ID of the device.

apps:environments:create

Create a new environment for an app in Capawesome Cloud.

npx @capawesome/cli apps:environments:create [options]

Options:

  • --app-id: The ID of the app.
  • --name: The name of the environment.

apps:environments:delete

Delete an environment from an app in Capawesome Cloud.

npx @capawesome/cli apps:environments:delete [options]

Options:

  • --app-id: The ID of the app.
  • --environment-id: The ID of the environment. Either the ID or name must be provided.
  • --name: The name of the environment. Either the ID or name must be provided.
  • --yes, -y: Skip confirmation prompt.

apps:environments:list

List all environments for an app in Capawesome Cloud.

npx @capawesome/cli apps:environments:list [options]

Options:

  • --app-id: The ID of the app.
  • --json: Output in JSON format.
  • --limit: The maximum number of environments to return.
  • --offset: The offset to start returning environments from.

apps:environments:set

Set environment variables and secrets for an environment in Capawesome Cloud.

npx @capawesome/cli apps:environments:set [options]

Options:

  • --app-id: The ID of the app.
  • --environment-id: The ID of the environment.
  • --variable: Environment variable in key=value format. Can be specified multiple times.
  • --variable-file: Path to a file containing environment variables in .env format.
  • --secret: Environment secret in key=value format. Can be specified multiple times.
  • --secret-file: Path to a file containing environment secrets in .env format.

apps:environments:unset

Unset environment variables and secrets for an environment in Capawesome Cloud.

npx @capawesome/cli apps:environments:unset [options]

Options:

  • --app-id: The ID of the app.
  • --environment-id: The ID of the environment.
  • --variable: Key of the environment variable to unset. Can be specified multiple times.
  • --secret: Key of the environment secret to unset. Can be specified multiple times.

apps:liveupdates:bundle

Generate manifest file and compress web assets into a zip file.

npx @capawesome/cli apps:liveupdates:bundle [options]

Options:

  • --input-path: Path to the web assets directory.
  • --output-path: Output path for the generated artifact file. Defaults to ./bundle.zip.
  • --overwrite: Overwrite output file if it already exists. Defaults to false.
  • --skip-manifest: Skip manifest file generation. Defaults to false.

apps:liveupdates:generatemanifest

Generate a manifest file.

npx @capawesome/cli apps:liveupdates:generatemanifest [options]

Options:

  • --path: Path to the web assets folder (e.g. www or dist).

apps:liveupdates:generatesigningkey

Generate a new code signing key pair for Live Updates. This command creates an RSA key pair that can be used to sign and verify Live Updates bundles.

npx @capawesome/cli apps:liveupdates:generatesigningkey [options]

Options:

  • --key-size: The RSA key size in bits. Must be 2048, 3072, or 4096. Defaults to 2048.
  • --public-key-path: Path where the public key should be saved. Defaults to public.pem.
  • --private-key-path: Path where the private key should be saved. Defaults to private.pem.

apps:liveupdates:rollback

Rollback the active build in a channel to a previous deployment.

npx @capawesome/cli apps:liveupdates:rollback [options]

Options:

  • --app-id: The ID of the app.
  • --channel: The name of the channel to rollback.
  • --steps: The number of deployments to go back (1-5).

apps:liveupdates:rollout

Update the rollout percentage of the active build in a channel.

npx @capawesome/cli apps:liveupdates:rollout [options]

Options:

  • --app-id: The ID of the app.
  • --channel: The name of the channel to update rollout for.
  • --percentage: The rollout percentage (0-100).

apps:liveupdates:upload

Upload a locally built bundle and deploy it to a channel.

npx @capawesome/cli apps:liveupdates:upload [options]

Options:

  • --android-eq: The exact Android version code (versionCode) that the bundle does not support.
  • --android-max: The maximum Android version code (versionCode) that the bundle supports.
  • --android-min: The minimum Android version code (versionCode) that the bundle supports.
  • --app-id: The ID of the app.
  • --artifact-type: The type of artifact to upload. Must be zip or manifest. Defaults to zip.
  • --channel: The channel to deploy the bundle to.
  • --commit-message: The commit message of the Git commit that the bundle is linked to. Deprecated, use --git-ref instead.
  • --commit-ref: The commit ref of the Git commit that the bundle is linked to. Deprecated, use --git-ref instead.
  • --commit-sha: The commit SHA of the Git commit that the bundle is linked to. Deprecated, use --git-ref instead.
  • --custom-property: A custom property to assign to the bundle. Must be in the format key=value. Can be specified multiple times.
  • --git-ref: The Git reference (branch, tag, or commit SHA) to associate with the bundle.
  • --ios-eq: The exact iOS version code (CFBundleVersion) that the bundle does not support.
  • --ios-max: The maximum iOS version code (CFBundleVersion) that the bundle supports.
  • --ios-min: The minimum iOS version code (CFBundleVersion) that the bundle supports.
  • --path: The path to the bundle to upload. Must be a folder or zip archive.
  • --private-key: The private key to sign the bundle with. Can be a file path to a .pem file or the private key content as plain text.
  • --rollout-percentage: The percentage of devices to deploy the bundle to. Must be an integer between 0 and 100.
  • --yes, -y: Skip confirmation prompts.

apps:liveupdates:register

Register a self-hosted bundle URL and deploy it to a channel.

npx @capawesome/cli apps:liveupdates:register [options]

Options:

  • --android-eq: The exact Android version code (versionCode) that the bundle does not support.
  • --android-max: The maximum Android version code (versionCode) that the bundle supports.
  • --android-min: The minimum Android version code (versionCode) that the bundle supports.
  • --app-id: The ID of the app.
  • --channel: The channel to deploy the bundle to.
  • --commit-message: The commit message of the Git commit that the bundle is linked to. Deprecated, use --git-ref instead.
  • --commit-ref: The commit ref of the Git commit that the bundle is linked to. Deprecated, use --git-ref instead.
  • --commit-sha: The commit SHA of the Git commit that the bundle is linked to. Deprecated, use --git-ref instead.
  • --custom-property: A custom property to assign to the bundle. Must be in the format key=value. Can be specified multiple times.
  • --git-ref: The Git reference (branch, tag, or commit SHA) to associate with the bundle.
  • --ios-eq: The exact iOS version code (CFBundleVersion) that the bundle does not support.
  • --ios-max: The maximum iOS version code (CFBundleVersion) that the bundle supports.
  • --ios-min: The minimum iOS version code (CFBundleVersion) that the bundle supports.
  • --path: Path to zip file for code signing only.
  • --private-key: The private key to sign the bundle with. Can be a file path to a .pem file or the private key content as plain text.
  • --rollout-percentage: The percentage of devices to deploy the bundle to. Must be an integer between 0 and 100.
  • --url: The URL to the self-hosted bundle file. The URL must start with https://.
  • --yes, -y: Skip confirmation prompts.

apps:liveupdates:setnativeversions

Set native version constraints on a web build.

npx @capawesome/cli apps:liveupdates:setnativeversions [options]

Options:

  • --app-id: The ID of the app.
  • --build-id: The ID of the build to update.
  • --android-eq: The exact Android version code (versionCode) that the build supports.
  • --android-max: The maximum Android version code (versionCode) that the build supports.
  • --android-min: The minimum Android version code (versionCode) that the build supports.
  • --ios-eq: The exact iOS bundle version (CFBundleVersion) that the build supports.
  • --ios-max: The maximum iOS bundle version (CFBundleVersion) that the build supports.
  • --ios-min: The minimum iOS bundle version (CFBundleVersion) that the build supports.

doctor

Print various information about the Capawesome CLI and your environment. This is useful for debugging issues with the CLI or your environment.

npx @capawesome/cli doctor

login

Log in to Capawesome Cloud.

npx @capawesome/cli login

Options:

  • --token: The token to use for authentication.

logout

Log out of Capawesome Cloud.

npx @capawesome/cli logout

whoami

Show the current logged-in user.

npx @capawesome/cli whoami

organizations:create

Create a new organization in Capawesome Cloud.

npx @capawesome/cli organizations:create [options]

Options:

  • --name: The name of the organization.

Advanced

Parsing JSON Output

Many commands in the Capawesome CLI support a --json flag that outputs the command result in JSON format. This is useful for scripting and automation.

You can use tools like jq to parse the JSON output. For example, to get the ID of a newly created build, you can run:

OUTPUT=$(mktemp)
npx @capawesome/cli apps:builds:create \
    --app-id <app-id> \
    --platform <platform> \
    --type <type> \
    --git-ref <git-ref> \
    --json \
    --yes | tee "$OUTPUT"
BUILD_ID=$(sed -n '/^{/,$p' "$OUTPUT" | jq -r '.id')
rm "$OUTPUT"

Then, you can use the BUILD_ID variable in subsequent commands, such as creating a deployment:

npx @capawesome/cli apps:deployments:create \
    --app-id <app-id> \
    --build-id "$BUILD_ID" \
    --destination <destination>