@bifos/nhncloud-cli 0.17.0 → 0.19.0

package/package.json

@@ -1,14 +1,32 @@
 {
   "name": "@bifos/nhncloud-cli",
-  "version": "0.17.0",
-  "description": "CLI tool for NHN Cloud services — AI agent & terminal friendly",
+  "version": "0.19.0",
+  "description": "CLI for NHN Cloud (Compute, Network, Kubernetes, Load Balancer, Log & Crash, Deploy, Secure Key Manager and more) — AI agent & terminal friendly",
   "keywords": [
     "nhncloud",
     "cli",
     "logncrash",
     "deploy",
-    "nhn"
+    "nhn",
+    "nhn-cloud",
+    "openstack",
+    "compute",
+    "kubernetes",
+    "nks",
+    "load-balancer",
+    "log-and-crash",
+    "secure-key-manager",
+    "ai-agent",
+    "claude-code"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jon890/nhncloud-cli.git"
+  },
+  "homepage": "https://github.com/jon890/nhncloud-cli#readme",
+  "bugs": {
+    "url": "https://github.com/jon890/nhncloud-cli/issues"
+  },
   "bin": {
     "nhncloud": "dist/index.js"
   },
@@ -17,6 +35,7 @@
     "skills",
     "README.md"
   ],
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=20"
   },
