@bifos/nhncloud-cli - npm Package Compare versions

Comparing version 0.7.0 to 0.9.0

skills/nhncloud-cli/references/ncs.md

+# NCS Reference
+
+`ncs` 명령군은 NHN Container Service 의 template(설계도)과 workload(런타임 실행)를 조회·관리한다.
+template 의 생성·삭제, workload 의 생성·변경(update/patch)·실행제어(일시정지/재개/재시작/삭제), 악성코드 검사(malware) 설정·결과 조회를 지원한다.
+
+## 설정
+
+공통 UAK와 NCS appkey가 필요하다.
+인증은 Deploy 와 같은 UAK OAuth Bearer 토큰을 재사용한다(profile 토큰 캐시 공유).
+
+`configure` 마법사는 아직 ncs를 지원하지 않는다.
+`--app-key` 옵션 또는 `~/.nhncloud/credentials.json` 의 `profiles.<profile>.ncs.appkey` 를 직접 추가한다.
+
+```bash
+nhncloud ncs template list --app-key <appkey>
+```
+
+`--app-key <key>`는 profile의 `ncs.appkey`보다 우선한다.
+기본 region은 `kr1`이고, `kr1`, `kr3`만 지원한다(판교·광주).
+
+## Template(설계도) 조회
+
+```bash
+nhncloud ncs template list --app-key <appkey> --json
+nhncloud ncs template list --region kr3 --app-key <appkey> --json
+nhncloud ncs template get <template-id> --app-key <appkey> --json
+nhncloud ncs template version list <template-id> --app-key <appkey> --json
+nhncloud ncs template version get <template-id> <version> --app-key <appkey> --json
+```
+
+## Template(설계도) 생성/삭제
+
+복잡한 생성 입력은 공식 API payload 를 JSON 파일로 전달한다(`--file`).
+삭제는 위험 명령이라 비대화형 환경에서 `--yes` 가 필수이고, TTY 에서는 확인 프롬프트가 뜬다.
+
+```bash
+nhncloud ncs template create --file ./template-create.json --app-key <appkey>
+nhncloud ncs template delete <template-id> --yes --app-key <appkey>
+```
+
+버전 생성도 동일하게 `--file` 을 쓰며, payload 의 `sourceVersion` 필드가 필수다(어느 버전을 기준으로 새 버전을 만들지 지정).
+
+```bash
+nhncloud ncs template version create <template-id> --file ./version-create.json --app-key <appkey>
+nhncloud ncs template version delete <template-id> <version> --yes --app-key <appkey>
+```
+
+## Workload(런타임 실행) 조회
+
+```bash
+nhncloud ncs workload list --app-key <appkey> --json
+nhncloud ncs workload list --q <워크로드 이름> --app-key <appkey> --json
+nhncloud ncs workload get <workload-id> --app-key <appkey> --json
+```
+
+컨테이너 로그와 이벤트는 특정 task 를 지정해야 한다.
+`--task`는 `workload get` 응답의 `tasks[].id`에서 얻는다.
+
+```bash
+nhncloud ncs workload logs <workload-id> --task <task-id> --container <name> --app-key <appkey> --json
+nhncloud ncs workload logs <workload-id> --task <task-id> --container <name> --from 1h --to now --app-key <appkey>
+nhncloud ncs workload events <workload-id> --task <task-id> --app-key <appkey> --json
+nhncloud ncs workload events <workload-id> --task <task-id> --type Warning --app-key <appkey> --json
+```
+
+실행 히스토리와 예약 실행 히스토리는 workload 단위로 조회한다.
+
+```bash
+nhncloud ncs workload history <workload-id> --app-key <appkey> --json
+nhncloud ncs workload history get <workload-id> <history-id> --app-key <appkey> --json
+nhncloud ncs workload schedule-history <workload-id> --app-key <appkey> --json
+```
+
+## Workload 실행제어
+
+일시정지·재개는 workload 단위, 재시작은 task 단위(`--task` 필수), 삭제는 위험 명령이라 `--yes` 필수(비대화형) 또는 확인 프롬프트(TTY)를 거친다.
+
+```bash
+nhncloud ncs workload pause <workload-id> --app-key <appkey>
+nhncloud ncs workload resume <workload-id> --app-key <appkey>
+nhncloud ncs workload restart <workload-id> --task <task-id> --app-key <appkey>
+nhncloud ncs workload delete <workload-id> --yes --app-key <appkey>
+```
+
+## Workload 생성/변경
+
+생성은 비동기다.
+`--wait`를 주면 `Running` 상태가 될 때까지 폴링하고, `--timeout <sec>`(기본 300)으로 대기 시간을 조절한다.
+변경은 `update`(PUT, 전체 교체)와 `patch`(PATCH, JSON Patch 배열 부분 변경) 두 가지다.
+
+```bash
+nhncloud ncs workload create --file ./workload-create.json --app-key <appkey> --json
+nhncloud ncs workload create --file ./workload-create.json --wait --timeout 600 --app-key <appkey> --json
+
+nhncloud ncs workload update <workload-id> --file ./workload-update.json --app-key <appkey> --json
+nhncloud ncs workload patch <workload-id> --file ./workload-patch.json --app-key <appkey> --json
+```
+
+`patch`의 `--file`은 JSON Patch(RFC 6902) 배열이다.
+
+```json
+[
+  { "op": "replace", "path": "/workload/desired", "value": 2 }
+]
+```
+
+## 악성코드 검사(malware)
+
+설정은 appkey 단위, 결과는 workload 실행 히스토리 단위로 조회한다.
+`historyId`는 `workload history` 목록 또는 `workload history get`의 `id`를 사용한다.
+
+```bash
+nhncloud ncs malware config get --app-key <appkey> --json
+nhncloud ncs malware config set --enabled true --app-key <appkey>
+nhncloud ncs malware config set --enabled false --app-key <appkey>
+
+nhncloud ncs malware result <workload-id> <history-id> --app-key <appkey> --json
+```
+
+## 체이닝 예시
+
+```bash
+nhncloud ncs template list --app-key <appkey> --json | jq -r '.[].id'
+nhncloud ncs workload list --app-key <appkey> --json | jq -r '.[] | select(.status=="Failed") | .id'
+nhncloud ncs workload get <workload-id> --app-key <appkey> --json | jq -r '.tasks[].id'
+nhncloud ncs workload history <workload-id> --app-key <appkey> --json | jq -r '.[0].id' # 최신 historyId
+```
+
+## 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--region <region>` | NCS region. 기본 `kr1`. `kr1`·`kr3`만 지원 |
+| `--app-key <key>` | NCS appkey |
+| `--profile <name>` | 사용할 profile |
+| `--page <page>` / `--size <size>` | 페이지네이션 (기본 size는 명령별 상이 — `--help` 확인) |
+| `--q <query>` | workload list·events 필터 |
+| `--task <taskId>` | `workload logs`·`workload events`·`workload restart` 필수 |
+| `--container <name>` | `workload logs` 필수 |
+| `--sort <sort>` | `workload history` 정렬 (역순은 필드명 앞에 `-`) |
+| `--file <path>` | `template create`·`template version create`·`workload create`·`workload update`·`workload patch` 필수 — JSON payload 파일 경로 (`patch`는 JSON Patch 배열) |
+| `--wait` / `--timeout <sec>` | `workload create` — Running 상태 폴링(`--timeout` 기본 300초) |
+| `--enabled <value>` | `malware config set` 필수. `true` 또는 `false` |
+| `--yes` | `template delete`·`template version delete`·`workload delete` — 비대화형 환경 필수, TTY 는 생략 시 확인 프롬프트 |
+
+## 주의사항
+
+- appkey는 NCS service appkey다. 인증 secret은 공통 UAK secret을 사용한다.
+- `workload logs`·`workload events`는 task 단위 조회라 `--task` 없이는 입력 오류다.
+- `workload restart`도 task 단위라 `--task` 없이는 입력 오류다.
+- `workload schedule-history`는 page/size를 아직 노출하지 않는다(대량 이력 시 첫 페이지만 반환될 수 있음 — ADR-020).
+- template/workload id, history id 인수가 공백이면 입력 오류다.
+- `template version create`의 `--file` payload 는 `sourceVersion` 필드가 필수다 — 누락 시 API 오류로 반환된다(클라이언트가 사전 검증하지 않음).
+- `--file` 로 지정한 JSON payload 파일은 1MB 를 넘거나 디렉터리면 입력 오류다.
+- 삭제 명령(`template delete`·`template version delete`·`workload delete`)은 비대화형 환경에서 `--yes` 없이 실행하면 입력 오류다.
+- `workload create --wait`는 타임아웃까지 `Running` 상태에 도달하지 못하면 마지막 상태를 메시지에 포함해 API 오류로 반환한다.
+- `workload patch`는 `Content-Type: application/json-patch+json`으로 전송된다 — `--file`에는 JSON Patch 배열(`op`/`path`/`value`)을 담아야 한다.
+- `malware config set --enabled`는 `true`·`false` 외의 값이면 입력 오류다.
+
+## 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| UAK 누락 또는 NCS appkey 미설정 | 4 |
+| UAK 인증 실패 | 2 |
+| 지원하지 않는 region, 빈 id 인수, `--task`/`--container` 누락, `--file` 파일 오류(누락·디렉터리·크기초과·JSON 파싱 실패), `--enabled` 값 오류(`true`/`false` 외), 비대화형 삭제 시 `--yes` 누락 | 3 |
+| NCS API 오류 (payload 필수값 누락, `workload create --wait` 타임아웃 등 서버측 검증·폴링 실패 포함) | 1 |

