@bifos/nhncloud-cli 0.16.0 → 0.18.0

package/package.json

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

package/skills/nhncloud-cli/SKILL.md

@@ -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,5 @@ 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) |
 | 인증·profile·region·출력·검색 제한 문제 해결 | [troubleshooting.md](references/troubleshooting.md) |

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

@@ -17,29 +17,9 @@ API 요청은 공통 UAK로 발급한 Bearer 토큰을 `X-NHN-Authorization` 헤
 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,9 +74,7 @@ nhncloud apigateway service list --region kr1 --json
 `delete` 가 `true`면 해당 플러그인을 삭제하므로 `pluginConfigJson`을 생략할 수 있다.
 `applyChildPath`는 경로 플러그인에만 사용하며 메서드 설정에 넣으면 입력 오류로 거부된다.
 
-`set-path-plugin`과 `set-method-plugin`만 `--dry-run`을 제공한다.
-하위 적용 범위를 서버가 판정하고 CORS 플러그인이 기존 OPTIONS 메서드를 삭제·대체하므로,
-다른 위험 명령의 `--yes` 확인만으로는 되돌릴 수 없는 범위를 적용 전에 확인할 수 없기 때문이다.
+플러그인은 `--dry-run`을 먼저 실행해 변경 범위를 확인한다.
 
 리소스 플러그인 변경을 스테이지에 반영하려면 별도의 리소스 반영과 배포가 필요하다.
 
@@ -144,22 +122,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

@@ -73,6 +73,11 @@ nhncloud skills uninstall --quiet
 첫 설정은 `nhncloud configure`로 한다.
 대화형 마법사가 profile, UAK, 서비스별 자격증명을 묻고 저장 전 연결을 테스트한다.
 
+공공망 profile에는 `~/.nhncloud/credentials.json`의 해당 profile 블록에 `"environment": "gov"`를 명시한다.
+기존 profile은 이 필드를 생략하면 일반망을 사용한다.
+현재 공공망 endpoint 선택 대상은 OAuth, Deploy, NCR, IaaS이며 공공망에서 주소가 확인되지 않은 API는 호출하지 않는다.
+`configure`의 연결 테스트는 일반망 주소를 사용한다. 공공망 자격증명은 `--no-verify`로 저장하고, profile에 `environment`를 추가한 뒤 조회 명령으로 확인한다.
+
 ```bash
 nhncloud configure
 nhncloud configure --profile staging
@@ -108,18 +113,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`로 지정한다.
@@ -143,9 +138,7 @@ profile 해석 순서:
 | `--json` | JSON stdout | 파싱, 자동화, AI 에이전트 |
 | `--quiet` | 명령이 문서화한 핵심 값 한 줄을 stdout으로 출력 | 단순 체이닝 |
 
-`--json`은 CLI 출력 계약이다.
-API 원본 wrapper를 항상 보존하지 않는다.
-예를 들어 `nhncloud instance get <instance-id> --json`은 `.server.status`가 아니라 `.status`를 읽는다.
+`--json`의 응답 구조는 서비스 reference에서 확인한다.
 
 ## 요청 타임아웃
 
@@ -184,72 +177,14 @@ 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` |
+| 비대화형 환경에서는 `--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 cluster resize`는 `--nodes-to-remove`를 생략해도 확인 없이 실행되며, 감축 대상 노드를 API가 선택할 수 있다는 경고를 출력한다.

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

@@ -1,13 +1,11 @@
 # 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`로 선택한다.
 
 배포 좌표(아티팩트·서버그룹·시나리오 등)는 config에 두지 않는다.
 매 호출마다 명령 옵션으로 넘긴다.
@@ -37,17 +35,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`로 한다.
@@ -57,22 +45,14 @@ nhncloud deploy run --artifact-id <id> --server-group-id <id> --scenario-ids <id
 ```bash
 nhncloud deploy artifacts --json
 nhncloud deploy server-groups --artifact-id <id> --json
+nhncloud deploy scenarios --artifact-id <id> --server-group-id <id> --json
 nhncloud deploy histories --artifact-id <id> --json
 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 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 }` 객체다.
 
 ## 바이너리 전송
@@ -82,7 +62,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`는 바이너리를 파일로 저장한다.
@@ -95,15 +75,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