@@ -27,7 +46,9 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run --passWithNoTests",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "verify:package": "node scripts/verify-package.mjs",
+    "check:pii": "node scripts/check-pii.mjs"
   },
   "license": "MIT",
   "dependencies": {

package/skills/nhncloud-cli/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   Claude Code 공개 스킬의 상태를 확인하거나
   `skills status|install|update|uninstall`로 관리하고 상태별 복구 방법을 안내할 때도 사용한다.
   Log & Crash, Deploy, Compute, Network, Block Storage, Floating IP,
-  Load Balancer, NCR, NKS, NCS, API Gateway 작업을 서비스별 참조와 명령 카탈로그로 안내한다.
+  Load Balancer, NCR, NKS, NCS, API Gateway, Secure Key Manager 작업을 서비스별 참조와 명령 카탈로그로 안내한다.
 ---
 
 # nhncloud-cli
@@ -17,7 +17,7 @@ description: >-
 2. 정확한 경로·인수·옵션이 필요하면 `nhncloud commands --json`에서 해당 명령을 찾는다.
 3. 조회 명령을 `--json`으로 실행해 대상 식별자와 현재 상태를 확인한다.
 4. 쓰기 명령은 대상, `--profile`, 필요한 `--region`을 명시하고, 명령이 지원하면 `--yes`를 API 호출 전에 전달한다.
-5. 결과는 stdout의 구조화 데이터로 판정하고 stderr는 진행 상황과 진단에 사용한다.
+5. 결과는 stdout의 구조화 데이터로 판정하고 stderr는 진행 상황과 진단에 사용한다. 파이프라인에는 stdout만 다음 명령에 넘기고 stderr는 진단 로그로 분리한다.
 6. 실패하면 [troubleshooting.md](references/troubleshooting.md)에서 종료 코드와 인증 모델을 확인한다.
 
 `--quiet`는 해당 명령이 핵심 값 한 줄 출력을 문서화한 경우에만 사용한다.
@@ -28,8 +28,7 @@ description: >-
 
 | 작업 | 읽을 파일 |
 |---|---|
-| CLI 설치, `configure`, profile, 출력 모드, 명령 카탈로그, 종료 코드 | [common.md](references/common.md) |
-| 공개 스킬 상태 확인·설치·갱신·제거와 상태별 복구 | [common.md](references/common.md) |
+| CLI 설치·설정·출력, 공개 스킬 관리 | [common.md](references/common.md) |
 | Log & Crash Search v3 커서 검색·scroll 대량 추출·collector 전송<br>반복 조회 자동화의 호출 비용 설계 | [logncrash.md](references/logncrash.md) |
 | Deploy 실행·조회·바이너리 전송 | [deploy.md](references/deploy.md) |
 | Compute, VPC, Block Storage, Floating IP | [iaas.md](references/iaas.md) |
@@ -37,6 +36,6 @@ description: >-
 | Container Registry | [ncr.md](references/ncr.md) |
 | Kubernetes Service | [nks.md](references/nks.md) |
 | Container Service | [ncs.md](references/ncs.md) |
-| API Gateway 서비스·리소스·스테이지·배포 조회와 Swagger export | [apigateway.md](references/apigateway.md) |
-| API Gateway `stage update`·`stage import-resources`·`stage deploy create`·`stage deploy rollback`, `resource set-path-plugin`·`set-method-plugin` | [apigateway.md](references/apigateway.md) |
+| API Gateway 조회·변경·배포·Swagger export | [apigateway.md](references/apigateway.md) |
+| Secure Key Manager 키·키 저장소·인증 정보 관리, 기밀 데이터·암복호화·서명 검증 | [skm.md](references/skm.md) |
 | 인증·profile·region·출력·검색 제한 문제 해결 | [troubleshooting.md](references/troubleshooting.md) |

package/skills/nhncloud-cli/references/apigateway.md

@@ -1,45 +1,21 @@
 # API Gateway 조회·변경 안내
 
-`apigateway` 명령군은 API Gateway 서비스, 리소스, 스테이지, 배포 이력을 조회하고 스테이지의 Swagger를 내보낸다.
-스테이지의 백엔드 URL·설명 수정과 리소스 경로·메서드 플러그인 설정도 지원한다.
+`apigateway` 명령군은 API Gateway 서비스, 리소스, 스테이지, 배포 이력을 다룬다.
 
 ## 인증과 설정
 
 공통 UAK와 API Gateway `appKey`가 필요하다.
 `nhncloud configure --apigateway-appkey <appkey>`로 `profile`의 `apigateway.appkey`를 설정한다.
 
-API 요청은 공통 UAK로 발급한 Bearer 토큰을 `X-NHN-Authorization` 헤더에 담는다.
-표준 `Authorization` 헤더가 아니므로 직접 API를 호출할 때 혼동하지 않는다.
-
 지원 `region`은 `kr1`, `kr2`, `kr3`이며 기본값은 `kr1`이다.
 
 ```bash
 nhncloud apigateway service list --region kr1 --json
 ```
 
-## 명령
-
-아래 표의 공통 옵션은 `--region <region>`, `--profile <name>`이다.
-루트 전역 옵션인 `--json`과 `--quiet`도 사용할 수 있다.
-
-| 명령 경로 | 인수 | 명령 옵션 |
-|---|---|---|
-| `nhncloud apigateway service list` | 없음 | 공통 옵션 |
-| `nhncloud apigateway service get` | `<service-id>` | 공통 옵션 |
-| `nhncloud apigateway resource list` | `<service-id>` | 공통 옵션 |
-| `nhncloud apigateway resource parameters` | `<service-id> <resource-id>` | 공통 옵션 |
-| `nhncloud apigateway resource responses` | `<service-id> <resource-id>` | 공통 옵션 |
-| `nhncloud apigateway resource set-path-plugin` | `<service-id> <resource-id>` | 공통 옵션, `--config-file <path>`, `--dry-run`, `--yes` |
-| `nhncloud apigateway resource set-method-plugin` | `<service-id> <resource-id>` | 공통 옵션, `--config-file <path>`, `--dry-run`, `--yes` |
-| `nhncloud apigateway stage list` | `<service-id>` | 공통 옵션 |
-| `nhncloud apigateway stage swagger` | `<service-id> <stage-id>` | 공통 옵션, `--output <file>`, `--force` |
-| `nhncloud apigateway stage resources` | `<service-id> <stage-id>` | 공통 옵션 |
-| `nhncloud apigateway stage update` | `<service-id> <stage-id>` | 공통 옵션, `--backend-endpoint-url <url>`, `--description <text>`, `--yes` |
-| `nhncloud apigateway stage import-resources` | `<service-id> <stage-id>` | 공통 옵션, `--yes` |
-| `nhncloud apigateway stage deploy create` | `<service-id> <stage-id>` | 공통 옵션, `--description <text>`, `--no-wait`, `--timeout <sec>`, `--yes` |
-| `nhncloud apigateway stage deploy list` | `<service-id> <stage-id>` | 공통 옵션 |
-| `nhncloud apigateway stage deploy latest` | `<service-id> <stage-id>` | 공통 옵션 |
-| `nhncloud apigateway stage deploy rollback` | `<service-id> <stage-id> <deploy-id>` | 공통 옵션, `--yes` |
+## 명령 탐색
+
+정확한 명령 경로와 옵션은 `nhncloud commands --json`에서 확인한다.
 
 `--quiet`가 식별자를 출력하는 명령은 다음과 같다.
 
@@ -94,15 +70,13 @@ nhncloud apigateway service list --region kr1 --json
 `delete` 가 `true`면 해당 플러그인을 삭제하므로 `pluginConfigJson`을 생략할 수 있다.
 `applyChildPath`는 경로 플러그인에만 사용하며 메서드 설정에 넣으면 입력 오류로 거부된다.
 
-`set-path-plugin`과 `set-method-plugin`만 `--dry-run`을 제공한다.
-하위 적용 범위를 서버가 판정하고 CORS 플러그인이 기존 OPTIONS 메서드를 삭제·대체하므로,
-다른 위험 명령의 `--yes` 확인만으로는 되돌릴 수 없는 범위를 적용 전에 확인할 수 없기 때문이다.
+플러그인은 `--dry-run`을 먼저 실행해 변경 범위를 확인한다.
 
 리소스 플러그인 변경을 스테이지에 반영하려면 별도의 리소스 반영과 배포가 필요하다.
 
 ## 반영·배포·롤백
 
-리소스 변경이 트래픽에 적용되려면 서비스 리소스를 스테이지로 반영한 뒤 스테이지를 배포하는 두 단계를 거친다.
+리소스 변경이 트래픽에 적용되려면 서비스 리소스를 스테이지로 반영한 뒤 스테이지를 배포하는 순서를 거친다.
 반영·배포·롤백 명령은 모두 API 호출 전에 `--yes`가 필요하다.
 
 ```text
@@ -144,22 +118,9 @@ nhncloud apigateway stage deploy rollback <service-id> <stage-id> <deploy-id> --
 
 ## JSON 구조
 
-API 응답 봉투의 `header`를 검사한 뒤 CLI는 아래 데이터를 꺼내 `--json`으로 출력한다.
-따라서 목록은 JSON 배열, 단건은 JSON 객체로 출력된다.
-특히 서비스 목록의 최상위 키는 `apigwServiceList`이고 서비스 단건은 `apigwService`로 서로 다르다.
-
-| 명령 | API 응답의 최상위 키 | CLI JSON 구조 |
-|---|---|---|
-| `service list` | `apigwServiceList`, `paging` | service 객체 배열 |
-| `service get` | `apigwService` | service 객체 |
-| `resource list` | `resourceList` | resource 객체 배열 |
-| `resource parameters` | `queryStringList`, `headerList`, `formDataList`, `requestBody`, `contentTypeList` | 같은 키를 가진 객체 |
-| `resource responses` | `responseList`, `contentTypeList` | 같은 키를 가진 객체 |
-| `stage list` | `stageList`, `paging` | stage 객체 배열 |
-| `stage swagger` | `swaggerData` | Swagger 객체 |
-| `stage resources` | `stageResourceList` | stage resource 객체 배열 |
-| `stage deploy list` | `stageDeployHistoryList`, `paging` | deploy 객체 배열 |
-| `stage deploy latest` | `latestStageDeployResult` | 최신 deploy 객체 |
+`--json`은 목록을 배열, 단건을 객체로 출력한다.
+`resource parameters`와 `resource responses`는 각각 파라미터와 응답 설정 객체를 반환한다.
+`stage swagger`는 Swagger 객체를, `stage deploy latest`는 최신 배포 객체를 반환한다.
 
 `stage list`의 `resourceUpdatedAt`은 배포 시점이 아니다.
 서비스 리소스를 해당 스테이지로 가져온 일시를 뜻하며, 실제 배포 시점은 배포 응답의 `deployedAt`으로 확인한다.

package/skills/nhncloud-cli/references/common.md

@@ -1,18 +1,10 @@
 # Common Reference
 
-CLI와 공개 스킬 설치, configure, profile, 출력 모드, 에러 코드를 다룬다.
+공개 스킬 관리, configure, profile, 출력 모드, 에러 코드를 다룬다.
 서비스별 세부 명령은 각 reference를 읽는다.
 
-## 설치
-
-```bash
-npm install -g @bifos/nhncloud-cli
-```
-
 ## Claude Code 공개 스킬 관리
 
-전역 설치한 CLI나 `npx`로 패키지의 공개 스킬을 관리 저장소에 설치할 수 있다.
-관리 저장소는 실행 중인 npm 패키지 경로와 분리되므로 `npx`의 임시 패키지 경로가 사라져도 활성 스킬은 유지된다.
 
 ```bash
 # 전역 설치한 CLI에서 설치
@@ -75,7 +67,7 @@ nhncloud skills uninstall --quiet
 
 공공망 profile에는 `~/.nhncloud/credentials.json`의 해당 profile 블록에 `"environment": "gov"`를 명시한다.
 기존 profile은 이 필드를 생략하면 일반망을 사용한다.
-현재 공공망 endpoint 선택 대상은 OAuth, Deploy, NCR, IaaS이며 공공망에서 주소가 확인되지 않은 API는 호출하지 않는다.
+공공망에서 주소가 확인되지 않은 API는 호출하지 않는다.
 `configure`의 연결 테스트는 일반망 주소를 사용한다. 공공망 자격증명은 `--no-verify`로 저장하고, profile에 `environment`를 추가한 뒤 조회 명령으로 확인한다.
 
 ```bash
@@ -90,6 +82,7 @@ nhncloud configure \
   --uak-id <uak-id> --uak-secret <uak-secret> \
   --logncrash-appkey <appkey> \
   --ncr-appkey <appkey> \
+  --skm-appkey <appkey> \
   --no-verify
 ```
 
@@ -113,18 +106,8 @@ CLI가 UAK를 OAuth 토큰으로 교환하므로 별도 logncrash secret은 저
 }
 ```
 
-주요 옵션:
-
-| 옵션 | 설명 |
-|------|------|
-| `--profile <name>` | 대상 profile. 기본값은 `default` |
-| `--uak-id <id>` / `--uak-secret <secret>` | 공통 User Access Key |
-| `--logncrash-appkey <key>` | Log & Crash 서비스 appkey |
-| `--logncrash-secret <secret>` | 폐기 예정 호환 옵션. 경고 후 사용·저장하지 않음 |
-| `--ncr-appkey <key>` | NCR appkey |
-| `--iaas-tenant-id <id>` / `--iaas-username <name>` / `--iaas-password <password>` | IaaS/NKS 자격증명 |
-| `--iaas-region <region>` | IaaS 기본 region |
-| `--no-verify` | 연결 테스트 생략 |
+설정 가능한 전체 옵션은 `nhncloud configure --help`에서 확인한다.
+폐기 예정인 `--logncrash-secret`은 경고 후 사용·저장하지 않는다.
 
 저장 파일은 `~/.nhncloud/credentials.json`이고 mode 0600으로 관리된다.
 기본 profile은 선택적으로 `~/.nhncloud/config.json`의 `defaultProfile`로 지정한다.
@@ -148,9 +131,7 @@ profile 해석 순서:
 | `--json` | JSON stdout | 파싱, 자동화, AI 에이전트 |
 | `--quiet` | 명령이 문서화한 핵심 값 한 줄을 stdout으로 출력 | 단순 체이닝 |
 
-`--json`은 CLI 출력 계약이다.
-API 원본 wrapper를 항상 보존하지 않는다.
-예를 들어 `nhncloud instance get <instance-id> --json`은 `.server.status`가 아니라 `.status`를 읽는다.
+`--json`의 응답 구조는 서비스 reference에서 확인한다.
 
 ## 요청 타임아웃
 
@@ -178,8 +159,7 @@ HTTP 요청 상한과는 다른 설정이므로 서로 대체하지 않는다.
 
 ## Command catalog
 
-`nhncloud commands`는 Commander tree에서 command path, argument, option, description을 출력한다.
-외부 API를 호출하지 않는 read-only metadata 명령이다.
+`nhncloud commands`는 command path, argument, option, description을 출력한다. 외부 API를 호출하지 않는다.
 
 ```bash
 nhncloud commands
