@bifos/nhncloud-cli 0.17.0 → 0.19.0

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 전환의 영향을 받지 않는다.
 
@@ -22,18 +23,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`로 고정 정렬한다.
 사용자 정렬 옵션은 제공하지 않는다.
 
@@ -57,6 +46,7 @@ API 제약:
 
 - 검색 시작은 최근 90일 이내여야 한다.
 - 검색 범위는 31일 이하여야 한다.
+- 검색 `--size`는 1부터 100까지 허용한다.
 - 문서상 제약보다 짧은 기간에서도 서버가 500 응답을 낼 수 있다. 처리 가능한 기간의
   경계는 프로젝트의 로그 양에 따라 달라진다.
 
@@ -117,7 +107,7 @@ nhncloud logncrash available-token --quiet
 호출 비용을 사전에 계산할 공식 규칙이 없고, 성공한 한 번의 호출이 잔량을 음수로 만들 수 있다.
 잔량 조회가 실패하면 CLI는 검색을 강행하지 않고 그 오류로 끝난다.
 
-**검색 기간만 좁히는 것을 보장된 해법으로 보지 않는다.**
+**검색 기간만 줄이는 것을 보장된 해법으로 보지 않는다.**
 공식 가이드는 기간, 크기와 쿼리 복잡도가 함께 비용에 영향을 준다고 설명하지만 산정식은 공개하지 않는다.
 기간을 나누면 한 호출의 비용이 줄 수 있지만 호출 수가 늘어난다.
 `available-token`의 추정 시간을 확인한 뒤 사용자가 다시 실행해야 한다.
@@ -128,31 +118,20 @@ 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의 기간 분할 대상이다.
-입력 오류와 설정 오류는 기다려도 풀리지 않는다.
-
-| 종료 코드 | 의미 | 기다리면 풀리나 |
-|---|---|---|
-| 1 | API 오류, 봉투 실패 (조회 횟수 제한 포함) | 오류에 따라 다르다 |
-| 2 | 인증 실패 | 아니다 |
-| 3 | 입력 오류 | 아니다 |
-| 4 | 설정 오류 | 아니다 |
+종료 코드 1(API 오류, 조회 횟수 제한 포함)은 오류에 따라 기다리면 풀릴 수 있다.
+종료 코드 2(인증 실패), 3(입력 오류), 4(설정 오류)는 기다려도 풀리지 않는다.
+종료 코드 표는 [troubleshooting.md](troubleshooting.md#exit-code)가 소유한다.
 
 **고정 간격 대신 매번 잔량을 확인한다.**
 호출 비용은 쿼리마다 다르고 한 번에 큰 음수로 내려갈 수 있다.
@@ -171,14 +150,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가 해당 기간을 절반으로
 줄여 자동으로 다시 시도한다. 성공한 기간 크기는 남은 구간에도 재사용하므로 사용자가
@@ -186,7 +158,7 @@ scroll 시작이나 계속 요청에서 서버가 500 응답을 반환하면 CLI
 
 더 나눌 수 없는 기간에서도 500 응답이 계속되거나 다른 오류가 발생하면 CLI가 원본
 오류를 보존한다.
-`--size`는 v3 scroll의 페이지 크기를 제어하지 않는다.
+`--size`는 v3 scroll의 페이지 크기를 제어하지 않는 폐기 예정 호환 옵션이다. 10부터 100까지만 검증하고 경고한 뒤 v3 요청에서는 무시한다.
 
 조회 횟수 제한을 만나면 기간을 나누지 않고 즉시 멈춘다.
 나눌수록 호출이 늘어 제한을 더 소모하기 때문이다.
@@ -241,24 +213,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가 필요하다.
@@ -48,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 |

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

@@ -1,12 +1,8 @@
 # NCS Reference
 
-`ncs` 명령군은 NHN Container Service 의 template(설계도)과 workload(런타임 실행)를 조회·관리한다.
-template 의 생성·삭제, workload 의 생성·변경(update/patch)·실행제어(일시정지/재개/재시작/삭제), 악성코드 검사(malware) 설정·결과 조회를 지원한다.
-
 ## 설정
 
 공통 UAK와 NCS appkey가 필요하다.
-인증은 Deploy 와 같은 UAK OAuth Bearer 토큰을 재사용한다(profile 토큰 캐시 공유).
 
 `nhncloud configure` (대화형 또는 `--ncs-appkey`) 로 설정한다.
 
@@ -53,6 +49,7 @@ nhncloud ncs workload get <workload-id> --json
 
 컨테이너 로그와 이벤트는 특정 task 를 지정해야 한다.
 `--task`는 `workload get` 응답의 `tasks[].id`에서 얻는다.
+`--size`의 API 기본값은 `workload logs`에서 100, 나머지 `--size` 지원 명령에서 10이다.
 
 ```bash
 nhncloud ncs workload logs <workload-id> --task <task-id> --container <name> --json