package.json

 {
   "name": "@bifos/nhncloud-cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "CLI tool for NHN Cloud services — AI agent & terminal friendly",
@@ -5,0 +5,0 @@ "keywords": [

README.md

 # nhncloud-cli
 
 NHN Cloud 서비스를 AWS CLI 방식으로 호출하는 통합 CLI.
-현재 98개 command catalog 항목을 지원한다.
-`configure`, `commands`, `logncrash search/send/export`, `deploy`, `instance`, `network`, `volume`, `floatingip`, `ncr`, `nks` 명령으로 NHN Cloud 서비스를 조회·운영할 수 있다.
+현재 106개 command catalog 항목을 지원한다.
+`configure`, `commands`, `logncrash search/send/export`, `deploy`, `instance`, `network`, `volume`, `floatingip`, `ncr`, `nks`, `ncs` 명령으로 NHN Cloud 서비스를 조회·운영할 수 있다.
+`skills`/`doctor` 로 Claude Code 스킬 설치와 상태 진단을 지원한다.
 
@@ -51,2 +52,24 @@ ## 설치
 
+### Claude Code 스킬 설치 (선택)
+
+Claude Code 에서 이 CLI 를 AI 에이전트 스킬로 쓰려면 스킬을 `~/.claude/skills` 에 설치한다.
+
+```bash
+# 심볼릭 링크로 설치 (전역 설치 전제 — npx 환경은 불가)
+nhncloud skills install
+
+# 설치 상태 확인
+nhncloud skills
+
+# 제거
+nhncloud skills uninstall
+```
+
+### 상태 진단
+
+```bash
+# 자격증명·스킬 설치 상태를 오프라인으로 진단
+nhncloud doctor
+```
+
 ## 사용 예
@@ -654,2 +677,76 @@
 
+### NHN Container Service (NCS)
+
+NCS는 template(설계도)과 workload(런타임 실행)를 조회한다.
+인증은 Deploy와 같은 UAK OAuth Bearer 토큰을 재사용하며(profile 토큰 캐시 공유), appkey는 경로에 포함한다.
+지원 region은 `kr1`(판교), `kr3`(광주)만이다.
+`configure` 마법사는 아직 ncs를 지원하지 않으므로 `--app-key` 옵션 또는 `~/.nhncloud/credentials.json`의
+`profiles.<profile>.ncs.appkey`를 직접 추가한다.
+
+template(설계도)의 생성·삭제, workload(런타임 실행)의 생성·변경·실행제어(일시정지/재개/재시작/삭제), 악성코드 검사(malware) 설정·결과 조회를 지원한다.
+
+```bash
+# template(설계도) 목록/단건/버전 조회
+nhncloud ncs template list --app-key <appkey>
+nhncloud ncs template get <template-id> --app-key <appkey>
+nhncloud ncs template version list <template-id> --app-key <appkey>
+nhncloud ncs template version get <template-id> <version> --app-key <appkey>
+
+# workload(런타임 실행) 목록/단건 조회
+nhncloud ncs workload list --app-key <appkey>
+nhncloud ncs workload get <workload-id> --app-key <appkey>
+
+# task 컨테이너 로그/이벤트 조회 (--task는 workload get 응답의 tasks[].id)
+nhncloud ncs workload logs <workload-id> --task <task-id> --container <name> --app-key <appkey>
+nhncloud ncs workload events <workload-id> --task <task-id> --app-key <appkey>
+
+# 실행 히스토리 / 예약 실행 히스토리 조회
+nhncloud ncs workload history <workload-id> --app-key <appkey>
+nhncloud ncs workload history get <workload-id> <history-id> --app-key <appkey>
+nhncloud ncs workload schedule-history <workload-id> --app-key <appkey>
+```
+
+template 생성·버전 생성처럼 복잡한 입력은 공식 API payload를 JSON 파일로 전달한다.
+삭제 명령은 비대화형 환경에서 `--yes`가 필요하다.
+
+```bash
+# template(설계도) 생성 / 삭제
+nhncloud ncs template create --file ./template-create.json --app-key <appkey>
+nhncloud ncs template delete <template-id> --yes --app-key <appkey>
+
+# template 버전 생성 / 삭제 (--file 의 sourceVersion 필드가 필수)
+nhncloud ncs template version create <template-id> --file ./version-create.json --app-key <appkey>
+nhncloud ncs template version delete <template-id> <version> --yes --app-key <appkey>
+
+# workload 실행제어 — 일시정지 / 재개 / task 재시작 / 삭제
+nhncloud ncs workload pause <workload-id> --app-key <appkey>
+nhncloud ncs workload resume <workload-id> --app-key <appkey>
+nhncloud ncs workload restart <workload-id> --task <task-id> --app-key <appkey>
+nhncloud ncs workload delete <workload-id> --yes --app-key <appkey>
+```
+
+workload 생성은 비동기다.
+`--wait`를 주면 `Running` 상태가 될 때까지 폴링하고, `--timeout`(초, 기본 300)으로 대기 시간을 조절한다.
+변경은 `update`(PUT, 전체 교체)와 `patch`(PATCH, JSON Patch 배열로 부분 변경) 두 가지다.
+
+```bash
+# workload 생성 (--wait로 Running 대기)
+nhncloud ncs workload create --file ./workload-create.json --wait --app-key <appkey>
+
+# workload 전체 교체 / 부분 변경(JSON Patch 배열)
+nhncloud ncs workload update <workload-id> --file ./workload-update.json --app-key <appkey>
+nhncloud ncs workload patch <workload-id> --file ./workload-patch.json --app-key <appkey>
+```
+
+악성코드 검사(malware) 설정은 appkey 단위이고, 검사 결과는 workload 실행 히스토리 단위로 조회한다.
+
+```bash
+# 악성코드 검사 설정 조회 / 변경
+nhncloud ncs malware config get --app-key <appkey>
+nhncloud ncs malware config set --enabled true --app-key <appkey>
+
+# 악성코드 검사 결과 조회 (workload history get 응답의 id를 historyId로 사용)
+nhncloud ncs malware result <workload-id> <history-id> --app-key <appkey>
+```
+
 ## 개발
@@ -656,0 +753,0 @@

skills/nhncloud-cli/SKILL.md

 ---
 name: nhncloud-cli
-description: NHN Cloud 서비스 CLI. commands --json catalog, configure, Log & Crash(logncrash search/send/export), Deploy(deploy run/artifacts/server-groups/histories/binary-groups/binaries/upload/download), Compute(instance), VPC/network, Block Storage(volume), Floating IP(floatingip), NHN Container Registry(ncr), NHN Kubernetes Service(nks supports/cluster/nodegroup/addon/kubeconfig) 등 NHN Cloud API를 터미널과 AI 에이전트에서 호출한다.
+description: NHN Cloud 서비스 CLI. commands --json catalog, configure, Log & Crash(logncrash search/send/export), Deploy(deploy run/artifacts/server-groups/histories/binary-groups/binaries/upload/download), Compute(instance), VPC/network, Block Storage(volume), Floating IP(floatingip), NHN Container Registry(ncr), NHN Kubernetes Service(nks supports/cluster/nodegroup/addon/kubeconfig), NHN Container Service(ncs template/workload 조회·생성·변경·실행제어, malware 검사 설정·결과 조회) 등 NHN Cloud API를 터미널과 AI 에이전트에서 호출한다.
 ---
@@ -23,2 +23,3 @@
 | NKS 클러스터, 노드 그룹, 애드온, kubeconfig | [nks.md](references/nks.md) |
+| NCS template, workload 조회·생성·변경·실행제어, malware 검사 설정·결과 조회 | [ncs.md](references/ncs.md) |
 | 인증 실패, profile 누락, region mismatch, JSON shape 혼동, scroll 제한 | [troubleshooting.md](references/troubleshooting.md) |
@@ -57,2 +58,3 @@
 | `nks` | Kubernetes cluster/nodegroup/addon/kubeconfig 관리 |
+| `ncs` | Container Service template/workload 조회·생성·변경·실행제어, malware 검사 설정·결과 조회 |
 
@@ -59,0 +61,0 @@ ## 안전한 탐색 순서

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

413544

31.48%

Number of package files

12

9.09%

Lines of code

7690

31.9%

Number of lines in readme file

762

14.59%

Worsened metrics

Number of low supply chain risk alerts

22

22.22%

No dependency changes