| name | capawesome-cloud |
| description | Guides the agent through setting up and using Capawesome Cloud for Capacitor and Cordova apps. Covers three core workflows: (1) Native Builds — cloud builds for iOS and Android (Capacitor, Cordova, or native projects), signing certificates, environments, Trapeze configuration, and build artifacts; (2) Live Updates — OTA updates via the @capawesome/capacitor-live-update or @capawesome/cordova-live-update plugin, channels, versioning, rollbacks, and code signing; (3) App Store Publishing — automated submissions to Apple App Store (TestFlight) and Google Play Store. Includes CI/CD integration for all workflows. Do not use for non-Capacitor, non-Cordova mobile frameworks such as React Native or Flutter. |
| metadata | {"author":"capawesome-team","source":"https://github.com/capawesome-team/skills/tree/main/skills/capawesome-cloud"} |
Capawesome Cloud
Set up and manage native builds, live updates, and app store publishing for Capacitor and Cordova apps using Capawesome Cloud.
Prerequisites
- A Capawesome Cloud account and organization.
- A Capacitor 6/7/8 or Cordova app. Notes:
- Live Updates: supported on both Capacitor and Cordova.
- Native Builds: supported on Capacitor, Cordova, and native iOS/Android projects.
- App Store Publishing: framework-agnostic — works with any native build produced by Native Builds.
- Node.js and npm installed.
- For Native Builds: The app must be in a Git repository (GitHub, GitLab, Bitbucket, or Azure DevOps).
- For Apple App Store Publishing: An active Apple Developer Program membership and an app created in App Store Connect.
- For Google Play Store Publishing: A Google Play Developer account and an app created in Google Play Console with at least one version uploaded manually.
General Rules
Before running any @capawesome/cli command for the first time, run it with the --help flag to review all available options.
MCP Server
The Capawesome MCP server serves the current Capawesome documentation, so it is always ahead of the guidance bundled with this skill. With an API token it also exposes the Capawesome Cloud management API.
- If the Capawesome MCP tools are available, call
search_docs for the topic and read the matching page with get_doc_page before applying the guidance below. Where the two disagree, follow the documentation. The cloud_* tools can carry out the Capawesome Cloud steps in this skill directly — creating apps, triggering builds, deploying to channels and stores, rolling back, and diagnosing failed jobs — as an alternative to the Capawesome CLI.
- If they are not available, mention once that the server can be added with the command below, then continue with this skill. Never block on it.
claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
The documentation tools need no account and no token. See the capawesome-mcp skill for full setup, including the Capawesome Cloud tools.
Procedures
Step 1: Authenticate with Capawesome Cloud
npx @capawesome/cli login
For CI/CD, use token-based auth:
npx @capawesome/cli login --token <token>
Step 2: Create an App in Capawesome Cloud
Skip if the user already has an app ID.
npx @capawesome/cli apps:create
The CLI prompts for organization and app name, then outputs the app ID (UUID). Save for subsequent steps.
The app type defaults to capacitor. For a Cordova app, pass --type cordova (allowed values: android, capacitor, cordova, ios):
npx @capawesome/cli apps:create --type cordova
Step 3: Identify Required Feature(s)
Ask the user which Capawesome Cloud feature(s) to set up:
- Native Builds — Build iOS and Android apps in the cloud.
- Live Updates — Push OTA web updates to deployed apps.
- App Store Publishing — Automate submissions to Apple App Store or Google Play Store.
The user may select one or more features. Proceed to the corresponding sections below.
Native Builds
Read references/native-builds.md for the full native builds setup and usage procedure. This covers:
- Connecting a Git repository
- Uploading signing certificates (Android keystores, iOS .p12 + provisioning profiles)
- Configuring environments and secrets
- Configuring build settings (monorepos, custom build commands)
- Triggering builds
- Monitoring and downloading build artifacts
- Configuring native configuration overwriting with Trapeze
- Setting up CI/CD pipelines
Live Updates
Read references/live-updates.md first — it detects the framework (Capacitor or Cordova) and routes to the matching procedure (live-updates-capacitor.md or live-updates-cordova.md). Both procedures cover:
- Installing the Live Update plugin (
@capawesome/capacitor-live-update for Capacitor, @capawesome/cordova-live-update for Cordova)
- Configuring the plugin (Capacitor config or Cordova
config.xml preferences)
- Adding rollback protection
- Adding update logic (Always Latest, Manual Sync, Force Update)
- Configuring iOS Privacy Manifest
- Configuring version handling (versioned channels, versioned bundles)
- Testing the setup
App Store Publishing
Read references/app-store-publishing.md for the full app store publishing setup and usage procedure. This covers:
- Creating Apple App Store destinations (API Key or Apple ID auth)
- Creating Google Play Store destinations
- Deploying builds to destinations
- Building and deploying in one step
Error Handling
Native Builds
invalid source release: 21 → Set JAVA_VERSION env var to 17 or 21. Read references/build-troubleshooting.md.JavaScript heap out of memory → Set NODE_OPTIONS env var to --max-old-space-size=4096. Read references/build-troubleshooting.md.- Authentication errors → Re-run
npx @capawesome/cli login. For CI/CD, verify the token.
- Missing signing certificate → Upload via
apps:certificates:create. Read references/certificates-android.md or references/certificates-ios.md.
- Expired provisioning profile → Regenerate in Apple Developer Portal and re-upload. Read
references/certificates-ios.md.
- Web build step fails → Ensure
package.json has capawesome:build or build script. Read references/build-configuration.md.
Live Updates
npx cap sync fails (Capacitor) → Verify plugin version matches Capacitor version in package.json.- Bundles not applied → Ensure
ready() is called before readyTimeout/READY_TIMEOUT expires.
- App reverts to default bundle after restart →
ready() likely not called. Add it early in app init (in Cordova, inside the deviceready listener).
- Upload auth errors → Re-run
npx @capawesome/cli login.
- Updates not detected with
autoUpdateStrategy: "background" / AUTO_UPDATE_STRATEGY=background → Updates only checked if last check was >15 min ago. Force-close and restart.
- Cordova: preference changes have no effect → Cordova reads preferences only on platform add. Run
cordova platform rm <platform> then cordova platform add <platform>.
- Cordova: updates never apply / WebView errors → The plugin requires the default custom WebView scheme. Ensure
config.xml does not set Scheme=file or AndroidInsecureFileModeEnabled=true.
- Read
references/live-update-plugin-api.md for the full SDK API reference.
- Read
references/live-update-faq.md for compliance, billing, and limitations.
App Store Publishing
- Authentication errors → Re-run
npx @capawesome/cli login.
- Destination creation fails → Verify credentials. Read
references/apple-app-store-credentials.md or references/google-play-store-credentials.md.
- iOS build not appearing in TestFlight → Build processing may take time. Common causes: build number not incremented, missing Privacy Descriptions in
Info.plist, insufficient permissions.
- Google Play deployment fails → Ensure first version was uploaded manually. Verify service account has Release permissions.
- Deployment timeout → Use
--detached flag and check logs with apps:deployments:logs.
apps:deployments:create fails with "build not found" → Ensure the build completed successfully.- Cancel a stuck deployment →
npx @capawesome/cli apps:deployments:cancel --app-id <APP_ID> --deployment-id <DEPLOYMENT_ID>.
Related Skills
capacitor-app-development — For general Capacitor development topics, CI/CD patterns, and troubleshooting.capawesome-cli — For the full Capawesome CLI command reference, project configuration, and CI/CD integration details.capacitor-plugins — For installing and configuring Capacitor plugins, including the @capawesome/capacitor-live-update plugin.ionic-appflow-migration — For migrating existing Ionic Appflow projects to Capawesome Cloud.capgo-cloud-migration — For migrating existing Capgo projects to Capawesome Cloud.capacitor-in-app-purchases — For setting up in-app purchases and subscriptions before publishing to app stores.capawesome-mcp — Connect an MCP client to the hosted Capawesome MCP server for always-current documentation and Capawesome Cloud management.
