cmp 명령줄 도구

포털 위치: 설치 명령어는 API 참조(https://<your-domain>/apidoc, 명령줄 인터페이스 섹션)에 있습니다. 로그인 승인: https://<your-domain>/link. 연결된 기기: API 키(/api-keys) › Connected apps & devices.

작동 내용

cmp은(는) 고객(및 관리자)을 위한 소형 명령줄 프로그램으로, 모든 API 작업을 명령어로 변환합니다(cmp vm list, cmp vm start <id>, cmp billing invoice list). 릴리스 시점에 사용자 설치 환경의 OpenAPI 문서로부터 빌드되므로 활성화된 기능과 명령어가 일치합니다. Linux, macOS 및 Windows(amd64 및 arm64)용 단일 정적 바이너리로 제공되며 추가로 설치할 것이 없습니다.

요구 사항

항목	요구 사항
서버	추가 항목 없음. 릴리스 패키지는 NexCMP 릴리스 내부에 포함되어 있으며 패널에서 https://<your-domain>/cli/를 통해 제공됩니다.
고객 머신	Linux, macOS 또는 Windows(PowerShell 5.1+). 서명 확인에만 ssh-keygen(OpenSSH 8.0+)이 필요합니다.
자격 증명	일회용 코드를 통한 브라우저 로그인 또는 API key.
네트워크	패널과의 HTTPS 연결. CLI는 일반 http:// 연결을 통한 키 전송을 localhost(으)로만 제한합니다.

인프라 준비

없음. 패널은 이러한 파일을 /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	릴리스 공개 키.

설치 (고객)

macOS 및 Linux:

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

Windows PowerShell:

irm https://cloud.example.com/cli/install.ps1 | iex

설치 프로그램은 OS와 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	다운로드 베이스 (미러용).

수동 다운로드 및 검증:

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

로그인

cmp login

1. CLI가 일회용 코드와 링크(https://cloud.example.com/link?code=WDJB-MJHT)를 출력하고, 브라우저를 연 후 대기합니다.
2. 브라우저에서 포털에 로그인하고, 클라이언트 이름, 장치, IP 및 국가를 확인한 후, 권한(scopes)을 체크하고 키 유효 기간을 선택합니다(기본값 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 환경이나 브라우저가 없는 서버의 경우 포털에서 발급받은 키를 사용하세요:

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

명령어 사용

cmp <group> [subgroup] <action> [<id> ...] [flags]

• 경로 파라미터는 위치 인자이며, 쿼리 파라미터와 바디 필드는 케밥 케이스 플래그(--start-port 443)가 됩니다.
• --data '{"a":1}', --data @file.json 또는 --data -는 전체 JSON 바디를 전송하며, 플래그를 통해 해당 필드를 재정의할 수 있습니다.
• cmp help vm firewall add (또는 --help)은 모든 명령어의 상세 정보를 표시합니다.

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이(가) 지정되지 않으면 실행을 거부합니다.

종료 코드

코드	의미
0	성공
1	기타 오류 (네트워크, 나열되지 않은 HTTP 4xx/5xx)
2	사용법 오류
3	권한 없음 (401/403)
4	찾을 수 없음 (404)
5	요청 한도 초과 (429)
6	확인 필요 또는 거부됨
130	중단됨

프로필 및 환경

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:

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

쉘 자동 완성: cmp completion bash|zsh|fish|powershell.

업데이트 및 제거

cmp version
cmp update --check
cmp update

cmp update은(는) latest.json, SHA256SUMS 및 서명을 다운로드하고, 실행 중인 바이너리에 내장된 공개키로 서명을 검증하고, 패키지 해시를 검증한 후에야 자신을 교체합니다. 다운그레이드에는 --force이(가) 필요합니다. NexCMP를 업데이트하면 패널은 새 버전에 포함된 CLI 릴리스를 제공합니다.

제거하려면 cmp 바이너리와 설정 디렉터리(cmp config path에서 표시됨)를 삭제하세요. 머신을 분실한 경우 API keys에서 키를 취소하세요.

확인

1. cmp version은(는) 버전 및 API 문서 버전을 출력합니다.
2. cmp login을(를) 실행하고 브라우저에서 승인한 다음 cmp whoami을(를) 실행하면 프로필과 패널의 URL이 표시됩니다.
3. cmp vm list은(는) VM을 반환하고, cmp vm list -o json | jq .은(는) 원본 JSON을 표시합니다.

한도 및 참고 사항

• 명령어 목록은 빌드에 따라 다릅니다. 패키지는 릴리스 빌드 시 설치된 환경의 OpenAPI 문서에서 생성되므로, 릴리스에서 비활성화된 제품에는 명령어가 없습니다. CLI가 알지 못하는 경로에는 cmp api을(를) 사용하세요.
• CLI는 MIT 라이선스 하에 배포됩니다.
• 각 패키지는 ed25519 키로 서명되며, 서명 키는 업데이트 시 가져오는 것이 아니라 설치 프로그램과 바이너리 내부에 고정되어 있습니다.
• 키는 키별 및 계정별로 제한됩니다(REST API 참조).

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 URL	https://을(를) 사용하거나, 테스트 환경인 경우에만 CMP_ALLOW_HTTP=1을(를) 사용하세요.
브라우저가 잘못된 사이트를 염	리셀러에 대해 --api-url이(가) 설정되지 않음	cmp login --api-url https://<reseller-domain>.