capawesome-cloud — Claude Code skill: builds, OTA, publishing

---
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 (Android, iOS, and Electron desktop) 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."
license: MIT
compatibility: "Requires Node.js, npm, network access, and a Capawesome Cloud account. Native builds additionally require the app to live in a Git repository; app store publishing requires an Apple Developer Program membership or a Google Play Developer account."
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

1. A [Capawesome Cloud](https://console.cloud.capawesome.io) account and organization.
2. A **Capacitor 6/7/8** or **Cordova** app. Notes:
   - **Live Updates**: supported on both Capacitor (Android, iOS, and — on Capacitor 8 only — the Electron desktop platform `@capawesome/capacitor-electron`) 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.
3. Node.js and npm installed.
4. For **Native Builds**: The app must be in a Git repository (GitHub, GitLab, Bitbucket, or Azure DevOps).
5. For **Apple App Store Publishing**: An active [Apple Developer Program](https://developer.apple.com/programs/) membership and an app created in [App Store Connect](https://appstoreconnect.apple.com).
6. For **Google Play Store Publishing**: A [Google Play Developer](https://play.google.com/console) 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](https://capawesome.io/docs/ai/mcp/capawesome/) 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.

```bash
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

```bash
npx @capawesome/cli login
```

For CI/CD, use token-based auth:

```bash
npx @capawesome/cli login --token <token>
```

### Step 2: Create an App in Capawesome Cloud

Skip if the user already has an app ID.

```bash
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`):

```bash
npx @capawesome/cli apps:create --type cordova
```

### Step 3: Identify Required Feature(s)

Ask the user which Capawesome Cloud feature(s) to set up:

1. **Native Builds** — Build iOS and Android apps in the cloud.
2. **Live Updates** — Push OTA web updates to deployed apps.
3. **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)
- Enabling Live Updates on the Electron desktop platform (Capacitor only)
- 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`.
- **Electron:** `npx cap sync electron` does nothing → It resolves to the unrelated `electron` npm package. Run `npx cap sync @capawesome/capacitor-electron`.
- **Electron:** a `manifest` bundle is not delivered → Electron devices only receive `zip` bundles. Upload with the default `--artifact-type zip`.
- **Electron:** every release reports app version `0.0.0` → Bump `version` in `electron/package.json` for every desktop release; it is the app version used for version constraints and versioned channels.
- 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.
- **`capacitor-platforms`** — For adding and configuring the `@capawesome/capacitor-electron` desktop platform that receives Live Updates.
- **`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.