--- title: cmp 명령줄 도구 description: 패널에서 제공하는 cmp CLI를 설치하고 사용해 보세요. 일회용 코드로 브라우저 로그인, API에서 생성된 명령어, 출력 및 종료 코드, CI 사용 및 서명된 업데이트를 지원합니다. url: https://nexcmp.com/ko/docs/developers/cmp-cli/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # `cmp` 명령줄 도구 {#cmp-command-line-tool} > **포털 위치:** 설치 명령어는 API 참조(`https:///apidoc`, 명령줄 인터페이스 섹션)에 있습니다. 로그인 승인: `https:///link`. 연결된 기기: API 키(`/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/ko/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 ``` 설치 프로그램은 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` | 다운로드 베이스 (미러용). | 수동 다운로드 및 검증: ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![macOS 및 Linux용 cmp 설치 명령어가 포함된 API 참조 섹션](https://nexcmp.com/ko/docs/images/developers/cmp-cli-01-install.webp) ## 로그인 {#log-in} ```bash 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 환경이나 브라우저가 없는 서버의 경우 포털에서 발급받은 키를 사용하세요: ```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] ``` - 경로 파라미터는 위치 인자이며, 쿼리 파라미터와 바디 필드는 케밥 케이스 플래그(`--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' ``` 쉘 자동 완성: `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`은(는) VM을 반환하고, `cmp vm list -o json | jq .`은(는) 원본 JSON을 표시합니다. ## 한도 및 참고 사항 {#limits-notes} - 명령어 목록은 빌드에 따라 다릅니다. 패키지는 릴리스 빌드 시 설치된 환경의 OpenAPI 문서에서 생성되므로, 릴리스에서 비활성화된 제품에는 명령어가 없습니다. CLI가 알지 못하는 경로에는 `cmp api`을(를) 사용하세요. - CLI는 MIT 라이선스 하에 배포됩니다. - 각 패키지는 ed25519 키로 서명되며, 서명 키는 업데이트 시 가져오는 것이 아니라 설치 프로그램과 바이너리 내부에 고정되어 있습니다. - 키는 키별 및 계정별로 제한됩니다([REST API](https://nexcmp.com/ko/docs/developers/api/#rate-limits) 참조). ## Troubleshooting {#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://`. |