@@ -187,74 +167,14 @@ nhncloud commands --json
 nhncloud commands --json | jq '.commands[] | select(.path=="nks cluster list")'
 ```
 
-AI 에이전트는 먼저 `commands --json`으로 실제 command path와 option 이름을 확인하고, 그다음 서비스 reference를 읽는다.
-
-## JSON shape 요약
-
-| 명령 | `--json` 출력 shape |
-|------|---------------------|
-| `commands` | `{ commands: [{ path, description, arguments, options, subcommands }] }` |
-| `logncrash search` | `{ totalItems, pageNumber, pageSize, data, nextCursor? }` |
-| `logncrash export` | 파일 출력 전용. stdout JSON 없음 |
-| `deploy artifacts` | Deploy API `body` 객체 |
-| `deploy server-groups` | Deploy API `body` 객체 |
-| `deploy histories` | Deploy API `body` 객체 |
-| `deploy binary-groups` | `binaryGroups` wrapper를 언랩한 배열 |
-| `deploy binaries` | `{ totalCount, binaries }` |
-| `deploy upload` | `{ downloadUrl, binaryKey }` |
-| `instance list` | `servers` wrapper를 언랩한 server 배열 |
-| `instance get` | `server` wrapper를 언랩한 단일 server |
-| `instance create --wait` | `server` wrapper를 언랩한 단일 server |
-| `instance flavors` | `flavors` wrapper를 언랩한 flavor 배열 |
-| `instance images` | `images` wrapper를 언랩한 image 배열 |
-| `instance availability-zones` | `availabilityZoneInfo` wrapper를 언랩한 배열 |
-| `instance keypairs` | `keypairs[].keypair`를 flatten한 keypair 배열 |
-| `instance volumes` | `volumeAttachments` wrapper를 언랩한 attachment 배열 |
-| `network list` | VPC 배열 |
-| `network subnet list` | subnet 배열 |
-| `volume list` | volume 배열 |
-| `volume get` | 단일 volume 객체 |
-| `volume create` | 단일 volume 객체 |
-| `floatingip list` | Floating IP 배열 |
-| `floatingip create` | 단일 Floating IP 객체 |
-| `loadbalancer list` | Load Balancer 배열 |
-| `loadbalancer get` | 단일 Load Balancer 객체 |
-| `loadbalancer ipacl list` | IP ACL 그룹 배열 |
-| `loadbalancer ipacl get` | 단일 IP ACL 그룹 객체 |
-| `loadbalancer ipacl target list` | IP ACL 대상 배열 |
-| `loadbalancer ipacl create/delete` | 작업 상태와 IP ACL 그룹 UUID 객체 |
-| `loadbalancer ipacl target add/remove` | 대상 UUID와 재바인딩 결과 객체 |
-| `loadbalancer set-ipacl/clear-ipacl` | 작업 상태와 Load Balancer UUID·그룹 UUID 객체 |
-| `ncr list` | `registries` wrapper를 언랩한 registry 배열 |
-| `ncr get` | `registry` wrapper를 언랩한 단일 registry |
-| `ncr images` | repository 배열 |
-| `ncr tags` | tag 배열 |
-| `nks supports` | 지원 Kubernetes version / event type 객체 |
-| `nks cluster list` | cluster 배열 |
-| `nks cluster events` | event 배열 |
-| `nks nodegroup list` | nodegroup 배열 |
-| `nks addon-type list` | addon type 배열 |
-| `nks addon list` | addon 배열 |
-| `nks cluster addon list` | cluster addon 배열 |
-
-NKS 단건 조회와 일부 설정 조회는 table 출력용 최소 컬럼을 만들고 `--json`에서는 raw 객체를 보존한다.
-NKS 쓰기 명령 중 생성, resize, 설정 변경, 노드 action, 애드온 변경은 `{ uuid }` 응답을 반환한다.
-삭제 명령은 성공 메시지를 stderr에 쓰고 stdout은 비운다.
-`nks cluster kubeconfig`는 kubeconfig 문자열을 stdout 또는 파일로 저장한다.
-
-## 에러 코드
-
-| 상황 | exit code |
-|------|-----------|
-| API 오류 / 봉투 실패 | 1 |
-| 인증 실패 | 2 |
-| 입력 오류 / 필수 옵션 누락 / confirm 누락 | 3 |
-| 자격증명 또는 config 오류 | 4 |
-
-## Agent 기본 규칙
-
-- 조회는 먼저 `--json`으로 실행하고 필요한 id를 추출한다.
-- 쓰기 명령 전에 `--profile`, `--region`, 대상 id를 명시한다.
-- `--quiet`는 해당 명령이 핵심 값 한 줄 출력을 문서화한 경우에만 사용한다.
-- 삭제 명령은 비대화형 환경에서 `--yes`를 명시한다.
-- stdout은 데이터로만 취급하고, 진행 메시지는 stderr로 분리된다고 가정한다.
+## 되돌릴 수 없는 명령
+
+되돌릴 수 없거나 서비스를 중단시키는 명령이다. 실행 전에 대상과 변경 범위를 조회한다. 확인 방식은 명령마다 다르다.
+
+| 확인 방식 | 명령 |
+|---|---|
+| TTY 여부와 관계없이 `--yes` 필수 | `apigateway stage update`, `apigateway stage import-resources`, `apigateway stage deploy create`, `apigateway stage deploy rollback`, `apigateway resource set-path-plugin`, `apigateway resource set-method-plugin` (`--dry-run` 제외), `loadbalancer ipacl delete`, `loadbalancer ipacl target add`, `loadbalancer ipacl target remove`, `loadbalancer set-ipacl`, `loadbalancer clear-ipacl`, `network security-group delete`, `network security-group rule delete`, `instance security-group add`, `instance security-group remove`, `skm key delete`, `skm key purge`, `skm keystore delete`, `skm keystore auth delete`, `skm keystore auth purge` |
+| 비대화형 환경에서는 `--yes` 필수, TTY에서는 확인 질문 | `instance delete`, `floatingip delete`, `nks cluster delete`, `nks cluster addon remove`, `nks nodegroup delete`, `ncs template delete`, `ncs template version delete`, `ncs workload delete` |
+| 확인 질문과 `--yes` 없음 | `instance keypair delete`, `deploy run`, `nks cluster resize --nodes-to-remove`, `nks nodegroup upgrade`, `ncs workload update` (PUT 전체 교체), `instance volume detach`, `instance resize`, `instance stop`, `instance reboot`, `nks nodegroup update-flavor`, `nks cluster set-ipacl`, `nks cluster set-control-plane-log`, `nks cluster update-sgw`, `ncs workload patch` (JSON Patch `remove` 포함 가능), `nks nodegroup stop-node` (지정 노드 중지), `ncs workload pause` (workload 일시정지), `ncs workload restart` (task 재시작), `instance resize-confirm` (새 flavor로 고정, 이후 `resize-revert` 불가), `skm secret update` (기밀 데이터 값 교체), `skm keystore update` (실행 위치가 키를 쓰지 못하게 될 수 있으므로 먼저 `skm confirm`) |
+
+`nks cluster resize`는 `--nodes-to-remove`를 생략해도 확인 없이 실행되며, 감축 대상 노드를 API가 선택할 수 있다는 경고를 출력한다.

package/skills/nhncloud-cli/references/deploy.md

@@ -1,15 +1,10 @@
 # Deploy Reference
 
-`deploy` 명령군은 NHN Cloud Deploy v2.1 API를 호출한다.
-UAK를 OAuth `client_credentials`로 교환한 Bearer token으로 인증하고, token은 만료 전까지 캐시한다.
-
 ## 설정
 
 `~/.nhncloud/credentials.json`에 profile 공통 `userAccessKey`가 필요하다.
 appkey는 `nhncloud configure --deploy-appkey <key>`로 profile에 설정한다.
-`nhncloud configure` 사용을 권장한다.
 공공망에서는 profile에 `"environment": "gov"`를 명시하고 `--profile`로 선택한다.
-공공망 Deploy API 주소는 `https://api-tcd.gov-nhncloudservice.com`이다.
 
 배포 좌표(아티팩트·서버그룹·시나리오 등)는 config에 두지 않는다.
 매 호출마다 명령 옵션으로 넘긴다.
