@bifos/nhncloud-cli 0.18.0 → 0.19.0

package/package.json

@@ -1,14 +1,32 @@
 {
   "name": "@bifos/nhncloud-cli",
-  "version": "0.18.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`는 해당 명령이 핵심 값 한 줄 출력을 문서화한 경우에만 사용한다.
@@ -37,4 +37,5 @@ description: >-
 | Kubernetes Service | [nks.md](references/nks.md) |
 | Container Service | [ncs.md](references/ncs.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,16 +1,12 @@
 # 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
@@ -80,7 +76,7 @@ nhncloud apigateway service list --region kr1 --json
 
 ## 반영·배포·롤백
 
-리소스 변경이 트래픽에 적용되려면 서비스 리소스를 스테이지로 반영한 뒤 스테이지를 배포하는 두 단계를 거친다.
+리소스 변경이 트래픽에 적용되려면 서비스 리소스를 스테이지로 반영한 뒤 스테이지를 배포하는 순서를 거친다.
 반영·배포·롤백 명령은 모두 API 호출 전에 `--yes`가 필요하다.
 
 ```text

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
 ```
 
@@ -166,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
@@ -175,16 +167,14 @@ nhncloud commands --json
 nhncloud commands --json | jq '.commands[] | select(.path=="nks cluster list")'
 ```
 
-AI 에이전트는 먼저 `commands --json`으로 실제 command path와 option 이름을 확인하고, 그다음 서비스 reference를 읽는다.
-
 ## 되돌릴 수 없는 명령
 
 되돌릴 수 없거나 서비스를 중단시키는 명령이다. 실행 전에 대상과 변경 범위를 조회한다. 확인 방식은 명령마다 다르다.
 
 | 확인 방식 | 명령 |
 |---|---|
-| 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` |
+| 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` 포함 가능) |
+| 확인 질문과 `--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

@@ -4,7 +4,6 @@
 
 `~/.nhncloud/credentials.json`에 profile 공통 `userAccessKey`가 필요하다.
 appkey는 `nhncloud configure --deploy-appkey <key>`로 profile에 설정한다.
-`nhncloud configure` 사용을 권장한다.
 공공망에서는 profile에 `"environment": "gov"`를 명시하고 `--profile`로 선택한다.
 
 배포 좌표(아티팩트·서버그룹·시나리오 등)는 config에 두지 않는다.

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

@@ -142,9 +142,8 @@ nhncloud loadbalancer ipacl target remove <target-id> \
 
 ## stdout과 stderr
 
-- 테이블, JSON, UUID, 정상 빈 결과는 stdout에 출력한다.
-- 진행 상황, 운영 경고, 오류는 stderr에 출력한다.
-- 파이프라인에서는 stdout만 다음 명령에 전달하고 stderr는 진단 로그로 분리한다.
+stdout과 stderr 분리 규칙은 [SKILL.md](../SKILL.md)를 따른다.
+
 - 부분 실패에서도 JSON 또는 UUID를 stdout에 먼저 출력한 뒤 stderr에 복구 안내를 출력한다.
 
 ## 부분 실패 복구

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

@@ -3,6 +3,7 @@
 `logncrash` 명령군은 Log & Crash Search v3 조회 토큰 확인, 커서 검색, scroll export, collector 전송을 다룬다.
 
 조회 토큰 확인, 검색과 export에는 profile의 logncrash appkey와 공통 UAK가 필요하다.
+기존 `logncrash.secret`은 Search v3 인증에 사용하지 않는다.
 CLI가 UAK를 OAuth 토큰으로 교환해 Bearer 인증을 적용한다.
 `send`는 별도 collector 계약이므로 Search v3 전환의 영향을 받지 않는다.
 
@@ -45,6 +46,7 @@ API 제약:
 
 - 검색 시작은 최근 90일 이내여야 한다.
 - 검색 범위는 31일 이하여야 한다.
+- 검색 `--size`는 1부터 100까지 허용한다.
 - 문서상 제약보다 짧은 기간에서도 서버가 500 응답을 낼 수 있다. 처리 가능한 기간의
   경계는 프로젝트의 로그 양에 따라 달라진다.
 
@@ -127,14 +129,9 @@ CLI는 자동으로 다시 시도하지 않는다.
 
 **재시도할 때 오류를 구분한다.**
 조회 횟수 제한은 토큰 회복 뒤 다시 시도할 수 있고, 서버 500은 export의 기간 분할 대상이다.
-입력 오류와 설정 오류는 기다려도 풀리지 않는다.
-
-| 종료 코드 | 의미 | 기다리면 풀리나 |
-|---|---|---|
-| 1 | API 오류, 봉투 실패 (조회 횟수 제한 포함) | 오류에 따라 다르다 |
-| 2 | 인증 실패 | 아니다 |
-| 3 | 입력 오류 | 아니다 |
-| 4 | 설정 오류 | 아니다 |
+종료 코드 1(API 오류, 조회 횟수 제한 포함)은 오류에 따라 기다리면 풀릴 수 있다.
+종료 코드 2(인증 실패), 3(입력 오류), 4(설정 오류)는 기다려도 풀리지 않는다.
+종료 코드 표는 [troubleshooting.md](troubleshooting.md#exit-code)가 소유한다.
 
 **고정 간격 대신 매번 잔량을 확인한다.**
 호출 비용은 쿼리마다 다르고 한 번에 큰 음수로 내려갈 수 있다.
@@ -161,7 +158,7 @@ scroll 시작이나 계속 요청에서 서버가 500 응답을 반환하면 CLI
 
 더 나눌 수 없는 기간에서도 500 응답이 계속되거나 다른 오류가 발생하면 CLI가 원본
 오류를 보존한다.
-`--size`는 v3 scroll의 페이지 크기를 제어하지 않는다.
+`--size`는 v3 scroll의 페이지 크기를 제어하지 않는 폐기 예정 호환 옵션이다. 10부터 100까지만 검증하고 경고한 뒤 v3 요청에서는 무시한다.
 
 조회 횟수 제한을 만나면 기간을 나누지 않고 즉시 멈춘다.
 나눌수록 호출이 늘어 제한을 더 소모하기 때문이다.

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

@@ -60,7 +60,7 @@ nhncloud ncs workload events <workload-id> --task <task-id> --type Warning --jso
 
 ### logs·events 시간 필터
 
-`--from`과 `--to`는 다음 두 형식을 받는다.
+`--from`과 `--to`는 다음 형식을 받는다.
 
 - 시간대와 초를 포함한 RFC3339 절대시간
 - `now`
@@ -88,7 +88,7 @@ nhncloud ncs workload logs <workload-id> \
 ```
 
 CLI는 입력을 API 호출 전에 `YYYY-MM-DDTHH:mm:ssZ` 형식으로 정규화하고 소수 초를 제거한다.
-두 옵션을 모두 생략하면 API 기본 범위를 사용한다.
+`--from`과 `--to`를 모두 생략하면 API 기본 범위를 사용한다.
 한쪽만 지정하면 지정한 필드만 API에 전달한다.
 
 존재하지 않는 날짜, 시간대 없는 절대시간, 지원하지 않는 상대시간 단위, `from > to`는 종료 코드 3으로 거부한다.
@@ -118,7 +118,7 @@ nhncloud ncs workload delete <workload-id> --yes
 
 생성은 비동기다.
 `--wait`를 주면 `Running` 상태가 될 때까지 폴링하고, `--timeout <sec>`(기본 300)으로 대기 시간을 조절한다.
-변경은 `update`(PUT, 전체 교체)와 `patch`(PATCH, JSON Patch 배열 부분 변경) 두 가지다.
+변경은 `update`(PUT, 전체 교체)와 `patch`(PATCH, JSON Patch 배열 부분 변경)다.
 
 ```bash
 nhncloud ncs workload create --file ./workload-create.json --json

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

@@ -95,7 +95,7 @@ control plane 이 먼저 올라가야 워커의 대상 버전이 생기기 때
 
 ### 워커 업그레이드 중 서비스 영향 조절
 
-두 옵션은 워커 업그레이드에만 의미가 있고 기본값은 모두 1이다.
+두 옵션은 `nodegroup upgrade`와 `nodegroup update-flavor`에서 받고 기본값은 모두 1이다.
 
 - `--num-buffer-nodes <n>`: 축출된 파드를 다시 받아 줄 여유 노드 수. 업그레이드가 끝나면 자동 삭제되지만 그동안 인스턴스 요금이 청구된다. 0으로 두면 기존 노드만으로 재배치해야 해 실패 위험이 커진다.
 - `--num-max-unavailable-nodes <n>`: 한 번에 서비스 불가 상태로 둘 노드 수. 크게 잡으면 빨라지고 가용성이 낮아진다.

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

@@ -0,0 +1,118 @@
+# Secure Key Manager 명령 안내
+
+`skm` 명령군은 Secure Key Manager의 키 저장소, 키, 인증 정보, 기밀 데이터를 다룬다.
+
+## 인증과 설정
+
+공통 UAK와 SKM `appKey`가 필요하다.
+`nhncloud configure --skm-appkey <appkey>`로 profile의 `skm.appkey`를 설정한다.
+
+공공망은 profile의 `"environment": "gov"`로 고른다.
+
+## 클라이언트 인증
+
+키 저장소에 등록한 클라이언트 인증 정보와 호출 환경이 맞아야 키와 데이터를 읽을 수 있다.
+CLI는 IPv4 인증과 MAC 인증을 지원한다. 인증서 인증 정보 등록(`auth add --type certificate`)은 지원하지만, CLI가 클라이언트 인증서를 보내 인증하는 것은 지원하지 않는다.
+
+- IPv4 인증은 서버가 본 요청 출발지 IP가 키 저장소에 등록돼 있어야 한다. 이 IP는 공인 IP와 다를 수 있다.
+  - 사내망처럼 내부 경로로 SKM endpoint에 닿는 환경에서는 서버에 사설 IP(예: `10.x.x.x`)로 보인다. 이때 공인 IP만 등록하면 `ipv4 auth failure`로 실패한다.
+  - 허용 IP는 `nhncloud skm confirm`의 `clientIp`를 기준으로 등록한다. 출발지 IP가 바뀔 수 있으면 `skm keystore auth add <keystore-id> <대역>/24 --type ipv4`처럼 CIDR 대역으로 등록한다.
+  - CLI는 `/0`부터 `/32`까지 받는다. `0.0.0.0/0`은 모든 출발지를 허용하므로 등록하지 않는다.
+  - 대역은 `10.0.0.0/24`처럼 호스트 비트를 0으로 맞춰 등록한다. 지울 때는 `auth list --type ipv4`에 나온 값을 `auth delete`에 그대로 넘긴다.
+- MAC 인증을 켠 키 저장소는 `--mac-address aa:bb:cc:dd:ee:ff`로 MAC을 넘긴다. 콜론 형식만 받고 소문자로 바꿔 보낸다.
+- `nhncloud skm confirm`은 서버가 본 클라이언트 IP와 MAC 헤더를 보여 준다. 인증 오류가 나면 먼저 확인한다.
+
+## 명령 탐색
+
+정확한 명령 경로와 옵션은 `nhncloud commands --json`에서 확인한다.
+
+```bash
+nhncloud skm keystore list
+nhncloud skm key list <keystore-id>
+nhncloud skm key list <keystore-id> --status active   # active|inactive 로 거른다
+nhncloud skm secret get <key-id> --quiet
+```
+
+`--quiet`가 출력하는 값은 다음과 같다.
+
+- `keystore list`·`keystore get`: `keyStoreId`
+- `key list`·`key get`: `keyId`
+- `secret get`: 기밀 데이터
+- `symmetric-key get`: 대칭키 원문
+- `symmetric-key encrypt`: 암호문
+- `symmetric-key decrypt`: 평문
+- `asymmetric-key sign`: 서명값
+- `asymmetric-key public-key`·`private-key`: `standardEncodedKey`(PKCS#8), 응답에 없으면 `encodedKey`. 일반망 문서의 응답에는 `standardEncodedKey`가 없다.
+- `symmetric-key create-local-key`: 평문 키와 암호화된 키 두 줄
+- `asymmetric-key verify`: 출력 없음
+- `key create`·`secret update`·`key delete|purge`: `keyId`
+- `keystore create|update|delete`: `keyStoreId`
+- `keystore auth add|delete|purge`: 입력한 IPv4·MAC 값(소문자로 정규화) 또는 인증서 이름
+- `keystore auth get`: 조회한 인증 정보의 값 또는 인증서 이름
+
+## 쓰기 명령
+
+처음 구성하는 순서 예시는 다음과 같다.
+
+```bash
+nhncloud skm keystore create --name <name> --auth ipv4
+nhncloud skm keystore auth add <keystore-id> 10.0.0.1 --type ipv4
+nhncloud skm keystore auth add <keystore-id> 10.0.0.0/24 --type ipv4   # CIDR 대역도 등록할 수 있다
+printf '%s' "$SECRET" | nhncloud skm key create <keystore-id> --type secret --name <name>
+```
+
+- 키 저장소는 `<keystore-id>`로 지정하고, CLI가 키 저장소 이름을 조회해 요청에 넣는다.
+- 기밀 데이터 값(`key create --type secret`, `secret update`)은 `--value`, `--file`, 표준 입력 중 하나로 넘긴다. `--value`로 넘긴 값은 셸 히스토리와 프로세스 목록에 남으므로 비밀값은 `--file`이나 표준 입력으로 넘긴다.
+- `keystore update`는 주지 않은 값을 현재 값으로 채운다. 조회 응답에 인증 결합 방식이 없으므로 `--auth-mode`는 매번 필수다. `--description`에 공백만 주면 현재 설명을 유지하며 설명을 지우는 경로는 없다.
+- `delete`는 7일 뒤 삭제되고 콘솔에서 취소할 수 있다. `purge`는 삭제가 예약된 대상만 즉시 지우며 되돌릴 수 없다. 모든 삭제 명령에 `--yes`가 필요하다.
+- 인증 정보를 지우거나 인증 설정을 바꾸기 전에 `nhncloud skm confirm`으로 현재 IP·MAC을 확인한다. 실행 위치가 키를 쓰지 못하게 될 수 있다.
+- 인증서 추가는 `--life-time <days>`가 필수다. 비밀번호는 `--password` 대신 `--password-file`이나 표준 입력을 권장하며, 끝 줄바꿈(`\n` 또는 `\r\n`) 하나를 지운다.
+- 대칭키·비대칭키는 자동 회전 없이 만들어진다. 자동 회전은 콘솔에서 설정한다.
+- MAC 값은 소문자로 바꿔 보내므로 콘솔에서 대문자로 등록한 MAC은 CLI로 지우지 못할 수 있다.
+
+## 입력과 크기 한도
+
+암복호화·서명·검증 명령의 입력은 `--plaintext`·`--ciphertext`, `--file`, 표준 입력 순서로 고른다.
+
+- `--plaintext`로 넘긴 값은 셸 히스토리와 프로세스 목록에 남는다. 비밀 평문은 `--file`이나 표준 입력으로 넘긴다.
+- 입력의 끝 줄바꿈과 BOM을 지우지 않는다. 줄바꿈 없는 값은 `echo` 대신 `printf`로 넘긴다.
+- 크기 한도는 명령마다 다르다.
+  - `symmetric-key encrypt`: 평문 32KB(32768바이트)
+  - `symmetric-key decrypt`: 암호문 1MB(1,000,000바이트)
+  - `asymmetric-key sign`·`verify`: 245바이트, `--standard`를 주면 64KB(65536바이트)
+  - `key create --type secret`·`secret update`: 기밀 데이터 값 1MB(1,000,000바이트)
+  - 인증서 비밀번호: 1024바이트
+- `--standard`는 바이너리 입력을 base64로 바꿔 보낸다.
+
+```bash
+printf 'hello' | nhncloud skm symmetric-key encrypt <key-id> --quiet
+```
+
+## 비밀값 출력
+
+비밀값을 출력하는 명령은 값을 숨기지 않는다.
+`--quiet`는 원문 뒤에 줄바꿈 하나를 붙이고, `--json`은 응답 그대로, 기본 출력은 제어 문자만 `?`로 바꾼 값을 낸다.
+입력은 끝 줄바꿈을 지우지 않으므로 `--quiet` 출력을 다른 skm 명령의 입력으로 넘기면 그 줄바꿈까지 암호화·서명된다.
+원문만 넘기려면 `--json` 출력에서 줄바꿈 없이 값을 꺼낸다.
+
+```bash
+nhncloud skm secret get <key-id> --json | jq -j '.secret' > secret.txt
+```
+인증서 인증 상세의 `password`는 `***`로 가린다.
+`secret update`는 바꾼 값을 출력하지 않는다.
+`symmetric-key get`은 대칭키 원문을 stdout에 낸다.
+`key get`, `keystore get`, `keystore auth get`은 메타데이터만 출력하고 키 원문과 인증서 비밀번호는 내지 않는다.
+비밀값 명령의 stdout을 로그나 이슈, 채팅에 붙이지 않는다.
+
+## 서명 검증 종료 코드
+
+`asymmetric-key verify`는 검증 결과가 `false`면 종료 코드 1을 반환한다.
+`--quiet`에서는 stdout이 비어 있으므로 종료 코드로 판단한다.
+
+```bash
+if nhncloud skm asymmetric-key verify <key-id> --plaintext hello --signature <signature>; then
+  echo ok
+fi
+```
+
+`--standard` 검증에 넘길 `--key-version`은 `asymmetric-key sign --standard --json` 출력의 `keyVersion`에서 얻는다.

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

@@ -15,22 +15,24 @@
 
 ## 인증 모델
 
-| 서비스 | 비밀 | 인증 방식 |
-|--------|------|-----------|
-| Log & Crash 검색/export | appkey 와 공통 UAK id/secret | UAK OAuth `X-NHN-Authorization: Bearer <token>` |
-| Log & Crash send | appkey | body `projectName=appkey`, 인증 헤더 없음 |
-| Deploy | UAK id 와 secret, Deploy appkey | OAuth Bearer token |
-| Instance/network/volume/floatingip | tenantId, username, API password | Keystone `X-Auth-Token` |
-| NKS | tenantId, username, API password | Keystone `X-Auth-Token` 과 container-infra API version |
-| NCR registry | UAK id, secret, NCR appkey | `X-TC-AUTHENTICATION-*` |
-| NCR images/tags | UAK id 와 secret | HTTP Basic Auth to Harbor REST |
-| NCS | UAK id 와 secret, NCS appkey | OAuth Bearer token (`X-NHN-Authorization`) |
-| API Gateway | UAK id 와 secret, API Gateway appkey | OAuth Bearer token (`X-NHN-Authorization`) |
+| 서비스 | 비밀 |
+|--------|------|
+| Log & Crash 검색/export | appkey 와 공통 UAK id/secret |
+| Log & Crash send | appkey |
+| Deploy | UAK id 와 secret, Deploy appkey |
+| Instance/network/volume/floatingip | tenantId, username, API password |
+| NKS | tenantId, username, API password |
+| NCR registry | UAK id, secret, NCR appkey |
+| NCR images/tags | UAK id 와 secret |
+| NCS | UAK id 와 secret, NCS appkey |
+| API Gateway | UAK id 와 secret, API Gateway appkey |
+| Secure Key Manager | UAK id 와 secret, SKM appkey, 키 저장소 IPv4·MAC 인증 |
 
 ## Exit code
 
 | exit code | 의미 | 대표 원인 |
 |-----------|------|-----------|
+| 0 | 성공 | 요청이 끝났고 출력이 완결됐다 |
 | 1 | API 오류 | 4xx/5xx, 봉투 실패, wait timeout |
 | 2 | 인증 실패 | UAK/secret/password 오류, 권한 부족 |
 | 3 | 입력 오류 | 필수 옵션 누락, region 미지원, 시간 범위 초과, `--yes` 누락 |
@@ -67,26 +69,8 @@ nhncloud ncr list --json | jq '.[0] | keys'
 
 ## Log & Crash 검색 제한
 
-- `--from`은 최근 90일 이내여야 한다.
-- `--to - --from` 범위는 31일 이하여야 한다.
-- `--page`는 0만 허용한다. 다음 페이지는 JSON의 `nextCursor`를 `--cursor`로 그대로 전달한다.
-- 검색 `--size`는 1부터 100까지 허용한다.
-- export `--size`는 폐기 예정 호환 옵션이며 10부터 100까지 검증 후 경고하고 v3 요청에서는 무시한다.
-- export가 중간 실패하면 보존된 원본 오류를 확인하고 검색 범위를 줄여 다시 실행한다.
-
-검색 또는 export에서 설정 오류가 나면 profile에 다음 두 값이 모두 있는지 확인한다.
-
-- `userAccessKey.id`와 `userAccessKey.secret`
-- `logncrash.appkey`
-
-기존 `logncrash.secret`은 Search v3 인증에 사용하지 않는다.
+검색 기간·`--size`·`--page`·export 제한은 [logncrash.md](logncrash.md)를 따른다.
 
 ## 쓰기 명령 확인
 
 명령별 확인 방식은 [되돌릴 수 없는 명령](common.md#되돌릴-수-없는-명령)에서 확인한다.
-
-## stdout/stderr 분리
-
-데이터는 stdout에 출력된다.
-진행 상황, 저장 완료, 성공 메시지, 에러는 stderr에 출력된다.
-스크립트에서 stdout만 파싱하고 stderr는 로그로 분리한다.