@ornncompute/cli 0.1.3 → 0.1.4

package/src/cli.mjs

@@ -8,6 +8,7 @@ import {
   CliApiError,
   cliRequest,
   computeEndpoint,
+  operatorRequest,
 } from "./api-client.mjs";
 import { clearAuthSession, getAuthConfigPath, loadAuthSession, saveAuthSession } from "./auth-store.mjs";
 import {
@@ -17,6 +18,7 @@ import {
   startDeviceFlow,
   waitForDeviceApproval,
 } from "./device-auth.mjs";
+import { maybeNotifyUpdate, updateCommand } from "./update.mjs";
 
 const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 const DEFAULT_BUY_NOW_USD_PER_GPU_HOUR = 10;
@@ -58,6 +60,14 @@ Examples:
   ornn clusters create <reservation-id> --type kubernetes --wait
   ornn networks list
   ornn storage volumes list
+  ornn storage deploy <drive-id> --reservation <reservation-id>
+  ornn storage deploy status --reservation <reservation-id>
+  ornn storage filesystem deploy --reservation <reservation-id>
+  ornn storage filesystem delete --reservation <reservation-id>
+  ornn storage buckets connect gcs --bucket <bucket>
+  ornn storage buckets connect s3 --bucket <bucket> [--access-key-id <id> --secret-access-key-file <path>]
+  ornn storage buckets connect r2 --bucket <bucket> --account-id <id> [--access-key-id <id> --secret-access-key-file <path>]
+  ornn storage buckets verify <drive-id>
   ornn ssh <machine-id>
 
 Run \`ornn --help\` for all commands, or \`ornn help <command>\`.
@@ -68,6 +78,7 @@ const HELP = `Ornn CLI
 Usage:
   ornn help [command]
   ornn login [--auth-base <url>] [--no-browser] [--timeout <seconds>]
+  ornn update
   ornn whoami [--json]
   ornn status [--json]
   ornn listings list [--gpu-type <type>] [--facility <name>] [--operator <name>] [--json]
@@ -92,6 +103,10 @@ Usage:
   ornn nodes ssh-command <node-or-reservation-id> [--json]
   ornn nodes keys attach <node-id> --key <path|id|label> [--json]
   ornn nodes keys list <node-id> [--json]
+  ornn node health <node-id> [--json]
+  ornn node diagnose <node-id> [--json]
+  ornn node drain <node-id> [--reason <text>] [--json]
+  ornn node restore <node-id> [--reason <text>] [--json]
   ornn ssh <node-or-reservation-id> [--print] [--identity-file <path>] [--user <name>] [--json]
   ornn metrics nodes [--json]
   ornn metrics node <node-id> [--json]
@@ -124,6 +139,17 @@ Usage:
   ornn storage volumes refresh <drive-id> [--json]
   ornn storage volumes clear <drive-id> [--json]
   ornn storage volumes delete <drive-id> [--json]
+  ornn storage deploy <drive-id> --reservation <reservation-id> [--mount-path <path>] [--read-only|--read-write] [--json]
+  ornn storage deploy status --reservation <reservation-id> [--json]
+  ornn storage filesystem deploy --reservation <reservation-id> [--performance-tier <tier>] [--capacity-gib <gib>] [--json]
+  ornn storage filesystem status --reservation <reservation-id> [--json]
+  ornn storage filesystem delete --reservation <reservation-id> [--json]
+  ornn storage buckets list [--json]
+  ornn storage buckets show <drive-id> [--json]
+  ornn storage buckets connect gcs|s3|r2 --bucket <bucket>|--url <url> [--name <name>] [--prefix <prefix>] [--region <region>] [--account-id <id>|--endpoint-url <url>] [--access-key-id <id> --secret-access-key-file <path>] [--read-only|--read-write] [--verify] [--json]
+  ornn storage buckets update-credentials <drive-id> --access-key-id <id> --secret-access-key-file <path> [--json]
+  ornn storage buckets verify <drive-id> [--json]
+  ornn storage buckets disconnect <drive-id> [--json]
   ornn keys list [--json]
   ornn keys add [<public-key-file>] [--public-key <key>] [--label <label>] [--json]
   ornn keys delete <key-id> [--json]
@@ -151,10 +177,17 @@ Aliases:
   exchange = bid
   gpus = reservations
 
+Operator commands:
+  The \`ornn node\` commands are for Ornn operators/reviewers. They wrap the
+  internal-reviewer-gated compute endpoints directly and require
+  ORNN_COMPUTE_BASE_URL and ORNN_INTERNAL_REVIEW_SECRET (see Environment).
+
 Environment:
-  ORNN_AUTH_BASE_URL  Web/auth server origin. Defaults to http://localhost:3000.
-  ORNN_API_BASE_URL   Optional web API origin. Defaults to ORNN_AUTH_BASE_URL.
-  ORNN_CONFIG_HOME    Directory for CLI auth state. Defaults to ~/.config/ornn.
+  ORNN_AUTH_BASE_URL         Web/auth server origin. Defaults to http://localhost:3000.
+  ORNN_API_BASE_URL          Optional web API origin. Defaults to ORNN_AUTH_BASE_URL.
+  ORNN_CONFIG_HOME           Directory for CLI auth state. Defaults to ~/.config/ornn.
+  ORNN_COMPUTE_BASE_URL      Internal compute service origin for \`ornn node\` operator commands.
+  ORNN_INTERNAL_REVIEW_SECRET  Reviewer secret for \`ornn node\` operator commands.
 
 Output:
   Commands print human-readable output by default.
@@ -185,20 +218,37 @@ const HELP_TOPICS = new Set([
   "metrics",
   "network",
   "networks",
+  "node",
   "nodes",
   "reservations",
   "ssh",
   "ssh-keys",
   "status",
   "storage",
+  "update",
   "whoami",
 ]);
 
+const NODE_OP_SUBCOMMANDS = new Set(["health", "diagnose", "drain", "restore"]);
 const LISTINGS_COMMANDS = new Set(["availability", "listing", "listings"]);
 const EXCHANGE_COMMANDS = new Set(["bid", "bids", "exchange"]);
 const GPU_COMMANDS = new Set(["gpu", "gpus", "reservations"]);
 
 export async function run(argv = [], io = {}) {
+  const exitCode = await dispatch(argv, io);
+  if (argv[0] !== "update") {
+    await maybeNotifyUpdate({
+      binPath: io.binPath ?? process.argv[1],
+      currentVersion: VERSION,
+      env: io.env ?? process.env,
+      fetchImpl: io.fetch ?? fetch,
+      stderr: io.stderr ?? process.stderr,
+    });
+  }
+  return exitCode;
+}
+
+async function dispatch(argv = [], io = {}) {
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;
   const env = io.env ?? process.env;
@@ -244,6 +294,19 @@ export async function run(argv = [], io = {}) {
       return await login(args, { env, fetchImpl, openBrowserImpl, stderr, stdout });
     }
 
+    if (command === "update") {
+      parseCommandOptions(args, {}, "Usage: ornn update");
+      return await updateCommand({
+        binPath: io.binPath ?? process.argv[1],
+        currentVersion: VERSION,
+        env,
+        fetchImpl,
+        spawnProcess,
+        stderr,
+        stdout,
+      });
+    }
+
     if (command === "whoami" || command === "account") {
       return await whoami(args, { env, fetchImpl, stderr, stdout });
     }
@@ -272,6 +335,10 @@ export async function run(argv = [], io = {}) {
       return await reservations(args, { commandName: command, env, fetchImpl, openBrowserImpl, stdout });
     }
 
+    if (command === "node") {
+      return await nodeOps(args, { env, fetchImpl, stdout });
+    }
+
     if (command === "nodes") {
       return await nodes(args, { env, fetchImpl, openBrowserImpl, spawnProcess, stdout });
     }
@@ -354,6 +421,10 @@ function validateHelpInvocation(command, args) {
     return validateNoPositionals(args, "Usage: ornn logout");
   }
 
+  if (command === "update") {
+    return validateNoPositionals(args, "Usage: ornn update");
+  }
+
   if (command === "whoami" || command === "account") {
     return validateNoPositionals(args, "Usage: ornn whoami [--json]", { booleanOptions: ["--json"] });
   }
@@ -433,6 +504,18 @@ function validateHelpInvocation(command, args) {
     return `Usage: ornn ${usageCommand} list|show|checkout`;
   }
 
+  if (command === "node") {
+    const parsed = parseHelpArgs(args, { booleanOptions: ["--json"], valueOptions: ["--reason"] });
+    if (parsed.error) {
+      return parsed.error;
+    }
+    const [subcommand, , ...extra] = parsed.positionals;
+    if (!subcommand || !NODE_OP_SUBCOMMANDS.has(subcommand)) {
+      return "Usage: ornn node health|diagnose|drain|restore <node-id>";
+    }
+    return extra.length ? nodeOpUsage(subcommand) : null;
+  }
+
   if (command === "nodes") {
     const parsed = parseHelpArgs(args, {
       booleanOptions: ["--json", "--no-open", "--open", "--wait"],
@@ -587,8 +670,8 @@ function validateHelpInvocation(command, args) {
 
   if (command === "storage") {
     const parsed = parseHelpArgs(args, {
-      booleanOptions: ["--json"],
-      valueOptions: ["--name", "--source", "--source-drive-id"],
+      booleanOptions: ["--json", "--read-only", "--read-write", "--verify"],
+      valueOptions: ["--access-key-id", "--account-id", "--bucket", "--endpoint-url", "--mount-path", "--name", "--prefix", "--region", "--reservation", "--reservation-id", "--secret-access-key", "--secret-access-key-file", "--source", "--source-drive-id", "--url"],
     });
     if (parsed.error) {
       return parsed.error;
@@ -597,8 +680,38 @@ function validateHelpInvocation(command, args) {
     if (!resource) {
       return null;
     }
+    if (resource === "deploy") {
+      return !subcommand || id || extra.length
+        ? "Usage: ornn storage deploy <drive-id> --reservation <reservation-id> [--mount-path <path>] [--read-only|--read-write] [--json]"
+        : null;
+    }
+    if (resource === "buckets") {
+      if (!subcommand || subcommand === "list") {
+        return id || extra.length ? "Usage: ornn storage buckets list [--json]" : null;
+      }
+      if (subcommand === "show") {
+        return !id || extra.length ? "Usage: ornn storage buckets show <drive-id> [--json]" : null;
+      }
+      if (subcommand === "connect") {
+        return !["gcs", "s3", "r2"].includes(id) || extra.length
+          ? "Usage: ornn storage buckets connect gcs|s3|r2 --bucket <bucket>|--url <url> [--name <name>] [--prefix <prefix>] [--region <region>] [--account-id <id>|--endpoint-url <url>] [--access-key-id <id> --secret-access-key-file <path>] [--read-only|--read-write] [--verify] [--json]"
+          : null;
+      }
+      if (subcommand === "verify") {
+        return !id || extra.length ? "Usage: ornn storage buckets verify <drive-id> [--json]" : null;
+      }
+      if (subcommand === "update-credentials") {
+        return !id || extra.length
+          ? "Usage: ornn storage buckets update-credentials <drive-id> --access-key-id <id> --secret-access-key-file <path> [--json]"
+          : null;
+      }
+      if (subcommand === "disconnect") {
+        return !id || extra.length ? "Usage: ornn storage buckets disconnect <drive-id> [--json]" : null;
+      }
+      return "Usage: ornn storage buckets list|show|connect|verify|update-credentials|disconnect";
+    }
     if (!["drives", "volumes"].includes(resource)) {
-      return "Usage: ornn storage volumes list|show|create|refresh|clear|delete";
+      return "Usage: ornn storage volumes list|show|create|refresh|clear|delete; ornn storage buckets connect gcs|s3|r2 --bucket <bucket>";
     }
     if (!subcommand || subcommand === "list") {
       return id || extra.length ? "Usage: ornn storage volumes list [--json]" : null;
@@ -1157,6 +1270,116 @@ async function reservations(args, context) {
   throw new Error(commandUsage);
 }
 
+// Operator-only surface (`ornn node`); distinct from tenant `ornn nodes`.
+async function nodeOps(args, context) {
+  const usage = "Usage: ornn node health|diagnose|drain|restore <node-id>";
+  const [subcommand, id, ...rest] = args;
+  if (!subcommand || !NODE_OP_SUBCOMMANDS.has(subcommand)) {
+    throw new Error(usage);
+  }
+  if (!id) {
+    throw new Error(nodeOpUsage(subcommand));
+  }
+
+  if (subcommand === "health") {
+    const options = parseCommandOptions(rest, { boolean: ["json"] }, nodeOpUsage(subcommand));
+    const node = await operatorRequest({
+      endpoint: `/provisioning/nodes/${encodeURIComponent(id)}`,
+      env: context.env,
+      fetchImpl: context.fetchImpl,
+    });
+    if (options.json) {
+      writeJson(context.stdout, redactNodeSecrets(node));
+    } else {
+      writeNodeHealth(context.stdout, node);
+    }
+    return 0;
+  }
+
+  if (subcommand === "diagnose") {
+    const options = parseCommandOptions(rest, { boolean: ["json"] }, nodeOpUsage(subcommand));
+    // source.mode tags the validation run as CLI-originated for compute audit.
+    const packet = await operatorRequest({
+      body: { source: { mode: "cli" } },
+      endpoint: `/provisioning/nodes/${encodeURIComponent(id)}/tests`,
+      env: context.env,
+      fetchImpl: context.fetchImpl,
+      method: "POST",
+    });
+    if (options.json) {
+      writeJson(context.stdout, packet);
+    } else {
+      context.stdout.write(`Node validation test run queued for node ${id}.\n`);
+      writeOptionalStatusLine(context.stdout, "Packet", packet?.packet_id ?? packet?.id);
+      writeOptionalStatusLine(context.stdout, "Request", packet?.request_id);
+    }
+    return 0;
+  }
+
+  // drain / restore share POST body + reason handling.
+  const options = parseCommandOptions(
+    rest,
+    { boolean: ["json"], value: ["reason"] },
+    nodeOpUsage(subcommand),
+  );
+  const reason = optionalStringOption(options.reason);
+  const node = await operatorRequest({
+    body: reason ? { reason } : {},
+    endpoint: `/provisioning/nodes/${encodeURIComponent(id)}/${subcommand}`,
+    env: context.env,
+    fetchImpl: context.fetchImpl,
+    method: "POST",
+  });
+  if (options.json) {
+    writeJson(context.stdout, redactNodeSecrets(node));
+  } else {
+    context.stdout.write(`Node ${subcommand} requested: ${node?.id ?? id}\n`);
+    writeNodeHealth(context.stdout, node);
+  }
+  return 0;
+}
+
+function nodeOpUsage(subcommand) {
+  if (subcommand === "drain" || subcommand === "restore") {
+    return `Usage: ornn node ${subcommand} <node-id> [--reason <text>] [--json]`;
+  }
+  return `Usage: ornn node ${subcommand} <node-id> [--json]`;
+}
+
+function writeNodeHealth(stdout, node) {
+  stdout.write(`${node?.id ?? "unknown"}\n`);
+  stdout.write(`Status: ${node?.status || "unknown"}\n`);
+
+  const readiness = node?.health_readiness;
+  const reasons = Array.isArray(readiness?.reasons) ? readiness.reasons : [];
+  const readyLabel = readiness?.ready ? "ready" : readiness?.status || "blocked";
+  stdout.write(`Launch readiness: ${readyLabel}\n`);
+  // Compute encodes passive faults as `passive_fault:<name>` in readiness.reasons.
+  const blockers = reasons.filter((reason) => !String(reason).startsWith("passive_fault:"));
+  if (blockers.length) {
+    stdout.write("Blockers:\n");
+    for (const reason of blockers) {
+      stdout.write(`    - ${reason}\n`);
+    }
+  }
+
+  const passiveFaults = reasons
+    .filter((reason) => String(reason).startsWith("passive_fault:"))
+    .map((reason) => String(reason).slice("passive_fault:".length));
+  if (passiveFaults.length) {
+    stdout.write("Passive faults:\n");
+    for (const fault of passiveFaults) {
+      stdout.write(`    - ${fault}\n`);
+    }
+  } else {
+    stdout.write("Passive faults: none\n");
+  }
+
+  stdout.write(`Validation: ${node?.validation_status || "unknown"}\n`);
+  writeOptionalStatusLine(stdout, "Validation checked", node?.validation_checked_at);
+  writeOptionalStatusLine(stdout, "Last heartbeat", node?.last_heartbeat_at);
+}
+
 async function nodes(args, context) {
   const [subcommand = "list", id, nested, ...rest] = args;
 
@@ -1837,9 +2060,346 @@ async function networks(args, context) {
 }
 
 async function storage(args, context) {
-  const [resource = "volumes", subcommand = "list", id, ...rest] = args;
+  const [resource = "volumes", rawSubcommand, id, ...rest] = args;
+  const subcommand =
+    rawSubcommand ?? (resource === "buckets" || ["drives", "volumes"].includes(resource) ? "list" : undefined);
+  if (resource === "filesystem" || resource === "fileshare") {
+    if (subcommand === "deploy") {
+      const options = parseCommandOptions(
+        [id, ...rest].filter(Boolean),
+        {
+          boolean: ["json"],
+          value: ["capacity-gib", "performance-tier", "reservation", "reservation-id"],
+        },
+        "Usage: ornn storage filesystem deploy --reservation <reservation-id> [--performance-tier <tier>] [--capacity-gib <gib>] [--json]",
+      );
+      const reservationId = requiredOption(options.reservation || options.reservationId, "--reservation");
+      const payload = await cliRequest({
+        body: {
+          ...(optionProvided(options.performanceTier) ? { performance_tier: requiredOption(options.performanceTier, "--performance-tier") } : {}),
+          ...(optionProvided(options.capacityGib) ? { capacity_gib: positiveIntegerOption(options.capacityGib, "--capacity-gib") } : {}),
+        },
+        endpoint: computeEndpoint(`/standalone-vms/reservations/${encodeURIComponent(reservationId)}/filesystem-deployment`),
+        env: context.env,
+        fetchImpl: context.fetchImpl,
+        method: "POST",
+      });
+      if (options.json) {
+        writeJson(context.stdout, payload);
+      } else {
+        context.stdout.write("Filesystem deployment started.\n");
+        writeReservationStorageAttachment(context.stdout, payload.attachment);
+      }
+      return 0;
+    }
+    if (subcommand === "status") {
+      const options = parseCommandOptions(
+        [id, ...rest].filter(Boolean),
+        {
+          boolean: ["json"],
+          value: ["reservation", "reservation-id"],
+        },
+        "Usage: ornn storage filesystem status --reservation <reservation-id> [--json]",
+      );
+      const reservationId = requiredOption(options.reservation || options.reservationId, "--reservation");
+      const payload = await cliRequest({
+        endpoint: computeEndpoint(`/standalone-vms/reservations/${encodeURIComponent(reservationId)}/storage-attachment`),
+        env: context.env,
+        fetchImpl: context.fetchImpl,
+      });
+      if (options.json) {
+        writeJson(context.stdout, payload);
+      } else {
+        context.stdout.write("Filesystem deployment status.\n");
+        writeReservationStorageAttachment(context.stdout, payload.attachment);
+      }
+      return 0;
+    }
+    if (subcommand === "delete" || subcommand === "teardown") {
+      const options = parseCommandOptions(
+        [id, ...rest].filter(Boolean),
+        {
+          boolean: ["json"],
+          value: ["reservation", "reservation-id"],
+        },
+        "Usage: ornn storage filesystem delete --reservation <reservation-id> [--json]",
+      );
+      const reservationId = requiredOption(options.reservation || options.reservationId, "--reservation");
+      const payload = await cliRequest({
+        endpoint: computeEndpoint(`/standalone-vms/reservations/${encodeURIComponent(reservationId)}/filesystem-deployment`),
+        env: context.env,
+        fetchImpl: context.fetchImpl,
+        method: "DELETE",
+      });
+      if (options.json) {
+        writeJson(context.stdout, payload);
+      } else {
+        context.stdout.write("Filesystem deletion requested.\n");
+        writeReservationStorageAttachment(context.stdout, payload.attachment);
+      }
+      return 0;
+    }
+    throw new Error("Usage: ornn storage filesystem deploy|status|delete --reservation <reservation-id> [--json]");
+  }
+  if (resource === "deploy" && subcommand === "status") {
+    const options = parseCommandOptions(
+      [id, ...rest].filter(Boolean),
+      {
+        boolean: ["json"],
+        value: ["reservation", "reservation-id"],
+      },
+      "Usage: ornn storage deploy status --reservation <reservation-id> [--json]",
+    );
+    const reservationId = requiredOption(options.reservation || options.reservationId, "--reservation");
+    const payload = await cliRequest({
+      endpoint: computeEndpoint(`/standalone-vms/reservations/${encodeURIComponent(reservationId)}/storage-attachment`),
+      env: context.env,
+      fetchImpl: context.fetchImpl,
+    });
+    if (options.json) {
+      writeJson(context.stdout, payload);
+    } else {
+      context.stdout.write("Storage deployment status.\n");
+      writeReservationStorageAttachment(context.stdout, payload.attachment);
+    }
+    return 0;
+  }
+  if (resource === "deploy" && subcommand) {
+    const options = parseCommandOptions(
+      [id, ...rest].filter(Boolean),
+      {
+        boolean: ["json", "read-only", "read-write"],
+        value: ["mount-path", "reservation", "reservation-id"],
+      },
+      "Usage: ornn storage deploy <drive-id> --reservation <reservation-id> [--mount-path <path>] [--read-only|--read-write] [--json]",
+    );
+    if (options.readOnly && options.readWrite) {
+      throw new Error("Choose only one of --read-only or --read-write.");
+    }
+    const reservationId = requiredOption(options.reservation || options.reservationId, "--reservation");
+    const payload = await cliRequest({
+      body: {
+        drive_id: subcommand,
+        ...(optionProvided(options.mountPath) ? { mount_path: requiredOption(options.mountPath, "--mount-path") } : {}),
+        access_mode: options.readOnly ? "read-only" : "read-write",
+      },
+      endpoint: computeEndpoint(`/standalone-vms/reservations/${encodeURIComponent(reservationId)}/storage-deployment`),
+      env: context.env,
+      fetchImpl: context.fetchImpl,
+      method: "POST",
+    });
+    if (options.json) {
+      writeJson(context.stdout, payload);
+    } else {
+      context.stdout.write("Storage deployment started.\n");
+      writeReservationStorageAttachment(context.stdout, payload.attachment);
+    }
+    return 0;
+  }
+  if (resource === "deploy") {
+    throw new Error("Usage: ornn storage deploy <drive-id> --reservation <reservation-id> [--mount-path <path>] [--read-only|--read-write] [--json]");
+  }
+  if (resource === "buckets") {
+    if (subcommand === "list") {
+      const options = parseCommandOptions(
+        [id, ...rest].filter(Boolean),
+        { boolean: ["json"] },
+        "Usage: ornn storage buckets list [--json]",
+      );
+      const payload = await fetchStorageDrives(context);
+      const buckets = storageBucketsFromPayload(payload);
+      if (options.json) {
+        writeJson(context.stdout, { buckets });
+      } else {
+        writeStorageBucketList(context.stdout, buckets);
+      }
+      return 0;
+    }
+    if (subcommand === "show" && id) {
+      const options = parseCommandOptions(
+        rest,
+        { boolean: ["json"] },
+        "Usage: ornn storage buckets show <drive-id> [--json]",
+      );
+      const bucket = await findStorageBucket(id, context);
+      if (options.json) {
+        writeJson(context.stdout, bucket);
+      } else {
+        writeStorageDriveDetail(context.stdout, bucket);
+      }
+      return 0;
+    }
+    if (subcommand === "verify" && id) {
+      const options = parseCommandOptions(
+        rest,
+        { boolean: ["json"] },
+        "Usage: ornn storage buckets verify <drive-id> [--json]",
+      );
+      const drive = await cliRequest({
+        endpoint: computeEndpoint(`/standalone-vms/storage-drives/${encodeURIComponent(id)}/verify-source`),
+        env: context.env,
+        fetchImpl: context.fetchImpl,
+        method: "POST",
+      });
+      const verificationFailed = drive?.source?.connection_status === "verification_failed";
+      if (options.json) {
+        writeJson(context.stdout, drive);
+      } else {
+        context.stdout.write(
+          verificationFailed ? "Bucket source verification failed.\n" : "Bucket source verified.\n",
+        );
+        writeStorageDriveDetail(context.stdout, drive);
+      }
+      return verificationFailed ? 1 : 0;
+    }
+    if (subcommand === "update-credentials" && id) {
+      const options = parseCommandOptions(
+        rest,
+        {
+          boolean: ["json"],
+          value: ["access-key-id", "secret-access-key", "secret-access-key-file"],
+        },
+        "Usage: ornn storage buckets update-credentials <drive-id> --access-key-id <id> --secret-access-key-file <path> [--json]",
+      );
+      if (options.secretAccessKey && options.secretAccessKeyFile) {
+        throw new Error("Use only one of --secret-access-key or --secret-access-key-file.");
+      }
+      const secretAccessKey = options.secretAccessKeyFile
+        ? (await readFile(options.secretAccessKeyFile, "utf8")).trim()
+        : optionalStringOption(options.secretAccessKey);
+      if (!secretAccessKey) {
+        throw new Error("--secret-access-key-file or --secret-access-key is required.");
+      }
+      const drive = await cliRequest({
+        body: {
+          external_access_key_id: requiredOption(options.accessKeyId, "--access-key-id"),
+          external_secret_access_key: secretAccessKey,
+        },
+        endpoint: computeEndpoint(`/standalone-vms/storage-drives/${encodeURIComponent(id)}/source-credentials`),
+        env: context.env,
+        fetchImpl: context.fetchImpl,
+        method: "PATCH",
+      });
+      if (options.json) {
+        writeJson(context.stdout, drive);
+      } else {
+        context.stdout.write("Bucket credentials updated.\n");
+        writeStorageDriveDetail(context.stdout, drive);
+      }
+      return 0;
+    }
+    if (subcommand === "disconnect" && id) {
+      const options = parseCommandOptions(
+        rest,
+        { boolean: ["json"] },
+        "Usage: ornn storage buckets disconnect <drive-id> [--json]",
+      );
+      await cliRequest({
+        endpoint: computeEndpoint(`/standalone-vms/storage-drives/${encodeURIComponent(id)}`),
+        env: context.env,
+        fetchImpl: context.fetchImpl,
+        method: "DELETE",
+      });
+      const result = { disconnected: true, drive_id: id };
+      if (options.json) {
+        writeJson(context.stdout, result);
+      } else {
+        context.stdout.write(`Bucket disconnected: ${id}\n`);
+      }
+      return 0;
+    }
+    if (subcommand !== "connect" || !["gcs", "s3", "r2"].includes(id)) {
+      throw new Error(
+        "Usage: ornn storage buckets list|show|connect|verify|update-credentials|disconnect",
+      );
+    }
+    const options = parseCommandOptions(
+      rest,
+      {
+        boolean: ["json", "read-only", "read-write", "verify"],
+        value: ["access-key-id", "account-id", "bucket", "endpoint-url", "name", "prefix", "region", "secret-access-key", "secret-access-key-file", "url"],
+      },
+      "Usage: ornn storage buckets connect gcs|s3|r2 --bucket <bucket>|--url <url> [--name <name>] [--prefix <prefix>] [--region <region>] [--account-id <id>|--endpoint-url <url>] [--access-key-id <id> --secret-access-key-file <path>] [--read-only|--read-write] [--verify] [--json]",
+    );
+    if (options.readOnly && options.readWrite) {
+      throw new Error("Choose only one of --read-only or --read-write.");
+    }
+    if (options.bucket && options.url) {
+      throw new Error("Use only one of --bucket or --url.");
+    }
+    if (id === "gcs" && options.verify) {
+      throw new Error("--verify is only supported for S3-compatible buckets.");
+    }
+    if (options.secretAccessKey && options.secretAccessKeyFile) {
+      throw new Error("Use only one of --secret-access-key or --secret-access-key-file.");
+    }
+    if (id === "gcs" && (options.accessKeyId || options.secretAccessKey || options.secretAccessKeyFile)) {
+      throw new Error("Access key credentials are only supported for S3-compatible buckets.");
+    }
+    const secretAccessKey = options.secretAccessKeyFile
+      ? (await readFile(options.secretAccessKeyFile, "utf8")).trim()
+      : optionalStringOption(options.secretAccessKey);
+    if (Boolean(options.accessKeyId) !== Boolean(secretAccessKey)) {
+      throw new Error("Use --access-key-id with --secret-access-key-file or --secret-access-key.");
+    }
+    const source = storageBucketSourceFromOptions(id, options);
+    const prefix = optionalStringOption(options.prefix) ?? source.prefix;
+    const endpointOptions = { ...options };
+    if (!optionProvided(endpointOptions.accountId) && source.accountId && !optionProvided(endpointOptions.endpointUrl)) {
+      endpointOptions.accountId = source.accountId;
+    }
+    const endpointUrl = storageBucketEndpointUrl(id, endpointOptions);
+    const sourceProvider = id === "gcs" ? "external_gcs" : "s3";
+    const bucketName = source.bucket;
+    let drive = await cliRequest({
+      body: {
+        name: optionalStringOption(options.name) ?? bucketName,
+        provider: "ornn_volume",
+        source_provider: sourceProvider,
+        external_bucket: bucketName,
+        external_prefix: prefix,
+        external_region: optionalStringOption(options.region) ?? source.region ?? (id === "r2" ? "auto" : null),
+        external_read_only: options.readWrite ? false : true,
+        ...(id === "r2" ? { external_s3_provider: "cloudflare_r2" } : {}),
+        ...(id === "s3" ? { external_s3_provider: "aws_s3" } : {}),
+        ...(endpointUrl ? { external_endpoint_url: endpointUrl } : {}),
+        ...(options.accessKeyId ? { external_access_key_id: options.accessKeyId } : {}),
+        ...(secretAccessKey ? { external_secret_access_key: secretAccessKey } : {}),
+      },
+      endpoint: computeEndpoint("/standalone-vms/storage-drives"),
+      env: context.env,
+      fetchImpl: context.fetchImpl,
+      method: "POST",
+    });
+    if (options.verify) {
+      drive = await verifyStorageBucketSource(drive.id, context);
+    }
+    const commands = storageBucketImportCommands({
+      bucket: bucketName,
+      endpointUrl,
+      prefix,
+      provider: id,
+      region: optionalStringOption(options.region) ?? source.region ?? (id === "r2" ? "auto" : null),
+      target: drive.import_target,
+    });
+    if (options.json) {
+      writeJson(context.stdout, { ...drive, import_commands: commands });
+    } else {
+      context.stdout.write("Bucket connected.\n");
+      if (options.verify) {
+        context.stdout.write(
+          drive?.source?.connection_status === "verification_failed"
+            ? "Bucket source verification failed.\n"
+            : "Bucket source verified.\n",
+        );
+      }
+      writeStorageDriveDetail(context.stdout, drive);
+      writeStorageImportCommands(context.stdout, commands);
+    }
+    return drive?.source?.connection_status === "verification_failed" ? 1 : 0;
+  }
   if (!["drives", "volumes"].includes(resource)) {
-    throw new Error("Usage: ornn storage volumes list|show|create|refresh|clear|delete");
+    throw new Error("Usage: ornn storage volumes list|show|create|refresh|clear|delete; ornn storage buckets connect gcs|s3|r2 --bucket <bucket>");
   }
 
   if (subcommand === "list") {
@@ -2725,6 +3285,15 @@ async function fetchStorageDrives(context) {
   });
 }
 
+async function verifyStorageBucketSource(driveId, context) {
+  return await cliRequest({
+    endpoint: computeEndpoint(`/standalone-vms/storage-drives/${encodeURIComponent(driveId)}/verify-source`),
+    env: context.env,
+    fetchImpl: context.fetchImpl,
+    method: "POST",
+  });
+}
+
 async function findStorageDrive(driveId, context) {
   const payload = await fetchStorageDrives(context);
   const drive = storageDrivesFromPayload(payload).find((item) => String(item.id) === String(driveId));
@@ -2734,6 +3303,15 @@ async function findStorageDrive(driveId, context) {
   return drive;
 }
 
+async function findStorageBucket(driveId, context) {
+  const payload = await fetchStorageDrives(context);
+  const bucket = storageBucketsFromPayload(payload).find((item) => String(item.id) === String(driveId));
+  if (!bucket) {
+    throw new Error(`Storage bucket not found: ${driveId}`);
+  }
+  return bucket;
+}
+
 function reservationSshKeysEndpoint(reservationId) {
   return computeEndpoint(`/standalone-vms/reservations/${reservationId}/ssh-keys`);
 }
@@ -3611,6 +4189,63 @@ function writeReservationNetwork(stdout, payload = {}) {
   writeOptionalStatusLine(stdout, "Status", payload.network.status);
 }
 
+function writeReservationStorageAttachment(stdout, attachment = {}) {
+  if (!attachment) {
+    stdout.write("No reservation storage attachment.\n");
+    return;
+  }
+  stdout.write(`${attachment.id || "storage-attachment"}\n`);
+  writeOptionalStatusLine(stdout, "Reservation", attachment.reservation_id);
+  writeOptionalStatusLine(stdout, "Drive", attachment.drive_id);
+  writeOptionalStatusLine(stdout, "State", attachment.state);
+  writeOptionalStatusLine(stdout, "Target region", attachment.target_region);
+  writeOptionalStatusLine(stdout, "Mount path", attachment.mount_path);
+  writeOptionalStatusLine(stdout, "Mount mode", attachment.mount_mode);
+  writeOptionalStatusLine(stdout, "Access", attachment.access_mode);
+  if (attachment.placement) {
+    const placement = attachment.placement;
+    stdout.write("Placement:\n");
+    writeOptionalStatusLine(stdout, "State", placement.state);
+    writeOptionalStatusLine(
+      stdout,
+      "Target",
+      placement.target_storage_uri ||
+        placement.storage_uri ||
+        storageObjectUri("gs", placement.bucket, placement.prefix),
+    );
+    writeOptionalStatusLine(stdout, "Transfer", placement.transfer_status);
+    if (
+      typeof placement.transfer_object_count === "number" ||
+      typeof placement.transfer_bytes === "number"
+    ) {
+      const objectCount = placement.transfer_object_count;
+      const bytes = placement.transfer_bytes;
+      const objectLabel =
+        typeof objectCount === "number"
+          ? `${objectCount} ${objectCount === 1 ? "object" : "objects"}`
+          : null;
+      const bytesLabel = typeof bytes === "number" ? formatBytes(bytes) : null;
+      writeOptionalStatusLine(
+        stdout,
+        "Copied",
+        [objectLabel, bytesLabel].filter(Boolean).join(", "),
+      );
+    }
+    writeOptionalStatusLine(stdout, "Source provider", placement.source_provider);
+    writeOptionalStatusLine(stdout, "Source bucket", placement.source_bucket);
+    writeOptionalStatusLine(stdout, "Source prefix", placement.source_prefix);
+  }
+  const nfsBackend = attachment.drive?.nfs_backend || attachment.drive?.accelerators?.nfs;
+  if (nfsBackend) {
+    stdout.write("Filesystem:\n");
+    writeOptionalStatusLine(stdout, "State", nfsBackend.state);
+    writeOptionalStatusLine(stdout, "Region", nfsBackend.region);
+    writeOptionalStatusLine(stdout, "Tier", nfsBackend.performance_tier);
+    writeOptionalStatusLine(stdout, "Capacity", nfsBackend.capacity_gib ? `${nfsBackend.capacity_gib} GiB` : null);
+    writeOptionalStatusLine(stdout, "Mount ready", nfsBackend.mount_ready ? "yes" : "no");
+  }
+}
+
 function writeStorageDriveList(stdout, drives) {
   if (!drives.length) {
     stdout.write("No storage volumes found.\n");
@@ -3623,6 +4258,12 @@ function writeStorageDriveList(stdout, drives) {
     if (drive.source_drive_id) {
       stdout.write(` source=${drive.source_drive_id}`);
     }
+    if (drive.source?.provider && drive.source.provider !== "ornn_object") {
+      stdout.write(` source=${drive.source.provider}`);
+      if (drive.source.bucket) {
+        stdout.write(` bucket=${drive.source.bucket}`);
+      }
+    }
     if (drive.active_mount) {
       stdout.write(` mounted=${drive.active_mount.reservation_id || "yes"}`);
     }
@@ -3630,12 +4271,67 @@ function writeStorageDriveList(stdout, drives) {
   }
 }
 
+function writeStorageBucketList(stdout, buckets) {
+  if (!buckets.length) {
+    stdout.write("No storage buckets found.\n");
+    return;
+  }
+  stdout.write("Storage buckets:\n");
+  for (const drive of buckets) {
+    const source = drive.source || {};
+    stdout.write(`- ${drive.id} ${drive.name || "unnamed"} ${source.provider || "unknown"}`);
+    if (source.s3_provider) {
+      stdout.write(`/${source.s3_provider}`);
+    }
+    if (source.bucket) {
+      stdout.write(` bucket=${source.bucket}`);
+    }
+    if (source.prefix) {
+      stdout.write(` prefix=${source.prefix}`);
+    }
+    if (source.connection_status) {
+      stdout.write(` status=${source.connection_status}`);
+    }
+    if (source.access_key_id_hint) {
+      stdout.write(` key=${source.access_key_id_hint}`);
+    }
+    if (source.provider && source.provider !== "ornn_object") {
+      stdout.write(` access=${source.read_only === false ? "read-write" : "read-only"}`);
+    }
+    stdout.write("\n");
+  }
+}
+
 function writeStorageDriveDetail(stdout, drive = {}) {
   stdout.write(`${drive.id || "drive"}\n`);
   stdout.write(`Name: ${drive.name || "unnamed"}\n`);
   stdout.write(`Status: ${drive.status || "unknown"}\n`);
   stdout.write(`Size: ${formatBytes(drive.size_bytes)}\n`);
   writeOptionalStatusLine(stdout, "Source", drive.source_drive_id);
+  if (drive.source) {
+    writeOptionalStatusLine(stdout, "Source provider", drive.source.provider);
+    writeOptionalStatusLine(stdout, "Bucket", drive.source.bucket);
+    writeOptionalStatusLine(stdout, "Prefix", drive.source.prefix);
+    writeOptionalStatusLine(stdout, "Region", drive.source.region);
+    writeOptionalStatusLine(stdout, "S3 provider", drive.source.s3_provider);
+    writeOptionalStatusLine(stdout, "Endpoint", drive.source.endpoint_url);
+    if (drive.source.credentials_configured) {
+      stdout.write(`Credentials: configured${drive.source.access_key_id_hint ? ` (${drive.source.access_key_id_hint})` : ""}\n`);
+    }
+    writeOptionalStatusLine(stdout, "Connection", drive.source.connection_status);
+    writeOptionalStatusLine(stdout, "Verified", drive.source.last_verified_at);
+    if (drive.source.verification_error) {
+      const error = drive.source.verification_error;
+      stdout.write(`Verification error: ${error.code || "failed"}`);
+      if (error.message) {
+        stdout.write(` - ${error.message}`);
+      }
+      stdout.write("\n");
+    }
+    if (drive.source.provider && drive.source.provider !== "ornn_object") {
+      stdout.write(`Access: ${drive.source.read_only === false ? "read-write" : "read-only"}\n`);
+    }
+  }
   writeOptionalStatusLine(stdout, "File tree", drive.file_tree_status);
   if (drive.file_tree_truncated) {
     stdout.write("    File tree: truncated\n");
@@ -3652,6 +4348,20 @@ function writeStorageDriveDetail(stdout, drive = {}) {
   writeOptionalStatusLine(stdout, "Updated", drive.updated_at);
 }
 
+function writeStorageImportCommands(stdout, commands = []) {
+  if (!commands.length) {
+    return;
+  }
+  stdout.write("\nRun these commands to import data into Ornn object storage:\n");
+  for (const item of commands) {
+    stdout.write(`\n# ${item.label}\n`);
+    if (item.note) {
+      stdout.write(`# ${item.note}\n`);
+    }
+    stdout.write(`${item.command}\n`);
+  }
+}
+
 function writeBillingSummary(stdout, summary = {}) {
   stdout.write("Billing summary:\n");
   stdout.write(`Open balance: ${formatCents(summary.open_balance_cents)}\n`);
@@ -3745,6 +4455,188 @@ function storageDrivesFromPayload(payload) {
   return Array.isArray(payload) ? payload : Array.isArray(payload?.drives) ? payload.drives : [];
 }
 
+function storageBucketsFromPayload(payload) {
+  return storageDrivesFromPayload(payload).filter(isStorageBucketDrive);
+}
+
+function isStorageBucketDrive(drive = {}) {
+  const source = drive.source || {};
+  return (
+    source.kind === "object" ||
+    ["ornn_object", "external_gcs", "s3"].includes(String(source.provider || ""))
+  );
+}
+
+function storageBucketLocationFromInput(value) {
+  const withoutScheme = String(value || "")
+    .trim()
+    .replace(/^(gs|s3|r2):\/\//i, "")
+    .replace(/^\/+|\/+$/g, "");
+  const [bucket, ...prefixParts] = withoutScheme.split("/");
+  return {
+    bucket,
+    prefix: prefixParts.join("/") || null,
+  };
+}
+
+function storageBucketSourceFromOptions(provider, options = {}) {
+  const rawBucket = optionalStringOption(options.bucket);
+  const rawUrl = optionalStringOption(options.url);
+  const parsed = rawUrl ? storageBucketSourceFromConsoleUrl(provider, rawUrl) : {};
+  const location = rawBucket ? storageBucketLocationFromInput(rawBucket) : parsed;
+  if (!location.bucket) {
+    throw new Error("--bucket or --url is required.");
+  }
+  return {
+    accountId: parsed.accountId || null,
+    bucket: location.bucket,
+    prefix: location.prefix || null,
+    region: parsed.region || null,
+  };
+}
+
+function storageBucketSourceFromConsoleUrl(provider, rawUrl) {
+  let url;
+  try {
+    url = new URL(String(rawUrl || "").trim());
+  } catch {
+    throw new Error("--url must be a valid console URL.");
+  }
+  const hostname = url.hostname.toLowerCase();
+  const pathParts = url.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+  if (provider === "s3") {
+    const bucketIndex = pathParts.findIndex((part, index) => part === "buckets" && pathParts[index - 1] === "s3");
+    const bucket = bucketIndex >= 0 ? storageConsolePathValue(pathParts[bucketIndex + 1]) : null;
+    const rawRegionFromHost = hostname.endsWith(".console.aws.amazon.com")
+      ? hostname.slice(0, -".console.aws.amazon.com".length)
+      : null;
+    const regionFromHost = rawRegionFromHost && rawRegionFromHost !== "s3" ? rawRegionFromHost : null;
+    const region = url.searchParams.get("region") || regionFromHost;
+    const prefix = url.searchParams.get("prefix");
+    if (!bucket) {
+      throw new Error("AWS S3 console URL must include /s3/buckets/<bucket>.");
+    }
+    return { bucket, prefix: normalizeStoragePrefix(prefix), region };
+  }
+  if (provider === "r2") {
+    const accountId = hostname === "dash.cloudflare.com" ? pathParts[0] : null;
+    const bucketIndex = pathParts.findIndex((part) => part === "buckets");
+    const bucket = bucketIndex >= 0 ? storageConsolePathValue(pathParts[bucketIndex + 1]) : null;
+    if (!accountId || !bucket) {
+      throw new Error("Cloudflare R2 console URL must include /<account-id>/r2/.../buckets/<bucket>.");
+    }
+    return { accountId, bucket, prefix: null, region: "auto" };
+  }
+  if (provider === "gcs") {
+    const browserIndex = pathParts.findIndex((part) => part === "browser");
+    const bucket = browserIndex >= 0 ? storageConsolePathValue(pathParts[browserIndex + 1]) : null;
+    const prefix = url.searchParams.get("prefix");
+    if (!bucket) {
+      throw new Error("GCS console URL must include /storage/browser/<bucket>.");
+    }
+    return { bucket, prefix: normalizeStoragePrefix(prefix), region: null };
+  }
+  throw new Error("Unsupported bucket provider.");
+}
+
+function storageConsolePathValue(value) {
+  return String(value || "").split(";", 1)[0] || null;
+}
+
+function normalizeStoragePrefix(value) {
+  const normalized = String(value || "").trim().replace(/^\/+|\/+$/g, "");
+  return normalized || null;
+}
+
+function storageBucketEndpointUrl(provider, options = {}) {
+  const endpointUrl = optionalStringOption(options.endpointUrl);
+  const accountId = optionalStringOption(options.accountId);
+  if (provider !== "r2") {
+    if (endpointUrl || accountId) {
+      throw new Error("--account-id and --endpoint-url are only supported for Cloudflare R2.");
+    }
+    return null;
+  }
+  if (endpointUrl && accountId) {
+    throw new Error("Use only one of --account-id or --endpoint-url.");
+  }
+  if (endpointUrl) {
+    return endpointUrl.replace(/\/+$/, "");
+  }
+  if (!accountId) {
+    throw new Error("Cloudflare R2 requires --account-id or --endpoint-url.");
+  }
+  return `https://${accountId}.r2.cloudflarestorage.com`;
+}
+
+function storageObjectUri(scheme, bucket, prefix) {
+  const normalizedPrefix = String(prefix || "").trim().replace(/^\/+|\/+$/g, "");
+  return normalizedPrefix ? `${scheme}://${bucket}/${normalizedPrefix}` : `${scheme}://${bucket}`;
+}
+
+function storageImportTargetUri(target = {}) {
+  if (target.storage_uri) {
+    return String(target.storage_uri);
+  }
+  if (target.bucket_name && target.object_prefix) {
+    return `gs://${target.bucket_name}/${String(target.object_prefix).replace(/^\/+/, "").replace(/\/?$/, "/")}`;
+  }
+  return null;
+}
+
+function storageBucketImportCommands({ bucket, endpointUrl, prefix, provider, region, target }) {
+  const targetUri = storageImportTargetUri(target);
+  if (!targetUri) {
+    return [];
+  }
+  const sourceScheme = provider === "gcs" ? "gs" : "s3";
+  const sourceUri = storageObjectUri(sourceScheme, bucket, prefix);
+  if (provider === "gcs") {
+    return [
+      {
+        label: "Import from GCS",
+        note: "Uses your active gcloud credentials.",
+        command: `gcloud storage rsync -r ${shellQuote(sourceUri)} ${shellQuote(targetUri)}`,
+      },
+    ];
+  }
+  if (provider === "s3") {
+    return [
+      {
+        label: "Check AWS S3 source",
+        note: "Uses your AWS credentials from the AWS CLI environment or ~/.aws/credentials.",
+        command: `aws s3 ls ${shellQuote(sourceUri)}`,
+      },
+      {
+        label: "Import from AWS S3",
+        note: "Uses gcloud storage interoperability with your AWS S3 credentials.",
+        command: `gcloud storage rsync -r ${shellQuote(sourceUri)} ${shellQuote(targetUri)}`,
+      },
+    ];
+  }
+  return [
+    {
+      label: "Check Cloudflare R2 source",
+      note: "Uses your R2 access key configured for the AWS CLI.",
+      command: `AWS_REGION=${shellQuote(region || "auto")} aws s3 ls ${shellQuote(sourceUri)} --endpoint-url ${shellQuote(endpointUrl)}`,
+    },
+    {
+      label: "Point gcloud at R2 for this import",
+      note: "Run the unset command below after the import if you do not want this endpoint kept in your gcloud config.",
+      command: `gcloud config set storage/s3_endpoint_url ${shellQuote(endpointUrl)}`,
+    },
+    {
+      label: "Import from Cloudflare R2",
+      note: "Uses your R2 S3-compatible credentials and copies into Ornn GCS.",
+      command: `gcloud storage rsync -r ${shellQuote(sourceUri)} ${shellQuote(targetUri)}`,
+    },
+    {
+      label: "Reset gcloud S3 endpoint",
+      command: "gcloud config unset storage/s3_endpoint_url",
+    },
+  ];
+}
+
 function metricSnapshotFromLivePayload(fallbackMachine, payload = {}) {
   const liveMachine = payload?.machine || null;
   const machine = liveMachine
@@ -4191,18 +5083,6 @@ function activeMachines(machines) {
   });
 }
 
-function writeMutationWithOpen(stdout, resource, opened, options, label) {
-  if (options.json) {
-    writeJson(stdout, { resource, opened: opened.opened, url: opened.url });
-    return;
-  }
-  stdout.write(`${label} updated.\n`);
-  if (resource?.id) {
-    stdout.write(`ID: ${resource.id}\n`);
-  }
-  writeCheckoutOpenResult(stdout, opened, label);
-}
-
 function writeSshKeyList(stdout, keys) {
   const activeKeys = activeSshKeys(keys);
   if (!activeKeys.length) {
@@ -4646,6 +5526,17 @@ function writeJson(stdout, payload) {
   stdout.write(`${JSON.stringify(payload ?? { ok: true }, null, 2)}\n`);
 }
 
+// Strip fields that leak into ticket pastes / CI logs on --json dumps.
+function redactNodeSecrets(node) {
+  if (!node || typeof node !== "object") {
+    return node;
+  }
+  const redacted = { ...node };
+  delete redacted.admin_private_key;
+  delete redacted.system_variables;
+  return redacted;
+}
+
 function formatCliError(error) {
   if (error instanceof CliApiError) {
     const structuredDetail = extractStructuredErrorDetail(error.detail);