@@ -39,17 +34,7 @@ nhncloud deploy run --artifact-id <id> --server-group-id <id> --scenario-ids <id
 nhncloud deploy run --artifact-id <id> --server-group-id <id> --scenario-ids <id1,id2> --target-hosts <host1,host2>
 ```
 
-| 옵션 | 설명 |
-|------|------|
-| `--artifact-id <id>` | 배포할 아티팩트 ID (`artifacts`로 확인) |
-| `--server-group-id <id>` | 배포 대상 서버그룹 ID (`server-groups`로 확인) |
-| `--scenario-ids <csv>` | 실행할 시나리오 ID 목록 (쉼표 구분) |
-| `--target-hosts <csv>` | 대상 호스트. 생략 시 서버그룹 전체 |
-| `--concurrent <n>` | 병렬 배포 수. 기본 1 |
-| `--next-when-fail` | 시나리오 실패 시에도 진행 |
-| `--note <s>` | 배포 메모 |
-| `--async` | 즉시 반환. 기본은 완료 대기 |
-| `--profile <name>` | 사용할 profile |
+전체 옵션은 `nhncloud deploy run --help`에서 확인한다.
 
 동기 모드는 서버가 배포 완료까지 응답을 보류한다.
 비동기 모드는 `deploying` 상태를 즉시 반환하고, 완료 확인은 `deploy histories`로 한다.
@@ -65,17 +50,6 @@ nhncloud deploy binary-groups --artifact-id <id> --json
 nhncloud deploy binaries --binary-group <key> --artifact-id <id> --json
 ```
 
