@bifos/nhncloud-cli 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bifos/nhncloud-cli",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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/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 에이전트에서 호출한다.
+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 Container Registry 레지스트리·이미지·태그 조회(ncr list/get/images/tags) 등 NHN Cloud PaaS API 를 터미널·AI 에이전트에서 호출한다.
 ---
 
 # nhncloud-cli
 
 NHN Cloud PaaS 서비스를 AWS CLI 방식으로 호출하는 TypeScript CLI.
-`configure`, `logncrash search/send`, `deploy`, `instance` (전원 제어·keypair·볼륨 연결 포함), `network` (VPC·서브넷 조회), `volume` (Block Storage 볼륨 목록·조회·생성), `floatingip` (공인 IP 관리) 명령을 지원한다.
+`configure`, `logncrash search/send`, `deploy`, `instance` (전원 제어·keypair·볼륨 연결 포함), `network` (VPC·서브넷 조회), `volume` (Block Storage 볼륨 목록·조회·생성), `floatingip` (공인 IP 관리), `ncr` (NHN Container Registry 레지스트리·이미지·태그 조회) 명령을 지원한다.
 
 ## 설치
 
@@ -42,6 +42,7 @@ nhncloud configure \
 | `--uak-secret <secret>` | 개인 UAK Secret |
 | `--logncrash-appkey <key>` | logncrash appkey |
 | `--logncrash-secret <secret>` | logncrash secret |
+| `--ncr-appkey <key>` | NCR(Container Registry) appkey |
 | `--no-verify` | 연결 테스트 생략 |
 
 저장 파일 구조 (`~/.nhncloud/credentials.json`, mode 0600):
@@ -85,6 +86,30 @@ logncrash appkey 와 secret 은 콘솔 → Log & Crash Search → 프로젝트
 | `--quiet` | 핵심 식별자만 출력 | 스크립팅 |
 
 **AI 에이전트는 `--json` 을 사용하여 구조화된 데이터를 파싱하라.**
+단, `--json`은 CLI 출력 계약이며 API 원본 래퍼를 그대로 보존하지 않을 수 있다.
+
+| 명령 | `--json` 출력 shape |
+|------|---------------------|
+| `logncrash search` | `{ totalItems, pageNumber, pageSize, data }` 객체 |
+| `deploy binary-groups` | `binaryGroups` 래퍼를 언랩한 배열 |
+| `deploy binaries` | `{ totalCount, binaries }` 객체 |
+| `instance list` | `servers` 래퍼를 언랩한 server 배열 |
+| `instance get` | `server` 래퍼를 언랩한 단일 server 객체 |
+| `instance flavors` | `flavors` 래퍼를 언랩한 flavor 배열 |
+| `instance images` | `images` 래퍼를 언랩한 image 배열 |
+| `instance availability-zones` | `availabilityZoneInfo` 래퍼를 언랩한 배열 |
+| `instance keypairs` | `keypairs[].keypair`를 flatten한 keypair 배열 |
+| `network list` | VPC 배열 |
+| `network subnet list` | subnet 배열 |
+| `volume list` | volume 배열 |
+| `volume get` | 단일 volume 객체 |
+| `floatingip list` | floating IP 배열 |
+| `ncr list` | `registries` 래퍼를 언랩한 registry 배열 |
+| `ncr get` | `registry` 래퍼를 언랩한 단일 registry 객체 |
+| `ncr images` | repository 배열 |
+| `ncr tags` | tag 배열 |
+
+예: `nhncloud instance get <instance-id> --json`은 `.server.status`가 아니라 `.status`를 읽는다.
 
 ---
 
