@bifos/nhncloud-cli 0.1.0 → 0.2.0

package/README.md

@@ -17,17 +17,32 @@ npm install -g @bifos/nhncloud-cli
 nhncloud configure
 ```
 
-- profile → UAK(id/secret) → logncrash appkey/secret 순으로 입력한다.
+- profile → UAK(id/secret) → logncrash appkey/secret → iaas 자격증명 순으로 입력한다.
 - 저장 전 연결 테스트를 자동으로 수행한다 (`--no-verify` 로 생략 가능).
 - CI/자동화는 flag 로 비대화형 설정이 가능하다.
 
 ```bash
+# UAK + logncrash 비대화형 설정
 nhncloud configure \
   --uak-id <id> --uak-secret <secret> \
   --logncrash-appkey <key> --logncrash-secret <secret> \
   --no-verify
+
+# iaas (Compute) 비대화형 설정 — API 비밀번호는 env 권장
+NHNCLOUD_IAAS_PASSWORD=<api-password> nhncloud configure \
+  --iaas-tenant-id <tenant-id> \
+  --iaas-username <iam-username> \
+  --iaas-region kr1 \
+  --no-verify
 ```
 
+> **iaas password 안내**: `--iaas-password` 에 입력하는 값은 NHN Cloud 콘솔 IAM 의 **API 비밀번호**입니다.
+> 로그인 비밀번호와 다릅니다.
+> IAM 사용자 상세 페이지 → "API 비밀번호 설정"에서 별도로 발급하세요.
+>
+> **iaas username 안내**: `--iaas-username` 은 NHN Cloud 계정 이메일 또는 IAM 계정 ID(사번)입니다.
+> tenantId 와 비슷한 "API 사용자 ID"(UUID)가 아닙니다.
+
 저장 경로: `~/.nhncloud/credentials.json` (mode 0600), `~/.nhncloud/config.json`.
 
 profile 해석 우선순위: `--profile` 옵션 > `NHNCLOUD_PROFILE` 환경변수 > `config.defaultProfile` > `"default"`.
@@ -129,11 +144,74 @@ nhncloud logncrash search --query '*' --from 1d --to now --json | jq '.totalItem
 | 3 | 입력 오류 (파라미터·시간 범위) |
 | 4 | 설정 오류 (자격증명 누락) |
 
+### 인스턴스 (Instance)
+
+`~/.nhncloud/credentials.json` 에 `iaas` 블록을 추가하거나 `nhncloud configure` 로 설정한다.
+
+```json
+{
+  "version": 1,
+  "profiles": {
+    "default": {
+      "iaas": {
+        "tenantId": "<tenant-id>",
+        "username": "<iam-username>",
+        "password": "<api-password>",
+        "region": "kr1"
+      }
+    }
+  }
+}
+```
+
+```bash
+# 인스턴스 목록 조회
+nhncloud instance list
+
+# 단일 인스턴스 상태 조회
+nhncloud instance get <instance-id>
+
+# 인스턴스 생성 (즉시 반환, BUILD 상태)
+nhncloud instance create \
+  --name my-server \
+  --flavor <flavor-id> \
+  --image <image-id> \
+  --network <network-uuid>
+
+# 인스턴스 생성 + ACTIVE 대기 (IP 할당까지 폴링)
+nhncloud instance create \
+  --name my-server \
+  --flavor <flavor-id> \
+  --image <image-id> \
+  --network <network-uuid> \
+  --wait
+
+# GPU(g2) 등 boot-from-volume 필수 flavor — --boot-volume-size 지정
+nhncloud instance create \
+  --name gpu-server \
+  --flavor <gpu-flavor-id> \
+  --image <image-id> \
+  --network <network-uuid> \
+  --boot-volume-size 30 \
+  --wait
+
+# --quiet --wait: 첫 IP 한 줄만 stdout (CI 파이프용)
+IP=$(nhncloud instance create --name ci-runner \
+  --flavor <flavor-id> --image <image-id> --network <network-uuid> \
+  --wait --quiet)
+
+# 인스턴스 삭제 (confirm 생략)
+nhncloud instance delete <instance-id> --yes
+```
+
+지원 region: `kr1` / `kr2` / `kr3` / `jp1` (`--region` 으로 override 가능).
+
 ## 개발
 
 ```bash
 pnpm install
 pnpm run build        # tsup 단일 번들 (dist/index.js)
 pnpm tsc --noEmit     # 타입 체크
