--- title: Công cụ dòng lệnh cmp description: Cài đặt và sử dụng cmp CLI từ panel của bạn: đăng nhập bằng mã một lần, lệnh sinh từ API, kết quả và mã thoát, dùng cho CI cùng cập nhật có chữ ký. url: https://nexcmp.com/vi/docs/developers/cmp-cli/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Công cụ dòng lệnh `cmp` {#cmp-command-line-tool} > **Vị trí trên portal:** các lệnh cài đặt nằm ở tài liệu tham khảo API (`https:///apidoc`, mục Command-line interface). Phê duyệt đăng nhập: `https:///link`. Thiết bị đã kết nối: API keys (`/api-keys`) › Connected apps & devices. ## Chức năng {#what-it-does} `cmp` là một chương trình dòng lệnh nhỏ gọn dành cho khách hàng (và cho chính bạn), biến **mọi thao tác API thành một lệnh**: `cmp vm list`, `cmp vm start `, `cmp billing invoice list`. Chương trình được build từ tài liệu OpenAPI của chính bản cài đặt của **bạn** khi phát hành, do đó các lệnh luôn khớp với những tính năng bạn đã bật. Đây là một file binary tĩnh duy nhất dành cho Linux, macOS và Windows (amd64 và arm64) mà không cần cài đặt thêm gì khác. ## Yêu cầu {#requirements} | Hạng mục | Yêu cầu | |---|---| | Máy chủ | Không cần gì thêm. Các gói phát hành nằm sẵn bên trong bản phát hành NexCMP và được phân phối bởi panel tại `https:///cli/`. | | Máy của khách hàng | Linux, macOS hoặc Windows (PowerShell 5.1+). `ssh-keygen` (OpenSSH 8.0+) chỉ cần thiết để xác minh chữ ký. | | Thông tin xác thực | Đăng nhập qua trình duyệt bằng mã một lần, hoặc một [API key](https://nexcmp.com/vi/docs/developers/api-keys/). | | Mạng | HTTPS tới panel của bạn. CLI từ chối gửi key qua `http://` thông thường ngoại trừ đến `localhost`. | ## Chuẩn bị hạ tầng {#prepare-the-infrastructure} Không cần làm gì. Panel tự phục vụ các tệp này từ `/cli/` (không cần build hay tải lên): | Tệp | Mục đích | |---|---| | `install.sh`, `install.ps1` | Trình cài đặt cho Linux/macOS và Windows; chứa sẵn địa chỉ panel của bạn. | | `latest.json` | Phiên bản hiện tại, danh sách tệp, kích thước, sha256. | | `v/cmp___.tar.gz` hoặc `.zip` | Các chương trình: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. | | `v/SHA256SUMS`, `SHA256SUMS.sig` | Mã checksum và chữ ký ed25519 tương ứng. | | `cmp-cli.pub` | Public key của bản phát hành. | ## Cài đặt (khách hàng) {#install-customer} macOS và Linux: ```bash curl -fsSL https://cloud.example.com/cli/install.sh | sh ``` Windows PowerShell: ```powershell irm https://cloud.example.com/cli/install.ps1 | iex ``` Trình cài đặt sẽ chọn gói phù hợp với hệ điều hành và CPU, tải về `SHA256SUMS` cùng chữ ký, xác minh chữ ký bằng key nhúng trong script, kiểm tra hash của gói và cài đặt `cmp` vào `/usr/local/bin` (với quyền root) hoặc `~/.local/bin`; trên Windows vào `%LOCALAPPDATA%\cmp\bin` (được thêm vào `PATH` của người dùng). Nếu có bước kiểm tra thất bại, sẽ không có gì được cài đặt. | Biến | Ý nghĩa | |---|---| | `CMP_VERSION` | Cài đặt phiên bản này thay vì bản mới nhất. | | `CMP_INSTALL_DIR` | Thư mục cài đặt. | | `CMP_REQUIRE_SIGNATURE` | `1` = hủy bỏ khi không thể xác minh chữ ký. | | `CMP_BASE_URL` | URL gốc để tải về (dành cho mirror). | Tải về và xác minh thủ công: ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![Mục tài liệu tham khảo API với lệnh cài đặt cmp cho macOS và Linux](https://nexcmp.com/vi/docs/images/developers/cmp-cli-01-install.webp) ## Đăng nhập {#log-in} ```bash cmp login ``` 1. CLI sẽ in ra một **mã** dùng một lần cùng đường dẫn (`https://cloud.example.com/link?code=WDJB-MJHT`), mở trình duyệt và chờ. 2. Trên trình duyệt, đăng nhập vào portal, kiểm tra tên client, thiết bị, IP và quốc gia, chọn các quyền (scope) và thời hạn hiệu lực của key (mặc định 90 ngày). Các quyền gây phát sinh chi phí hoặc xóa dữ liệu mặc định sẽ không được chọn. Bấm approve. 3. CLI sẽ nhận **key riêng**, tách biệt với các key mà khách hàng tự tạo thủ công, và lưu tại `~/.config/cmp/config.json` (mode `0600`; `%APPDATA%\cmp` trên Windows). Key này xuất hiện trong **API keys › Connected apps & devices** và có thể bị thu hồi tại đó. Mã sẽ hết hạn sau 10 phút. Việc phê duyệt yêu cầu một phiên portal đã đăng nhập thực tế với email đã xác minh — không dùng key khác và không dùng phiên mạo danh. Các flag hữu ích: `--scopes vm:read,billing:read`, `--name "build server"`, `--no-browser`, `--profile`, `--api-url`. Đối với CI hoặc máy chủ không có trình duyệt, hãy dùng key từ portal: ```bash printf %s "$KEY" | cmp login --with-token export CMP_TOKEN=vk_XXXX # nothing is written to disk cmp whoami ``` ## Sử dụng các lệnh {#using-commands} ```text cmp [subgroup] [ ...] [flags] ``` - Các path parameter là tham số vị trí; query parameter và trường body sẽ trở thành flag dạng kebab-case (`--start-port 443`). - `--data '{"a":1}'`, `--data @file.json` hoặc `--data -` gửi toàn bộ phần thân JSON; các flag sẽ ghi đè các trường của nó. - `cmp help vm firewall add` (hoặc `--help`) hiển thị thông tin chi tiết của lệnh bất kỳ. ```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 ``` Các lệnh tích hợp sẵn: `login`, `logout`, `whoami`, `config`, `api`, `completion`, `version`, `update`, `help`. Mọi lệnh khác đều lấy từ tài liệu API. Các flag toàn cục: | Flag | Ý nghĩa | |---|---| | `-o, --output json\|table\|yaml` | Định dạng. Mặc định là `table` trên terminal và `json` khi dùng pipe. | | `--profile`, `--api-url` | Thông tin đăng nhập đã lưu nào và trang nào. | | `-y, --yes` | Bỏ qua bước xác nhận đối với các lệnh có tính phá hủy hoặc có tính phí. | | `--idempotency-key ` | Chọn key của một lệnh tính phí. | | `--retry ` | Khi gặp HTTP 429, đợi `Retry-After` và thử lại tối đa n lần. | | `--timeout ` | Số giây chờ response header (mặc định 60). | | `--debug` | Hiển thị quá trình trao đổi HTTP trên stderr, với các key được che. | Các lệnh **trừ tiền ví hoặc xóa dữ liệu** sẽ yêu cầu xác nhận và nếu có tính phí, sẽ gửi `Idempotency-Key` được tạo tự động (được in trên stderr để bạn có thể thử lại an toàn với `--idempotency-key`). Khi không có terminal, lệnh sẽ từ chối thực hiện trừ khi có `--yes`. ### Mã thoát {#exit-codes} | Mã | Ý nghĩa | |---|---| | 0 | Thành công | | 1 | Lỗi khác (mạng, HTTP 4xx/5xx không có trong danh sách) | | 2 | Lỗi sử dụng | | 3 | Không có quyền (401/403) | | 4 | Không tìm thấy (404) | | 5 | Bị giới hạn tốc độ (429) | | 6 | Yêu cầu xác nhận hoặc bị từ chối | | 130 | Bị gián đoạn | ### Profile và môi trường {#profiles-and-environment} `cmp config` liệt kê các profile; `cmp config use ` chuyển đổi; khách hàng của reseller sử dụng domain riêng của họ: `cmp login --api-url https://shop.example.net --profile shop`. Thứ tự ưu tiên: flag, biến môi trường, tệp cấu hình. Các biến: `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 completion: `cmp completion bash|zsh|fish|powershell`. ## Cập nhật và gỡ cài đặt {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` `cmp update` tải về `latest.json`, `SHA256SUMS` và chữ ký, xác minh chữ ký bằng public key **được tích hợp sẵn trong tệp nhị phân đang chạy**, xác minh hash gói và chỉ sau đó mới tự thay thế. Việc hạ cấp cần có `--force`. Khi bạn cập nhật NexCMP, panel sẽ cung cấp bản phát hành CLI đi kèm với phiên bản mới. Để gỡ cài đặt, hãy xóa tệp nhị phân `cmp` và thư mục cấu hình (`cmp config path` sẽ hiển thị thư mục này). Hãy thu hồi key trong mục **API keys** nếu máy bị mất. ## Kiểm tra {#verify} 1. `cmp version` in ra phiên bản và phiên bản tài liệu API. 2. `cmp login`, phê duyệt trên trình duyệt, sau đó `cmp whoami` sẽ hiển thị profile và URL panel của bạn. 3. `cmp vm list` trả về danh sách VM của bạn; `cmp vm list -o json | jq .` hiển thị JSON thô. ## Hạn mức & lưu ý {#limits-notes} - Danh sách lệnh phụ thuộc vào bản build của bạn: các gói được tạo từ tài liệu OpenAPI của bản cài đặt khi bản phát hành được build, do đó sản phẩm bị tắt trong bản phát hành của bạn sẽ không có lệnh. Sử dụng `cmp api` cho đường dẫn mà CLI không nhận biết. - CLI được phát hành theo giấy phép MIT. - Mỗi gói được ký bằng một ed25519 key; key chữ ký được ghim bên trong trình cài đặt và tệp nhị phân, không được tải về tại thời điểm cập nhật. - Các key bị giới hạn theo từng key và theo từng tài khoản (xem [REST API](https://nexcmp.com/vi/docs/developers/api/#rate-limits)). ## Xử lý sự cố {#troubleshooting} | Hiện tượng | Nguyên nhân | Cách khắc phục | |---|---|---| | `curl .../cli/install.sh` trả về 404 | Bản phát hành trên máy chủ không có thư mục CLI, hoặc host không có trong license | Kiểm tra `https:///cli/latest.json` và domain; cập nhật NexCMP. | | "không thể xác minh chữ ký" | `ssh-keygen` bị thiếu hoặc quá cũ | Cài đặt OpenSSH 8.0+, hoặc chỉ đặt `CMP_REQUIRE_SIGNATURE=0` nếu bạn chấp nhận rủi ro. | | `cmp login` báo mã đã hết hạn | Đã quá 10 phút | Chạy lại `cmp login`. | | Exit code 3 | Khóa thiếu scope, đã hết hạn hoặc bị thu hồi | `cmp whoami`; tạo mới hoặc phê duyệt lại với nhiều scope hơn. | | Exit code 6 trong tập lệnh | Lệnh có tính phí hoặc phá hủy chạy mà không có terminal | Thêm `--yes` (và `--idempotency-key` của riêng bạn). | | "từ chối gửi key qua http" | URL API dùng http không mã hóa | Dùng `https://`, hoặc chỉ dùng `CMP_ALLOW_HTTP=1` cho môi trường lab. | | Trình duyệt mở sai trang | Chưa thiết lập `--api-url` cho reseller | `cmp login --api-url https://`. |