capawesome-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capawesome CLI

Install, configure, and use the Capawesome CLI (

@capawesome/cli

) for authentication, project linking, command execution, and CI/CD integration.

安装、配置并使用Capawesome CLI（

@capawesome/cli

）完成认证、项目关联、命令执行和CI/CD集成工作。

Prerequisites

前置要求

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

已安装Node.js（v18及以上版本）和npm。
拥有Capawesome Cloud账号和所属组织。

General Rules

通用规则

Before running any

@capawesome/cli

command for the first time, run it with the

--help

flag to review all available options.

首次运行任意

@capawesome/cli

命令前，请添加

--help

参数运行，查看所有可用选项。

Procedures

操作步骤

Step 1: Install the CLI

步骤1：安装CLI

Install globally:

bash

npm install -g @capawesome/cli@latest

Alternatively, use

npx

to run commands without global installation:

bash

npx @capawesome/cli <command>

Verify the installation:

bash

npx @capawesome/cli doctor

The

doctor

command prints environment and CLI diagnostic information.

全局安装：

bash

npm install -g @capawesome/cli@latest

或者无需全局安装，直接使用

npx

运行命令：

bash

npx @capawesome/cli <command>

验证安装是否成功：

bash

npx @capawesome/cli doctor

doctor

命令会输出环境信息和CLI诊断结果。

Step 2: Authenticate

步骤2：身份认证

Interactive Login (Local Development)

交互式登录（本地开发场景）

bash

npx @capawesome/cli login

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

bash

npx @capawesome/cli login

执行后会打开浏览器端认证流程，流程完成后CLI会在本地存储会话信息。

Token-Based Login (CI/CD)

Token登录（CI/CD场景）

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

bash

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

在Capawesome Cloud控制台的设置 > Token页面生成Token。
使用Token完成认证：

bash

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

Verify Session

验证会话状态

bash

npx @capawesome/cli whoami

bash

npx @capawesome/cli whoami

Log Out

退出登录

bash

npx @capawesome/cli logout

bash

npx @capawesome/cli logout

Step 3: Create or Select an App

步骤3：创建或选择应用

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

Create a new app:

bash

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

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

如果用户已有Capawesome Cloud应用ID，可跳过本步骤。

创建新应用：

bash

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

CLI会输出应用ID（UUID格式），请妥善保存供后续命令使用。

Step 4: Link a Project (Optional)

步骤4：关联项目（可选）

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:

json

{
  "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.

如果是标准项目配置（应用位于仓库根目录，使用

npm install

npm run build

命令），可跳过本步骤。

如果是单仓多包（monorepo）、应用位于子目录，或者使用自定义构建命令，请在项目根目录创建

capawesome.config.json

文件：

json

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

查看

references/project-configuration.md

文件了解所有配置选项，包括单仓多包、pnpm和Yarn环境的配置方法。

Step 5: Run CLI Commands

步骤5：运行CLI命令

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

查看

references/commands.md

文件获取按类别整理的完整命令参考：

认证 —
```
login
```
,
```
logout
```
,
```
whoami
```
应用管理 —
```
apps:create
```
,
```
apps:delete
```

构建命令 —

apps:builds:create

apps:builds:cancel

apps:builds:download

apps:builds:logs

证书命令 —

apps:certificates:create

apps:certificates:list

apps:certificates:get

apps:certificates:update

apps:certificates:delete

环境变量命令 —

apps:environments:create

apps:environments:list

apps:environments:set

apps:environments:unset

apps:environments:delete

渠道命令 —

apps:channels:create

apps:channels:delete

apps:channels:get

apps:channels:list

apps:channels:pause

apps:channels:resume

apps:channels:update

热更新命令 —

apps:liveupdates:upload

apps:liveupdates:register

apps:liveupdates:bundle

apps:liveupdates:generatemanifest

apps:liveupdates:generatesigningkey

apps:liveupdates:rollback

apps:liveupdates:rollout

apps:liveupdates:setnativeversions

部署命令 —

apps:deployments:create

apps:deployments:cancel

apps:deployments:logs

目标端命令 —

apps:destinations:create

apps:destinations:list

apps:destinations:get

apps:destinations:update

apps:destinations:delete

设备命令 —

apps:devices:delete

apps:devices:forcechannel

apps:devices:unforcechannel

apps:devices:probe

组织命令 —
```
organizations:create
```
工具类 —
```
doctor
```

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

步骤6：配置CI/CD集成（可选）

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

除非用户需要在CI/CD流水线中运行CLI命令，否则可跳过本步骤。

查看

references/ci-cd-integration.md

文件获取完整的CI/CD配置流程，覆盖以下内容：

基于Token的认证
使用
```
--detached
```
参数实现非阻塞构建
使用
```
--json
```
参数输出机器可读格式结果
使用
```
--yes
```
参数跳过确认提示
GitHub Actions和其他CI平台的示例工作流

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.

command not found: @capawesome/cli
— CLI未全局安装。可以执行
```
npm install -g @capawesome/cli@latest
```
全局安装，或者在命令前添加
```
npx
```
前缀运行。
认证错误 /
Not authenticated
— 重新执行
```
npx @capawesome/cli login
```
。如果是CI/CD场景，请验证Token有效且未过期。
whoami
返回非预期用户 — 执行
```
npx @capawesome/cli logout
```
退出登录，再使用正确账号重新登录。
命令因缺少参数执行失败 — 添加
```
--help
```
参数运行命令，查看所有必填和可选参数。
doctor
命令报告问题 — 按照诊断输出解决环境问题（Node.js版本、npm版本、CLI版本）。
未检测到
capawesome.config.json
— 确认文件位于项目根目录（和
```
package.json
```
同级），并验证JSON格式合法。

capawesome-cli

Original

Translation

Capawesome CLI

Capawesome CLI

Prerequisites

前置要求

General Rules

通用规则

Procedures

操作步骤

Step 1: Install the CLI

步骤1：安装CLI

Step 2: Authenticate

步骤2：身份认证

Interactive Login (Local Development)

交互式登录（本地开发场景）

Token-Based Login (CI/CD)

Token登录（CI/CD场景）

Verify Session

验证会话状态

Log Out

退出登录

Step 3: Create or Select an App

步骤3：创建或选择应用

Step 4: Link a Project (Optional)

步骤4：关联项目（可选）

Step 5: Run CLI Commands

步骤5：运行CLI命令

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

步骤6：配置CI/CD集成（可选）

Error Handling

错误处理

Related Skills

相关技能