@@ -2,6 +2,8 @@
 
 `instance`, `network`, `volume`, `floatingip`은 IaaS 자격증명과 Keystone token을 공유한다.
 region이 중요하면 `--region <region>`을 명시한다.
+공공망 profile에는 `"environment": "gov"`를 명시한다.
+공식 문서에 endpoint가 있는 공공망 IaaS region은 `kr1`과 `kr2`다.
 
 ## IaaS 설정
 
@@ -82,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
@@ -115,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,22 +140,6 @@ 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에 출력한다.
@@ -225,13 +193,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 |

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

@@ -22,18 +22,6 @@ nhncloud logncrash search \
   --json
 ```
 
-옵션:
-
-| 옵션 | 필수 | 설명 |
-|------|:---:|------|
-| `--query <lucene>` | 예 | Lucene 질의 문자열. API에 그대로 전달 |
-| `--from <time>` | 예 | 검색 시작. 초와 시간대를 갖춘 ISO8601 또는 상대시간 |
-| `--to <time>` | 예 | 검색 끝. 초와 시간대를 갖춘 ISO8601, 상대시간, `now` |
-| `--page <n>` | 아니오 | 전환 호환용 pageNumber. 기본 0이며 0만 허용 |
-| `--size <n>` | 아니오 | pageSize. 기본 10, 범위 1~100 |
-| `--cursor <value>` | 아니오 | 직전 JSON 응답의 불투명한 `nextCursor` |
-| `--profile <name>` | 아니오 | 사용할 profile |
-
 CLI는 REAL API 실측 계약에 따라 모든 커서 요청을 `logTime DESC`로 고정 정렬한다.
 사용자 정렬 옵션은 제공하지 않는다.
 
@@ -117,7 +105,7 @@ nhncloud logncrash available-token --quiet
 호출 비용을 사전에 계산할 공식 규칙이 없고, 성공한 한 번의 호출이 잔량을 음수로 만들 수 있다.
 잔량 조회가 실패하면 CLI는 검색을 강행하지 않고 그 오류로 끝난다.
 
-**검색 기간만 좁히는 것을 보장된 해법으로 보지 않는다.**
+**검색 기간만 줄이는 것을 보장된 해법으로 보지 않는다.**
 공식 가이드는 기간, 크기와 쿼리 복잡도가 함께 비용에 영향을 준다고 설명하지만 산정식은 공개하지 않는다.
 기간을 나누면 한 호출의 비용이 줄 수 있지만 호출 수가 늘어난다.
 `available-token`의 추정 시간을 확인한 뒤 사용자가 다시 실행해야 한다.
@@ -128,21 +116,15 @@ CLI는 자동으로 다시 시도하지 않는다.
 ### 반복 조회를 설계할 때
 
 주기적으로 로그를 수집하는 자동화라면 아래를 전제로 짠다.
-실패한 워크플로에서 되짚어 얻은 것이다.
 
 **호출 비용을 이전 실측값으로 예측하지 않는다.**
-같은 프로젝트에서도 좁힌 쿼리의 비용이 호출당 약 85에서 약 21,870까지 다르게 관측됐다.
+같은 프로젝트에서도 범위를 줄인 쿼리의 비용이 호출당 약 85에서 약 21,870까지 다르게 관측됐다.
 쿼리와 기간은 필요한 데이터 범위에 맞추되, 다음 호출 전에 `available-token`을 다시 확인한다.
 
 **전수 수집은 `search` 반복이 아니라 `export` 한 번이다.**
 `search`를 페이지마다 부르면 호출 수가 페이지 수만큼 늘어난다.
 `export`는 같은 양을 훨씬 적은 호출로 받고, 기간 재분할과 페이지 순회를 CLI가 처리한다.
 
-**`--page`로 페이지네이션을 직접 만들지 않는다.**
-Search v3에서 `--page`는 `0`만 받는다.
-`1` 이상을 넘기면 입력 오류(종료 코드 3)로 거부되며, 이것은 시간이 지나도 풀리지 않는다.
-100건을 넘겨 받아야 하면 `export`를 쓴다.
-
 **재시도할 때 오류를 구분한다.**
 조회 횟수 제한은 토큰 회복 뒤 다시 시도할 수 있고, 서버 500은 export의 기간 분할 대상이다.
 입력 오류와 설정 오류는 기다려도 풀리지 않는다.
@@ -171,14 +153,7 @@ nhncloud logncrash export \
   --output logs.jsonl
 ```
 
