--- description: Automate the Capawesome Cloud CLI in scripts and CI — token authentication, non-interactive flags, parsing JSON output, polling builds, and handling failures. title: CLI Scripting - Capawesome image: https://capawesome.io/docs/assets/images/social/cloud/cli/scripting.png --- [ Skip to content](#scripting) [ 🔐 Introducing the **Capacitor Vault** plugin — store secrets behind biometrics or a device passcode.](/blog/announcing-the-capacitor-vault-plugin/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm or Yarn ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * [ Wait for a build to finish ](#wait-for-a-build-to-finish) * [ Handle failures ](#handle-failures) * [ Make repeated runs idempotent ](#make-repeated-runs-idempotent) * [ Full example: build and deploy in CI ](#full-example-build-and-deploy-in-ci) * [ Next steps ](#next-steps) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ Wait for a build to finish ](#wait-for-a-build-to-finish) * [ Handle failures ](#handle-failures) * [ Make repeated runs idempotent ](#make-repeated-runs-idempotent) * [ Full example: build and deploy in CI ](#full-example-build-and-deploy-in-ci) * [ Next steps ](#next-steps) # Scripting[¶](#scripting "Permanent link") The CLI is designed to run unattended. This guide covers what changes when there's no human at the keyboard: authenticating without a browser, running commands non-interactively, parsing JSON output, waiting on long-running jobs, and failing the pipeline when something goes wrong. If you're looking for ready-made snippets, see [Examples](/docs/cloud/cli/examples/). This page explains the underlying behavior so you can adapt them safely. ## Authenticate with a token[¶](#authenticate-with-a-token "Permanent link") Interactive login doesn't work on a build server. Instead, create an [API token](/docs/cloud/accounts/tokens/) and expose it as the `CAPAWESOME_TOKEN` environment variable — the CLI reads it automatically, so you don't need to pass it on every command: `[](#%5F%5Fcodelineno-0-1)export CAPAWESOME_TOKEN="$YOUR_CI_SECRET" [](#%5F%5Fcodelineno-0-2)npx @capawesome/cli whoami ` Store the token as a secret in your CI provider and never commit it to version control. You can also pass `--token` on an individual command if you prefer; see [Authentication](/docs/cloud/cli/authentication/) for details. Alternative variable `CAPAWESOME_CLOUD_TOKEN` is also accepted and takes precedence over `CAPAWESOME_TOKEN` if both are set. ## Run commands non-interactively[¶](#run-commands-non-interactively "Permanent link") Run a command without a TTY and two things will trip you up: confirmation prompts and missing required values. Pass every required value as a flag, and add `--yes` to skip confirmations: `[](#%5F%5Fcodelineno-1-1)npx @capawesome/cli apps:builds:create \ [](#%5F%5Fcodelineno-1-2) --app-id "$APP_ID" \ [](#%5F%5Fcodelineno-1-3) --platform android \ [](#%5F%5Fcodelineno-1-4) --type release \ [](#%5F%5Fcodelineno-1-5) --git-ref main \ [](#%5F%5Fcodelineno-1-6) --yes ` The CLI only prompts when both input and output are a terminal and the `CI` environment variable is unset. In CI it therefore won't hang waiting for input — if a required value like `--app-id` is missing, it exits with a non-zero code instead. Always pass the required flags explicitly. ## Pin the CLI version[¶](#pin-the-cli-version "Permanent link") `npx @capawesome/cli` resolves to the latest version, which can change behavior between pipeline runs. Pin a version so your automation stays reproducible: `[](#%5F%5Fcodelineno-2-1)npx @capawesome/cli@4.9.3 whoami ` ## Parse JSON output[¶](#parse-json-output "Permanent link") Add `--json` to get machine-readable output instead of human-readable text. How you consume it depends on the command. ### Commands that print only JSON[¶](#commands-that-print-only-json "Permanent link") Read-style commands — such as `apps:list`, `apps:builds:get`, or `apps:channels:list` — print nothing but the JSON object. You can pipe them straight into [jq](https://jqlang.github.io/jq/): `[](#%5F%5Fcodelineno-3-1)npx @capawesome/cli apps:list --json | jq -r '.[].id' ` ### Commands that stream progress[¶](#commands-that-stream-progress "Permanent link") Commands that do long-running work — `apps:builds:create` and `apps:liveupdates:upload` — print progress lines to standard output while they run and the JSON object only at the very end. Both share the same stream, so piping directly into `jq` fails on the progress lines. Capture the output and extract the trailing JSON block instead: `[](#%5F%5Fcodelineno-4-1)OUTPUT=$(mktemp) [](#%5F%5Fcodelineno-4-2)npx @capawesome/cli apps:builds:create \ [](#%5F%5Fcodelineno-4-3) --app-id "$APP_ID" \ [](#%5F%5Fcodelineno-4-4) --platform android \ [](#%5F%5Fcodelineno-4-5) --type release \ [](#%5F%5Fcodelineno-4-6) --git-ref main \ [](#%5F%5Fcodelineno-4-7) --json \ [](#%5F%5Fcodelineno-4-8) --yes | tee "$OUTPUT" [](#%5F%5Fcodelineno-4-9)BUILD_ID=$(sed -n '/^{/,$p' "$OUTPUT" | jq -r '.id') [](#%5F%5Fcodelineno-4-10)rm "$OUTPUT" ` The JSON is pretty-printed, so it begins with a `{` on its own line. `sed -n '/^{/,$p'` keeps everything from that line to the end and drops the progress above it, while `tee` still shows the progress in your CI logs. ## Wait for a build to finish[¶](#wait-for-a-build-to-finish "Permanent link") By default, `apps:builds:create` and `apps:deployments:create` wait for the job to complete and exit non-zero if it fails — so a failed build stops your pipeline with no extra work on your part. Pass `--detached` when you'd rather not block, for example to run other steps while the build runs. There's a trade-off: a detached command exits `0` as soon as the build is _queued_, regardless of whether it later succeeds or fails. To get the real outcome, poll [apps:builds:get](/docs/cloud/cli/commands/#appsbuildsget) — which prints clean JSON — until the status is terminal: `[](#%5F%5Fcodelineno-5-1)while true; do [](#%5F%5Fcodelineno-5-2) STATUS=$(npx @capawesome/cli apps:builds:get \ [](#%5F%5Fcodelineno-5-3) --app-id "$APP_ID" \ [](#%5F%5Fcodelineno-5-4) --build-id "$BUILD_ID" \ [](#%5F%5Fcodelineno-5-5) --json | jq -r '.job.status') [](#%5F%5Fcodelineno-5-6) case "$STATUS" in [](#%5F%5Fcodelineno-5-7) succeeded) echo "Build succeeded"; break ;; [](#%5F%5Fcodelineno-5-8) failed|canceled|rejected|timed_out) echo "Build $STATUS"; exit 1 ;; [](#%5F%5Fcodelineno-5-9) *) sleep 10 ;; # queued, pending, in_progress [](#%5F%5Fcodelineno-5-10) esac [](#%5F%5Fcodelineno-5-11)done ` The build's status lives on the nested `job` object (`.job.status`), not at the top level. ## Handle failures[¶](#handle-failures "Permanent link") The CLI exits `0` on success and non-zero on failure, so in most CI systems a failed command stops the job automatically. A build or deployment that fails counts as a failure and exits non-zero — unless you detached from it, in which case you own the polling (see above). To understand _why_ a build failed, request an AI-generated summary with `--failure-summary` (powered by [Capawesome Cloud Assist](/docs/cloud/assist/)), or fetch one afterward with [apps:builds:failure-summary](/docs/cloud/cli/commands/#appsbuildsfailure-summary). Transient network errors The CLI automatically retries failed requests caused by network errors or `5xx` responses, and honors the `HTTPS_PROXY` and `HTTP_PROXY` environment variables — useful behind a corporate proxy. ## Make repeated runs idempotent[¶](#make-repeated-runs-idempotent "Permanent link") A pipeline shouldn't fail just because a resource already exists. `apps:channels:create` accepts `--ignore-errors`, which exits `0` even when the channel is already there, so you can create-then-use without a separate existence check: `[](#%5F%5Fcodelineno-6-1)npx @capawesome/cli apps:channels:create --app-id "$APP_ID" --name production --ignore-errors ` This flag is specific to channel creation. ## Full example: build and deploy in CI[¶](#full-example-build-and-deploy-in-ci "Permanent link") Putting it together — authenticate with a token from a CI secret, pin the version, ensure the channel exists, then build and deploy non-interactively. Because the default behavior waits and fails on a bad build, no extra error handling is needed to fail the pipeline: `[](#%5F%5Fcodelineno-7-1)# CAPAWESOME_TOKEN is provided as a CI secret [](#%5F%5Fcodelineno-7-2)CLI="npx @capawesome/cli@4.9.3" [](#%5F%5Fcodelineno-7-3) [](#%5F%5Fcodelineno-7-4)# Ensure the channel exists (won't fail if it already does) [](#%5F%5Fcodelineno-7-5)$CLI apps:channels:create --app-id "$APP_ID" --name production --ignore-errors [](#%5F%5Fcodelineno-7-6) [](#%5F%5Fcodelineno-7-7)# Build the web app in the cloud and deploy it to the channel [](#%5F%5Fcodelineno-7-8)$CLI apps:builds:create \ [](#%5F%5Fcodelineno-7-9) --app-id "$APP_ID" \ [](#%5F%5Fcodelineno-7-10) --platform web \ [](#%5F%5Fcodelineno-7-11) --channel production \ [](#%5F%5Fcodelineno-7-12) --git-ref "$GIT_SHA" \ [](#%5F%5Fcodelineno-7-13) --yes ` ## Next steps[¶](#next-steps "Permanent link") * [Examples](/docs/cloud/cli/examples/) — ready-made recipes for builds, Live Updates, and CI. * [Usage](/docs/cloud/cli/usage/) — command anatomy, global flags, and the `doctor` command. * [Command reference](/docs/cloud/cli/commands/) — every command and its options. * [Integrations](/docs/cloud/integrations/) — wire these scripts into your CI/CD provider. June 9, 2026 Back to top