@@ -101,6 +126,13 @@ logncrash appkey 와 secret 은 콘솔 → Log & Crash Search → 프로젝트
 | 다른 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` |
+| NCR 레지스트리 목록 조회 | `nhncloud ncr list --app-key <appkey>` |
+| NCR 레지스트리 목록 (JSON 파싱용) | `nhncloud ncr list --app-key <appkey> --json` |
+| NCR 단일 레지스트리 조회 | `nhncloud ncr get <registry-name> --app-key <appkey>` |
+| NCR 이미지(repository) 목록 조회 | `nhncloud ncr images <registry>` |
+| NCR 이미지 목록 (JSON) | `nhncloud ncr images <registry> --json` |
+| NCR 태그 목록 조회 | `nhncloud ncr tags <registry> <repository>` |
+| NCR 태그 목록 (JSON) | `nhncloud ncr tags <registry> <repository> --json` |
 
 ## logncrash search 옵션
 
@@ -115,6 +147,18 @@ logncrash appkey 와 secret 은 콘솔 → Log & Crash Search → 프로젝트
 
 전역 옵션: `--json` / `--quiet` / `--no-color`
 
+`--query` 는 Log & Crash Search API 의 Lucene 쿼리 원문이다.
+콘솔의 body 키워드 검색처럼 쓰고 싶으면 필드를 명시한다.
+
+| 의도 | 쿼리 |
+|------|------|
+| body 단어 검색 | `body:request_received` |
+| body 부분 문자열 검색 | `body:*request_received*` |
+| logType 검색 | `logType:"ERROR"` |
+
+전송 직후에는 인덱싱 지연으로 잠시 0건이 나올 수 있다.
+반복 검색이나 넓은 wildcard 검색은 API rate limit 에 걸릴 수 있으므로 시간 범위를 좁혀 확인한다.
+
 ## 시간 입력 형식
 
 - 상대시간: `1h` (1시간 전), `30m` (30분 전), `2d` (2일 전), `now` (현재)
@@ -624,3 +668,76 @@ nhncloud floatingip delete <floatingip-id> --yes
 | 외부 네트워크 미발견 (create --network 미지정) | 3 (PARAM_ERROR) |
 | 비대화형 delete --yes 누락 | 3 (PARAM_ERROR) |
 | Floating IP API 오류 | 1 (API_ERROR) |
+
+## ncr — NHN Container Registry 레지스트리·이미지·태그 조회
+
+NCR Management API 로 레지스트리(Harbor 프로젝트)를 조회한다.
+이미지(repository)·태그는 레지스트리 데이터플레인 Harbor REST API 를 직접 호출한다.
+두 경로 모두 공통 UAK 를 사용하므로 추가 설정은 없다.
+appKey 는 `--app-key` 옵션 또는 `nhncloud configure --ncr-appkey <appkey>` 로 profile 에 저장한 값을 자동 사용한다.
+
+### 의도 → 커맨드 매핑
+
+| 의도 | 커맨드 |
+|------|--------|
+| 레지스트리 목록 조회 | `nhncloud ncr list --app-key <appkey>` |
+| 레지스트리 목록 (JSON) | `nhncloud ncr list --app-key <appkey> --json` |
+| 다른 region 조회 (기본 kr1) | `nhncloud ncr list --region kr2 --app-key <appkey>` |
+| 단일 레지스트리 조회 | `nhncloud ncr get <registry> --app-key <appkey>` |
+| appkey 저장 후 생략 | `nhncloud configure --ncr-appkey <appkey>` → `nhncloud ncr list` |
+| 이미지(repository) 목록 조회 | `nhncloud ncr images <registry>` |
+| 이미지 목록 (JSON) | `nhncloud ncr images <registry> --json` |
+| 특정 이미지의 태그 목록 조회 | `nhncloud ncr tags <registry> <repository>` |
+| 태그 목록 (JSON) | `nhncloud ncr tags <registry> <repository> --json` |
+
+### ncr list / get 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--region <region>` | NCR region (기본: `kr1`). 지원: `kr1`, `kr2`, `kr3` |
+| `--app-key <key>` | NCR appKey (profile 의 `ncr.appkey` 보다 우선) |
+| `--profile <name>` | 사용할 profile 이름 |
+
+### ncr images / ncr tags 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--region <region>` | NCR region (기본: `kr1`) |
+| `--app-key <key>` | NCR appKey (profile 의 `ncr.appkey` 보다 우선) |
+| `--profile <name>` | 사용할 profile 이름 |
+
+### 체이닝 예시
+
+```bash
+# 레지스트리 목록 (이름만 추출)
+nhncloud ncr list --app-key <appkey> --json | jq -r '.[].name'
+
+# 레지스트리 수 확인
+nhncloud ncr list --app-key <appkey> --json | jq length
+
+# 단일 레지스트리 상세 조회
+nhncloud ncr get <registry> --app-key <appkey> --json
+
+# 이미지 목록 (이름만 추출)
+nhncloud ncr images <registry> --json | jq -r '.[].repository'
+
+# 이미지별 artifact 수 확인
+nhncloud ncr images <registry> --json | jq '.[] | {repository, artifact_count}'
+
+# 특정 이미지의 태그 목록
+nhncloud ncr tags <registry> <repository> --json | jq -r '.[].tag'
+
+# 가장 최근 push 태그 확인
+nhncloud ncr tags <registry> <repository> --json | jq 'sort_by(.push_time) | last | .tag'
+```
+
+### ncr 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| UAK 누락·불완전 | 4 (CONFIG_ERROR) |
+| NCR appkey 미설정 (`--app-key` 미지정 + configure 미설정) | 4 (CONFIG_ERROR) |
+| 지원하지 않는 region | 3 (PARAM_ERROR) |
+| registry / repository 인수 공백·빈값 | 3 (PARAM_ERROR) |
+| UAK 인증 실패 (401/403) | 2 (AUTH_ERROR) |
+| NCR API 오류 | 1 (API_ERROR) |