-옵션:
-
-| 옵션 | 설명 |
-|------|------|
-| `--output <file>` | 필수. 출력 파일 |
-| `--format json` | JSON 배열로 저장. 기본은 JSON Lines |
-| `--force` | 기존 파일 덮어쓰기 |
-| `--size <n>` | 폐기 예정 호환 옵션. 10~100 검증 후 경고하고 v3 요청에는 미전달 |
+기본 파일 형식은 JSON Lines이며, `--format json`을 지정하면 JSON 배열로 저장한다.
 
 scroll 시작이나 계속 요청에서 서버가 500 응답을 반환하면 CLI가 해당 기간을 절반으로
 줄여 자동으로 다시 시도한다. 성공한 기간 크기는 남은 구간에도 재사용하므로 사용자가
@@ -241,24 +216,4 @@ nhncloud logncrash send --file ./error.log --level ERROR
 본문이 없거나 비어 있으면 입력 오류다.
 단일 로그 본문은 8MB 한도이며 초과 시 전송 전 차단된다.
 
-옵션:
-
-| 옵션 | 설명 |
-|------|------|
-| `--body <text>` | 로그 본문 |
-| `--file <path>` | 본문 파일 |
-| `--level <level>` | DEBUG, INFO, WARN, ERROR, FATAL |
-| `--app-version <ver>` | projectVersion |
-| `--source <s>` / `--type <t>` / `--host <h>` | 부가 필드 |
-| `--profile <name>` | 사용할 profile |
-
 `--json`이면 `{ ok: true, bytes }`를 stdout에 출력한다.
-
-## 에러 코드
-
-| 상황 | exit code |
-|------|-----------|
-| 검색 appkey 또는 공통 UAK 누락 | 4 |
-| 인증 실패 | 2 |
-| 시간 범위 초과, 본문 없음, 8MB 초과 | 3 |
-| API 오류 또는 봉투 실패 | 1 |

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

@@ -1,9 +1,5 @@
 # NCR Reference
 
-`ncr` 명령군은 NHN Container Registry 레지스트리, 이미지, 태그를 조회한다.
-Management API는 공통 UAK 정적 헤더를 사용한다.
-이미지와 태그 조회는 Harbor REST `/api/v2.0` 데이터플레인을 직접 호출하고 UAK Basic Auth를 사용한다.
-
 ## 설정
 
 공통 UAK와 NCR appkey가 필요하다.
@@ -13,6 +9,7 @@ nhncloud configure --uak-id <uak-id> --uak-secret <uak-secret> --ncr-appkey <app
 ```
 
 기본 region은 `kr1`이고, `kr1`, `kr2`, `kr3`를 지원한다.
+공공망 profile(`"environment": "gov"`)의 NCR API는 `kr1`만 지원한다.
 
 ## Registry 조회
 
@@ -47,25 +44,7 @@ nhncloud ncr tags <registry> <repository> --json | jq -r '.[].tag'
 nhncloud ncr tags <registry> <repository> --json | jq 'sort_by(.push_time) | last | .tag'
 ```
 
-## 옵션
-
-| 옵션 | 설명 |
-|------|------|
-| `--region <region>` | NCR region. 기본 `kr1` |
-| `--profile <name>` | 사용할 profile |
-
 ## 주의사항
 
-- appkey는 NCR service appkey다.
-- 인증 secret은 공통 UAK secret을 사용한다.
 - Harbor REST 경로는 NHN 공통 봉투가 아니므로 wrapper unwrap을 기대하지 않는다.
 - registry나 repository 인수는 공백 또는 빈값이면 입력 오류다.
-
-## 에러 코드
-
-| 상황 | exit code |
-|------|-----------|
-| UAK 누락 또는 NCR appkey 미설정 | 4 |
-| UAK 인증 실패 | 2 |
-| 지원하지 않는 region, 빈 registry/repository 인수 | 3 |
-| NCR API 또는 Harbor API 오류 | 1 |