-의도별 명령:
-
-| 의도 | 명령 |
-|------|------|
-| 아티팩트 목록 | `deploy artifacts` |
-| 서버그룹 목록 | `deploy server-groups --artifact-id <id>` |
-| 시나리오 목록 | `deploy scenarios --artifact-id <id> --server-group-id <id>` |
-| 배포 이력 | `deploy histories --artifact-id <id>` |
-| 바이너리 그룹 목록 | `deploy binary-groups --artifact-id <id>` |
-| 바이너리 목록 | `deploy binaries --binary-group <key> --artifact-id <id>` |
-
 `deploy binary-groups --json`은 `binaryGroups` wrapper를 언랩한 배열이다.
 `deploy scenarios --json`은 시나리오 배열이며, `--quiet`은 시나리오 ID를 한 줄씩 출력한다.
 `deploy binaries --json`은 `{ totalCount, binaries }` 객체다.
@@ -87,7 +61,7 @@ nhncloud deploy upload --artifact-id <id> --file ./app.tgz --binary-group <key>
 nhncloud deploy download --artifact-id <id> --binary-group <key> --binary-key <key> -o ./app.tgz
 ```
 
-`upload`는 multipart로 로컬 파일을 업로드한다.
+`upload`는 로컬 파일을 업로드한다.
 `--quiet`이면 `binaryKey`만 출력한다.
 
 `download`는 바이너리를 파일로 저장한다.
@@ -100,15 +74,3 @@ nhncloud deploy artifacts --json | jq -r '.[0].artifactId'
 nhncloud deploy run --artifact-id <artifactId> --server-group-id <id> --scenario-ids <ids>
 nhncloud deploy histories --artifact-id <id> --json | jq '.[0] | {deployKey, deployStatus}'
 ```
