@kvbox/cli 0.5.25 → 0.5.26

package/dist/kvbox.js

@@ -164,7 +164,7 @@ function versionOf(srcFileUrl, injected) {
 }
 
 // src/version.ts
-var VERSION = versionOf(import.meta.url, true ? "0.5.25" : void 0);
+var VERSION = versionOf(import.meta.url, true ? "0.5.26" : void 0);
 
 // src/commands/vm/index.ts
 import { Command as Command26 } from "commander";
@@ -193,6 +193,8 @@ function paths(home = kvboxHome()) {
     serverLog: join(home, "server.log"),
     /** The CLI's login to the control plane (`kvbox login`): url, bearer token, user. Mode 600. */
     cli: join(home, "cli.json"),
+    /** The CLI's last look at npm for a newer @kvbox/cli: `{checkedAt, latest}`, at most once a day (cli update.ts). */
+    updateCheck: join(home, "update-check.json"),
     ssh: join(home, "ssh"),
     sshKey: join(home, "ssh", "id_ed25519"),
     /** The device key signed by the control plane's CA (#51); ssh loads it by itself next to `-i id_ed25519`. */
@@ -495,6 +497,8 @@ var VolumeSchema = z2.object({
   ownerKind: z2.enum(["user", "org"]).optional()
 });
 var MAX_VOLUME_GIB = 4096;
+var VOLUME_NAME_RE = /^[a-z0-9][a-z0-9-]{0,11}$/;
+var VOLUME_NAME_RULE = "1-12 chars, lowercase letters, digits and '-', starting with a letter or digit";
 var CreateVolumeRequest = z2.object({
   name: z2.string(),
   sizeGib: z2.number().int().min(1).max(MAX_VOLUME_GIB),
@@ -825,10 +829,26 @@ var TopUpSchema = z2.object({
   slug: z2.string(),
   amount: z2.number(),
   currency: z2.string(),
-  source: z2.enum(["admin", "card", "trial"]),
+  /** `transfer` (#93): an owner moving credit to an org they own, a negative row on their slug and a positive one on the org's. */
+  source: z2.enum(["admin", "card", "trial", "transfer"]),
   note: z2.string().nullable(),
   at: z2.string()
 });
+var TOP_UP_AMOUNTS = [10, 25, 50, 100];
+var BillingInfoSchema = z2.object({
+  card: z2.object({ brand: z2.string(), last4: z2.string() }).nullable(),
+  cardInUse: z2.boolean(),
+  balance: BalanceSchema
+});
+var BillingRedirectSchema = z2.object({ url: z2.string() });
+var TopUpCheckoutRequestSchema = z2.object({
+  amount: z2.literal(TOP_UP_AMOUNTS)
+});
+var TransferRequestSchema = z2.object({
+  org: z2.string().min(1),
+  amount: z2.number().positive().multipleOf(0.01, "amount is in cents at most")
+});
+var TransferResponseSchema = z2.object({ from: BalanceSchema, to: BalanceSchema, activated: z2.boolean() });
 var LoginRequestSchema = z2.object({
   email: z2.string().min(1),
   password: z2.string().min(1),
@@ -1381,6 +1401,199 @@ async function serving(p, timeoutMs, check) {
   throw new KvboxError(`kvbox-server did not start within ${timeoutMs / 1e3}s; see ${p.serverLog}`);
 }
 
+// src/prompt.ts
+import { createInterface } from "readline/promises";
+function interactive() {
+  return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}
+var ESC = "\x1B";
+var ENTER = "\r";
+var CTRL_C = "";
+var CTRL_D = "";
+var cancelled = () => new KvboxError("cancelled", 130);
+function keysIn(chunk) {
+  const keys = [];
+  for (let i = 0; i < chunk.length; ) {
+    if (chunk[i] === ESC && chunk[i + 1] === "[" && i + 2 < chunk.length) {
+      let j = i + 2;
+      while (j < chunk.length && /[0-9;?]/.test(chunk[j])) j += 1;
+      const end = j < chunk.length ? j + 1 : j;
+      keys.push(chunk.slice(i, end));
+      i = end;
+    } else if (chunk[i] === ESC && chunk[i + 1] === "O" && i + 2 < chunk.length) {
+      keys.push(chunk.slice(i, i + 3));
+      i += 3;
+    } else {
+      keys.push(chunk[i]);
+      i += 1;
+    }
+  }
+  return keys;
+}
+var isUp = (k) => k === `${ESC}[A` || k === `${ESC}OA` || k === "k";
+var isDown = (k) => k === `${ESC}[B` || k === `${ESC}OB` || k === "j";
+var ANSI2 = /\x1b\[[0-9;]*[A-Za-z]/g;
+function rows(line, columns = process.stderr.columns ?? 80) {
+  const width2 = line.replace(ANSI2, "").length;
+  return Math.max(1, Math.ceil(width2 / Math.max(1, columns)));
+}
+function settled(message, answer) {
+  return `${color.green("\u2713")} ${color.bold(message)}  ${color.cyan(answer)}`;
+}
+async function select(message, choices, initial = 0) {
+  const out = process.stderr;
+  const inp = process.stdin;
+  let index = Math.min(Math.max(initial, 0), choices.length - 1);
+  let drawn = 0;
+  const render = () => {
+    if (drawn > 0) out.write(`${ESC}[${drawn}A`);
+    const lines = [
+      `${color.green("?")} ${color.bold(message)} ${color.dim("\u2191\u2193 to move, enter to pick")}`,
+      ...choices.map((c, i) => {
+        const hint = c.hint ? color.dim(`  ${c.hint}`) : "";
+        return i === index ? `${color.cyan(`\u276F ${c.label}`)}${hint}` : `  ${c.label}${hint}`;
+      })
+    ];
+    out.write(`\r${ESC}[J${lines.join("\n")}
+`);
+    drawn = lines.reduce((n, l) => n + rows(l), 0);
+  };
+  inp.setRawMode(true);
+  inp.resume();
+  inp.setEncoding("utf8");
+  render();
+  let done = false;
+  try {
+    return await new Promise((resolve3, reject) => {
+      const onData = (chunk) => {
+        for (const key of keysIn(chunk)) {
+          if (isUp(key)) index = (index - 1 + choices.length) % choices.length;
+          else if (isDown(key)) index = (index + 1) % choices.length;
+          else if (key === ENTER || key === "\n") {
+            inp.off("data", onData);
+            done = true;
+            resolve3(choices[index].value);
+            return;
+          } else if (key === CTRL_C || key === CTRL_D) {
+            inp.off("data", onData);
+            reject(cancelled());
+            return;
+          } else continue;
+          render();
+        }
+      };
+      inp.on("data", onData);
+    });
+  } finally {
+    inp.setRawMode(false);
+    inp.pause();
+    out.write(`${ESC}[${drawn}A\r${ESC}[J${done ? `${settled(message, choices[index].label)}
+` : ""}`);
+  }
+}
+async function text(message, opts = {}) {
+  const out = process.stderr;
+  for (; ; ) {
+    const hint = opts.default !== void 0 ? ` ${color.dim(`(${opts.default})`)}` : "";
+    const question = `${color.green("?")} ${color.bold(message)}${hint} ${color.dim("\u203A")} `;
+    const rl = createInterface({ input: process.stdin, output: out });
+    const line = await askLine(rl, question);
+    const raw = opts.trim === false ? line : line.trim();
+    const answer = raw === "" && opts.default !== void 0 ? opts.default : raw;
+    const problem = opts.validate?.(answer);
+    out.write(`${ESC}[${rows(question + raw)}A\r${ESC}[J`);
+    if (problem === void 0) {
+      out.write(`${settled(message, answer)}
+`);
+      return answer;
+    }
+    out.write(`${color.yellow("!")} ${problem}
+`);
+  }
+}
+async function hiddenText(message) {
+  const out = process.stderr;
+  const inp = process.stdin;
+  const question = `${color.green("?")} ${color.bold(message)} ${color.dim("(hidden) \u203A")} `;
+  out.write(question);
+  inp.setRawMode(true);
+  inp.resume();
+  inp.setEncoding("utf8");
+  let chars = [];
+  let done = false;
+  try {
+    return await new Promise((resolve3, reject) => {
+      const onData = (chunk) => {
+        for (const key of keysIn(chunk)) {
+          if (key === ENTER || key === "\n") {
+            inp.off("data", onData);
+            done = true;
+            resolve3(chars.join(""));
+            return;
+          }
+          if (key === CTRL_C || key === CTRL_D) {
+            inp.off("data", onData);
+            reject(cancelled());
+            return;
+          }
+          if (key === "\x7F" || key === "\b") chars = chars.slice(0, -1);
+          else if (key.length === 1 && (key >= " " || key === "	")) chars.push(key);
+        }
+      };
+      inp.on("data", onData);
+    });
+  } finally {
+    inp.setRawMode(false);
+    inp.pause();
+    out.write(`\r${ESC}[J${done ? `${settled(message, "\u2022\u2022\u2022\u2022\u2022")}
+` : "\n"}`);
+  }
+}
+async function askLine(rl, question) {
+  let onClose = () => {
+  };
+  const closed = new Promise((_, reject) => {
+    onClose = () => reject(cancelled());
+    rl.once("close", onClose);
+  });
+  try {
+    return await Promise.race([rl.question(question).catch(abortIsCancel), closed]);
+  } finally {
+    rl.off("close", onClose);
+    rl.close();
+  }
+}
+function abortIsCancel(err) {
+  if (err.code === "ABORT_ERR") throw cancelled();
+  throw err;
+}
+
+// src/pick.ts
+function askOrUsage(usage) {
+  if (!interactive()) throw new KvboxError(`${usage} (or run it in a terminal to be asked)`);
+}
+function refOf(item, user) {
+  return user !== void 0 && slugOf(item.owner) !== user ? `${slugOf(item.owner)}/${item.name}` : item.name;
+}
+async function pickBox(client, message = "Box", extra = []) {
+  const user = me(client);
+  const boxes = await spin("listing your boxes\u2026", client.listMachines());
+  const choices = boxes.map((b) => ({ value: refOf(b, user), label: refOf(b, user), hint: b.status }));
+  if (choices.length === 0 && extra.length === 0) throw new KvboxError("you have no boxes yet: make one with kvbox new");
+  return select(message, [...choices, ...extra]);
+}
+async function pickVolume(client, keep, none) {
+  const user = me(client);
+  const volumes = (await spin("listing your volumes\u2026", client.listVolumes())).filter(keep);
+  if (volumes.length === 0) throw new KvboxError(none);
+  const refs = volumes.map((v) => refOf(v, user));
+  const ref = await select(
+    "Volume",
+    volumes.map((v, i) => ({ value: refs[i], label: refs[i], hint: `${v.sizeGib} GB, ${v.attachedTo === null ? "not attached" : `on ${v.attachedTo}`}` }))
+  );
+  return { ...volumes[refs.indexOf(ref)], ref };
+}
+
 // src/commands/vm/new.ts
 import { Command, Option } from "commander";
 var newCommand = new Command("new").description("boot a new box from the base image or a snapshot").argument("[name]", "box name (box1, box2, \u2026 when omitted)").addOption(new Option("-s, --size <size>", "box size (default: server config, s)").choices(SIZE_NAMES)).option("-f, --from <snapshot>", "start from a snapshot instead of the base image").option("--auto-hibernate <duration>", "hibernate the box after this long without network traffic (30m, 4h, 1d; off: never; default: server config, off)").option("--force", "skip the capacity guard").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
@@ -1433,12 +1646,14 @@ function parseIdleTimeout(text2) {
 
 // src/commands/vm/connect.ts
 var SSH_FAILED = 255;
-var connectCommand = new Command2("connect").alias("cn").description("open a shell in a box over SSH (or run a command: kvbox connect <name> -- <cmd>)").argument("<name>", "box name").argument("[cmd...]", "command to run instead of a shell").passThroughOptions().action(async (name, cmdArgs, _opts, cmd) => {
+var connectCommand = new Command2("connect").alias("cn").description("open a shell in a box over SSH (or run a command: kvbox connect <name> -- <cmd>)").argument("[name]", "box name (picked from a list when left out)").argument("[cmd...]", "command to run instead of a shell").passThroughOptions().action(async (nameArg, cmdArgs, _opts, cmd) => {
+  if (nameArg === void 0) askOrUsage("give the box: kvbox connect <name>");
   const client = await clientFor(cmd.optsWithGlobals());
   let ep;
   let cert;
   let owner;
   try {
+    const name = nameArg ?? await pickBox(client);
     let box = pickRef(await boxesFor(client, name), name, me(client));
     if (!box) throw new KvboxError(`box ${name}: not found (kvbox ls)`);
     cert = await ensureCert(client, void 0, void 0, { owner: box.owner });
@@ -1793,12 +2008,17 @@ function assertRouteName(text2) {
 }
 
 // src/commands/vm/proxy/claim.ts
-var claimCommand = new Command9("claim").description("give a box its HTTPS address, https://<subdomain>.kvbox.app, serving one of its ports").argument("<box>", "box name").argument("<subdomain>", "3-63 lowercase letters, digits and '-'; must be free").requiredOption("--port <port>", "the box port the address serves").option("--json", "print the subdomain as JSON").action(async (name, subdomain, opts, cmd) => {
-  assertSubdomain(subdomain);
-  const [port] = parsePorts([opts.port]);
+var claimCommand = new Command9("claim").description("give a box its HTTPS address, https://<subdomain>.kvbox.app, serving one of its ports").argument("[box]", "box name (picked from a list when left out)").argument("[subdomain]", "3-63 lowercase letters, digits and '-'; must be free (asked for when left out)").option("--port <port>", "the box port the address serves (asked for when left out)").option("--json", "print the subdomain as JSON").action(async (nameArg, subArg, opts, cmd) => {
+  if (nameArg === void 0 || subArg === void 0 || opts.port === void 0) askOrUsage("give the box, the subdomain and the port: kvbox vm proxy claim <box> <subdomain> --port <port>");
+  if (subArg !== void 0) assertSubdomain(subArg);
+  if (opts.port !== void 0) parsePorts([opts.port]);
   const client = await clientFor(cmd.optsWithGlobals());
   try {
     requireCloud(client);
+    const name = nameArg ?? await pickBox(client);
+    const subdomain = subArg ?? await text("Subdomain", { validate: (a) => subdomainProblem(a) ?? void 0 });
+    const portText = opts.port ?? await text("Port inside the box", { default: "3000", validate: (a) => /^\d+$/.test(a) && +a >= 1 && +a <= 65535 ? void 0 : "a port is 1-65535" });
+    const [port] = parsePorts([portText]);
     const user = me(client);
     const found = await findBox(client, name);
     const box = displayName(found, user);
@@ -2438,175 +2658,6 @@ import { hostname as osHostname } from "os";
 import { createInterface as createInterface2 } from "readline/promises";
 import { Writable } from "stream";
 import { Command as Command35 } from "commander";
-
-// src/prompt.ts
-import { createInterface } from "readline/promises";
-function interactive() {
-  return process.stdin.isTTY === true && process.stderr.isTTY === true;
-}
-var ESC = "\x1B";
-var ENTER = "\r";
-var CTRL_C = "";
-var CTRL_D = "";
-var cancelled = () => new KvboxError("cancelled", 130);
-function keysIn(chunk) {
-  const keys = [];
-  for (let i = 0; i < chunk.length; ) {
-    if (chunk[i] === ESC && chunk[i + 1] === "[" && i + 2 < chunk.length) {
-      let j = i + 2;
-      while (j < chunk.length && /[0-9;?]/.test(chunk[j])) j += 1;
-      const end = j < chunk.length ? j + 1 : j;
-      keys.push(chunk.slice(i, end));
-      i = end;
-    } else if (chunk[i] === ESC && chunk[i + 1] === "O" && i + 2 < chunk.length) {
-      keys.push(chunk.slice(i, i + 3));
-      i += 3;
-    } else {
-      keys.push(chunk[i]);
-      i += 1;
-    }
-  }
-  return keys;
-}
-var isUp = (k) => k === `${ESC}[A` || k === `${ESC}OA` || k === "k";
-var isDown = (k) => k === `${ESC}[B` || k === `${ESC}OB` || k === "j";
-var ANSI2 = /\x1b\[[0-9;]*[A-Za-z]/g;
-function rows(line, columns = process.stderr.columns ?? 80) {
-  const width2 = line.replace(ANSI2, "").length;
-  return Math.max(1, Math.ceil(width2 / Math.max(1, columns)));
-}
-function settled(message, answer) {
-  return `${color.green("\u2713")} ${color.bold(message)}  ${color.cyan(answer)}`;
-}
-async function select(message, choices, initial = 0) {
-  const out = process.stderr;
-  const inp = process.stdin;
-  let index = Math.min(Math.max(initial, 0), choices.length - 1);
-  let drawn = 0;
-  const render = () => {
-    if (drawn > 0) out.write(`${ESC}[${drawn}A`);
-    const lines = [
-      `${color.green("?")} ${color.bold(message)} ${color.dim("\u2191\u2193 to move, enter to pick")}`,
-      ...choices.map((c, i) => {
-        const hint = c.hint ? color.dim(`  ${c.hint}`) : "";
-        return i === index ? `${color.cyan(`\u276F ${c.label}`)}${hint}` : `  ${c.label}${hint}`;
-      })
-    ];
-    out.write(`\r${ESC}[J${lines.join("\n")}
-`);
-    drawn = lines.reduce((n, l) => n + rows(l), 0);
-  };
-  inp.setRawMode(true);
-  inp.resume();
-  inp.setEncoding("utf8");
-  render();
-  let done = false;
-  try {
-    return await new Promise((resolve3, reject) => {
-      const onData = (chunk) => {
-        for (const key of keysIn(chunk)) {
-          if (isUp(key)) index = (index - 1 + choices.length) % choices.length;
-          else if (isDown(key)) index = (index + 1) % choices.length;
-          else if (key === ENTER || key === "\n") {
-            inp.off("data", onData);
-            done = true;
-            resolve3(choices[index].value);
-            return;
-          } else if (key === CTRL_C || key === CTRL_D) {
-            inp.off("data", onData);
-            reject(cancelled());
-            return;
-          } else continue;
-          render();
-        }
-      };
-      inp.on("data", onData);
-    });
-  } finally {
-    inp.setRawMode(false);
-    inp.pause();
-    out.write(`${ESC}[${drawn}A\r${ESC}[J${done ? `${settled(message, choices[index].label)}
-` : ""}`);
-  }
-}
-async function text(message, opts = {}) {
-  const out = process.stderr;
-  for (; ; ) {
-    const hint = opts.default !== void 0 ? ` ${color.dim(`(${opts.default})`)}` : "";
-    const question = `${color.green("?")} ${color.bold(message)}${hint} ${color.dim("\u203A")} `;
-    const rl = createInterface({ input: process.stdin, output: out });
-    const line = await askLine(rl, question);
-    const raw = opts.trim === false ? line : line.trim();
-    const answer = raw === "" && opts.default !== void 0 ? opts.default : raw;
-    const problem = opts.validate?.(answer);
-    out.write(`${ESC}[${rows(question + raw)}A\r${ESC}[J`);
-    if (problem === void 0) {
-      out.write(`${settled(message, answer)}
-`);
-      return answer;
-    }
-    out.write(`${color.yellow("!")} ${problem}
-`);
-  }
-}
-async function hiddenText(message) {
-  const out = process.stderr;
-  const inp = process.stdin;
-  const question = `${color.green("?")} ${color.bold(message)} ${color.dim("(hidden) \u203A")} `;
-  out.write(question);
-  inp.setRawMode(true);
-  inp.resume();
-  inp.setEncoding("utf8");
-  let chars = [];
-  let done = false;
-  try {
-    return await new Promise((resolve3, reject) => {
-      const onData = (chunk) => {
-        for (const key of keysIn(chunk)) {
-          if (key === ENTER || key === "\n") {
-            inp.off("data", onData);
-            done = true;
-            resolve3(chars.join(""));
-            return;
-          }
-          if (key === CTRL_C || key === CTRL_D) {
-            inp.off("data", onData);
-            reject(cancelled());
-            return;
-          }
-          if (key === "\x7F" || key === "\b") chars = chars.slice(0, -1);
-          else if (key.length === 1 && (key >= " " || key === "	")) chars.push(key);
-        }
-      };
-      inp.on("data", onData);
-    });
-  } finally {
-    inp.setRawMode(false);
-    inp.pause();
-    out.write(`\r${ESC}[J${done ? `${settled(message, "\u2022\u2022\u2022\u2022\u2022")}
-` : "\n"}`);
-  }
-}
-async function askLine(rl, question) {
-  let onClose = () => {
-  };
-  const closed = new Promise((_, reject) => {
-    onClose = () => reject(cancelled());
-    rl.once("close", onClose);
-  });
-  try {
-    return await Promise.race([rl.question(question).catch(abortIsCancel), closed]);
-  } finally {
-    rl.off("close", onClose);
-    rl.close();
-  }
-}
-function abortIsCancel(err) {
-  if (err.code === "ABORT_ERR") throw cancelled();
-  throw err;
-}
-
-// src/commands/login.ts
 var loginCommand = new Command35("login").description("log in to the kvbox cloud (or your own control plane) and target it from now on").argument("[url]", `control plane URL (default: ${DEFAULT_CLOUD_URL})`).option("-e, --email <email>", "account email (prompted otherwise)").option("--password-stdin", "read the password from the first line of stdin (for scripts)").action(async (urlArg, opts) => {
   const url = normalizeUrl(urlArg ?? DEFAULT_CLOUD_URL);
   const creds = await readCredentials(opts);
@@ -3643,9 +3694,12 @@ function describeMount(machine, volume, box) {
   const path = machine.volumes?.find((v) => volume === v.name || volume.endsWith(`/${v.name}`))?.mountPath ?? volumeMountPath(volume.slice(volume.lastIndexOf("/") + 1));
   return machine.status === "running" ? `  the box was restarted; the volume is at ${path} inside it` : `  box ${box} is ${machine.status}; the volume is at ${path} once it runs`;
 }
-var attachCommand = new Command51("attach").description("attach a volume to a box at /mnt/<volume> (a running box is restarted to take it)").argument("<volume>", "volume name").argument("<box>", "box name").option("--json", "print the box as JSON").action(async (volume, box, opts, cmd) => {
+var attachCommand = new Command51("attach").description("attach a volume to a box at /mnt/<volume> (a running box is restarted to take it)").argument("[volume]", "volume name (picked from a list when left out)").argument("[box]", "box name (picked from a list when left out)").option("--json", "print the box as JSON").action(async (volumeArg, boxArg, opts, cmd) => {
+  if (volumeArg === void 0 || boxArg === void 0) askOrUsage("give the volume and the box: kvbox volume attach <volume> <box>");
   const client = await clientFor(cmd.optsWithGlobals());
   try {
+    const volume = volumeArg ?? (await pickVolume(client, (v) => v.attachedTo === null, "no volume is free to attach (kvbox volume ls); make one with kvbox volume new")).ref;
+    const box = boxArg ?? await pickBox(client);
     const machine = await spin(`attaching volume ${volume} to box ${box} (a running box is restarted)\u2026`, client.attachVolume(volume, { box }));
     if (opts.json) {
       json(machine);
@@ -3667,10 +3721,26 @@ function parseGib2(text2) {
   if (gib > MAX_VOLUME_GIB) throw new KvboxError(`--size ${text2}: a volume is at most ${MAX_VOLUME_GIB} GB`);
   return gib;
 }
-var createCommand = new Command52("create").alias("new").description("create a volume for a box: an empty disk of its own at /mnt/<name> inside it (a running box is restarted)").argument("<name>", "volume name (1-12 chars; the box mounts it at /mnt/<name>)").requiredOption("--size <gb>", "size in GB, like 50 or 50GB (whole GB; it only occupies what is written)").option("--box <box>", "the box it is for: made on that box's host and attached to it (required on kvbox.sh; optional with --local)").option("--json", "print the volume as JSON").action(async (name, opts, cmd) => {
-  const sizeGib = parseGib2(opts.size);
+function sizeProblem(answer) {
+  try {
+    parseGib2(answer);
+    return void 0;
+  } catch (err) {
+    return err instanceof KvboxError ? err.message.replace(/^--size \S+: /, "") : String(err);
+  }
+}
+var createCommand = new Command52("create").alias("new").description("create a volume for a box: an empty disk of its own at /mnt/<name> inside it (a running box is restarted)").argument("[name]", "volume name (1-12 chars; the box mounts it at /mnt/<name>; asked for when left out)").option("--size <gb>", "size in GB, like 50 or 50GB (whole GB; it only occupies what is written)").option("--box <box>", "the box it is for: made on that box's host and attached to it (required on kvbox.sh; optional with --local)").option("--json", "print the volume as JSON").action(async (nameArg, opts, cmd) => {
+  const ask = interactive();
+  if (nameArg === void 0 || opts.size === void 0) askOrUsage("give the name and the size: kvbox volume create <name> --size <gb> --box <box>");
+  const name = nameArg ?? await text("Volume name", { validate: (a) => VOLUME_NAME_RE.test(a) ? void 0 : VOLUME_NAME_RULE });
+  const sizeGib = opts.size !== void 0 ? parseGib2(opts.size) : parseGib2(await text("Size in GB", { default: "10", validate: sizeProblem }));
   const client = await clientFor(cmd.optsWithGlobals());
   try {
+    if (opts.box === void 0 && ask) {
+      const none = client.target.kind === "cloud" ? [] : [{ value: "", label: "none", hint: "attach it later with kvbox volume attach" }];
+      const picked = await pickBox(client, "Box", none);
+      if (picked !== "") opts.box = picked;
+    }
     if (opts.box === void 0 && client.target.kind === "cloud") {
       throw new KvboxError(`a volume is made for a box, on that box's host: kvbox volume create ${name} --size ${sizeGib} --box <box>`);
     }
@@ -3693,9 +3763,19 @@ var createCommand = new Command52("create").alias("new").description("create a v
 
 // src/commands/volume/detach.ts
 import { Command as Command53 } from "commander";
-var detachCommand = new Command53("detach").description("detach a volume from a box; its data is kept (a running box is restarted)").argument("<volume>", "volume name").argument("<box>", "box name").option("--json", "print the box as JSON").action(async (volume, box, opts, cmd) => {
+var detachCommand = new Command53("detach").description("detach a volume from a box; its data is kept (a running box is restarted)").argument("[volume]", "volume name (picked from a list when left out)").argument("[box]", "box name (the one the volume is on when left out)").option("--json", "print the box as JSON").action(async (volumeArg, boxArg, opts, cmd) => {
+  if (volumeArg === void 0) askOrUsage("give the volume: kvbox volume detach <volume> [box]");
   const client = await clientFor(cmd.optsWithGlobals());
   try {
+    let volume = volumeArg;
+    let box = boxArg;
+    if (volume === void 0 || box === void 0) {
+      const found = volume === void 0 ? await pickVolume(client, (v) => v.attachedTo !== null, "no volume is attached to a box (kvbox volume ls)") : pickRef(await spin("finding the volume\u2026", client.listVolumes()), volume, me(client), "volume");
+      if (!found) throw new KvboxError(`volume ${volume}: not found (kvbox volume ls)`);
+      if (found.attachedTo === null) throw new KvboxError(`volume ${volume}: not attached to a box`);
+      volume ??= refOf(found, me(client));
+      box ??= refOf({ name: found.attachedTo, owner: found.owner }, me(client));
+    }
     const machine = await spin(`detaching volume ${volume} from box ${box} (a running box is restarted)\u2026`, client.detachVolume(volume, { box }));
     if (opts.json) {
       json(machine);
@@ -3894,9 +3974,90 @@ function buildProgram() {
   return program;
 }
 
+// src/update.ts
+import { mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { dirname } from "path";
+var REGISTRY_URL = "https://registry.npmjs.org/@kvbox/cli/latest";
+var CHECK_EVERY_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 1500;
+var UPDATE_COMMAND = "npm install -g @kvbox/cli";
+function isNewer(a, b) {
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return false;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i];
+  }
+  return false;
+}
+function parse(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function readUpdateState(file = paths().updateCheck) {
+  try {
+    const raw = JSON.parse(readFileSync3(file, "utf8"));
+    if (typeof raw.checkedAt !== "number" || typeof raw.latest !== "string") return null;
+    return { checkedAt: raw.checkedAt, latest: raw.latest };
+  } catch {
+    return null;
+  }
+}
+function writeUpdateState(state, file = paths().updateCheck) {
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(state) + "\n");
+  } catch {
+  }
+}
+async function fetchLatest(fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(REGISTRY_URL, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+async function refreshUpdateState(opts = {}) {
+  const file = opts.file ?? paths().updateCheck;
+  const now = opts.now ?? Date.now();
+  const cached = readUpdateState(file);
+  if (cached && now - cached.checkedAt < CHECK_EVERY_MS) return cached;
+  const latest = await fetchLatest(opts.fetchImpl);
+  const state = { checkedAt: now, latest: latest ?? cached?.latest ?? VERSION };
+  writeUpdateState(state, file);
+  return state;
+}
+function updateNotice(latest, current = VERSION) {
+  if (!isNewer(latest, current)) return null;
+  return `
+  A new version of kvbox is available (v${latest.replace(/^v/, "")}). Update with:
+    ${color.bold(UPDATE_COMMAND)}
+`;
+}
+function enabled() {
+  return process.stderr.isTTY === true && !process.env["CI"] && !process.env["KVBOX_NO_UPDATE_CHECK"];
+}
+function startUpdateCheck() {
+  if (!enabled()) return Promise.resolve();
+  process.on("exit", () => {
+    const state = readUpdateState();
+    const notice = state ? updateNotice(state.latest) : null;
+    if (notice) process.stderr.write(notice);
+  });
+  return refreshUpdateState();
+}
+
 // src/index.ts
+var updateCheck = startUpdateCheck();
 try {
   await buildProgram().parseAsync(process.argv);
+  await updateCheck;
 } catch (err) {
   if (err instanceof KvboxError) {
     process.stderr.write(color.red(`error: ${err.message}`) + "\n");