Capawesome CLI

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

Prerequisites

Node.js (v18 or later) and npm installed.
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.

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)

Generate a token in the Capawesome Cloud Console under Settings > Tokens.
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
Build Commands — apps:builds:create, apps:builds:cancel, apps:builds:download, 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: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: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: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
Utility — doctor

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-cli