-
-## 에러 코드
-
-| 상황 | exit code |
-|------|-----------|
-| UAK 누락 또는 profile에 deploy appkey 없음 | 4 |
-| 필수 옵션 누락(좌표, `--binary-group`·`--binary-key`·`--file`·`-o`) | 3 |
-| OAuth 인증 실패 | 2 |
-| Deploy API 오류 또는 봉투 실패 | 1 |
-
-필수 옵션 누락은 검증 방식과 관계없이 종료 코드 3으로 끝난다.
-Commander의 조기 검증과 명령 내부 검증은 오류 문구가 다를 수 있지만 자동화는 같은 입력 오류로 처리할 수 있다.

package/skills/nhncloud-cli/references/iaas.md

@@ -84,11 +84,67 @@ nhncloud instance keypair delete <name>
 ```bash
 nhncloud network list --json
 nhncloud network subnet list --json
+nhncloud network security-group list --json
+nhncloud network security-group get <group> --json
+nhncloud network security-group rule list <group> --json
+nhncloud network security-group rule get <rule-id> --json
+nhncloud network security-group ports <group> --json
+nhncloud network security-group ports <group> --quiet   # 연결된 인스턴스 UUID
 ```
 
 `instance create --network <uuid>`에는 `network list`의 VPC id를 사용한다.
 subnet id가 아니다.
 