+node dist/index.js instance --help
 node dist/index.js logncrash search --help
 ```

package/dist/index.js

@@ -24,8 +24,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/index.ts
-var import_commander7 = require("commander");
-var import_chalk2 = __toESM(require("chalk"));
+var import_commander11 = require("commander");
+var import_chalk4 = __toESM(require("chalk"));
 
 // src/utils/spinner.ts
 var import_ora = __toESM(require("ora"));
@@ -191,9 +191,9 @@ nhncloud configure \uB97C \uC2E4\uD589\uD574 UAK id/secret \uC744 \uC124\uC815\u
   return uak;
 }
 async function getServiceCredential(service, profileName) {
-  if (service === "userAccessKey") {
+  if (service === "userAccessKey" || service === "iaas") {
     throw new NhnCloudCliError(
-      "userAccessKey \uB294 \uC11C\uBE44\uC2A4 \uC790\uACA9\uC99D\uBA85\uC774 \uC544\uB2D9\uB2C8\uB2E4 \u2014 getUserAccessKey \uB97C \uC0AC\uC6A9\uD558\uC138\uC694.",
+      `"${service}" \uB294 \uC11C\uBE44\uC2A4 \uC790\uACA9\uC99D\uBA85\uC774 \uC544\uB2D9\uB2C8\uB2E4 \u2014 \uC804\uC6A9 getter \uB97C \uC0AC\uC6A9\uD558\uC138\uC694.`,
       EXIT_PARAM_ERROR
     );
   }
@@ -255,6 +255,38 @@ async function setServiceCredential(profileName, service, cred) {
   creds.profiles[profileName] = { ...profile, [service]: cred };
   await saveCredentials(creds);
 }
+function isIaasCredential(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["tenantId"] === "string" && obj["tenantId"].length > 0 && typeof obj["username"] === "string" && obj["username"].length > 0 && typeof obj["password"] === "string" && obj["password"].length > 0 && typeof obj["region"] === "string" && obj["region"].length > 0;
+}
+async function getIaasCredential(profileName) {
+  const credentials = await loadCredentials();
+  const profile = credentials.profiles[profileName];
+  if (!profile) {
+    throw new NhnCloudCliError(
+      `profile "${profileName}" \uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.
+${CREDENTIALS_PATH} \uC5D0\uC11C profiles.${profileName} \uBE14\uB85D\uC744 \uCD94\uAC00\uD558\uAC70\uB098 nhncloud configure \uB97C \uC2E4\uD589\uD558\uC138\uC694.`,
+      EXIT_CONFIG_ERROR
+    );
+  }
+  const iaas = profile["iaas"];
+  if (!isIaasCredential(iaas)) {
+    throw new NhnCloudCliError(
+      `profile "${profileName}" \uC5D0 iaas \uC790\uACA9\uC99D\uBA85\uC774 \uC5C6\uAC70\uB098 \uBD88\uC644\uC804\uD569\uB2C8\uB2E4.
+nhncloud configure \uB97C \uC2E4\uD589\uD574 tenantId / username / password / region \uC744 \uC124\uC815\uD558\uC138\uC694.
+password \uB294 NHN Cloud \uCF58\uC194 IAM \uC758 API \uBE44\uBC00\uBC88\uD638\uC785\uB2C8\uB2E4 (\uB85C\uADF8\uC778 \uBE44\uBC00\uBC88\uD638\uAC00 \uC544\uB2D9\uB2C8\uB2E4).`,
+      EXIT_CONFIG_ERROR
+    );
+  }
+  return iaas;
+}
+async function setIaasCredential(profileName, iaas) {
+  const creds = await loadCredentialsOrEmpty();
+  const profile = creds.profiles[profileName] ?? {};
+  creds.profiles[profileName] = { ...profile, iaas };
+  await saveCredentials(creds);
+}
 async function getDeployTarget(name) {
   const config = await loadConfig();
   const targets = config?.deploy?.targets;
@@ -279,6 +311,44 @@ var import_node_path2 = require("path");
 var import_node_os2 = require("os");
 var import_node_crypto = require("crypto");
 var CACHE_DIR = (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".nhncloud", "cache");
+function iaasCachePath(profile, region) {
+  return (0, import_node_path2.join)(CACHE_DIR, `iaas-token-${profile}-${region}.json`);
+}
+function isIaasTokenCache(val) {
+  if (typeof val !== "object" || val === null) return false;
+  const obj = val;
+  return typeof obj["tokenId"] === "string" && typeof obj["expiresAt"] === "string" && typeof obj["computeEndpoint"] === "string";
+}
+async function readIaasToken(profile, region) {
+  const filePath = iaasCachePath(profile, region);
+  try {
+    const raw = await (0, import_promises2.readFile)(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!isIaasTokenCache(parsed)) return null;
+    const expiresAt = new Date(parsed.expiresAt).getTime();
+    const BUFFER_MS = 6e4;
+    if (expiresAt - Date.now() < BUFFER_MS) return null;
+    return {
+      tokenId: parsed.tokenId,
+      expiresAt: parsed.expiresAt,
+      computeEndpoint: parsed.computeEndpoint
+    };
+  } catch {
+    return null;
+  }
+}
+async function writeIaasToken(profile, region, data) {
+  const filePath = iaasCachePath(profile, region);
+  await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(filePath), { recursive: true });
+  const cache = {
+    tokenId: data.tokenId,
+    expiresAt: data.expiresAt,
+    computeEndpoint: data.computeEndpoint
+  };
+  const tmp = filePath + "." + (0, import_node_crypto.randomBytes)(4).toString("hex") + ".tmp";
+  await (0, import_promises2.writeFile)(tmp, JSON.stringify(cache, null, 2), { encoding: "utf-8", mode: 384 });
+  await (0, import_promises2.rename)(tmp, filePath);
+}
 function tokenCachePath(profile) {
   return (0, import_node_path2.join)(CACHE_DIR, `deploy-token-${profile}.json`);
 }
@@ -372,7 +442,7 @@ async function getAccessToken(profile, uakId, uakSecret, forceRefresh = false) {
   return raw.access_token;
 }
 
-// src/services/logncrash/client.ts
+// src/api/keystone.ts
 var import_ky3 = __toESM(require("ky"));
 
 // src/api/endpoints.ts
@@ -390,6 +460,78 @@ function endpointFor(service) {
   }
   return endpoint;
 }
+function keystoneIdentityUrl() {
+  return "https://api-identity-infrastructure.nhncloudservice.com/v2.0/tokens";
+}
+var INSTANCE_HOST = {
+  kr1: "kr1-api-instance-infrastructure.nhncloudservice.com",
+  kr2: "kr2-api-instance-infrastructure.nhncloudservice.com",
+  kr3: "kr3-api-instance-infrastructure.nhncloudservice.com",
+  jp1: "jp1-api-instance-infrastructure.nhncloudservice.com"
+};
+function instanceHost(region) {
+  const host = INSTANCE_HOST[region];
+  if (!host) {
+    throw new NhnCloudCliError(
+      `\uC9C0\uC6D0\uD558\uC9C0 \uC54A\uB294 region \uC785\uB2C8\uB2E4: "${region}". \uC0AC\uC6A9 \uAC00\uB2A5\uD55C region: ${Object.keys(INSTANCE_HOST).join(", ")}`,
+      EXIT_PARAM_ERROR
+    );
+  }
+  return host;
+}
+
+// src/api/keystone.ts
+function isKeystoneTokenResponse(val) {
+  if (typeof val !== "object" || val === null) return false;
+  const obj = val;
+  if (typeof obj["access"] !== "object" || obj["access"] === null) return false;
+  const access = obj["access"];
+  if (typeof access["token"] !== "object" || access["token"] === null) return false;
+  const token = access["token"];
+  return typeof token["id"] === "string" && typeof token["expires"] === "string";
+}
+async function getIaasToken(profile, iaas, forceRefresh = false) {
+  if (!forceRefresh) {
+    const cached = await readIaasToken(profile, iaas.region);
+    if (cached !== null) {
+      return { tokenId: cached.tokenId, computeEndpoint: cached.computeEndpoint };
+    }
+  }
+  const host = instanceHost(iaas.region);
+  const computeEndpoint = `https://${host}/v2/${encodeURIComponent(iaas.tenantId)}`;
+  let raw;
+  try {
+    raw = await import_ky3.default.post(keystoneIdentityUrl(), {
+      json: {
+        auth: {
+          tenantId: iaas.tenantId,
+          passwordCredentials: {
+            username: iaas.username,
+            password: iaas.password
+          }
+        }
+      },
+      retry: 0
+    }).json();
+  } catch (err) {
+    throw toNhnCloudCliError(err);
+  }
+  if (!isKeystoneTokenResponse(raw)) {
+    throw new NhnCloudCliError(
+      "Keystone \uC751\uB2F5 \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 access.token.id / expires \uD544\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.",
+      EXIT_API_ERROR
+    );
+  }
+  const tokenId = raw.access.token.id;
+  const expiresAt = raw.access.token.expires;
+  if (!forceRefresh) {
+    await writeIaasToken(profile, iaas.region, { tokenId, expiresAt, computeEndpoint });
+  }
+  return { tokenId, computeEndpoint };
+}
+
+// src/services/logncrash/client.ts
+var import_ky4 = __toESM(require("ky"));
 
 // src/api/envelope.ts
 function unwrap(res) {
@@ -417,7 +559,7 @@ var LogncrashClient = class {
     const endpoint = endpointFor("logncrash");
     const url = `${endpoint}/api/v2/search/${encodeURIComponent(this.appkey)}`;
     try {
-      const res = await import_ky3.default.post(url, {
+      const res = await import_ky4.default.post(url, {
         headers: {
           "X-LNCS-SECRET": this.secret,
           "Content-Type": "application/json"
@@ -449,6 +591,17 @@ async function verifyUserAccessKey(uak) {
     throw err;
   }
 }
+async function verifyIaas(iaas) {
+  try {
+    await getIaasToken("__verify__", iaas, true);
+    return true;
+  } catch (err) {
+    if (err instanceof NhnCloudCliError && err.exitCode === EXIT_AUTH_ERROR) {
+      return false;
+    }
+    throw err;
+  }
+}
 async function verifyLogncrash(cred) {
   if (!cred.appkey || !cred.secret) return false;
   const client = new LogncrashClient(cred.appkey, cred.secret);
@@ -472,7 +625,7 @@ async function verifyLogncrash(cred) {
 }
 
 // src/commands/configure.ts
-async function saveAndVerify(profileName, uak, logncrash, doVerify) {
+async function saveAndVerify(profileName, uak, logncrash, iaas, doVerify) {
   if (doVerify) {
     if (uak) {
       const ok = await verifyUserAccessKey(uak);
@@ -496,6 +649,17 @@ async function saveAndVerify(profileName, uak, logncrash, doVerify) {
         );
       }
     }
+    if (iaas) {
+      const ok = await verifyIaas(iaas);
+      if (ok) {
+        process.stderr.write(import_chalk.default.green("  \u2713 iaas \uC5F0\uACB0 \uC131\uACF5\n"));
+      } else {
+        throw new NhnCloudCliError(
+          "iaas \uC778\uC99D \uC2E4\uD328 \u2014 tenantId / username / API \uBE44\uBC00\uBC88\uD638\uB97C \uD655\uC778\uD558\uC138\uC694.",
+          EXIT_AUTH_ERROR
+        );
+      }
+    }
   }
   if (uak) {
     await setUserAccessKey(profileName, uak);
@@ -503,6 +667,9 @@ async function saveAndVerify(profileName, uak, logncrash, doVerify) {
   if (logncrash) {
     await setServiceCredential(profileName, "logncrash", logncrash);
   }
+  if (iaas) {
+    await setIaasCredential(profileName, iaas);
+  }
   process.stderr.write(import_chalk.default.green(`
 \u2713 profile "${profileName}" \uC124\uC815\uC774 \uC800\uC7A5\uB418\uC5C8\uC2B5\uB2C8\uB2E4.
 `));
@@ -534,12 +701,40 @@ async function runInteractive(opts) {
     const secret = await password({ message: "logncrash secret", mask: "*" });
     logncrash = { appkey, secret };
   }
+  let iaas;
+  const setupIaas = await confirm({
+    message: "iaas (Compute) \uC790\uACA9\uC99D\uBA85\uB3C4 \uC124\uC815\uD558\uC2DC\uACA0\uC2B5\uB2C8\uAE4C?",
+    default: false
+  });
+  if (setupIaas) {
+    process.stderr.write(import_chalk.default.gray("\n\u2014 iaas (Compute) \uC790\uACA9\uC99D\uBA85 \u2014\n"));
+    process.stderr.write(
+      import_chalk.default.yellow(
+        "  \u203B password \uB294 NHN Cloud \uCF58\uC194 IAM \uC758 API \uBE44\uBC00\uBC88\uD638\uC785\uB2C8\uB2E4 (\uB85C\uADF8\uC778 \uBE44\uBC00\uBC88\uD638\uAC00 \uC544\uB2D9\uB2C8\uB2E4).\n"
+      )
+    );
+    const { select } = await import("@inquirer/prompts");
+    const tenantId = await input({ message: "tenantId (\uD504\uB85C\uC81D\uD2B8 ID)" });
+    const iaasUsername = await input({ message: "IAM username" });
+    const iaasPassword = await password({ message: "API \uBE44\uBC00\uBC88\uD638", mask: "*" });
+    const region = await select({
+      message: "region",
+      choices: [
+        { value: "kr1", name: "kr1 (\uD55C\uAD6D \uD310\uAD50)" },
+        { value: "kr2", name: "kr2 (\uD55C\uAD6D \uD3C9\uCD0C)" },
+        { value: "kr3", name: "kr3 (\uD55C\uAD6D \uAD11\uC8FC)" },
+        { value: "jp1", name: "jp1 (\uC77C\uBCF8 \uB3C4\uCFC4)" }
+      ],
+      default: "kr1"
+    });
+    iaas = { tenantId, username: iaasUsername, password: iaasPassword, region };
+  }
   if (opts.verify) {
     process.stderr.write(import_chalk.default.gray("\n\u2014 \uC5F0\uACB0 \uD14C\uC2A4\uD2B8 \uC911\u2026 \u2014\n"));
   }
   if (opts.verify) {
     try {
-      await saveAndVerify(profileName, uak, logncrash, true);
+      await saveAndVerify(profileName, uak, logncrash, iaas, true);
     } catch (err) {
       if (err instanceof NhnCloudCliError && err.exitCode === EXIT_AUTH_ERROR) {
         process.stderr.write(import_chalk.default.red(`  \u2717 ${err.message}
@@ -552,34 +747,44 @@ 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, false);
+        await saveAndVerify(profileName, uak, logncrash, iaas, false);
       } else {
         throw err;
       }
     }
   } else {
-    await saveAndVerify(profileName, uak, logncrash, false);
+    await saveAndVerify(profileName, uak, logncrash, iaas, false);
   }
 }
 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 (!uak && !logncrash) {
+  const iaas = opts.iaasTenantId && opts.iaasUsername && iaasPassword ? {
+    tenantId: opts.iaasTenantId,
+    username: opts.iaasUsername,
+    password: iaasPassword,
+    region: opts.iaasRegion ?? "kr1"
+  } : void 0;
+  if (!uak && !logncrash && !iaas) {
     throw new NhnCloudCliError(
-      "\uBE44\uB300\uD654\uD615 \uBAA8\uB4DC: --uak-id + UAK secret \uB610\uB294 --logncrash-appkey + logncrash secret \uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.\nsecret \uC740 \uB178\uCD9C \uBC29\uC9C0\uB97C \uC704\uD574 \uD658\uACBD\uBCC0\uC218 \uAD8C\uC7A5: NHNCLOUD_UAK_SECRET / NHNCLOUD_LOGNCRASH_SECRET.",
+      "\uBE44\uB300\uD654\uD615 \uBAA8\uB4DC: --uak-id + UAK secret, --logncrash-appkey + logncrash secret,\n\uB610\uB294 --iaas-tenant-id + --iaas-username + iaas password \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.",
       EXIT_PARAM_ERROR
     );
   }
   if (opts.verify) {
     process.stderr.write(import_chalk.default.gray("\uC5F0\uACB0 \uD14C\uC2A4\uD2B8 \uC911\u2026\n"));
   }
-  await saveAndVerify(profileName, uak, logncrash, opts.verify);
+  await saveAndVerify(profileName, uak, logncrash, iaas, opts.verify);
 }
-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("--no-verify", "\uC5F0\uACB0 \uD14C\uC2A4\uD2B8 \uC0DD\uB7B5").action(async (opts) => {
-  const hasFlag = opts.uakId || opts.uakSecret || opts.logncrashAppkey || opts.logncrashSecret;
+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(
+  "--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("--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;
   try {
     if (hasFlag) {
       await runNonInteractive(opts);
@@ -784,7 +989,7 @@ credentials.json \uC5D0 "secret": "<secretkey>" \uB97C \uCD94\uAC00\uD558\uC138\
 var import_commander3 = require("commander");
 
 // src/services/deploy/client.ts
-var import_ky4 = __toESM(require("ky"));
+var import_ky5 = __toESM(require("ky"));
 var SYNC_TIMEOUT_MS = 6e5;
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DeployClient = class {
@@ -818,7 +1023,7 @@ var DeployClient = class {
       payload["targetServerHostnames"] = params.targetHosts;
     }
     try {
-      const res = await import_ky4.default.post(url, {
+      const res = await import_ky5.default.post(url, {
         headers: {
           ...this.authHeaders(),
           "Content-Type": "application/json"
@@ -838,7 +1043,7 @@ var DeployClient = class {
   async artifacts(appKey) {
     const url = `${this.baseUrl}/api/v2.1/projects/${appKey}/artifacts`;
     try {
-      const res = await import_ky4.default.get(url, {
+      const res = await import_ky5.default.get(url, {
         headers: this.authHeaders(),
         retry: 0,
         timeout: DEFAULT_TIMEOUT_MS
@@ -854,7 +1059,7 @@ var DeployClient = class {
   async serverGroups(appKey, artifactId) {
     const url = `${this.baseUrl}/api/v2.1/projects/${appKey}/artifacts/${artifactId}/server-groups`;
     try {
-      const res = await import_ky4.default.get(url, {
+      const res = await import_ky5.default.get(url, {
         headers: this.authHeaders(),
         retry: 0,
         timeout: DEFAULT_TIMEOUT_MS
@@ -870,7 +1075,7 @@ var DeployClient = class {
   async histories(appKey, artifactId) {
     const url = `${this.baseUrl}/api/v2.1/projects/${appKey}/artifacts/${artifactId}/deploy-histories`;
     try {
-      const res = await import_ky4.default.get(url, {
+      const res = await import_ky5.default.get(url, {
         headers: this.authHeaders(),
         retry: 0,
         timeout: DEFAULT_TIMEOUT_MS
@@ -1017,31 +1222,408 @@ var historiesCommand = new import_commander6.Command("histories").description("\
   });
 });
 
+// src/commands/instance/list.ts
+var import_commander7 = require("commander");
+
+// src/services/instance/client.ts
+var import_ky6 = __toESM(require("ky"));
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+var DEFAULT_POLL_INTERVAL_MS = 5e3;
+function isServer(val) {
+  if (typeof val !== "object" || val === null) return false;
+  const obj = val;
+  return typeof obj["id"] === "string" && typeof obj["name"] === "string" && typeof obj["status"] === "string" && typeof obj["addresses"] === "object" && obj["addresses"] !== null;
+}
+function isServerResponse(val) {
+  if (typeof val !== "object" || val === null) return false;
+  const obj = val;
+  return isServer(obj["server"]);
+}
+function isServersResponse(val) {
+  if (typeof val !== "object" || val === null) return false;
+  const obj = val;
+  return Array.isArray(obj["servers"]);
+}
+function isCreateResponse(val) {
+  if (typeof val !== "object" || val === null) return false;
+  const server = val["server"];
+  if (typeof server !== "object" || server === null) return false;
+  return typeof server["id"] === "string";
+}
+function hasIpAddress(server) {
+  return Object.values(server.addresses).some((list) => list.length > 0);
+}
+var InstanceClient = class {
+  tokenId;
+  computeEndpoint;
+  constructor(tokenId, computeEndpoint) {
+    this.tokenId = tokenId;
+    this.computeEndpoint = computeEndpoint;
+  }
+  authHeaders() {
+    return { "X-Auth-Token": this.tokenId };
+  }
+  /**
+   * 인스턴스 목록을 조회한다 (GET /servers/detail).
+   */
+  async list() {
+    const url = `${this.computeEndpoint}/servers/detail`;
+    try {
+      const raw = await import_ky6.default.get(url, {
+        headers: this.authHeaders(),
+        retry: 0,
+        timeout: DEFAULT_TIMEOUT_MS2
+      }).json();
+      if (!isServersResponse(raw)) {
+        throw new NhnCloudCliError(
+          "instance list \uC751\uB2F5 \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 servers \uBC30\uC5F4\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.",
+          EXIT_API_ERROR
+        );
+      }
+      return raw.servers;
+    } catch (err) {
+      throw toNhnCloudCliError(err);
+    }
+  }
+  /**
+   * 단일 인스턴스를 조회한다 (GET /servers/{id}).
+   */
+  async get(id) {
+    const url = `${this.computeEndpoint}/servers/${encodeURIComponent(id)}`;
+    try {
+      const raw = await import_ky6.default.get(url, {
+        headers: this.authHeaders(),
+        retry: 0,
+        timeout: DEFAULT_TIMEOUT_MS2
+      }).json();
+      if (!isServerResponse(raw)) {
+        throw new NhnCloudCliError(
+          `instance get(${id}) \uC751\uB2F5 \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 server \uAC1D\uCCB4\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.`,
+          EXIT_API_ERROR
+        );
+      }
+      return raw.server;
+    } catch (err) {
+      throw toNhnCloudCliError(err);
+    }
+  }
+  /**
+   * 인스턴스를 생성한다 (POST /servers).
+   * NHN 확장 필드(ephemeralDiskSize / protect)는 정의됐을 때만 payload 에 포함한다.
+   */
+  async create(params) {
+    const url = `${this.computeEndpoint}/servers`;
+    const serverBody = {
+      name: params.name,
+      flavorRef: params.flavorRef,
+      networks: params.networks.map((uuid) => ({ uuid }))
+    };
+    if (params.bootVolumeSize !== void 0) {
+      serverBody["block_device_mapping_v2"] = [
+        {
+          boot_index: 0,
+          uuid: params.imageRef,
+          source_type: "image",
+          destination_type: "volume",
+          volume_size: params.bootVolumeSize,
+          delete_on_termination: true
+        }
+      ];
+    } else {
+      serverBody["imageRef"] = params.imageRef;
+    }
+    if (params.keyName !== void 0) {
+      serverBody["key_name"] = params.keyName;
+    }
+    if (params.securityGroups !== void 0) {
+      serverBody["security_groups"] = params.securityGroups.map((name) => ({ name }));
+    }
+    if (params.ephemeralDiskSize !== void 0) {
+      serverBody["NHN-EXT-ATTR:ephemeral_disk_size"] = params.ephemeralDiskSize;
+    }
+    if (params.protect !== void 0) {
+      serverBody["NHN-EXT-ATTR:protect"] = params.protect;
+    }
+    let raw;
+    try {
+      raw = await import_ky6.default.post(url, {
+        headers: this.authHeaders(),
+        json: { server: serverBody },
+        retry: 0,
+        timeout: DEFAULT_TIMEOUT_MS2
+      }).json();
+    } catch (err) {
+      throw toNhnCloudCliError(err);
+    }
+    if (!isCreateResponse(raw)) {
+      throw new NhnCloudCliError(
+        "instance create \uC751\uB2F5\uC5D0 server.id \uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.",
+        EXIT_API_ERROR
+      );
+    }
+    return this.get(raw.server.id);
+  }
+  /**
+   * 인스턴스를 삭제한다 (DELETE /servers/{id}, 204 No Content).
+   */
+  async delete(id) {
+    const url = `${this.computeEndpoint}/servers/${encodeURIComponent(id)}`;
+    try {
+      await import_ky6.default.delete(url, {
+        headers: this.authHeaders(),
+        retry: 0,
+        timeout: DEFAULT_TIMEOUT_MS2
+      });
+    } catch (err) {
+      throw toNhnCloudCliError(err);
+    }
+  }
+  /**
+   * 인스턴스가 ACTIVE 상태 + IP 1개 이상이 될 때까지 폴링한다.
+   *
+   * - status === "ACTIVE" + addresses 에 IP 1개 이상: 즉시 반환
+   * - timeout 초과: 마지막 status 를 포함한 NhnCloudCliError(EXIT_API_ERROR)
+   */
+  async waitForActive(id, opts) {
+    const intervalMs = opts.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const deadline = Date.now() + opts.timeoutMs;
+    let lastServer = null;
+    while (Date.now() < deadline) {
+      const server = await this.get(id);
+      lastServer = server;
+      if (server.status === "ACTIVE" && hasIpAddress(server)) {
+        return server;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remaining)));
+    }
+    const lastStatus = lastServer ? lastServer.status : "unknown";
+    throw new NhnCloudCliError(
+      `\uC778\uC2A4\uD134\uC2A4 ${id} \uAC00 ACTIVE \uAC00 \uB418\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4 (\uB9C8\uC9C0\uB9C9 \uC0C1\uD0DC: ${lastStatus}). --wait \uD0C0\uC784\uC544\uC6C3(${Math.round(opts.timeoutMs / 1e3)}\uCD08) \uCD08\uACFC.`,
+      EXIT_API_ERROR
+    );
+  }
+};
+
+// src/commands/instance/helpers.ts
+async function resolveInstanceClient(opts) {
+  const profileName = await resolveProfileName(opts.profile);
+  const iaas = await getIaasCredential(profileName);
+  const effectiveIaas = opts.region ? { ...iaas, region: opts.region } : iaas;
+  const { tokenId, computeEndpoint } = await getIaasToken(profileName, effectiveIaas);
+  return { client: new InstanceClient(tokenId, computeEndpoint), profileName };
+}
+
+// src/commands/instance/list.ts
+function getIps(server) {
+  return Object.values(server.addresses).flat().map((a) => a.addr).join(", ");
+}
+var listCommand = new import_commander7.Command("list").description("\uC778\uC2A4\uD134\uC2A4 \uBAA9\uB85D\uC744 \uC870\uD68C\uD55C\uB2E4").option("--region <region>", "region override (\uAE30\uBCF8: iaas \uC790\uACA9\uC99D\uBA85\uC758 region)").option("--profile <name>", "\uC0AC\uC6A9\uD560 profile \uC774\uB984").action(async (_opts, cmd) => {
+  const opts = cmd.optsWithGlobals();
+  const { client } = await resolveInstanceClient(opts);
+  startSpinner("\uC778\uC2A4\uD134\uC2A4 \uBAA9\uB85D \uC870\uD68C \uC911...");
+  let servers;
+  try {
+    servers = await client.list();
+  } catch (err) {
+    stopSpinner(false);
+    throw err;
+  }
+  stopSpinner(true);
+  output(opts, {
+    headers: ["id", "name", "status", "IPs", "flavor"],
+    rows: servers.map((s) => [s.id, s.name, s.status, getIps(s), s.flavor.id]),
+    raw: servers,
+    ids: servers.map((s) => s.id)
+  });
+});
+
+// src/commands/instance/get.ts
+var import_commander8 = require("commander");
+function getIps2(server) {
+  return Object.values(server.addresses).flat().map((a) => a.addr).join(", ");
+}
+function getImageId(server) {
+  return typeof server.image === "object" ? server.image.id : "";
+}
+var getCommand = new import_commander8.Command("get").description("\uB2E8\uC77C \uC778\uC2A4\uD134\uC2A4 \uC0C1\uD0DC\uB97C \uC870\uD68C\uD55C\uB2E4").argument("<id>", "\uC778\uC2A4\uD134\uC2A4 ID").option("--region <region>", "region override (\uAE30\uBCF8: iaas \uC790\uACA9\uC99D\uBA85\uC758 region)").option("--profile <name>", "\uC0AC\uC6A9\uD560 profile \uC774\uB984").action(async (id, _opts, cmd) => {
+  const opts = cmd.optsWithGlobals();
+  const { client } = await resolveInstanceClient(opts);
+  startSpinner("\uC778\uC2A4\uD134\uC2A4 \uC870\uD68C \uC911...");
+  let server;
+  try {
+    server = await client.get(id);
+  } catch (err) {
+    stopSpinner(false);
+    throw err;
+  }
+  stopSpinner(true);
+  const rows = [
+    ["id", server.id],
+    ["name", server.name],
+    ["status", server.status],
+    ["IPs", getIps2(server)],
+    ["flavor", server.flavor.id],
+    ["image", getImageId(server)],
+    ["key_name", server.key_name ?? ""],
+    ["created", server.created],
+    ["updated", server.updated]
+  ];
+  output(opts, {
+    headers: ["field", "value"],
+    rows,
+    raw: server,
+    ids: [server.id]
+  });
+});
+
+// src/commands/instance/create.ts
+var import_commander9 = require("commander");
+var import_chalk2 = __toESM(require("chalk"));
+function getFirstIp(server) {
+  for (const list of Object.values(server.addresses)) {
+    for (const addr of list) {
+      return addr.addr;
+    }
+  }
+  return "";
+}
+function getIps3(server) {
+  return Object.values(server.addresses).flat().map((a) => a.addr).join(", ");
+}
+function getImageId2(server) {
+  return typeof server.image === "object" ? server.image.id : "";
+}
+var createCommand = new import_commander9.Command("create").description("\uC778\uC2A4\uD134\uC2A4\uB97C \uC0DD\uC131\uD55C\uB2E4").requiredOption("--name <name>", "\uC778\uC2A4\uD134\uC2A4 \uC774\uB984").requiredOption("--flavor <id>", "flavor ID").requiredOption("--image <id>", "\uC774\uBBF8\uC9C0 ID").requiredOption("--network <uuid>", "\uB124\uD2B8\uC6CC\uD06C UUID (\uC5EC\uB7EC \uAC1C: \uBC18\uBCF5 \uC9C0\uC815)", (v, prev) => [...prev, v], []).option("--boot-volume-size <gb>", "boot-from-volume root \uBCFC\uB968 \uD06C\uAE30 (GB). GPU(g2) \uB4F1 boot-from-volume \uD544\uC218 flavor \uC5D0 \uC9C0\uC815").option("--key-name <name>", "\uD0A4\uD398\uC5B4 \uC774\uB984").option("--security-group <name>", "\uBCF4\uC548 \uADF8\uB8F9 \uC774\uB984 (\uC5EC\uB7EC \uAC1C: \uBC18\uBCF5 \uC9C0\uC815)", (v, prev) => [...prev, v], []).option("--ephemeral-disk-size <gb>", "\uC784\uC2DC \uB514\uC2A4\uD06C \uD06C\uAE30 (GB, NHN \uD655\uC7A5)").option("--protect", "\uC0AD\uC81C \uBC29\uC9C0 \uC124\uC815 (NHN \uD655\uC7A5)").option("--wait", "ACTIVE \uC0C1\uD0DC\uAC00 \uB420 \uB54C\uAE4C\uC9C0 \uB300\uAE30").option("--timeout <sec>", "wait \uD0C0\uC784\uC544\uC6C3 (\uCD08, \uAE30\uBCF8 300)", "300").option("--region <region>", "region override (\uAE30\uBCF8: iaas \uC790\uACA9\uC99D\uBA85\uC758 region)").option("--profile <name>", "\uC0AC\uC6A9\uD560 profile \uC774\uB984").action(async (_opts, cmd) => {
+  const opts = cmd.optsWithGlobals();
+  const networks = opts.network ?? [];
+  if (networks.length === 0) {
+    throw new NhnCloudCliError("--network \uB294 \uCD5C\uC18C 1\uAC1C \uD544\uC694\uD569\uB2C8\uB2E4.", EXIT_PARAM_ERROR);
+  }
+  const timeoutMs = parseInt(opts.timeout ?? "300", 10) * 1e3;
+  const { client } = await resolveInstanceClient(opts);
+  startSpinner("\uC778\uC2A4\uD134\uC2A4 \uC0DD\uC131 \uC911...");
+  let server;
+  try {
+    server = await client.create({
+      name: opts.name,
+      flavorRef: opts.flavor,
+      imageRef: opts.image,
+      networks,
+      bootVolumeSize: opts.bootVolumeSize !== void 0 ? parseInt(opts.bootVolumeSize, 10) : void 0,
+      keyName: opts.keyName,
+      securityGroups: opts.securityGroup && opts.securityGroup.length > 0 ? opts.securityGroup : void 0,
+      ephemeralDiskSize: opts.ephemeralDiskSize !== void 0 ? parseInt(opts.ephemeralDiskSize, 10) : void 0,
+      protect: opts.protect
+    });
+  } catch (err) {
+    stopSpinner(false);
+    throw err;
+  }
+  stopSpinner(true);
+  if (opts.wait) {
+    startSpinner(`ACTIVE \uB300\uAE30 \uC911... (id: ${server.id})`);
+    try {
+      server = await client.waitForActive(server.id, { timeoutMs });
+    } catch (err) {
+      stopSpinner(false);
+      throw err;
+    }
+    stopSpinner(true, `ACTIVE \uD655\uC778 (id: ${server.id})`);
+  }
+  if (opts.quiet && opts.wait) {
+    const ip = getFirstIp(server);
+    if (ip) process.stdout.write(ip + "\n");
+    return;
+  }
+  if (opts.wait) {
+    process.stderr.write(import_chalk2.default.green(`  IP: ${getIps3(server)}
+`));
+  }
+  const rows = [
+    ["id", server.id],
+    ["name", server.name],
+    ["status", server.status],
+    ["IPs", getIps3(server)],
+    ["flavor", server.flavor.id],
+    ["image", getImageId2(server)]
+  ];
+  output(opts, {
+    headers: ["field", "value"],
+    rows,
+    raw: server,
+    ids: [server.id]
+  });
+});
+
+// src/commands/instance/delete.ts
+var import_commander10 = require("commander");
+var import_chalk3 = __toESM(require("chalk"));
+var deleteCommand = new import_commander10.Command("delete").description("\uC778\uC2A4\uD134\uC2A4\uB97C \uC0AD\uC81C\uD55C\uB2E4").argument("<id>", "\uC778\uC2A4\uD134\uC2A4 ID").option("--yes", "\uD655\uC778 \uD504\uB86C\uD504\uD2B8 \uC0DD\uB7B5 (CI/\uBE44\uB300\uD654\uD615 \uD544\uC218)").option("--region <region>", "region override (\uAE30\uBCF8: iaas \uC790\uACA9\uC99D\uBA85\uC758 region)").option("--profile <name>", "\uC0AC\uC6A9\uD560 profile \uC774\uB984").action(async (id, _opts, cmd) => {
+  const opts = cmd.optsWithGlobals();
+  const isTTY = process.stdin.isTTY;
+  if (!isTTY && !opts.yes) {
+    throw new NhnCloudCliError(
+      "\uBE44\uB300\uD654\uD615 \uD658\uACBD\uC5D0\uC11C \uC778\uC2A4\uD134\uC2A4 \uC0AD\uC81C\uB294 --yes \uD50C\uB798\uADF8\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+      EXIT_PARAM_ERROR
+    );
+  }
+  if (isTTY && !opts.yes) {
+    const { confirm } = await import("@inquirer/prompts");
+    const ok = await confirm({
+      message: `\uC778\uC2A4\uD134\uC2A4 "${id}" \uB97C \uC0AD\uC81C\uD558\uC2DC\uACA0\uC2B5\uB2C8\uAE4C?`,
+      default: false
+    });
+    if (!ok) {
+      process.stderr.write(import_chalk3.default.yellow("\uC0AD\uC81C\uAC00 \uCDE8\uC18C\uB418\uC5C8\uC2B5\uB2C8\uB2E4.\n"));
+      return;
+    }
+  }
+  const { client } = await resolveInstanceClient(opts);
+  startSpinner(`\uC778\uC2A4\uD134\uC2A4 \uC0AD\uC81C \uC911... (id: ${id})`);
+  try {
+    await client.delete(id);
+  } catch (err) {
+    stopSpinner(false);
+    throw err;
+  }
+  stopSpinner(true);
+  process.stderr.write(import_chalk3.default.green(`\u2713 \uC778\uC2A4\uD134\uC2A4 "${id}" \uAC00 \uC0AD\uC81C\uB418\uC5C8\uC2B5\uB2C8\uB2E4.
+`));
+});
+
 // src/index.ts
-var program = new import_commander7.Command();
-program.name("nhncloud").description("NHN Cloud CLI \u2014 AI agent & terminal friendly").version("0.1.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");
+var program = new import_commander11.Command();
+program.name("nhncloud").description("NHN Cloud CLI \u2014 AI agent & terminal friendly").version("0.2.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");
 program.hook("preAction", () => {
   const opts = program.opts();
   if (!opts.color || process.env["NO_COLOR"]) {
-    import_chalk2.default.level = 0;
+    import_chalk4.default.level = 0;
   }
   if (opts.json || opts.quiet) {
     setQuiet(true);
   }
 });
 program.addCommand(configureCommand);
-var logncrashCommand = new import_commander7.Command("logncrash").description("Log & Crash \uAD00\uB828 \uBA85\uB839");
+var logncrashCommand = new import_commander11.Command("logncrash").description("Log & Crash \uAD00\uB828 \uBA85\uB839");
 logncrashCommand.addCommand(searchCommand);
 program.addCommand(logncrashCommand);
-var deployCommand = new import_commander7.Command("deploy").description("NHN Cloud Deploy \uAD00\uB828 \uBA85\uB839");
+var deployCommand = new import_commander11.Command("deploy").description("NHN Cloud Deploy \uAD00\uB828 \uBA85\uB839");
 deployCommand.addCommand(runCommand);
 deployCommand.addCommand(artifactsCommand);
 deployCommand.addCommand(serverGroupsCommand);
 deployCommand.addCommand(historiesCommand);
 program.addCommand(deployCommand);
+var instanceCommand = new import_commander11.Command("instance").description("Compute \uC778\uC2A4\uD134\uC2A4 \uAD00\uB828 \uBA85\uB839");
+instanceCommand.addCommand(listCommand);
+instanceCommand.addCommand(getCommand);
+instanceCommand.addCommand(createCommand);
+instanceCommand.addCommand(deleteCommand);
+program.addCommand(instanceCommand);
 program.parseAsync().catch((err) => {
   const message = err instanceof Error ? err.message : String(err);
   const exitCode = err instanceof NhnCloudCliError ? err.exitCode : 1;
-  process.stderr.write(import_chalk2.default.red(`\uC624\uB958: ${message}`) + "\n");
+  process.stderr.write(import_chalk4.default.red(`\uC624\uB958: ${message}`) + "\n");
   process.exit(exitCode);
 });

package/package.json

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

package/skills/nhncloud-cli/SKILL.md

@@ -250,3 +250,120 @@ nhncloud deploy histories my-service --json | jq '.[0] | {deployKey, deployStatu
 | UAK 누락 / config target 없음 | 4 (CONFIG_ERROR) 또는 3 (PARAM_ERROR) |
 | OAuth 인증 실패 (401/403) | 2 (AUTH_ERROR) |
 | Deploy API 오류 / 봉투 실패 | 1 (API_ERROR) |
+
+---
+
+## instance — Compute 인스턴스 발급·조회·삭제
+
+`instance` 명령군은 OpenStack Nova v2 호환 Compute API 를 호출한다.
+Keystone v2 토큰 인증을 사용하며 토큰은 만료 전까지 region 별로 캐시한다.
+
+### instance 설정
+
+`nhncloud configure` 대화형 마법사에서 "iaas 자격증명도 설정하시겠습니까?" 에 응답하거나,
+flag 로 직접 입력한다.
+
+```bash
+# 대화형 (권장)
+nhncloud configure
+
+# 비대화형 — API 비밀번호는 env 로 전달 (cmdline 노출 방지)
+NHNCLOUD_IAAS_PASSWORD=<api-password> nhncloud configure \
+  --iaas-tenant-id <tenant-id> \
+  --iaas-username <iam-username> \
+  --iaas-region kr1 \
+  --no-verify
+```
+
+> **주의 (password)**: `--iaas-password` 에 입력하는 값은 NHN Cloud 콘솔 IAM 의 **API 비밀번호**입니다.
+> NHN Cloud 로그인 비밀번호와 다릅니다.
+> IAM 사용자 상세 페이지 → "API 비밀번호 설정"에서 별도로 발급합니다.
+>
+> **주의 (username)**: `--iaas-username` 은 NHN Cloud 계정 이메일 **또는 IAM 계정 ID(사번)** 입니다.
+> tenantId 와 비슷한 32자리 hex "API 사용자 ID"(UUID)가 아닙니다 — 잘못 넣으면 `Could not find user` 인증 실패가 납니다.
+
+저장 위치: `~/.nhncloud/credentials.json` 의 `profiles.<profile>.iaas` 블록.
+
+```json
+{
+  "version": 1,
+  "profiles": {
+    "default": {
+      "iaas": {
+        "tenantId": "<tenant-id>",
+        "username": "<iam-username>",
+        "password": "<api-password>",
+        "region": "kr1"
+      }
+    }
+  }
+}
+```
+
+### 의도 → 커맨드 매핑
+
+| 의도 | 커맨드 |
+|------|--------|
+| 인스턴스 목록 조회 | `nhncloud instance list` |
+| 특정 인스턴스 상태 조회 | `nhncloud instance get <id>` |
+| 인스턴스 생성 (즉시 반환) | `nhncloud instance create --name <name> --flavor <id> --image <id> --network <uuid>` |
+| 인스턴스 생성 + ACTIVE 대기 | `nhncloud instance create ... --wait` |
+| GPU 인스턴스 생성 | `nhncloud instance create --flavor <gpu-flavor-id> --boot-volume-size <gb> ...` (GPU 는 boot-from-volume 필수) |
+| 인스턴스 삭제 (confirm 없이) | `nhncloud instance delete <id> --yes` |
+| 다른 region 사용 | `nhncloud instance list --region kr2` |
+| 다른 profile 사용 | `nhncloud instance list --profile staging` |
+
+### instance create 옵션
+
+| 옵션 | 필수 | 설명 |
+|------|:---:|------|
+| `--name <name>` | 예 | 인스턴스 이름 |
+| `--flavor <id>` | 예 | flavor ID (CPU/메모리 사양. GPU 발급 시 GPU flavor ID 지정) |
+| `--image <id>` | 예 | 이미지 ID |
+| `--network <uuid>` | 예 | 네트워크 UUID (반복 지정으로 여러 개 가능) |
+| `--boot-volume-size <gb>` | 조건부 | boot-from-volume root 볼륨 크기(GB). **GPU(g2) 등 일부 flavor 는 필수** (없으면 `Missing Block Device Mapping` 발급 실패). 미지정 시 로컬 디스크 부팅 |
+| `--key-name <name>` | 아니오 | 키페어 이름 |
+| `--security-group <name>` | 아니오 | 보안 그룹 이름 (반복 지정) |
+| `--ephemeral-disk-size <gb>` | 아니오 | 임시 디스크 크기(GB, NHN 확장) |
+| `--protect` | 아니오 | 삭제 방지 설정 (NHN 확장) |
+| `--wait` | 아니오 | ACTIVE 상태 + IP 할당까지 대기 |
+| `--timeout <sec>` | 아니오 | wait 타임아웃 (초, 기본 300) |
+| `--region <region>` | 아니오 | region override (kr1/kr2/kr3/jp1) |
+| `--profile <name>` | 아니오 | 사용할 profile 이름 |
+
+### 체이닝 예시
+
+```bash
+# 1. 인스턴스 생성 후 ACTIVE + IP 대기 → IP 추출 → SSH 접속
+IP=$(nhncloud instance create \
+  --name ci-runner \
+  --flavor <flavor-id> \
+  --image <image-id> \
+  --network <network-uuid> \
+  --wait --quiet)
+ssh ubuntu@"$IP" "echo ready"
+
+# 2. --wait --json 으로 전체 필드 취득 후 jq 로 IP 파싱
+nhncloud instance create \
+  --name ci-runner \
+  --flavor <flavor-id> \
+  --image <image-id> \
+  --network <network-uuid> \
+  --wait --json | jq -r '.addresses | to_entries[0].value[0].addr'
+
+# 3. 사용 후 삭제 (ephemeral CI 패턴)
+nhncloud instance delete "$INSTANCE_ID" --yes
+
+# 4. 목록에서 id 만 추출
+nhncloud instance list --quiet
+```
+
+### instance 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| iaas 자격증명 누락·불완전 | 4 (CONFIG_ERROR) |
+| Keystone 인증 실패 (401/403) | 2 (AUTH_ERROR) |
+| 미등록 region / 필수 옵션 누락 | 3 (PARAM_ERROR) |
+| API 오류 / waitForActive 타임아웃 | 1 (API_ERROR) |
+| 비대화형 delete 에서 --yes 미지정 | 3 (PARAM_ERROR) |