--- title: cmp 命令行工具 description: 安装并使用面板自带的 cmp CLI：通过一次性代码进行浏览器登录、根据API生成的命令、输出与退出码、CI使用以及签名更新。 url: https://nexcmp.com/zh-cn/docs/developers/cmp-cli/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # `cmp` 命令行工具 {#cmp-command-line-tool} > **门户位置：**安装命令位于API参考（`https:///apidoc`，Command-line interface节）。批准登录：`https:///link`。连接的设备：API keys (`/api-keys`) › Connected apps & devices。 ## 功能说明 {#what-it-does} `cmp` 是一个为客户（及管理员）提供的小型命令行程序，它将**每个API操作都变成了一条命令**：`cmp vm list`、`cmp vm start `、`cmp billing invoice list`。它根据**您**安装环境在发布时的OpenAPI文档构建，因此命令与您已启用的功能完全匹配。它是一个适用于Linux、macOS和Windows（amd64和arm64）的静态二进制文件，无需安装其他依赖。 ## 前提条件 {#requirements} | 项目 | 要求 | |---|---| | 服务器 | 无需额外组件。发布包已包含在NexCMP发布版中，并由面板通过 `https:///cli/` 提供服务。 | | 客户机器 | Linux、macOS或Windows（PowerShell 5.1+）。仅在验证签名时需要 `ssh-keygen`（OpenSSH 8.0+）。 | | 凭据 | 使用一次性代码的浏览器登录，或使用 [API key](https://nexcmp.com/zh-cn/docs/developers/api-keys/)。 | | 网络 | 连接面板的 HTTPS。CLI 拒绝通过纯 `http://` 发送密钥，除非发送至 `localhost`。 | ## 准备基础设施 {#prepare-the-infrastructure} 无。面板从 `/cli/` 提供这些文件（无需构建或上传）： | 文件 | 用途 | |---|---| | `install.sh`, `install.ps1` | Linux/macOS 和 Windows 安装程序；其中包含您的面板地址。 | | `latest.json` | 当前版本、文件列表、大小、sha256。 | | `v/cmp___.tar.gz` 或 `.zip` | 程序：linux amd64/arm64、darwin amd64/arm64/universal、windows amd64/arm64。 | | `v/SHA256SUMS`, `SHA256SUMS.sig` | 校验和及其 ed25519 签名。 | | `cmp-cli.pub` | 发行版公钥。 | ## 安装（客户） {#install-customer} macOS 和 Linux： ```bash curl -fsSL https://cloud.example.com/cli/install.sh | sh ``` Windows PowerShell： ```powershell irm https://cloud.example.com/cli/install.ps1 | iex ``` 安装程序为操作系统和 CPU 选择软件包，下载 `SHA256SUMS` 及其签名，使用脚本中内置的密钥验证签名，验证软件包哈希，并将 `cmp` 安装到 `/usr/local/bin`（以 root 身份）或 `~/.local/bin`；在 Windows 上安装到 `%LOCALAPPDATA%\cmp\bin`（已添加到用户 `PATH`）。如果任何检查失败，则不会安装任何内容。 | 变量 | 说明 | |---|---| | `CMP_VERSION` | 安装此版本而非最新版本。 | | `CMP_INSTALL_DIR` | 安装文件夹。 | | `CMP_REQUIRE_SIGNATURE` | `1` = 当无法验证签名时中止。 | | `CMP_BASE_URL` | 下载基准（用于镜像）。 | 手动下载和验证： ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![API参考页面中包含适用于 macOS 和 Linux 的 cmp install 命令](https://nexcmp.com/zh-cn/docs/images/developers/cmp-cli-01-install.webp) ## 登录 {#log-in} ```bash cmp login ``` 1. CLI 会打印一次性 **code** 和一个链接（`https://cloud.example.com/link?code=WDJB-MJHT`），打开浏览器并等待。 2. 在浏览器中登录门户，检查客户端名称、设备、IP 和国家/地区，勾选权限（作用域）并选择密钥的有效期（默认 90 天）。涉及扣费或删除数据的权限默认不勾选。点击批准。 3. CLI 接收**其自己的密钥**（独立于客户手动创建的密钥），并将其存储在 `~/.config/cmp/config.json` 中（模式 `0600`；Windows 上为 `%APPDATA%\cmp`）。它会显示在 **API keys › Connected apps & devices** 下，并可在该处吊销。 该代码在 10 分钟后过期。批准需要一个经过身份验证的真实门户会话以及已验证的电子邮箱——不能是其他密钥，也不能是模拟会话。 实用的标志：`--scopes vm:read,billing:read`、`--name "build server"`、`--no-browser`、`--profile`、`--api-url`。 对于 CI 或无浏览器的服务器，请使用来自门户的密钥： ```bash printf %s "$KEY" | cmp login --with-token export CMP_TOKEN=vk_XXXX # nothing is written to disk cmp whoami ``` ## 使用命令 {#using-commands} ```text cmp [subgroup] [ ...] [flags] ``` - 路径参数是位置参数；查询参数和正文域会变成短横线命名法（kebab-case）的标志（`--start-port 443`）。 - `--data '{"a":1}'`、`--data @file.json` 或 `--data -` 会发送完整的 JSON 正文；标志会覆盖其字段。 - `cmp help vm firewall add`（或 `--help`）显示任何命令的详细信息。 ```bash cmp catalog plans cmp vm list --state active --per-page 50 cmp vm get 3f2a1c9e-0000-4000-8000-000000000000 cmp vm start 3f2a1c9e-0000-4000-8000-000000000000 cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24 cmp billing wallet cmp api GET /v1/vm --query page=2 # raw call to any endpoint ``` 内置命令：`login`、`logout`、`whoami`、`config`、`api`、`completion`、`version`、`update`、`help`。其余所有内容均来自 API 文档。 全局标志： | 标志 | 说明 | |---|---| | `-o, --output json\|table\|yaml` | 格式。在终端中默认为 `table`，通过管道输出时默认为 `json`。 | | `--profile`, `--api-url` | 存储的登录信息和站点。 | | `-y, --yes` | 跳过对破坏性或付费命令的确认。 | | `--idempotency-key ` | 选择一个付费命令的键。 | | `--retry ` | 当遇到 HTTP 429 时等待 `Retry-After` 并重试最多 n 次。 | | `--timeout ` | 等待响应标头的秒数（默认 60）。 | | `--debug` | 在 stderr 上显示 HTTP 交互，并掩盖密钥。 | 会**扣除钱包余额或删除数据**的命令会要求确认，如果是付费命令，会发送自动生成的 `Idempotency-Key`（打印到 stderr，因此你可以安全地使用 `--idempotency-key` 重试）。在没有终端的情况下，除非提供了 `--yes`，否则它们会拒绝执行。 ### 退出码 {#exit-codes} | 代码 | 说明 | |---|---| | 0 | 成功 | | 1 | 其他错误（网络错误、未列出的 HTTP 4xx/5xx） | | 2 | 用法错误 | | 3 | 未授权 (401/403) | | 4 | 未找到 (404) | | 5 | 请求过多 (429) | | 6 | 需要确认或已被拒绝 | | 130 | 已中断 | ### 配置文件与环境变量 {#profiles-and-environment} `cmp config` 列出配置文件；`cmp config use ` 切换；分销商的客户使用自己的域名：`cmp login --api-url https://shop.example.net --profile shop`。优先级：标志、环境变量、配置文件。变量：`CMP_TOKEN`、`CMP_PROFILE`、`CMP_API_URL`、`CMP_OUTPUT`、`CMP_CONFIG_DIR`、`CMP_ALLOW_HTTP`、`CMP_UPDATE_URL`。 GitHub Actions： ```yaml - name: Install cmp run: | curl -fsSL https://cloud.example.com/cli/install.sh | CMP_INSTALL_DIR="$RUNNER_TEMP/bin" sh echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH" - name: List running VMs env: CMP_TOKEN: ${{ secrets.CMP_TOKEN }} # a read-only key run: cmp vm list -o json | jq -r '.items[] | select(.cs_state=="Running") | .hostname' ``` Shell 自动补全：`cmp completion bash|zsh|fish|powershell`。 ## 更新与卸载 {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` `cmp update` 下载 `latest.json`、`SHA256SUMS` 及签名，使用**内置于运行中二进制文件**的公钥验证签名，验证软件包哈希，然后才会替换自身。降级需要 `--force`。当你更新 NexCMP 时，面板会提供随新版本发布的 CLI 发行版。 要卸载，请删除 `cmp` 二进制文件和配置目录（`cmp config path` 会显示它）。如果机器丢失，请在 **API keys** 下吊销密钥。 ## 验证 {#verify} 1. `cmp version` 打印版本和 API 文档版本。 2. `cmp login`，在浏览器中批准，然后 `cmp whoami` 显示配置文件和你的面板 URL。 3. `cmp vm list` 返回你的虚拟机；`cmp vm list -o json | jq .` 显示原始 JSON。 ## 限制与注意事项 {#limits-notes} - 命令列表取决于你的构建：软件包是在构建发行版时根据你的安装的 OpenAPI 文档生成的，因此在你版本中禁用的产品没有对应的命令。对于 CLI 不知道的路径，请使用 `cmp api`。 - CLI 采用 MIT 许可证。 - 每个软件包都使用 ed25519 密钥签名；签名密钥内置于安装程序和二进制文件中，而不是在更新时获取。 - 密钥数量受每密钥和每账户限制（参见 [REST API](https://nexcmp.com/zh-cn/docs/developers/api/#rate-limits)）。 ## 故障排查 {#troubleshooting} | 症状 | 原因 | 解决办法 | |---|---|---| | `curl .../cli/install.sh` 返回 404 | 服务器上的发行版没有 CLI 文件夹，或者主机不在授权范围内 | 检查 `https:///cli/latest.json` 和域名；更新 NexCMP。 | | “签名无法验证” | `ssh-keygen` 缺失或版本过旧 | 安装 OpenSSH 8.0+，或者仅在接受风险的情况下设置 `CMP_REQUIRE_SIGNATURE=0`。 | | `cmp login` 提示代码已过期 | 已过 10 分钟 | 再次运行 `cmp login`。 | | 退出码 3 | 密钥缺少作用域、已过期或已被吊销 | `cmp whoami`；创建或重新批准更多作用域。 | | 脚本中的退出码 6 | 在没有终端的情况下执行付费或破坏性命令 | 添加 `--yes`（以及你自己的 `--idempotency-key`）。 | | “拒绝通过 http 发送密钥” | 纯 HTTP API URL | 使用 `https://`，或者仅在实验室环境中红使用 `CMP_ALLOW_HTTP=1`。 | | 浏览器打开了错误的网站 | 未给分销商设置 `--api-url` | `cmp login --api-url https://`. |