@bifos/nhncloud-cli 0.11.0 → 0.12.0

package/README.md

@@ -25,17 +25,17 @@ npm install -g @bifos/nhncloud-cli
 nhncloud configure
 ```
 
-- profile → UAK(id/secret) → logncrash appkey/secret → iaas 자격증명 → ncr appkey → ncs appkey 순으로 입력한다.
+- profile → 공통 UAK(id/secret) → logncrash appkey → iaas 자격증명 → ncr appkey → ncs appkey 순으로 입력한다.
 - profile 은 프로젝트 단위다 — 여러 NHN Cloud 프로젝트를 쓰면 profile 을 분리하되, 같은 UAK 를 쓴다면
   대화형 마법사가 기존 profile 의 UAK 재사용 여부를 먼저 물어 재입력을 줄여준다.
 - 저장 전 연결 테스트를 자동으로 수행한다 (`--no-verify` 로 생략 가능).
 - CI/자동화는 flag 로 비대화형 설정이 가능하다.
 
 ```bash
-# UAK + logncrash + ncs 비대화형 설정
+# 공통 UAK + logncrash + ncs 비대화형 설정
 nhncloud configure \
-  --uak-id <id> --uak-secret <secret> \
-  --logncrash-appkey <key> --logncrash-secret <secret> \
+  --uak-id <uak-id> --uak-secret <uak-secret> \
+  --logncrash-appkey <appkey> \
   [--ncs-appkey <appkey>] \
   --no-verify
 
@@ -143,6 +143,11 @@ nhncloud deploy download <target> --binary-group <key> --binary-key <binary-key>
 
 ### 로그 검색
 
+Log & Crash Search v3는 profile의 logncrash appkey와 공통 UAK를 사용한다.
+CLI가 UAK를 OAuth 토큰으로 교환해 `X-NHN-Authorization: Bearer <token>`으로 인증한다.
+기존 logncrash secret은 검색에 사용하거나 새 설정에 저장하지 않는다.
+전환 호환 옵션 `nhncloud configure --logncrash-secret`은 경고 후 무시한다.
+
 ```bash
 # 최근 1시간 NORMAL 로그
 nhncloud logncrash search \
@@ -161,6 +166,15 @@ nhncloud logncrash search \
   --query 'body:*request_received*' \
   --from 1h \
   --to now
+
+# 다음 페이지 조회: 직전 JSON의 nextCursor를 그대로 전달
+next_cursor="$(nhncloud logncrash search \
+  --query '*' --from 1h --to now --json | jq -r '.nextCursor // empty')"
+if [ -n "$next_cursor" ]; then
+  nhncloud logncrash search \
+    --query '*' --from 1h --to now \
+    --cursor "$next_cursor" --json
+fi
 ```
 
 `--query` 는 콘솔의 간편 검색어가 아니라 Log & Crash Search API 의 Lucene 쿼리다.
@@ -170,6 +184,9 @@ body 검색 의도가 명확하면 `body:<keyword>` 또는 `body:*<keyword>*`
 API 제약상 검색 시작은 최근 90일 이내, 검색 범위는 31일 이하여야 한다 (초과 시 입력 오류로 거절).
 전송 직후에는 인덱싱 지연으로 잠시 0건이 나올 수 있다.
 반복 검색이나 넓은 wildcard 검색은 API rate limit 에 걸릴 수 있으므로 시간 범위를 좁혀 확인한다.
+검색 결과는 `logTime DESC`로 고정 정렬한다.
+`--page`는 전환 호환을 위해 남아 있지만 `0`만 허용한다.
+다음 페이지는 JSON 응답에 `nextCursor`가 있을 때 그 값을 `--cursor`로 변형 없이 전달한다.
 
 ### 로그 대량 추출 (export)
 
@@ -187,7 +204,9 @@ nhncloud logncrash export --query 'logType:"ERROR"' --from 1h --to now \
 
 단발 검색(`search`)과 달리 scroll API 로 전체 결과(최대 10만 건)를 순회해 파일로 저장한다.
 진행 상황은 stderr, 데이터는 파일에만 기록된다(stdout 비움).
-scrollKey 유효기간은 1분이므로 데이터가 많을 때는 `--size` 를 키워 페이지 수를 줄이는 것을 권장한다.
+중간 요청이 실패하면 원본 오류를 확인하고 검색 시간 범위를 좁혀 다시 실행한다.
+기존 `--size`는 전환 호환 옵션이다.
+명시하면 10~100 범위를 검증하고 폐기 예정 경고를 출력하지만 Search v3 요청에는 전달하지 않는다.
 시간 범위 제한은 search 와 동일(90일 이내·31일 이하).
 
 #### export 옵션
@@ -199,7 +218,7 @@ scrollKey 유효기간은 1분이므로 데이터가 많을 때는 `--size` 를
 | `--to <time>` | 예 | 검색 끝 |
 | `--output <file>` | 예 | 출력 파일 경로 |
 | `--format <fmt>` | 아니오 | `jsonl`(기본, 한 줄당 한 로그) 또는 `json`(배열) |
-| `--size <n>` | 아니오 | scroll pageSize — 범위 10~100, 기본 100 |
+| `--size <n>` | 아니오 | 폐기 예정 호환 옵션. 10~100 검증 후 경고하고 v3 요청에서는 무시 |
 | `--force` | 아니오 | 출력 파일이 있으면 덮어쓴다 (기본 거부) |
 | `--profile <name>` | 아니오 | 사용할 profile 이름 |
 
@@ -219,7 +238,9 @@ echo "배치 작업 종료" | nhncloud logncrash send --level INFO
 nhncloud logncrash send --body "deploy 시작" --app-version 2.3.0 --source batch
 ```
 
-> logncrash send 는 검색과 다른 collector 로 전송하며 appkey 만 사용한다 (secret 불요). 단일 로그 본문은 8MB 까지.
+> `logncrash send`는 Search v3 전환의 영향을 받지 않는다.
+> 검색과 다른 collector로 전송하며 appkey만 사용한다.
+> 단일 로그 본문은 8MB까지 허용한다.
 
 ### 출력 모드
 
@@ -247,7 +268,7 @@ root와 주요 service group의 `--help`에는 짧은 agent hint가 포함된다
 | 명령 | `--json` 출력 shape |
 |------|---------------------|
 | `commands` | `{ commands: [{ path, description, arguments, options, subcommands }] }` |
-| `logncrash search` | `{ totalItems, pageNumber, pageSize, data }` 객체 |
+| `logncrash search` | `{ totalItems, pageNumber, pageSize, data, nextCursor? }` 객체 |
 | `logncrash export` | 파일 출력 전용. stdout JSON 없음 |
 | `deploy artifacts` | Deploy API `body` 객체 |
 | `deploy server-groups` | Deploy API `body` 객체 |
@@ -318,8 +339,9 @@ nhncloud logncrash search --query '*' --from 1d --to now --json | jq '.totalItem
 | `--query <lucene>` | 예 | Lucene 질의 문자열 |
 | `--from <time>` | 예 | 검색 시작 (ISO8601 또는 상대시간) |
 | `--to <time>` | 예 | 검색 끝 |
-| `--page <n>` | 아니오 | pageNumber (기본 0) |
-| `--size <n>` | 아니오 | pageSize (기본 10, 최대 100) |
+| `--page <n>` | 아니오 | 전환 호환용 pageNumber. 기본 0이며 0만 허용 |
+| `--size <n>` | 아니오 | pageSize (기본 10, 범위 1~100) |
+| `--cursor <value>` | 아니오 | 직전 JSON 응답의 불투명한 `nextCursor` |
 | `--profile <name>` | 아니오 | 사용할 profile |
 
 전역 옵션: `--json` / `--quiet` / `--no-color`.

package/dist/index.js

@@ -114,7 +114,7 @@ nhncloud configure \uB97C \uC2E4\uD589\uD574 \uC790\uACA9\uC99D\uBA85\uC744 \uC1
           profiles: {
             default: {
               userAccessKey: { id: "<uak-id>", secret: "<uak-secret>" },
-              logncrash: { appkey: "<appkey>", secret: "<secretkey>" }
+              logncrash: { appkey: "<appkey>" }
             }
           }
         },
@@ -215,7 +215,7 @@ ${CREDENTIALS_PATH} \uC5D0\uC11C profiles.${profileName} \uBE14\uB85D\uC744 \uCD
     throw new NhnCloudCliError(
       `profile "${profileName}" \uC5D0 "${service}" \uC790\uACA9\uC99D\uBA85\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.
 ${CREDENTIALS_PATH} \uC5D0\uC11C profiles.${profileName}.${service} \uBE14\uB85D\uC744 \uCD94\uAC00\uD558\uC138\uC694.