@@ -63,7 +60,7 @@ nhncloud ncs workload events <workload-id> --task <task-id> --type Warning --jso
 
 ### logs·events 시간 필터
 
-`--from`과 `--to`는 다음 두 형식을 받는다.
+`--from`과 `--to`는 다음 형식을 받는다.
 
 - 시간대와 초를 포함한 RFC3339 절대시간
 - `now`
@@ -91,7 +88,7 @@ nhncloud ncs workload logs <workload-id> \
 ```
 
 CLI는 입력을 API 호출 전에 `YYYY-MM-DDTHH:mm:ssZ` 형식으로 정규화하고 소수 초를 제거한다.
-두 옵션을 모두 생략하면 API 기본 범위를 사용한다.
+`--from`과 `--to`를 모두 생략하면 API 기본 범위를 사용한다.
 한쪽만 지정하면 지정한 필드만 API에 전달한다.
 
 존재하지 않는 날짜, 시간대 없는 절대시간, 지원하지 않는 상대시간 단위, `from > to`는 종료 코드 3으로 거부한다.
@@ -121,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
@@ -161,46 +158,9 @@ nhncloud ncs workload get <workload-id> --json | jq -r '.tasks[].id'
 nhncloud ncs workload history <workload-id> --json | jq -r '.[0].id' # 최신 historyId
 ```
 
-## 옵션
-
-| 옵션 | 설명 |
-|------|------|
-| `--region <region>` | NCS region. 기본 `kr1`. `kr1`·`kr3`만 지원 |
-| `--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` 필수 |
-| `--from <time>` / `--to <time>` | `workload logs`·`workload events` 시간 필터. 시간대 포함 RFC3339, `now`, 0 이상의 정수와 `m`·`h`·`d` 단위 |
-| `--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 logs`·`workload events` 데이터는 stdout, 진행 상황과 오류는 stderr에 출력한다.
-- 시간 필터를 생략하면 CLI가 임의 기본값을 만들지 않고 API 기본 범위를 유지한다.
-- `workload restart`도 task 단위라 `--task` 없이는 입력 오류다.
-- `workload schedule-history`는 page/size를 아직 노출하지 않는다(대량 이력 시 첫 페이지만 반환될 수 있음 — ADR-020).
+- `workload schedule-history`는 page/size를 아직 노출하지 않아 대량 이력에서 첫 페이지만 반환될 수 있다.
 - 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` 누락 | 3 |
-| 잘못된 logs·events 시간 필터 | 3 |
-| `--file` 파일 오류, 잘못된 `--enabled`, 비대화형 삭제 시 `--yes` 누락 | 3 |
-| NCS API 오류 (payload 필수값 누락, `workload create --wait` 타임아웃 등 서버측 검증·폴링 실패 포함) | 1 |

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>`: 한 번에 서비스 불가 상태로 둘 노드 수. 크게 잡으면 빨라지고 가용성이 낮아진다.
@@ -143,12 +143,3 @@ nhncloud nks cluster set-control-plane-log <cluster> --file ./control-plane-log.
 단건 조회와 설정 조회는 API raw 객체를 보존하는 쪽을 우선한다.
 생성, resize, 설정 변경, 노드 action, 애드온 변경은 `{ uuid }` 응답을 반환한다.
 삭제 명령은 성공 메시지만 stderr에 쓰고 stdout은 비운다.