+보안그룹 조회의 `<group>`에는 이름 또는 UUID를 지정한다.
+이름이 중복되면 후보 UUID를 보여 주고 종료 코드 3으로 끝난다.
+한 포트에 보안그룹이 여러 개면 모든 그룹의 허용 규칙이 함께 적용된다.
+공유 그룹의 규칙을 바꾸면 그 그룹을 쓰는 모든 포트에 영향을 주므로 먼저 `ports`로 연결 대상을 확인한다.
+`ports`의 `instance_name`은 Compute 인스턴스 목록에서 얻는다.
+인스턴스 조회가 실패하면 이름 칸은 비어 있고 stderr에 경고가 남는다.
+
+### 보안그룹 변경
+
+```bash
+nhncloud network security-group create --name <name> --description "<설명>"
+nhncloud network security-group update <group> --name <new-name> --description "<설명>"
+nhncloud network security-group delete <group> --yes
+nhncloud network security-group rule create <group> --direction ingress --protocol tcp --port 22 --cidr <admin-cidr>
+nhncloud network security-group rule delete <rule-id> --yes
+nhncloud instance security-group add <instance-id> <group> --yes
+nhncloud instance security-group remove <instance-id> <group> --yes
+```
+
+- 그룹을 만들면 송신 기본 규칙(IPv4, IPv6)이 자동으로 포함된다.
+- `rule create`의 `--direction`은 `ingress` 또는 `egress`이고 필수다.
+- `--protocol`은 `tcp`, `udp`, `icmp`, `any` 중 하나다.
+- 포트(`--port` 또는 `--port-range <start-end>`)는 `tcp`와 `udp`에만 지정할 수 있다.
+- `--cidr`(IPv4 주소나 CIDR)와 `--remote-group` 중 하나만 쓴다. 함께 지정하면 거부된다.
+- 규칙 수정 API가 없다. 규칙을 교체하려면 새 규칙을 먼저 만들고 옛 규칙을 지운다.
+  두 단계라 중간에 실패하면 두 규칙이 함께 남거나 허용이 빠질 수 있으므로, 각 단계 뒤 `rule list`로 확인한다.
+- 그룹 삭제는 연결된 포트가 있으면 거부된다.
+  다른 그룹 규칙이 삭제할 그룹을 원격 그룹으로 참조하고 있어도 삭제는 진행되고 경고만 남는다.
+- 인스턴스 연결 변경(`add`, `remove`)은 같은 이름의 그룹이 둘 이상이면 요청 전에 거부된다.
+  한쪽 이름을 `update --name`으로 먼저 바꾼다.
+- 연결 변경 뒤 `경고: 요청은 접수됐지만 ...`이 stderr에 나오면 요청은 접수된 것이다.
+  다시 실행하지 말고 `network security-group ports <group>`으로 반영을 확인한다. 이때 종료 코드는 0이다.
+
+#### 공유 그룹을 쓰는 개발 DB를 전용 그룹으로 분리
+
+```bash
+nhncloud network security-group ports <shared-group> --json          # 공유 그룹을 쓰는 인스턴스 확인
+nhncloud network security-group rule list <shared-group> --json      # 옮길 규칙 확인
+nhncloud network security-group create --name dev-db --description "개발 DB 전용" --quiet
+nhncloud network security-group rule create dev-db --direction ingress --protocol tcp --port 22 --cidr <admin-cidr>
+nhncloud network security-group rule create dev-db --direction ingress --protocol tcp --port 5432 --remote-group <app-group>
+nhncloud instance security-group add <db-instance-id> dev-db --yes
+nhncloud instance security-group remove <db-instance-id> <shared-group> --yes
+nhncloud network security-group ports dev-db
+```
+
+- SSH 관리 경로를 새 그룹에 먼저 넣고 새 그룹을 연결한 뒤에 공유 그룹을 해제해야, 해제하는 사이에 접근이 끊기지 않는다.
+- 송신 규칙은 그룹 생성 시 기본 규칙으로 보존되므로 따로 만들지 않는다.
+- 복구: `nhncloud instance security-group add <db-instance-id> <shared-group> --yes`로 공유 그룹을 다시 연결한다.
+
 ## Volume
 
 ```bash
@@ -117,12 +173,3 @@ nhncloud floatingip delete <floatingip-id> --yes
 
 `floatingip create --quiet`는 발급된 Floating IP id를 출력한다.
 `floatingip associate`는 instance→port_id 매핑 경로 미확정으로 아직 제공하지 않는다.
-
-## 에러 코드
-
-| 상황 | exit code |
-|------|-----------|
-| IaaS 자격증명 누락 또는 불완전 | 4 |
-| Keystone 인증 실패 | 2 |
-| 미등록 region, 필수 옵션 누락, `--yes` 누락 | 3 |
-| API 오류 또는 wait timeout | 1 |

package/skills/nhncloud-cli/references/loadbalancer.md

@@ -20,22 +20,6 @@ nhncloud loadbalancer ipacl target list <group> \
   --json
 ```
 
