Công cụ dòng lệnh cmp

Vị trí trên portal: các lệnh cài đặt nằm ở tài liệu tham khảo API (https://<your-domain>/apidoc, mục Command-line interface). Phê duyệt đăng nhập: https://<your-domain>/link. Thiết bị đã kết nối: API keys (/api-keys) › Connected apps & devices.

Chức năng

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 <id>, 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

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://<your-domain>/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.
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

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<version>/cmp_<version>_<os>_<arch>.tar.gz hoặc .zip	Các chương trình: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64.
v<version>/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)

macOS và Linux:

curl -fsSL https://cloud.example.com/cli/install.sh | sh

Windows 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:

curl -fsSLO https://cloud.example.com/cli/latest.json
sha256sum --check --ignore-missing SHA256SUMS

Đăng nhập

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:

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

cmp <group> [subgroup] <action> [<id> ...] [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ỳ.

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 <k>	Chọn key của một lệnh tính phí.
--retry <n>	Khi gặp HTTP 429, đợi Retry-After và thử lại tối đa n lần.
--timeout <s>	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

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

cmp config liệt kê các profile; cmp config use <name> 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:

- 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

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

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 ý

• 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).

Xử lý sự cố

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://<domain>/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://<reseller-domain>.