capawesome-cli

Capawesome CLI

Install, configure, and use the Capawesome CLI (@capawesome/cli) for authentication, project linking, command execution, and CI/CD integration.

Prerequisites

1. Node.js (v18 or later) and npm installed.
2. A Capawesome Cloud account and organization.

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: Install the CLI

Install globally:

npm install -g @capawesome/cli@latest

Alternatively, use npx to run commands without global installation:

npx @capawesome/cli <command>

Verify the installation:

npx @capawesome/cli doctor

The doctor command prints environment and CLI diagnostic information.

Step 2: Authenticate

Interactive Login (Local Development)

npx @capawesome/cli login

This opens a browser-based authentication flow. After completing the flow, the CLI stores the session locally.

Token-Based Login (CI/CD)

1. Generate a token in the Capawesome Cloud Console under Settings > Tokens.
2. Authenticate using the token:

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

Verify Session

npx @capawesome/cli whoami

Log Out

npx @capawesome/cli logout

Step 3: Create or Select an App

Skip if the user already has a Capawesome Cloud app ID.

Create a new app:

npx @capawesome/cli apps:create --name "My App" --organization-id <ORGANIZATION_ID>

The CLI outputs the app ID (UUID). Save it for subsequent commands.

Step 4: Link a Project (Optional)

Skip for standard project setups where the app is in the repo root and uses npm install + npm run build.

For monorepos, subdirectory apps, or custom build commands, create capawesome.config.json in the project root:

{
  "cloud": {
    "apps": [
      {
        "appId": "<APP_ID>",
        "baseDir": "apps/my-app",
        "dependencyInstallCommand": "npm install",
        "webBuildCommand": "npm run build"
      }
    ]
  }
}

Read references/project-configuration.md for all configuration options including monorepo, pnpm, and Yarn setups.

Step 5: Run CLI Commands

Read references/commands.md for the full command reference organized by category:

• Authentication — login, logout, whoami
• App Management — apps:create, apps:delete, apps:get, apps:list, apps:transfer, apps:link, apps:unlink
• Build Commands — apps:builds:create, apps:builds:cancel, apps:builds:download, apps:builds:failure-summary, apps:builds:get, apps:builds:list, apps:builds:logs
• Certificate Commands — apps:certificates:create, apps:certificates:list, apps:certificates:get, apps:certificates:update, apps:certificates:delete
• Environment Commands — apps:environments:create, apps:environments:get, apps:environments:list, apps:environments:set, apps:environments:unset, apps:environments:delete
• Channel Commands — apps:channels:create, apps:channels:delete, apps:channels:get, apps:channels:list, apps:channels:pause, apps:channels:resume, apps:channels:update
• Live Update Commands — apps:liveupdates:create, apps:liveupdates:upload, apps:liveupdates:register, apps:liveupdates:bundle, apps:liveupdates:generatemanifest, apps:liveupdates:generatesigningkey, apps:liveupdates:rollback, apps:liveupdates:rollout, apps:liveupdates:setnativeversions
• Deployment Commands — apps:deployments:create, apps:deployments:cancel, apps:deployments:failure-summary, apps:deployments:get, apps:deployments:list, apps:deployments:logs
• Destination Commands — apps:destinations:create, apps:destinations:list, apps:destinations:get, apps:destinations:update, apps:destinations:delete
• Device Commands — apps:devices:delete, apps:devices:forcechannel, apps:devices:unforcechannel, apps:devices:probe
• Organization Commands — organizations:create, organizations:get, organizations:list
• Utility — doctor
• Deprecated — apps:bundles:*, manifests:generate (kept for backward compatibility)

Step 6: Set Up CI/CD Integration (Optional)

Skip unless the user wants to run CLI commands in a CI/CD pipeline.

Read references/ci-cd-integration.md for the full CI/CD setup procedure covering:

• Token-based authentication
• Non-blocking builds with --detached
• Machine-readable output with --json
• Skipping confirmation prompts with --yes
• Example workflows for GitHub Actions and other CI platforms

Error Handling

• `command not found: @capawesome/cli` — The CLI is not installed globally. Either install with npm install -g @capawesome/cli@latest or prefix commands with npx.
• Authentication errors / `Not authenticated` — Re-run npx @capawesome/cli login. For CI/CD, verify the token is valid and not expired.
• `whoami` returns unexpected user — Log out with npx @capawesome/cli logout and log in again with the correct account.
• Command fails with missing options — Run the command with --help to see all required and optional flags.
• `doctor` reports issues — Follow the diagnostic output to resolve environment problems (Node.js version, npm version, CLI version).
• `capawesome.config.json` not detected — Ensure the file is in the project root directory (same level as package.json). Verify the JSON is valid.

Related Skills

• `capawesome-cloud` — For setting up and using Capawesome Cloud features (native builds, live updates, app store publishing). Uses the CLI as a tool but covers the full workflow.
• `capacitor-plugins` — For installing and configuring Capacitor plugins, including the @capawesome/capacitor-live-update plugin.
• `capawesome-mcp` — Connect an MCP client to the hosted Capawesome MCP server for always-current documentation and Capawesome Cloud management.