-\uC608\uC2DC: { "appkey": "<appkey>", "secret": "<secretkey>" }`,
+\uC608\uC2DC: { "appkey": "<appkey>" }`,
       EXIT_CONFIG_ERROR
     );
   }
@@ -681,33 +681,26 @@ function unwrap(res) {
 // src/services/logncrash/client.ts
 var LogncrashClient = class {
   appkey;
-  /** 검색(X-LNCS-SECRET)에만 필요. collector send 는 secret 을 쓰지 않으므로 옵셔널 (ADR-014). */
-  secret;
-  constructor(appkey, secret) {
+  /** Search v3 읽기 요청에만 필요하다. collector send 는 인증 헤더를 쓰지 않는다(ADR-014). */
+  accessToken;
+  constructor(appkey, accessToken) {
     this.appkey = appkey;
-    this.secret = secret;
+    this.accessToken = accessToken;
   }
-  async search(params) {
-    if (!this.secret) {
-      throw new NhnCloudCliError(
-        "logncrash search \uC5D0\uB294 secret \uC774 \uD544\uC694\uD569\uB2C8\uB2E4. configure \uB85C logncrash secret \uC744 \uC124\uC815\uD558\uC138\uC694.",
-        EXIT_CONFIG_ERROR
-      );
-    }
+  async cursorSearch(params) {
+    const headers = this.readHeaders();
     const endpoint = endpointFor("logncrash");
-    const url = `${endpoint}/api/v2/search/${encodeURIComponent(this.appkey)}`;
+    const url = `${endpoint}/v3/${encodeURIComponent(this.appkey)}/logs/cursor`;
     try {
       const res = await import_ky4.default.post(url, {
-        headers: {
-          "X-LNCS-SECRET": this.secret,
-          "Content-Type": "application/json"
-        },
+        headers,
         json: {
           query: params.query,
           from: params.from,
           to: params.to,
-          pageNumber: params.pageNumber ?? 0,
-          pageSize: params.pageSize ?? 10
+          sort: { logTime: "DESC" },
+          ...params.pageSize !== void 0 ? { pageSize: params.pageSize } : {},
+          ...params.cursor !== void 0 ? { cursor: params.cursor } : {}
         }
       }).json();
       return unwrap(res);
@@ -716,29 +709,19 @@ var LogncrashClient = class {
     }
   }
   /**
-   * scroll 검색을 시작한다. POST /api/v2/search/scroll/{appkey}.
-   * body 는 search 와 동일(query/from/to/pageSize). 응답 scrollKey 로 scrollNext 를 이어 호출한다.
+   * v3 scroll 검색을 시작한다. 응답 scrollKey 로 scrollNext 를 이어 호출한다.
    */
   async scrollStart(params) {
-    if (!this.secret) {
-      throw new NhnCloudCliError(
-        "logncrash scroll \uC5D0\uB294 secret \uC774 \uD544\uC694\uD569\uB2C8\uB2E4. configure \uB85C logncrash secret \uC744 \uC124\uC815\uD558\uC138\uC694.",
-        EXIT_CONFIG_ERROR
-      );
-    }
+    const headers = this.readHeaders();
     const endpoint = endpointFor("logncrash");
-    const url = `${endpoint}/api/v2/search/scroll/${encodeURIComponent(this.appkey)}`;
+    const url = `${endpoint}/v3/${encodeURIComponent(this.appkey)}/logs/scroll`;
     try {
       const res = await import_ky4.default.post(url, {
-        headers: {
-          "X-LNCS-SECRET": this.secret,
-          "Content-Type": "application/json"
-        },
+        headers,
         json: {
           query: params.query,
           from: params.from,
-          to: params.to,
-          pageSize: params.pageSize ?? 100
+          to: params.to
         }
       }).json();
       return unwrap(res);
@@ -747,31 +730,30 @@ var LogncrashClient = class {
     }
   }
   /**
-   * scroll 다음 페이지를 가져온다. POST /api/v2/search/scroll/{appkey}/{scrollKey}.
-   * body 는 보내지 않는다(scrollKey 가 좌표). scrollKey 만료 시 API 가 실패 봉투를 주며,
-   * unwrap 이 EXIT_API_ERROR 로 변환한다 — 호출부에서 만료 안내 메시지로 감싼다.
+   * v3 scroll 다음 페이지를 가져온다. body 없이 scrollKey 경로만 사용한다.
    */
   async scrollNext(scrollKey) {
-    if (!this.secret) {
-      throw new NhnCloudCliError(
-        "logncrash scroll \uC5D0\uB294 secret \uC774 \uD544\uC694\uD569\uB2C8\uB2E4. configure \uB85C logncrash secret \uC744 \uC124\uC815\uD558\uC138\uC694.",
-        EXIT_CONFIG_ERROR
-      );
-    }
+    const headers = this.readHeaders();
     const endpoint = endpointFor("logncrash");
-    const url = `${endpoint}/api/v2/search/scroll/${encodeURIComponent(this.appkey)}/${encodeURIComponent(scrollKey)}`;
+    const url = `${endpoint}/v3/${encodeURIComponent(this.appkey)}/logs/scroll/${encodeURIComponent(scrollKey)}`;
     try {
       const res = await import_ky4.default.post(url, {
-        headers: {
-          "X-LNCS-SECRET": this.secret,
-          "Content-Type": "application/json"
-        }
+        headers
       }).json();
       return unwrap(res);
     } catch (err) {
       throw toNhnCloudCliError(err);
     }
   }
+  readHeaders() {
+    if (!this.accessToken) {
+      throw new NhnCloudCliError(
+        "Log & Crash Search v3 \uD638\uCD9C\uC5D0\uB294 \uACF5\uD1B5 UAK\uB85C \uBC1C\uAE09\uD55C access token\uC774 \uD544\uC694\uD569\uB2C8\uB2E4. nhncloud configure\uB85C UAK\uB97C \uC124\uC815\uD558\uC138\uC694.",
+        EXIT_CONFIG_ERROR
+      );
+    }
+    return { "X-NHN-Authorization": `Bearer ${this.accessToken}` };
+  }
   /**
    * 로그 한 건을 Log & Crash collector 로 전송한다 (ADR-014).
    * - host: api-logncrash (검색의 api-lncs-search 와 별도)
@@ -1766,17 +1748,17 @@ async function verifyNcs(uak, appkey) {
     throw err;
   }
 }
-async function verifyLogncrash(cred) {
-  if (!cred.appkey || !cred.secret) return false;
-  const client = new LogncrashClient(cred.appkey, cred.secret);
+async function verifyLogncrash(uak, appkey) {
+  if (!appkey) return false;
   const now = /* @__PURE__ */ new Date();
   const oneMinuteAgo = new Date(now.getTime() - 6e4);
   try {
-    await client.search({
+    const token = await getAccessToken("__verify__", uak.id, uak.secret, true);
+    const client = new LogncrashClient(appkey, token);
+    await client.cursorSearch({
       query: "*",
       from: oneMinuteAgo.toISOString(),
       to: now.toISOString(),
-      pageNumber: 0,
       pageSize: 1
     });
     return true;
@@ -1789,7 +1771,7 @@ async function verifyLogncrash(cred) {
 }
 
 // src/commands/configure.ts
-async function saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, doVerify) {
+async function saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, doVerify, logncrashUak = uak) {
   if (doVerify) {
     if (uak) {
       const ok = await verifyUserAccessKey(uak);
@@ -1803,12 +1785,18 @@ async function saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, doVeri
       }
     }
     if (logncrash) {
-      const ok = await verifyLogncrash(logncrash);
+      if (!logncrashUak) {
+        throw new NhnCloudCliError(
+          "logncrash Search v3 \uAC80\uC99D\uC5D0\uB294 \uACF5\uD1B5 UAK\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. --uak-id\uC640 UAK secret\uC744 \uD568\uAED8 \uC124\uC815\uD558\uAC70\uB098 \uAE30\uC874 profile\uC5D0 UAK\uB97C \uC124\uC815\uD558\uC138\uC694.",
+          EXIT_CONFIG_ERROR
+        );
+      }
+      const ok = await verifyLogncrash(logncrashUak, logncrash.appkey ?? "");
       if (ok) {
         process.stderr.write(import_chalk.default.green("  \u2713 logncrash \uC5F0\uACB0 \uC131\uACF5\n"));
       } else {
         throw new NhnCloudCliError(
-          "logncrash \uC778\uC99D \uC2E4\uD328 \u2014 appkey / secret \uC744 \uD655\uC778\uD558\uC138\uC694.",
+          "logncrash \uC778\uC99D \uC2E4\uD328 \u2014 appkey \uB610\uB294 UAK\uB97C \uD655\uC778\uD558\uC138\uC694.",
           EXIT_AUTH_ERROR
         );
       }
@@ -1932,8 +1920,7 @@ async function runInteractive(opts) {
       message: "logncrash appkey",
       validate: (v) => v.trim().length > 0 || "logncrash appkey \uB97C \uC785\uB825\uD558\uC138\uC694"
     });
-    const secret = await password({ message: "logncrash secret", mask: "*" });
-    logncrash = { appkey, secret };
+    logncrash = { appkey: appkey.trim() };
   }
   let iaas;
   const setupIaas = await confirm({
@@ -1994,7 +1981,7 @@ async function runInteractive(opts) {
   }
   if (opts.verify) {
     try {
-      await saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, true);
+      await saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, true, uak);
     } catch (err) {
       if (err instanceof NhnCloudCliError && err.exitCode === EXIT_AUTH_ERROR) {
         process.stderr.write(import_chalk.default.red(`  \u2717 ${err.message}
@@ -2007,22 +1994,43 @@ async function runInteractive(opts) {
           process.stderr.write(import_chalk.default.yellow("\uC800\uC7A5\uC774 \uCDE8\uC18C\uB418\uC5C8\uC2B5\uB2C8\uB2E4.\n"));
           return;
         }
-        await saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, false);
+        await saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, false, uak);
       } else {
         throw err;
       }
     }
   } else {
-    await saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, false);
+    await saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, false, uak);
   }
 }
 async function runNonInteractive(opts) {
-  const profileName = await resolveProfileName(opts.profile);
   const uakSecret = opts.uakSecret ?? process.env["NHNCLOUD_UAK_SECRET"];
-  const logncrashSecret = opts.logncrashSecret ?? process.env["NHNCLOUD_LOGNCRASH_SECRET"];
   const iaasPassword = opts.iaasPassword ?? process.env["NHNCLOUD_IAAS_PASSWORD"];
-  const uak = opts.uakId && uakSecret ? { id: opts.uakId, secret: uakSecret } : void 0;
-  const logncrash = opts.logncrashAppkey && logncrashSecret ? { appkey: opts.logncrashAppkey, secret: logncrashSecret } : void 0;
+  if (opts.uakId !== void 0 && opts.uakId.trim().length === 0) {
+    throw new NhnCloudCliError("--uak-id \uAC12\uC740 \uBE44\uC5B4 \uC788\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.", EXIT_PARAM_ERROR);
+  }
+  if (uakSecret !== void 0 && uakSecret.length === 0) {
+    throw new NhnCloudCliError("UAK secret \uAC12\uC740 \uBE44\uC5B4 \uC788\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.", EXIT_PARAM_ERROR);
+  }
+  if (opts.uakId !== void 0 !== (uakSecret !== void 0)) {
+    throw new NhnCloudCliError(
+      "\uBE44\uB300\uD654\uD615 \uBAA8\uB4DC\uC5D0\uC11C --uak-id\uC640 UAK secret\uC740 \uD568\uAED8 \uC9C0\uC815\uD574\uC57C \uD569\uB2C8\uB2E4.",
+      EXIT_PARAM_ERROR
+    );
+  }
+  if (opts.logncrashAppkey !== void 0 && opts.logncrashAppkey.trim().length === 0) {
+    throw new NhnCloudCliError("--logncrash-appkey \uAC12\uC740 \uBE44\uC5B4 \uC788\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.", EXIT_PARAM_ERROR);
+  }
+  if (opts.logncrashSecret !== void 0) {
+    process.stderr.write(
+      import_chalk.default.yellow(
+        "\uACBD\uACE0: --logncrash-secret\uC740 \uD3D0\uAE30 \uC608\uC815\uC774\uBA70 Search v3 \uC778\uC99D\uC5D0 \uC0AC\uC6A9\uD558\uAC70\uB098 \uC800\uC7A5\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.\n"
+      )
+    );
+  }
+  const profileName = await resolveProfileName(opts.profile);
+  const uak = opts.uakId !== void 0 && uakSecret !== void 0 ? { id: opts.uakId.trim(), secret: uakSecret } : void 0;
+  const logncrash = opts.logncrashAppkey?.trim() ? { appkey: opts.logncrashAppkey.trim() } : void 0;
   const iaas = opts.iaasTenantId && opts.iaasUsername && iaasPassword ? {
     tenantId: opts.iaasTenantId,
     username: opts.iaasUsername,
@@ -2033,20 +2041,33 @@ async function runNonInteractive(opts) {
   const ncs = opts.ncsAppkey?.trim() ? { appkey: opts.ncsAppkey.trim() } : void 0;
   if (!uak && !logncrash && !iaas && !ncr && !ncs) {
     throw new NhnCloudCliError(
-      "\uBE44\uB300\uD654\uD615 \uBAA8\uB4DC: --uak-id + UAK secret, --logncrash-appkey + logncrash secret,\n--iaas-tenant-id + --iaas-username + iaas password,\n--ncr-appkey, \uB610\uB294 --ncs-appkey \uC911 \uD558\uB098\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.\nsecret/password \uB294 \uB178\uCD9C \uBC29\uC9C0\uB97C \uC704\uD574 \uD658\uACBD\uBCC0\uC218 \uAD8C\uC7A5:\nNHNCLOUD_UAK_SECRET / NHNCLOUD_LOGNCRASH_SECRET / NHNCLOUD_IAAS_PASSWORD.",
+      "\uBE44\uB300\uD654\uD615 \uBAA8\uB4DC: --uak-id + UAK secret, --logncrash-appkey,\n--iaas-tenant-id + --iaas-username + iaas password,\n--ncr-appkey, \uB610\uB294 --ncs-appkey \uC911 \uD558\uB098\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.\nsecret/password \uB294 \uB178\uCD9C \uBC29\uC9C0\uB97C \uC704\uD574 \uD658\uACBD\uBCC0\uC218 \uAD8C\uC7A5:\nNHNCLOUD_UAK_SECRET / NHNCLOUD_IAAS_PASSWORD.",
       EXIT_PARAM_ERROR
     );
   }
+  let logncrashUak = uak;
+  if (opts.verify && logncrash && !logncrashUak) {
+    logncrashUak = await getUserAccessKey(profileName);
+  }
   if (opts.verify) {
     process.stderr.write(import_chalk.default.gray("\uC5F0\uACB0 \uD14C\uC2A4\uD2B8 \uC911\u2026\n"));
   }
-  await saveAndVerify(profileName, uak, logncrash, iaas, ncr, ncs, opts.verify);
+  await saveAndVerify(
+    profileName,
+    uak,
+    logncrash,
+    iaas,
+    ncr,
+    ncs,
+    opts.verify,
+    logncrashUak
+  );
 }
-var configureCommand = new import_commander.Command("configure").description("\uC790\uACA9\uC99D\uBA85 \uC124\uC815 \uB9C8\uBC95\uC0AC (\uB300\uD654\uD615 + flag)").option("--profile <name>", "\uB300\uC0C1 profile \uC774\uB984 (\uAE30\uBCF8: default)").option("--uak-id <id>", "\uAC1C\uC778 UAK ID (\uBE44\uB300\uD654\uD615)").option("--uak-secret <secret>", "\uAC1C\uC778 UAK Secret (\uBE44\uB300\uD654\uD615, \uB178\uCD9C \uBC29\uC9C0\uB85C env NHNCLOUD_UAK_SECRET \uAD8C\uC7A5)").option("--logncrash-appkey <key>", "logncrash appkey (\uBE44\uB300\uD654\uD615)").option("--logncrash-secret <secret>", "logncrash secret (\uBE44\uB300\uD654\uD615, env NHNCLOUD_LOGNCRASH_SECRET \uAD8C\uC7A5)").option("--iaas-tenant-id <id>", "iaas tenantId / \uD504\uB85C\uC81D\uD2B8 ID (\uBE44\uB300\uD654\uD615)").option("--iaas-username <user>", "iaas IAM username (\uBE44\uB300\uD654\uD615)").option(
+var configureCommand = new import_commander.Command("configure").description("\uC790\uACA9\uC99D\uBA85 \uC124\uC815 \uB9C8\uBC95\uC0AC (\uB300\uD654\uD615 + flag)").option("--profile <name>", "\uB300\uC0C1 profile \uC774\uB984 (\uAE30\uBCF8: default)").option("--uak-id <id>", "\uAC1C\uC778 UAK ID (\uBE44\uB300\uD654\uD615)").option("--uak-secret <secret>", "\uAC1C\uC778 UAK Secret (\uBE44\uB300\uD654\uD615, \uB178\uCD9C \uBC29\uC9C0\uB85C env NHNCLOUD_UAK_SECRET \uAD8C\uC7A5)").option("--logncrash-appkey <key>", "logncrash appkey (\uBE44\uB300\uD654\uD615)").option("--logncrash-secret <secret>", "\uD3D0\uAE30 \uC608\uC815: Search v3\uC5D0\uC11C\uB294 \uC0AC\uC6A9\xB7\uC800\uC7A5\uD558\uC9C0 \uC54A\uC74C").option("--iaas-tenant-id <id>", "iaas tenantId / \uD504\uB85C\uC81D\uD2B8 ID (\uBE44\uB300\uD654\uD615)").option("--iaas-username <user>", "iaas IAM username (\uBE44\uB300\uD654\uD615)").option(
   "--iaas-password <pass>",
   "iaas API \uBE44\uBC00\uBC88\uD638 (\uBE44\uB300\uD654\uD615, \uB178\uCD9C \uBC29\uC9C0\uB85C env NHNCLOUD_IAAS_PASSWORD \uAD8C\uC7A5)"
 ).option("--iaas-region <region>", "iaas region (\uAE30\uBCF8: kr1)", "kr1").option("--ncr-appkey <key>", "ncr appkey (\uBE44\uB300\uD654\uD615)").option("--ncs-appkey <key>", "ncs appkey (\uBE44\uB300\uD654\uD615)").option("--no-verify", "\uC5F0\uACB0 \uD14C\uC2A4\uD2B8 \uC0DD\uB7B5").action(async (opts) => {
-  const hasFlag = opts.uakId || opts.uakSecret || opts.logncrashAppkey || opts.logncrashSecret || opts.iaasTenantId || opts.iaasUsername || opts.iaasPassword || opts.ncrAppkey || opts.ncsAppkey;
+  const hasFlag = opts.uakId !== void 0 || opts.uakSecret !== void 0 || opts.logncrashAppkey !== void 0 || opts.logncrashSecret !== void 0 || opts.iaasTenantId !== void 0 || opts.iaasUsername !== void 0 || opts.iaasPassword !== void 0 || opts.ncrAppkey !== void 0 || opts.ncsAppkey !== void 0;
   try {
     if (hasFlag) {
       await runNonInteractive(opts);
@@ -2400,6 +2421,21 @@ function parseNonNegativeIntegerOption(value, flag) {
   return parseIntegerOption(value, flag, { min: 0 });
 }
 
+// src/commands/logncrash/helpers.ts
+async function resolveLogncrashClient(profile) {
+  const profileName = await resolveProfileName(profile);
+  const credential = await getServiceCredential("logncrash", profileName);
+  if (typeof credential.appkey !== "string" || credential.appkey.length === 0) {
+    throw new NhnCloudCliError(
+      `profile "${profileName}"\uC758 logncrash \uC790\uACA9\uC99D\uBA85\uC5D0 appkey\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4. nhncloud configure\uB85C appkey\uB97C \uC124\uC815\uD558\uC138\uC694.`,
+      EXIT_CONFIG_ERROR
+    );
+  }
+  const uak = await getUserAccessKey(profileName);
+  const accessToken = await getAccessToken(profileName, uak.id, uak.secret);
+  return new LogncrashClient(credential.appkey, accessToken);
+}
+
 // src/commands/logncrash/search.ts
 function getString(value) {
   return typeof value === "string" ? value : String(value ?? "");
@@ -2410,7 +2446,7 @@ function formatLogRow(log) {
   const body = truncate(getString(log["logBody"] ?? log["body"] ?? log["message"] ?? ""), 60);
   return [logTime, logType, body];
 }
-var searchCommand = new import_commander4.Command("search").description("Log & Crash \uB85C\uADF8 \uAC80\uC0C9").option("--query <lucene>", "Lucene \uC9C8\uC758 \uBB38\uC790\uC5F4 (\uD544\uC218)").option("--from <time>", "\uAC80\uC0C9 \uC2DC\uC791: ISO8601 \uB610\uB294 \uC0C1\uB300\uC2DC\uAC04 (1h/30m/2d/now) (\uD544\uC218)").option("--to <time>", "\uAC80\uC0C9 \uB05D: ISO8601 \uB610\uB294 \uC0C1\uB300\uC2DC\uAC04 (\uD544\uC218)").option("--page <n>", "pageNumber (\uAE30\uBCF8 0)", "0").option("--size <n>", "pageSize (\uAE30\uBCF8 10, \uCD5C\uB300 100)", "10").option("--profile <name>", "\uC0AC\uC6A9\uD560 profile \uC774\uB984").action(async (_opts, cmd) => {
+var searchCommand = new import_commander4.Command("search").description("Log & Crash \uB85C\uADF8 \uAC80\uC0C9").option("--query <lucene>", "Lucene \uC9C8\uC758 \uBB38\uC790\uC5F4 (\uD544\uC218)").option("--from <time>", "\uAC80\uC0C9 \uC2DC\uC791: ISO8601 \uB610\uB294 \uC0C1\uB300\uC2DC\uAC04 (1h/30m/2d/now) (\uD544\uC218)").option("--to <time>", "\uAC80\uC0C9 \uB05D: ISO8601 \uB610\uB294 \uC0C1\uB300\uC2DC\uAC04 (\uD544\uC218)").option("--page <n>", "pageNumber (\uAE30\uBCF8 0)", "0").option("--size <n>", "pageSize (\uAE30\uBCF8 10, \uCD5C\uB300 100)", "10").option("--cursor <value>", "\uB2E4\uC74C \uD398\uC774\uC9C0 \uC870\uD68C\uC6A9 opaque cursor").option("--profile <name>", "\uC0AC\uC6A9\uD560 profile \uC774\uB984").action(async (_opts, cmd) => {
   const opts = cmd.optsWithGlobals();
   if (!opts.query) {
     throw new NhnCloudCliError(`--query \uC635\uC158\uC740 \uD544\uC218\uC785\uB2C8\uB2E4. \uC608: --query 'logType:"NORMAL"'`, EXIT_PARAM_ERROR);
@@ -2423,35 +2459,28 @@ var searchCommand = new import_commander4.Command("search").description("Log & C
   }
   const page = parseNonNegativeIntegerOption(opts.page ?? "0", "--page");
   const size = parseIntegerOption(opts.size ?? "10", "--size", { min: 1, max: 100 });
-  const fromIso = resolveTime(opts.from);
-  const toIso = resolveTime(opts.to);
-  assertSearchRange(fromIso, toIso);
-  const profileName = await resolveProfileName(opts.profile);
-  const cred = await getServiceCredential("logncrash", profileName);
-  if (!cred.appkey) {
+  if (page !== 0) {
     throw new NhnCloudCliError(
-      `profile "${profileName}" \uC758 logncrash \uC790\uACA9\uC99D\uBA85\uC5D0 appkey \uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.
-credentials.json \uC5D0 "appkey": "<appkey>" \uB97C \uCD94\uAC00\uD558\uC138\uC694.`,
-      EXIT_CONFIG_ERROR
+      "Search v3\uC5D0\uC11C\uB294 --page 0\uB9CC \uC9C0\uC6D0\uD569\uB2C8\uB2E4. \uB2E4\uC74C \uD398\uC774\uC9C0\uB294 --cursor <nextCursor>\uB97C \uC0AC\uC6A9\uD558\uC138\uC694.",
+      EXIT_PARAM_ERROR
     );
   }
-  if (!cred.secret) {
-    throw new NhnCloudCliError(
-      `profile "${profileName}" \uC758 logncrash \uC790\uACA9\uC99D\uBA85\uC5D0 secret \uC774 \uC5C6\uC2B5\uB2C8\uB2E4.
-credentials.json \uC5D0 "secret": "<secretkey>" \uB97C \uCD94\uAC00\uD558\uC138\uC694.`,
-      EXIT_CONFIG_ERROR
-    );
+  if (opts.cursor !== void 0 && opts.cursor.trim().length === 0) {
+    throw new NhnCloudCliError("--cursor \uAC12\uC740 \uBE44\uC5B4 \uC788\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.", EXIT_PARAM_ERROR);
   }
-  const client = new LogncrashClient(cred.appkey, cred.secret);
+  const fromIso = resolveTime(opts.from);
+  const toIso = resolveTime(opts.to);
+  assertSearchRange(fromIso, toIso);
+  const client = await resolveLogncrashClient(opts.profile);
   startSpinner("\uB85C\uADF8 \uAC80\uC0C9 \uC911...");
   let result;
   try {
-    result = await client.search({
+    result = await client.cursorSearch({
       query: opts.query,
       from: fromIso,
       to: toIso,
-      pageNumber: page,
-      pageSize: size
+      pageSize: size,
+      ...opts.cursor !== void 0 ? { cursor: opts.cursor } : {}
     });
   } catch (err) {
     stopSpinner(false);
@@ -2467,7 +2496,8 @@ credentials.json \uC5D0 "secret": "<secretkey>" \uB97C \uCD94\uAC00\uD558\uC138\
       totalItems: result.totalItems,
       pageNumber: result.pageNumber,
       pageSize: result.pageSize,
-      data: result.data
+      data: result.data,
+      ...result.nextCursor !== void 0 ? { nextCursor: result.nextCursor } : {}
     },
     ids
   });
@@ -2581,7 +2611,7 @@ function assertWritable(path3, force) {
     EXIT_PARAM_ERROR
   );
 }
-var exportCommand = new import_commander6.Command("export").description("Log & Crash \uB85C\uADF8\uB97C scroll \uB85C \uC804\uCCB4 \uCD94\uCD9C\uD574 \uD30C\uC77C\uB85C \uC800\uC7A5 (\uB300\uB7C9 \uCD94\uCD9C)").option("--query <lucene>", "Lucene \uC9C8\uC758 \uBB38\uC790\uC5F4 (\uD544\uC218)").option("--from <time>", "\uAC80\uC0C9 \uC2DC\uC791: ISO8601 \uB610\uB294 \uC0C1\uB300\uC2DC\uAC04 (1h/30m/2d/now) (\uD544\uC218)").option("--to <time>", "\uAC80\uC0C9 \uB05D: ISO8601 \uB610\uB294 \uC0C1\uB300\uC2DC\uAC04 (\uD544\uC218)").option("--output <file>", "\uCD9C\uB825 \uD30C\uC77C \uACBD\uB85C (\uD544\uC218)").option("--format <fmt>", "\uCD9C\uB825 \uD615\uC2DD: jsonl(\uAE30\uBCF8, \uD55C \uC904\uB2F9 \uD55C \uB85C\uADF8) \uB610\uB294 json(\uBC30\uC5F4)", "jsonl").option("--size <n>", "scroll \uD398\uC774\uC9C0 \uD06C\uAE30 (docs \uBC94\uC704 10~100, \uAE30\uBCF8 100)", "100").option("--force", "\uCD9C\uB825 \uD30C\uC77C\uC774 \uC788\uC73C\uBA74 \uB36E\uC5B4\uC4F4\uB2E4").option("--profile <name>", "\uC0AC\uC6A9\uD560 profile \uC774\uB984").action(async (_opts, cmd) => {
+var exportCommand = new import_commander6.Command("export").description("Log & Crash \uB85C\uADF8\uB97C scroll \uB85C \uC804\uCCB4 \uCD94\uCD9C\uD574 \uD30C\uC77C\uB85C \uC800\uC7A5 (\uB300\uB7C9 \uCD94\uCD9C)").option("--query <lucene>", "Lucene \uC9C8\uC758 \uBB38\uC790\uC5F4 (\uD544\uC218)").option("--from <time>", "\uAC80\uC0C9 \uC2DC\uC791: ISO8601 \uB610\uB294 \uC0C1\uB300\uC2DC\uAC04 (1h/30m/2d/now) (\uD544\uC218)").option("--to <time>", "\uAC80\uC0C9 \uB05D: ISO8601 \uB610\uB294 \uC0C1\uB300\uC2DC\uAC04 (\uD544\uC218)").option("--output <file>", "\uCD9C\uB825 \uD30C\uC77C \uACBD\uB85C (\uD544\uC218)").option("--format <fmt>", "\uCD9C\uB825 \uD615\uC2DD: jsonl(\uAE30\uBCF8, \uD55C \uC904\uB2F9 \uD55C \uB85C\uADF8) \uB610\uB294 json(\uBC30\uC5F4)", "jsonl").option("--size <n>", "\uD3D0\uAE30 \uC608\uC815: Search v3\uC5D0\uC11C\uB294 \uBB34\uC2DC\uB428 (\uD638\uD658 \uAC80\uC99D \uBC94\uC704 10~100)").option("--force", "\uCD9C\uB825 \uD30C\uC77C\uC774 \uC788\uC73C\uBA74 \uB36E\uC5B4\uC4F4\uB2E4").option("--profile <name>", "\uC0AC\uC6A9\uD560 profile \uC774\uB984").action(async (_opts, cmd) => {
   const opts = cmd.optsWithGlobals();
   if (!opts.query) {
     throw new NhnCloudCliError(`--query \uC635\uC158\uC740 \uD544\uC218\uC785\uB2C8\uB2E4. \uC608: --query 'logType:"NORMAL"'`, EXIT_PARAM_ERROR);
@@ -2599,35 +2629,23 @@ var exportCommand = new import_commander6.Command("export").description("Log & C
   if (format !== "jsonl" && format !== "json") {
     throw new NhnCloudCliError("--format \uC740 jsonl \uB610\uB294 json \uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.", EXIT_PARAM_ERROR);
   }
-  const sizeRaw = opts.size ?? "100";
-  if (!/^[1-9]\d*$/.test(sizeRaw)) {
-    throw new NhnCloudCliError("--size \uB294 \uC591\uC758 \uC815\uC218\uC5EC\uC57C \uD569\uB2C8\uB2E4 (docs \uBC94\uC704 10~100).", EXIT_PARAM_ERROR);
-  }
-  const size = parseInt(sizeRaw, 10);
-  if (size < 10 || size > 100) {
-    throw new NhnCloudCliError("--size \uB294 10~100 \uC0AC\uC774\uC5EC\uC57C \uD569\uB2C8\uB2E4 (Log & Crash scroll pageSize \uD55C\uB3C4).", EXIT_PARAM_ERROR);
+  if (opts.size !== void 0) {
+    if (!/^[1-9]\d*$/.test(opts.size)) {
+      throw new NhnCloudCliError("--size \uB294 \uC591\uC758 \uC815\uC218\uC5EC\uC57C \uD569\uB2C8\uB2E4 (\uD638\uD658 \uBC94\uC704 10~100).", EXIT_PARAM_ERROR);
+    }
+    const size = parseInt(opts.size, 10);
+    if (size < 10 || size > 100) {
+      throw new NhnCloudCliError("--size \uB294 10~100 \uC0AC\uC774\uC5EC\uC57C \uD569\uB2C8\uB2E4.", EXIT_PARAM_ERROR);
+    }
+    process.stderr.write(
+      "\uACBD\uACE0: logncrash export --size\uB294 \uD3D0\uAE30 \uC608\uC815\uC774\uBA70 Search v3 \uC694\uCCAD\uC5D0\uC11C\uB294 \uBB34\uC2DC\uB429\uB2C8\uB2E4.\n"
+    );
   }
   const fromIso = resolveTime(opts.from);
   const toIso = resolveTime(opts.to);
   assertSearchRange(fromIso, toIso);
   assertWritable(opts.output, opts.force ?? false);
-  const profileName = await resolveProfileName(opts.profile);
-  const cred = await getServiceCredential("logncrash", profileName);
-  if (!cred.appkey) {
-    throw new NhnCloudCliError(
-      `profile "${profileName}" \uC758 logncrash \uC790\uACA9\uC99D\uBA85\uC5D0 appkey \uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.
-credentials.json \uC5D0 "appkey": "<appkey>" \uB97C \uCD94\uAC00\uD558\uC138\uC694.`,
-      EXIT_CONFIG_ERROR
-    );
-  }
-  if (!cred.secret) {
-    throw new NhnCloudCliError(
-      `profile "${profileName}" \uC758 logncrash \uC790\uACA9\uC99D\uBA85\uC5D0 secret \uC774 \uC5C6\uC2B5\uB2C8\uB2E4.
-credentials.json \uC5D0 "secret": "<secret>" \uB97C \uCD94\uAC00\uD558\uC138\uC694.`,
-      EXIT_CONFIG_ERROR
-    );
-  }
-  const client = new LogncrashClient(cred.appkey, cred.secret);
+  const client = await resolveLogncrashClient(opts.profile);
   const tmp = opts.output + "." + (0, import_node_crypto2.randomBytes)(4).toString("hex") + ".tmp";
   const stream = (0, import_node_fs2.createWriteStream)(tmp, { encoding: "utf-8" });
   const spinner = startSpinner("\uB85C\uADF8 \uCD94\uCD9C \uC911...");
@@ -2645,12 +2663,16 @@ credentials.json \uC5D0 "secret": "<secret>" \uB97C \uCD94\uAC00\uD558\uC138\uC6
   };
   try {
     if (format === "json") stream.write("[");
-    let res = await client.scrollStart({ query: opts.query, from: fromIso, to: toIso, pageSize: size });
+    let res = await client.scrollStart({
+      query: opts.query,
+      from: fromIso,
+      to: toIso
+    });
     total = res.totalItems;
     writePage(res.data);
     spinner.text = `\uB85C\uADF8 \uCD94\uCD9C \uC911... ${count}/${total}`;
     while (res.data.length > 0 && res.scrollKey && count < Math.min(total, MAX_TOTAL)) {
-      res = await scrollNextOrExpire(client, res.scrollKey);
+      res = await scrollNextWithHint(client, res.scrollKey);
       writePage(res.data);
       spinner.text = `\uB85C\uADF8 \uCD94\uCD9C \uC911... ${count}/${total}`;
     }
@@ -2684,13 +2706,13 @@ credentials.json \uC5D0 "secret": "<secret>" \uB97C \uCD94\uAC00\uD558\uC138\uC6
   process.stderr.write(`${opts.output} \uC5D0 ${count}\uAC74 \uC800\uC7A5
 `);
 });
-async function scrollNextOrExpire(client, scrollKey) {
+async function scrollNextWithHint(client, scrollKey) {
   try {
     return await client.scrollNext(scrollKey);
   } catch (err) {
     if (err instanceof NhnCloudCliError && err.exitCode === EXIT_API_ERROR) {
       throw new NhnCloudCliError(
-        `scroll \uB2E4\uC74C \uD398\uC774\uC9C0 \uC694\uCCAD\uC774 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4 (\uC6D0\uC778: ${err.message}). scrollKey \uB9CC\uB8CC(\uC720\uD6A8 1\uBD84)\uC77C \uC218 \uC788\uC73C\uB2C8, \uB9CC\uB8CC\uB77C\uBA74 \uAC80\uC0C9 \uBC94\uC704\uB97C \uC881\uD788\uAC70\uB098 --size \uB97C \uD0A4\uC6CC \uD398\uC774\uC9C0 \uC218\uB97C \uC904\uC778 \uB4A4 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uC138\uC694.`,
+        `scroll \uB2E4\uC74C \uD398\uC774\uC9C0 \uC694\uCCAD\uC774 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4 (\uC6D0\uC778: ${err.message}). \uAC80\uC0C9 \uBC94\uC704\uB97C \uC881\uD600 \uB2E4\uC2DC \uC2E4\uD589\uD558\uC138\uC694.`,
         EXIT_API_ERROR
       );
     }
@@ -8641,7 +8663,7 @@ Agent workflow:
   3. nhncloud ncs workload get <id> --json
 `;
 var program = new import_commander53.Command();
-program.name("nhncloud").description("NHN Cloud CLI \u2014 AI agent & terminal friendly").version("0.11.0").option("--json", "JSON \uD615\uC2DD\uC73C\uB85C \uCD9C\uB825").option("--quiet", "\uCD5C\uC18C \uCD9C\uB825 (\uC790\uB3D9\uD654\uC6A9)").option("--no-color", "\uC0C9\uC0C1 \uBE44\uD65C\uC131\uD654").addHelpText("after", rootAgentHints);
+program.name("nhncloud").description("NHN Cloud CLI \u2014 AI agent & terminal friendly").version("0.12.0").option("--json", "JSON \uD615\uC2DD\uC73C\uB85C \uCD9C\uB825").option("--quiet", "\uCD5C\uC18C \uCD9C\uB825 (\uC790\uB3D9\uD654\uC6A9)").option("--no-color", "\uC0C9\uC0C1 \uBE44\uD65C\uC131\uD654").addHelpText("after", rootAgentHints);
 program.hook("preAction", () => {
   const opts = program.opts();
   if (!opts.color || process.env["NO_COLOR"]) {

package/package.json

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

package/skills/nhncloud-cli/SKILL.md

@@ -1,81 +1,37 @@
 ---
 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),
-  Load Balancer와 IP ACL(loadbalancer 조회·쓰기·재바인딩 복구), NHN Container Registry(ncr),
-  NHN Kubernetes Service(nks supports/cluster/nodegroup/addon/kubeconfig),
-  NHN Container Service(ncs template/workload 조회·시간 필터·생성·변경·실행제어,
-  malware 검사 설정·결과 조회) 등 NHN Cloud API를 터미널과 AI 에이전트에서 호출한다.
+  NHN Cloud 리소스를 nhncloud CLI로 조회·생성·변경·삭제하거나,
+  configure·profile·출력 형식·종료 코드·명령 문법을 확인할 때 사용한다.
+  Log & Crash, Deploy, Compute, Network, Block Storage, Floating IP,
+  Load Balancer, NCR, NKS, NCS 작업을 서비스별 참조와 명령 카탈로그로 안내한다.
 ---
 
 # nhncloud-cli
 
-NHN Cloud 서비스를 AWS CLI 방식으로 호출하는 TypeScript CLI다.
-이 파일은 router다.
-작업하려는 서비스에 맞는 reference를 먼저 읽고, 필요한 명령은 `--json`으로 확인한다.
-
-## 먼저 읽을 것
-
-| 상황 | 읽을 reference |
-|------|----------------|
-| 명령 경로, 인수, option metadata 확인 | `nhncloud commands --json` 실행 후 필요한 reference 선택 |
-| 설치, configure, profile, 출력 모드, 에러 코드, 자동화 기본 규칙 | [common.md](references/common.md) |
-| Log & Crash 검색, scroll export, 로그 전송 | [logncrash.md](references/logncrash.md) |
-| Deploy 실행, 배포 조회, 바이너리 업로드/다운로드 | [deploy.md](references/deploy.md) |
-| Compute instance, network, volume, floatingip | [iaas.md](references/iaas.md) |
-| Load Balancer와 IP ACL 그룹·대상 조회·쓰기·재바인딩 복구 | [loadbalancer.md](references/loadbalancer.md) |
-| NCR 레지스트리, 이미지, 태그 조회 | [ncr.md](references/ncr.md) |
-| NKS 클러스터, 노드 그룹, 애드온, kubeconfig | [nks.md](references/nks.md) |
-| NCS template, workload 조회·UTC 시간 필터·생성·변경·실행제어, malware 검사 설정·결과 조회 | [ncs.md](references/ncs.md) |
-| 인증 실패, profile 누락, region mismatch, JSON shape 혼동, scroll 제한 | [troubleshooting.md](references/troubleshooting.md) |
-
-## 공통 우선 규칙
-
-- 구조화 출력이 필요하면 `--json`을 우선 사용한다.
-- 스크립트 체이닝은 해당 명령이 `--quiet` 식별자 출력을 문서화했는지 확인한 뒤 사용한다.
-- profile은 기본값에 의존하지 말고 가능하면 `--profile <name>`을 명시한다.
-- IaaS 계열(`instance`, `network`, `volume`, `floatingip`, `loadbalancer`, `nks`)은 region이 중요하면 `--region <region>`을 명시한다.
-- 삭제, 제거, 비용 발생, 리소스 생성 같은 파괴적/쓰기 명령은 `--yes` 없으면 대화형 confirm이 있을 수 있다.
-- 데이터는 stdout, 진행 상황·운영 경고·에러는 stderr에 출력한다.
-- 비밀값, appkey, tenantId, 실제 instance/network id는 문서나 이슈에 그대로 쓰지 않고 placeholder를 사용한다.
-- Load Balancer IP ACL 쓰기는 `--profile`, `--region`, `--json`을 명시하고, 삭제·연결 교체·대상 변경에는 `--yes`도 명시한다.
-- IP ACL 대상 변경은 기본 재바인딩을 유지한다.
-- 대상 변경의 종료 코드가 1이면 stdout JSON의 `rebind.failed[]`를 확인한다.
-- 복구에는 `retry_argv` 배열을 그대로 사용하고, `retry_command`는 사람 확인용으로만 사용한다.
-- NCS workload logs·events 시간 필터는 시간대 포함 RFC3339, `now`, 0 이상의 정수와 `m`·`h`·`d` 단위를 사용한다.
-- 잘못된 NCS 시간 입력은 종료 코드 3이므로 자격증명 문제로 재시도하지 말고 입력을 수정한다.
-
-## 빠른 시작
-
-```bash
-npm install -g @bifos/nhncloud-cli
-nhncloud configure
-nhncloud logncrash search --query '*' --from 1h --to now --json
-```
-
-## 주요 명령군
-
-| 명령군 | 용도 |
-|--------|------|
-| `configure` | 자격증명 설정 마법사와 비대화형 profile 저장 |
-| `logncrash` | 로그 검색, 대량 export, collector 전송 |
-| `deploy` | NHN Cloud Deploy 실행과 배포/바이너리 조회·전송 |
-| `instance` | Compute 인스턴스, flavor, image, keypair, volume attach 관리 |
-| `network` | VPC와 subnet 조회 |
-| `volume` | Block Storage volume 조회·생성 |
-| `floatingip` | Floating IP 조회·발급·삭제 |
-| `loadbalancer` | Load Balancer와 IP ACL 그룹·대상 조회·쓰기·재바인딩 복구 |
-| `ncr` | Container Registry registry/image/tag 조회 |
-| `nks` | Kubernetes cluster/nodegroup/addon/kubeconfig 관리 |
-| `ncs` | Container Service template/workload 조회·UTC 시간 필터·생성·변경·실행제어, malware 검사 설정·결과 조회 |
-
-## 안전한 탐색 순서
-
-1. [common.md](references/common.md)에서 profile과 출력 모드를 확인한다.
-2. 대상 서비스 reference를 읽는다.
-3. 조회/discovery 명령을 `--json`으로 먼저 실행한다.
-4. 쓰기 명령은 대상 id, region, profile, `--yes`, payload file을 명시한다.
-5. 실패하면 [troubleshooting.md](references/troubleshooting.md)의 exit code와 서비스별 인증 모델을 대조한다.
+## 실행 순서
+
+1. 아래 표에서 대상 서비스의 reference 하나만 먼저 읽는다.
+2. 정확한 경로·인수·옵션이 필요하면 `nhncloud commands --json`에서 해당 명령을 찾는다.
+3. 조회 명령을 `--json`으로 실행해 대상 식별자와 현재 상태를 확인한다.
+4. 쓰기 명령은 대상, `--profile`, 필요한 `--region`을 명시하고, 명령이 지원하면 `--yes`를 API 호출 전에 전달한다.
+5. 결과는 stdout의 구조화 데이터로 판정하고 stderr는 진행 상황과 진단에 사용한다.
+6. 실패하면 [troubleshooting.md](references/troubleshooting.md)에서 종료 코드와 인증 모델을 확인한다.
+
+`--quiet`는 해당 명령이 식별자 출력을 문서화한 경우에만 사용한다.
+명령 문법이나 응답 형태를 추측하지 않는다.
+비밀값과 실제 사용자 리소스 ID는 문서·이슈·보고서에 남기지 않고 placeholder로 바꾼다.
+
+## 참조 라우터
+
+| 작업 | 읽을 파일 |
+|---|---|
+| 설치, `configure`, profile, 출력 모드, 명령 카탈로그, 종료 코드 | [common.md](references/common.md) |
+| Log & Crash Search v3 커서 검색·scroll 대량 추출·collector 전송 | [logncrash.md](references/logncrash.md) |
+| Deploy 실행·조회·바이너리 전송 | [deploy.md](references/deploy.md) |
+| Compute, VPC, Block Storage, Floating IP | [iaas.md](references/iaas.md) |
+| Load Balancer와 IP ACL | [loadbalancer.md](references/loadbalancer.md) |
+| Container Registry | [ncr.md](references/ncr.md) |
+| Kubernetes Service | [nks.md](references/nks.md) |
+| Container Service | [ncs.md](references/ncs.md) |
+| 인증·profile·region·출력·검색 제한 문제 해결 | [troubleshooting.md](references/troubleshooting.md) |

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

@@ -24,18 +24,39 @@ CI나 자동화에서는 flag로 비대화형 저장을 한다.
 ```bash
 nhncloud configure \
   --uak-id <uak-id> --uak-secret <uak-secret> \
-  --logncrash-appkey <appkey> --logncrash-secret <secret> \
+  --logncrash-appkey <appkey> \
   --ncr-appkey <appkey> \
   --no-verify
 ```
 
+Log & Crash Search v3는 서비스 appkey와 profile 공통 UAK를 함께 사용한다.
+CLI가 UAK를 OAuth 토큰으로 교환하므로 별도 logncrash secret은 저장하지 않는다.
+
+```json
+{
+  "version": 1,
+  "profiles": {
+    "default": {
+      "userAccessKey": {
+        "id": "<uak-id>",
+        "secret": "<uak-secret>"
+      },
+      "logncrash": {
+        "appkey": "<appkey>"
+      }
+    }
+  }
+}
+```
+
 주요 옵션:
 
 | 옵션 | 설명 |
 |------|------|
 | `--profile <name>` | 대상 profile. 기본값은 `default` |
 | `--uak-id <id>` / `--uak-secret <secret>` | 공통 User Access Key |
-| `--logncrash-appkey <key>` / `--logncrash-secret <secret>` | Log & Crash 검색 자격증명 |
+| `--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 |
@@ -85,7 +106,7 @@ AI 에이전트는 먼저 `commands --json`으로 실제 command path와 option
 | 명령 | `--json` 출력 shape |
 |------|---------------------|
 | `commands` | `{ commands: [{ path, description, arguments, options, subcommands }] }` |
-| `logncrash search` | `{ totalItems, pageNumber, pageSize, data }` |
+| `logncrash search` | `{ totalItems, pageNumber, pageSize, data, nextCursor? }` |
 | `deploy binary-groups` | `binaryGroups` wrapper를 언랩한 배열 |
 | `deploy binaries` | `{ totalCount, binaries }` |
 | `instance list` | `servers` wrapper를 언랩한 server 배열 |

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

@@ -1,6 +1,10 @@
 # Log & Crash Reference
 
-`logncrash` 명령군은 Log & Crash Search 검색, scroll export, collector 전송을 다룬다.
+`logncrash` 명령군은 Log & Crash Search v3 커서 검색, scroll export, collector 전송을 다룬다.
+
+검색과 export에는 profile의 logncrash appkey와 공통 UAK가 필요하다.
+CLI가 UAK를 OAuth 토큰으로 교환해 Bearer 인증을 적용한다.
+`send`는 별도 collector 계약이므로 Search v3 전환의 영향을 받지 않는다.
 
 ## 검색
 
@@ -25,10 +29,14 @@ nhncloud logncrash search \
 | `--query <lucene>` | 예 | Lucene 질의 문자열. API에 그대로 전달 |
 | `--from <time>` | 예 | 검색 시작. ISO8601 또는 상대시간 |
 | `--to <time>` | 예 | 검색 끝. ISO8601, 상대시간, `now` |
-| `--page <n>` | 아니오 | pageNumber. 기본 0 |
-| `--size <n>` | 아니오 | pageSize. 기본 10, 최대 100 |
+| `--page <n>` | 아니오 | 전환 호환용 pageNumber. 기본 0이며 0만 허용 |
+| `--size <n>` | 아니오 | pageSize. 기본 10, 범위 1~100 |
+| `--cursor <value>` | 아니오 | 직전 JSON 응답의 불투명한 `nextCursor` |
 | `--profile <name>` | 아니오 | 사용할 profile |
 
+CLI는 REAL API 실측 계약에 따라 모든 커서 요청을 `logTime DESC`로 고정 정렬한다.
+사용자 정렬 옵션은 제공하지 않는다.
+
 Lucene 예시:
 
 | 의도 | 쿼리 |
@@ -50,15 +58,28 @@ API 제약:
 
 ## 검색 출력
 
-`--json` 출력은 `{ totalItems, pageNumber, pageSize, data }` 객체다.
+`--json` 출력은 `{ totalItems, pageNumber, pageSize, data, nextCursor? }` 객체다.
+마지막 페이지에는 `nextCursor`가 없을 수 있다.
 
 ```bash
 nhncloud logncrash search \
   --query '*' \
   --from 1h --to now \
   --json | jq '.totalItems'
+
+# 다음 cursor가 있을 때만 순차 조회
+next_cursor="$(nhncloud logncrash search \
+  --query '*' --from 1h --to now --json | jq -r '.nextCursor // empty')"
+if [ -n "$next_cursor" ]; then
+  nhncloud logncrash search \
+    --query '*' --from 1h --to now \
+    --cursor "$next_cursor" --json
+fi
 ```
 
+cursor는 파싱하거나 인코딩을 바꾸지 않고 받은 문자열 그대로 전달한다.
+임의 페이지 이동은 지원하지 않으므로 `--page 1` 이상은 입력 오류다.
+
 전송 직후에는 인덱싱 지연으로 잠시 0건이 나올 수 있다.
 반복 검색이나 넓은 wildcard 검색은 시간 범위를 좁혀 확인한다.
 
@@ -82,16 +103,17 @@ nhncloud logncrash export \
 | `--output <file>` | 필수. 출력 파일 |
 | `--format json` | JSON 배열로 저장. 기본은 JSON Lines |
 | `--force` | 기존 파일 덮어쓰기 |
-| `--size <n>` | scroll pageSize. 10~100 |
+| `--size <n>` | 폐기 예정 호환 옵션. 10~100 검증 후 경고하고 v3 요청에는 미전달 |
 
-scrollKey는 1분 만료다.
-데이터가 많아 다음 호출까지 1분을 넘기면 만료될 수 있다.
-이 경우 검색 범위를 좁히거나 `--size`를 키워 페이지 수를 줄인다.
+scroll 계속 요청이 실패하면 CLI가 원본 오류를 보존한다.
+오류를 확인한 뒤 검색 시간 범위를 좁혀 다시 실행한다.
+`--size`는 v3 scroll의 페이지 크기를 제어하지 않는다.
 
 ## 로그 전송
 
 `logncrash send`는 collector host로 로그 한 건을 전송한다.
-검색과 달리 secret 헤더를 쓰지 않고, body의 `projectName`에 appkey를 넣는다.
+검색의 UAK OAuth Bearer 인증을 재사용하지 않는다.
+인증 헤더 없이 body의 `projectName`에 appkey를 넣는다.
 
 ```bash
 nhncloud logncrash send --body "batch finished" --level INFO
@@ -120,7 +142,7 @@ nhncloud logncrash send --file ./error.log --level ERROR
 
 | 상황 | exit code |
 |------|-----------|
-| appkey 또는 secret 누락 | 4 |
+| 검색 appkey 또는 공통 UAK 누락 | 4 |
 | 인증 실패 | 2 |
 | 시간 범위 초과, 본문 없음, 8MB 초과 | 3 |
 | API 오류 또는 봉투 실패 | 1 |

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

@@ -15,7 +15,7 @@
 
 | 서비스 | 비밀 | 인증 방식 |
 |--------|------|-----------|
-| Log & Crash 검색/export | appkey + secret | `X-LNCS-SECRET` |
+| 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` |
@@ -70,8 +70,17 @@ nhncloud ncr list --json | jq '.[0] | keys'
 
 - `--from`은 최근 90일 이내여야 한다.
 - `--to - --from` 범위는 31일 이하여야 한다.
-- scrollKey는 1분 만료다.
-- export가 중간 실패하면 검색 범위를 좁히거나 `--size`를 키운다.
+- `--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