-
-## 에러 코드
-
-| 상황 | exit code |
-|------|-----------|
-| IaaS 자격증명 누락 또는 불완전 | 4 |
-| Keystone 또는 NKS 인증 실패 | 2 |
-| 지원하지 않는 region, payload JSON 파싱 실패, `--yes` 누락 | 3 |
-| NKS API 오류 또는 응답 형식 불일치 | 1 |

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

@@ -11,22 +11,28 @@
 5. exit code를 확인한다.
 6. 서비스별 인증 모델을 대조한다.
 
+`nhncloud doctor`는 자격증명과 공개 스킬 설치 상태를 오프라인에서 진단한다.
+
 ## 인증 모델
 
-| 서비스 | 비밀 | 인증 방식 |
-|--------|------|-----------|
-| 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 | 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 |
+| 서비스 | 비밀 |
+|--------|------|
+| 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` 누락 |
@@ -34,13 +40,7 @@
 
 ## Profile 누락
 
-profile은 다음 순서로 해석된다.
-
-1. `--profile <name>`
-2. `NHNCLOUD_PROFILE`
-3. `~/.nhncloud/config.json`의 `defaultProfile`
-4. `default`
-
+profile 선택 순서는 [Profile 우선순위](common.md#profile-우선순위)를 확인한다.
 자동화에서 의도와 다른 profile이 쓰이면 `--profile`을 명시한다.
 
 ## Region mismatch
@@ -57,9 +57,10 @@ nhncloud ncr list --region kr2 --json
 
 ## JSON shape 혼동
 
-CLI는 API wrapper를 일관되게 언랩한다.
-예를 들어 `instance get --json`은 `.server.status`가 아니라 `.status`다.
-목록과 단건의 shape가 다를 수 있으므로 jq path를 쓰기 전에 `--json` 원문을 확인한다.
+서비스와 명령에 따라 API wrapper 처리 방식이 다르다.
+`instance get --json`은 `.server.status`가 아니라 `.status`를 반환하지만, NKS 단건·설정 조회는 raw 객체를 보존한다.
+NCR의 Harbor 이미지·태그 조회에는 NHN 공통 wrapper 언랩을 적용하지 않는다.
+jq path를 쓰기 전에 `--json` 원문을 확인한다.
 
 ```bash
 nhncloud instance get <instance-id> --json | jq keys
@@ -68,33 +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 인증에 사용하지 않는다.
-
-## 쓰기 명령 confirm
-
-삭제, 제거, 비용 발생 가능 명령은 비대화형 환경에서 `--yes`가 필요할 수 있다.
-
-```bash
-nhncloud instance delete <instance-id> --yes
-nhncloud floatingip delete <floatingip-id> --yes
-nhncloud nks cluster delete <cluster> --yes
-nhncloud nks cluster addon remove <cluster> <addon> --yes
-```
+검색 기간·`--size`·`--page`·export 제한은 [logncrash.md](logncrash.md)를 따른다.
 
-## stdout/stderr 분리
+## 쓰기 명령 확인
 
-데이터는 stdout에 출력된다.
-진행 상황, 저장 완료, 성공 메시지, 에러는 stderr에 출력된다.
-스크립트에서 stdout만 파싱하고 stderr는 로그로 분리한다.
+명령별 확인 방식은 [되돌릴 수 없는 명령](common.md#되돌릴-수-없는-명령)에서 확인한다.