---
title: cmp 指令列工具
description: 安裝並使用由您自己的面板提供的 cmp CLI：透過一次性驗證碼進行瀏覽器登入、由 API 自動產生的指令、輸出與結束代碼、CI 使用以及已簽署的更新。
url: https://nexcmp.com/zh-tw/docs/developers/cmp-cli/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# `cmp` 指令列工具 {#cmp-command-line-tool}

> **在入口網站中的位置：**安裝指令位於API參考文件（`https://<your-domain>/apidoc`，Command-line interface章節）。核准登入：`https://<your-domain>/link`。已連線裝置：API keys (`/api-keys`) › Connected apps & devices。

## 功能 {#what-it-does}

`cmp` 是一個供您的客戶（以及您自己）使用的輕量指令列程式，它能將**所有 API 操作轉化為指令**：`cmp vm list`、`cmp vm start <id>`、`cmp billing invoice list`。它是從**您的**安裝實例在發布時的 OpenAPI 文件所建置，因此指令會與您啟用的功能完全相符。它是一個適用於 Linux、macOS 與 Windows（amd64 和 arm64）的單一靜態二進位檔，無需安裝其他任何東西。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 伺服器 | 無需額外安裝。發布套件已包含在 NexCMP 發布版本中，並由面板透過 `https://<your-domain>/cli/` 提供。 |
| 客戶端機器 | Linux、macOS 或 Windows（PowerShell 5.1+）。僅需 `ssh-keygen`（OpenSSH 8.0+）即可驗證簽章。 |
| 憑證 | 透過一次性代碼進行瀏覽器登入，或使用 [API key](https://nexcmp.com/zh-tw/docs/developers/api-keys/)。 |
| 網路 | 連線至你的面板必須使用 HTTPS。CLI 拒絕透過明文 `http://` 發送金鑰，除非是至 `localhost`。 |

## 準備基礎設施 {#prepare-the-infrastructure}

不需要任何操作。面板直接從 `/cli/` 提供這些檔案（無需建置或上傳）：

| 檔案 | 用途 |
|---|---|
| `install.sh`, `install.ps1` | 適用於 Linux/macOS 與 Windows 的安裝程式；內含你面板的網址。 |
| `latest.json` | 目前版本、檔案清單、大小、sha256。 |
| `v<version>/cmp_<version>_<os>_<arch>.tar.gz` 或 `.zip` | 程式：linux amd64/arm64、darwin amd64/arm64/universal、windows amd64/arm64。 |
| `v<version>/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
```

![包含適用於 macOS 與 Linux 之 cmp 安裝指令的 API 參考章節](https://nexcmp.com/zh-tw/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. 在瀏覽器中登入 portal，檢查客戶名稱、裝置、IP 與國家/地區，勾選權限（scopes）並選擇金鑰的有效期限（預設 90 天）。涉及付費或刪除資料的權限預設為未勾選。點擊核准。
3. CLI 會收到**專屬金鑰**（與客戶手動建立的金鑰分開），並將其儲存於 `~/.config/cmp/config.json`（權限模式為 `0600`；在 Windows 上為 `%APPDATA%\cmp`）。它會顯示在 **API keys › Connected apps & devices** 底下，並可在該處撤銷。

代碼會在 10 分鐘後過期。核准需要真實的已登入 portal 工作階段且具備已驗證的電子郵件——不能使用其他金鑰，也不能使用模擬（impersonated）工作階段。

實用的旗標（flags）：`--scopes vm:read,billing:read`、`--name "build server"`、`--no-browser`、`--profile`、`--api-url`。

若是 CI 或沒有瀏覽器的伺服器，請使用來自 portal 的金鑰：

```bash
printf %s "$KEY" | cmp login --with-token
export CMP_TOKEN=vk_XXXX      # nothing is written to disk
cmp whoami
```

## 使用指令 {#using-commands}

```text
cmp <group> [subgroup] <action> [<id> ...] [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 <k>` | 選擇付費指令的金鑰。 |
| `--retry <n>` | 遇到 HTTP 429 時等待 `Retry-After` 並重試最多 n 次。 |
| `--timeout <s>` | 等待回應標頭的秒數（預設 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 <name>` 進行切換；經銷商的客戶使用其自己的網域：`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` 會顯示設定檔與你的面板網址。
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-tw/docs/developers/api/#rate-limits)）。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `curl .../cli/install.sh` 傳回 404 | 伺服器上的版本沒有 CLI 資料夾，或主機不在授權範圍內 | 檢查 `https://<domain>/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 網址 | 使用 `https://`，或僅在測試環境使用 `CMP_ALLOW_HTTP=1`。 |
| 瀏覽器開啟了錯誤的網站 | 未針對經銷商設定 `--api-url` | `cmp login --api-url https://<reseller-domain>`. |