-## 명령
-
-| 명령 | 용도 | 기본 테이블 컬럼 |
-|------|------|------------------|
-| `loadbalancer list` | Load Balancer 목록 조회 | `id`, `name`, `vip_address`, `provisioning_status`, `operating_status`, `ipacl_group_action` |
-| `loadbalancer get <loadbalancer>` | 이름 또는 UUID로 단건 조회 | `field`, `value` |
-| `loadbalancer ipacl list` | IP ACL 그룹 목록 조회 | `id`, `name`, `action`, `ipacl_target_count`, `loadbalancer_count` |
-| `loadbalancer ipacl get <group>` | 이름 또는 UUID로 IP ACL 그룹 단건 조회 | `field`, `value` |
-| `loadbalancer ipacl target list <group>` | 그룹의 IP ACL 대상 목록 조회 | `id`, `cidr_address`, `description`, `ipacl_group_id` |
-| `loadbalancer ipacl create` | IP ACL 그룹 생성 | `field`, `value` |
-| `loadbalancer ipacl delete <group>` | IP ACL 그룹과 하위 대상·연결 규칙 삭제 | `field`, `value` |
-| `loadbalancer ipacl target add <group>` | 대상 추가 후 관련 Load Balancer 재바인딩 | `field`, `value` |
-| `loadbalancer ipacl target remove <target-id>` | 대상 삭제 후 관련 Load Balancer 재바인딩 | `field`, `value` |
-| `loadbalancer set-ipacl <loadbalancer>` | IP ACL 그룹 연결 전체 교체 | `field`, `value` |
-| `loadbalancer clear-ipacl <loadbalancer>` | IP ACL 그룹 연결 전체 해제 | `field`, `value` |
-
 단건 Load Balancer 테이블에는 `id`, `name`, `vip_address`, `provisioning_status`, `operating_status`, `ipacl_group_action`, `ipacl_group_ids`가 행으로 출력된다.
 단건 IP ACL 그룹 테이블에는 `id`, `name`, `action`, `ipacl_target_count`, `loadbalancer_ids`가 행으로 출력된다.
 
@@ -156,27 +140,10 @@ nhncloud loadbalancer ipacl target remove <target-id> \
 목록이 비어 있으면 기본 모드는 `결과 없음`을 stdout에 출력하고, `--json`은 빈 배열을 출력하며, `--quiet`는 출력하지 않는다.
 `--json`은 NHN Cloud 응답의 최상위 래퍼를 제거한 객체 또는 배열이다.
 
-## 공통 옵션
-
-| 옵션 | 설명 |
-|------|------|
-| `--region <region>` | region override. 생략하면 IaaS 자격증명의 region을 사용 |
-| `--profile <name>` | 사용할 profile |
-| `--json` | 객체 또는 배열을 JSON으로 stdout에 출력 |
-| `--quiet` | 리소스 UUID만 stdout에 출력 |
-
-## 쓰기 전용 옵션
-
-| 옵션 | 적용 명령 | 설명 |
-|------|-----------|------|
-| `--yes` | `ipacl delete`, `ipacl target add/remove`, `set-ipacl`, `clear-ipacl` | 삭제·연결 교체·대상 변경을 비대화형으로 확인 |
-| `--no-rebind` | `ipacl target add/remove` | 대상 변경 후 자동 재바인딩 생략 |
-
 ## stdout과 stderr
 
-- 테이블, JSON, UUID, 정상 빈 결과는 stdout에 출력한다.
-- 진행 상황, 운영 경고, 오류는 stderr에 출력한다.
-- 파이프라인에서는 stdout만 다음 명령에 전달하고 stderr는 진단 로그로 분리한다.
+stdout과 stderr 분리 규칙은 [SKILL.md](../SKILL.md)를 따른다.
+
 - 부분 실패에서도 JSON 또는 UUID를 stdout에 먼저 출력한 뒤 stderr에 복구 안내를 출력한다.
 
 ## 부분 실패 복구
@@ -225,13 +192,3 @@ stdout JSON의 `status`는 `partial`이며, 실패마다 기계 실행용 `retry
 AI 에이전트는 `retry_command`를 셸에서 다시 해석하지 말고 `retry_argv` 배열을 직접 실행한다.
 빈 그룹 snapshot의 복구 배열은 `clear-ipacl`을 사용한다.
 복구 명령이 성공한 뒤 원래 대상 추가·삭제를 반복하지 않는다.
-
-## 에러 코드
-
-| 상황 | exit code |
-|------|-----------|
-| Load Balancer 또는 IP ACL API 오류 | 1 |
-| 대상 변경 후 재바인딩 부분 실패 | 1 |
-| Keystone 인증 실패 | 2 |
-| 빈 이름·UUID, 리소스 없음, 중복 이름 | 3 |
-| IaaS 자격증명 누락 또는 미등록 region | 4 |