@bifos/nhncloud-cli 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bifos/nhncloud-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI tool for NHN Cloud services — AI agent & terminal friendly",
   "keywords": [
     "nhncloud",

package/skills/nhncloud-cli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: nhncloud-cli
-description: NHN Cloud 서비스 CLI. 자격증명 설정(configure), Log & Crash 로그 검색(logncrash search), Deploy 배포 실행 등 NHN Cloud PaaS API 를 터미널·AI 에이전트에서 호출한다.
+description: NHN Cloud 서비스 CLI. 자격증명 설정(configure), Log & Crash 로그 검색·전송(logncrash search/send), Deploy 배포 실행·바이너리 그룹·바이너리 목록 조회·업로드·다운로드(deploy upload/download), Compute 인스턴스 관리(instance — 목록·발급·전원 제어·타입 변경(resize/resize-confirm/resize-revert)·키페어·이미지·가용성 영역 조회·볼륨 연결(instance volume attach/detach, instance volumes)), VPC·서브넷 조회(network list/subnet list), Block Storage 볼륨 관리(volume list/get/create), Floating IP 관리(floatingip list/create/delete) 등 NHN Cloud PaaS API 를 터미널·AI 에이전트에서 호출한다.
 ---
 
 # nhncloud-cli
 
 NHN Cloud PaaS 서비스를 AWS CLI 방식으로 호출하는 TypeScript CLI.
-`configure`, `logncrash search`, `deploy` 명령을 지원한다.
+`configure`, `logncrash search/send`, `deploy`, `instance` (전원 제어·keypair·볼륨 연결 포함), `network` (VPC·서브넷 조회), `volume` (Block Storage 볼륨 목록·조회·생성), `floatingip` (공인 IP 관리) 명령을 지원한다.
 
 ## 설치
 
@@ -99,6 +99,8 @@ logncrash appkey 와 secret 은 콘솔 → Log & Crash Search → 프로젝트
 | 시간 범위 지정 검색 | `nhncloud logncrash search --query '*' --from 2024-01-01T00:00:00+09:00 --to 2024-01-01T12:00:00+09:00` |
 | 페이지네이션 | `nhncloud logncrash search --query '*' --from 1h --to now --page 1 --size 50` |
 | 다른 profile 사용 | `nhncloud logncrash search --query '*' --from 1h --to now --profile staging` |
+| 로그 대량 추출 (파일로) | `nhncloud logncrash export --query '<lucene>' --from 1h --to now --output logs.jsonl` |
+| Log & Crash 로그 전송 | `nhncloud logncrash send --body "<메시지>" --level INFO` |
 
 ## logncrash search 옵션
 
@@ -148,6 +150,25 @@ nhncloud logncrash search \
 | API 오류 / 봉투 isSuccessful:false | 1 (API_ERROR) |
 | 시간 범위 초과·필수 옵션 누락 | 3 (PARAM_ERROR) |
 
+### logncrash export (대량 추출)
+
+- `nhncloud logncrash export` — 검색 결과 전체를 파일로 내보낸다.
+  단발 검색(search)이 한 페이지만 보여주는 것과 달리, scroll 로 전체(최대 10만 건)를 순회한다.
+- `--output <file>` 필수. 기본은 JSON Lines(한 줄당 한 로그), `--format json` 이면 JSON 배열. 기존 파일은 기본 거부 — 덮어쓰려면 `--force`.
+- 진행 상황은 stderr, 데이터는 파일에만 쓴다(stdout 비움).
+- scrollKey 는 1분 만료 — 데이터가 많아 1분을 넘기면 만료 에러가 난다.
+  이때는 검색 범위를 좁히거나 `--size`(범위 10~100, 기본 100)를 키워 페이지 수를 줄인 뒤 다시 시도한다.
+- 시간 범위 제한은 search 와 동일(90일 이내·31일 이하).
+
+### logncrash send 전송
+
+- `nhncloud logncrash send --body "<메시지>"` — 로그 한 건을 Log & Crash 로 전송한다.
+  본문은 `--body`, 또는 `--file <path>`, 또는 stdin(파이프) 으로 전달한다.
+- `--level` 로 DEBUG/INFO/WARN/ERROR/FATAL 을 지정한다.
+  `--app-version`(projectVersion)·`--source`/`--type`/`--host` 로 부가 필드를 설정한다.
+- 검색과 달리 collector 로 전송하며 **appkey 만 사용**한다 (secret 불요·ADR-014).
+  단일 로그 본문은 8MB 한도이며 초과 시 입력 오류로 차단된다.
+
 ---
 
 ## deploy — NHN Cloud Deploy 배포 실행
@@ -206,6 +227,10 @@ UAK 는 NHN Cloud 콘솔 → 계정 → User Access Key 에서 발급한다.
 | 아티팩트 목록 조회 | `nhncloud deploy artifacts my-service` |
 | 서버그룹 목록 조회 | `nhncloud deploy server-groups my-service` |
 | 배포 이력 조회 | `nhncloud deploy histories my-service` |
+| 바이너리 그룹 목록 | `nhncloud deploy binary-groups <target>` |
+| 바이너리 목록 | `nhncloud deploy binaries <target> --binary-group <key>` (전체 필드는 `--json`) |
+| 바이너리 업로드 | `nhncloud deploy upload <target> --file <path> --binary-group <key>` |
+| 바이너리 다운로드 | `nhncloud deploy download <target> --binary-group <key> --binary-key <key> -o <file>` |
 | 다른 profile 사용 | `nhncloud deploy run my-service --profile staging` |
 
 ### deploy run 옵션
@@ -243,6 +268,23 @@ nhncloud deploy run my-service --artifact-id <artifactId>
 nhncloud deploy histories my-service --json | jq '.[0] | {deployKey, deployStatus}'
 ```
 
+### deploy 바이너리 조회
+
+- `nhncloud deploy binary-groups <target>` — 아티팩트의 바이너리 그룹 목록을 조회한다.
+  출력의 key 를 binaries 입력으로 쓴다.
+- `nhncloud deploy binaries <target> --binary-group <key>` — 해당 그룹의 바이너리 목록을 조회한다.
+  컬럼: version·binaryName·size(bytes)·uploadDate·uploader.
+  `--binary-group` 은 필수다.
+- 정렬은 `--sort-key UPLOAD_DATE --sort-direction DESC`, 페이지는 `--page-num` / `--page-size`.
+- size 는 bytes 정수이며 KB/MB 변환 없이 원시값으로 출력한다.
+  정밀값은 `--json` 으로 확인한다.
+
+### deploy 바이너리 전송
+
+- `nhncloud deploy upload <target> --file <path> --binary-group <key>` — 로컬 파일을 바이너리 그룹에 업로드 (multipart). `--application-type`(기본 server) · `--description` 선택. 출력의 binaryKey 를 download 입력으로 쓴다. `--quiet` 면 binaryKey 만.
+- `nhncloud deploy download <target> --binary-group <key> --binary-key <key> -o <file>` — 바이너리를 파일로 저장. 대상이 이미 있으면 기본 거부, `--force` 로 덮어쓴다.
+- 그룹 key 와 바이너리 key 는 `deploy binary-groups` / `deploy binaries` 로 확인한다.
+
 ### deploy 에러 코드
 
 | 상황 | exit code |
@@ -305,14 +347,65 @@ NHNCLOUD_IAAS_PASSWORD=<api-password> nhncloud configure \
 | 의도 | 커맨드 |
 |------|--------|
 | 인스턴스 목록 조회 | `nhncloud instance list` |
+| 이미지 목록 조회 | `nhncloud instance images` (create --image 소스, 전체 필드는 `--json`) |
+| 특정 노출 범위 이미지 | `nhncloud instance images --visibility public` |
+| 인스턴스 타입(flavor) 목록 | `nhncloud instance flavors` |
+| 가용성 영역 목록 | `nhncloud instance availability-zones` |
+| 인스턴스 타입 상세 (스펙 포함) | `nhncloud instance flavors --detail` (전체 필드는 `--json`) |
+| 키페어 목록 | `nhncloud instance keypairs` |
+| 키페어 생성 (키 저장) | `nhncloud instance keypair create <keypair-name> -o ./key.pem` |
+| 키페어 삭제 | `nhncloud instance keypair delete <keypair-name>` |
 | 특정 인스턴스 상태 조회 | `nhncloud instance get <id>` |
 | 인스턴스 생성 (즉시 반환) | `nhncloud instance create --name <name> --flavor <id> --image <id> --network <uuid>` |
 | 인스턴스 생성 + ACTIVE 대기 | `nhncloud instance create ... --wait` |
 | GPU 인스턴스 생성 | `nhncloud instance create --flavor <gpu-flavor-id> --boot-volume-size <gb> ...` (GPU 는 boot-from-volume 필수) |
 | 인스턴스 삭제 (confirm 없이) | `nhncloud instance delete <id> --yes` |
+| 인스턴스 시작 | `nhncloud instance start <id>` |
+| 인스턴스 정지 | `nhncloud instance stop <id>` |
+| 인스턴스 재부팅 | `nhncloud instance reboot <id>` (`--hard` 로 HARD) |
+| 인스턴스 타입 변경 | `nhncloud instance resize <id> --flavor <flavor-id>` |
+| resize 확정 | `nhncloud instance resize-confirm <id>` |
+| resize 롤백 | `nhncloud instance resize-revert <id>` |
 | 다른 region 사용 | `nhncloud instance list --region kr2` |
 | 다른 profile 사용 | `nhncloud instance list --profile staging` |
 
+### instance 전원 제어 (start / stop / reboot)
+
+- `nhncloud instance start <id>` — 정지된(SHUTOFF) 인스턴스를 켠다 (→ ACTIVE).
+- `nhncloud instance stop <id>` — 동작 중인(ACTIVE) 인스턴스를 끈다 (→ SHUTOFF).
+- `nhncloud instance reboot <id>` — 재부팅한다. 기본은 SOFT(OS graceful), `--hard` 는 강제 전원 cycle.
+- 세 명령 모두 요청만 보내고(202 무본문) 상태 전이는 비동기다. 전이 확인은 `nhncloud instance get <id>` 로 한다.
+
+### instance 타입 변경 (resize)
+
+- `nhncloud instance resize <id> --flavor <flavor-id>` — 인스턴스 타입(flavor)을 바꾼다. 사전 상태는 ACTIVE 또는 SHUTOFF.
+- 변경할 `<flavor-id>` 는 `nhncloud instance flavors --detail` 로 후보를 조회해 고른다 (vcpus·ram·disk 비교).
+- resize 후 인스턴스는 VERIFY_RESIZE 에서 멈춘다. `resize-confirm <id>` 로 새 flavor 를 고정하거나 `resize-revert <id>` 로 롤백한다.
+- 상태 전이는 비동기다 — `nhncloud instance get <id>` 로 status 를 확인한다.
+
+### instance keypair 관리
+
+- `nhncloud instance keypairs` — 키페어 name·fingerprint 목록.
+  create 의 `--key-name` 에 넣을 키를 고를 때 사용한다.
+- `nhncloud instance keypair create <keypair-name> -o <keyfile>` — NHN 이 키쌍을 생성하고 private_key 를 `<keyfile>` 에 mode 0600 으로 저장한다.
+  **private_key 는 생성 시 한 번만 받을 수 있으므로** 자동화에서는 항상 `-o` 로 저장한다.
+- `--public-key <path|key>` 로 기존 공개키를 등록하면 private_key 는 반환되지 않는다.
+- `nhncloud instance keypair delete <keypair-name>` — 삭제.
+
+### instance flavors 조회
+
+- `nhncloud instance flavors` — 인스턴스 타입 id·name 목록.
+  create 의 `--flavor` 에 넣을 id 를 고를 때 사용한다.
+- `--detail` 로 vcpus·ram(MB)·disk(GB) 스펙을 확인한다.
+  테이블은 핵심 5컬럼이며, is_public·extra_specs 등 나머지 필드는 `--json` 으로 확인한다.
+- `--min-disk <gb>` / `--min-ram <mb>` 로 조건에 맞는 타입만 필터한다.
+
+### instance availability-zones 조회
+
+- `nhncloud instance availability-zones` — 가용성 영역 목록(zoneName·available). 인스턴스 발급 가능한 영역을 확인할 때. (현재 `instance create` 에는 `--availability-zone` 옵션이 없다 — 영역 정보 참고용.)
+- `available` 이 false 인 영역은 신규 발급이 막혀 있으니 true 인 영역을 참고한다.
+- 전체 응답(zoneState 등)은 `--json` 으로 확인한다.
+
 ### instance create 옵션
 
 | 옵션 | 필수 | 설명 |
@@ -378,3 +471,156 @@ nhncloud instance create \
 | 미등록 region / 필수 옵션 누락 | 3 (PARAM_ERROR) |
 | API 오류 / waitForActive 타임아웃 | 1 (API_ERROR) |
 | 비대화형 delete 에서 --yes 미지정 | 3 (PARAM_ERROR) |
+
+---
+
+## network — VPC·서브넷 조회
+
+`network` 명령군은 NHN VPC API 를 호출한다.
+`instance` 와 같은 `iaas` 자격증명·Keystone 토큰을 공유하므로 별도 설정이 필요 없다.
+
+### 의도 → 커맨드 매핑
+
+| 의도 | 커맨드 |
+|------|--------|
+| VPC 목록 조회 | `nhncloud network list` (전체 필드는 `--json`) |
+| 서브넷 목록 조회 | `nhncloud network subnet list` |
+| 다른 region VPC | `nhncloud network list --region kr2` |
+| VPC id 를 instance create 에 사용 | `nhncloud instance create ... --network <network-uuid>` |
+
+> **`--network` 가 받는 uuid**: `network list` 의 **VPC id** 를 그대로 사용한다 (subnet id 아님, 실측 확정).
+> VPC id 를 `--quiet` 로 추출해 create 로 파이프하는 흐름을 지원한다.
+
+### 체이닝 예시
+
+```bash
+# VPC id 한 줄씩 (--quiet)
+nhncloud network list --quiet
+
+# 서브넷 id·CIDR 확인
+nhncloud network subnet list --json | jq '.[] | {id, cidr, vpc_id}'
+
+# VPC 선택 후 인스턴스 생성
+nhncloud instance create \
+  --name web \
+  --flavor <flavor-id> \
+  --image <image-id> \
+  --network <network-uuid> \
+  --wait --quiet
+```
+
+### network 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| iaas 자격증명 누락·불완전 | 4 (CONFIG_ERROR) |
+| Keystone 인증 실패 (401/403) | 2 (AUTH_ERROR) |
+| 미등록 region | 3 (PARAM_ERROR) |
+| VPC API 오류 | 1 (API_ERROR) |
+
+---
+
+## volume — Block Storage 볼륨 관리
+
+`volume` 명령군은 NHN Block Storage (Cinder volumev2) API 를 호출한다.
+`instance`·`network` 와 같은 `iaas` 자격증명·Keystone 토큰을 공유하므로 별도 설정이 필요 없다.
+
+> **쓰기 작업 주의**: `volume create`, `instance volume attach`, `instance volume detach` 는 쓰기 작업이다.
+> 실행 전 환경을 확인한다(수동 QA 필수).
+
+### 의도 → 커맨드 매핑
+
+| 의도 | 커맨드 |
+|------|--------|
+| 볼륨 목록 조회 | `nhncloud volume list` |
+| 정렬·페이지네이션 | `nhncloud volume list --sort created_at:desc --limit 20` |
+| 단일 볼륨 상세 조회 | `nhncloud volume get <volume-id>` |
+| 볼륨 생성 (⚠️ 쓰기) | `nhncloud volume create --size <gb>` |
+| 이름·타입 지정 생성 (⚠️ 쓰기) | `nhncloud volume create --size 50 --name my-volume --volume-type "General SSD"` |
+| 인스턴스 연결 볼륨 목록 | `nhncloud instance volumes <instance-id>` |
+| 볼륨 연결 (⚠️ 쓰기) | `nhncloud instance volume attach <instance-id> --volume <volume-id>` |
+| 볼륨 연결 해제 (⚠️ 쓰기) | `nhncloud instance volume detach <instance-id> <volume-id>` |
+| 다른 region | `nhncloud volume list --region kr2` |
+
+> **UX 비대칭**: `attach` 는 `--volume <id>` 플래그로 볼륨을 지정하고,
+> `detach` 는 `<instanceId> <volumeId>` 위치 인수 두 개로 지정한다.
+
+### volume list 옵션
+
+| 옵션 | 필수 | 설명 |
+|------|:---:|------|
+| `--sort <field:dir>` | 아니오 | 정렬 (예: `created_at:desc`) |
+| `--limit <n>` | 아니오 | 최대 반환 건수 |
+| `--offset <n>` | 아니오 | 오프셋 |
+| `--marker <id>` | 아니오 | 페이지네이션 marker |
+| `--region <region>` | 아니오 | region override (kr1/kr2/kr3/jp1) |
+| `--profile <name>` | 아니오 | 사용할 profile 이름 |
+
+### volume create 옵션
+
+| 옵션 | 필수 | 설명 |
+|------|:---:|------|
+| `--size <gb>` | 예 | 볼륨 크기(GB) |
+| `--name <name>` | 아니오 | 볼륨 이름 |
+| `--description <text>` | 아니오 | 볼륨 설명 |
+| `--volume-type <type>` | 아니오 | 볼륨 타입 (예: `General SSD`) |
+| `--snapshot-id <id>` | 아니오 | 스냅샷 ID (스냅샷으로부터 생성) |
+| `--region <region>` | 아니오 | region override |
+| `--profile <name>` | 아니오 | 사용할 profile 이름 |
+
+### volume 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| iaas 자격증명 누락·불완전 | 4 (CONFIG_ERROR) |
+| Keystone 인증 실패 (401/403) | 2 (AUTH_ERROR) |
+| 미등록 region / 필수 옵션 누락 | 3 (PARAM_ERROR) |
+| Block Storage API 오류 | 1 (API_ERROR) |
+
+---
+
+## floatingip — 공인 IP(Floating IP) 관리
+
+인스턴스에 공인 IP 를 부여하거나 회수한다.
+`floatingip` 명령군은 `network` 와 같은 `iaas` 자격증명·Keystone 토큰을 공유한다.
+
+> **쓰기 작업 주의**: `floatingip create`(공인 IP 발급·비용)·`floatingip delete`(IP 회수)는 쓰기 작업이다.
+> 실행 전 환경을 확인한다(수동 QA 필수).
+
+### 의도 → 커맨드 매핑
+
+| 의도 | 커맨드 |
+|------|--------|
+| Floating IP 목록 조회 | `nhncloud floatingip list` |
+| Floating IP 발급 (외부 VPC 자동) | `nhncloud floatingip create` |
+| 특정 외부 VPC 로 발급 | `nhncloud floatingip create --network <network-uuid>` |
+| Floating IP 삭제 (⚠️ 쓰기) | `nhncloud floatingip delete <floatingip-id> --yes` |
+
+> **associate 보류**: `floatingip associate` (인스턴스 연결) 는 instance→port_id 매핑 경로 미확정으로 보류 중.
+> 후속 task 에서 실측 확정 후 추가한다.
+
+### 체이닝 예시
+
+```bash
+# Floating IP 목록 (id·공인 IP·상태·연결 port 확인)
+nhncloud floatingip list
+
+# 발급 후 id 추출
+nhncloud floatingip create --quiet
+
+# JSON 으로 발급 정보 확인
+nhncloud floatingip create --json | jq '{id, floating_ip_address, status}'
+
+# 삭제 (비대화형 환경)
+nhncloud floatingip delete <floatingip-id> --yes
+```
+
+### floatingip 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| iaas 자격증명 누락·불완전 | 4 (CONFIG_ERROR) |
+| Keystone 인증 실패 (401/403) | 2 (AUTH_ERROR) |
+| 외부 네트워크 미발견 (create --network 미지정) | 3 (PARAM_ERROR) |
+| 비대화형 delete --yes 누락 | 3 (PARAM_ERROR) |
+| Floating IP API 오류 | 1 (API_ERROR) |