@kvbox/cli 0.5.25 → 0.5.27

package/dist/kvbox.js

@@ -149,7 +149,7 @@ async function spin(message, work, opts = {}) {
 }
 
 // src/program.ts
-import { Command as Command61 } from "commander";
+import { Command as Command65 } from "commander";
 
 // ../shared/src/version.ts
 import { createRequire } from "module";
@@ -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.27" : 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`. */
@@ -440,6 +442,19 @@ var SubdomainSchema = z2.object({
   url: z2.string(),
   routes: z2.array(z2.object({ name: z2.string(), port: BoxPortSchema, url: z2.string() }))
 });
+var AddDomainRequest = z2.object({ domain: z2.string(), port: BoxPortSchema.optional() });
+var DomainSchema = z2.object({
+  owner: z2.string(),
+  box: z2.string(),
+  domain: z2.string(),
+  port: BoxPortSchema,
+  status: z2.enum(["pending", "live"]),
+  www: z2.boolean(),
+  url: z2.string(),
+  error: z2.string().nullable(),
+  records: z2.array(z2.object({ type: z2.enum(["A", "TXT", "CNAME"]), name: z2.string(), value: z2.string() })),
+  createdAt: z2.string()
+});
 var MachineSchema = z2.object({
   /** Host-unique short id (the tap is `kv-<id>`). Missing only on a box made before ids that has not restarted since. */
   id: z2.string(),
@@ -495,6 +510,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 +842,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),
@@ -1125,6 +1158,17 @@ var ServerClient = class {
   listSubdomains() {
     return this.call("GET", "/subdomains", z3.array(SubdomainSchema));
   }
+  /** Custom domains (#89), the control plane's only: serve the box at the user's own name. */
+  addDomain(name, req) {
+    return this.call("POST", `/machines/${encodeURIComponent(name)}/domains`, DomainSchema, req);
+  }
+  removeDomain(name, domain) {
+    return this.call("DELETE", `/machines/${encodeURIComponent(name)}/domains/${encodeURIComponent(domain)}`, DomainSchema);
+  }
+  /** Every readable box's custom domains. */
+  listDomains() {
+    return this.call("GET", "/domains", z3.array(DomainSchema));
+  }
   /** A running box's own load, memory and disk, asked of its guest (#67). */
   machineStats(name) {
     return this.call("GET", `/machines/${encodeURIComponent(name)}/stats`, MachineStatsSchema);
@@ -1274,8 +1318,8 @@ var me = (client) => client.target.kind === "cloud" ? client.target.user : void
 async function clientFor(opts, client = {}) {
   return new ServerClient(await resolveTarget(opts), client);
 }
-function sshEndpoint(box, target) {
-  if (target.kind === "local") return { host: box.ip, port: 22, user: BOX_SSH_USER };
+function sshEndpoint(box, target, direct = false) {
+  if (target.kind === "local" || direct) return { host: box.ip, port: 22, user: BOX_SSH_USER };
   if (box.ssh === void 0) throw new KvboxError(`box ${box.name} has no public SSH port`);
   return { ...box.ssh, alias: `${box.id}.${box.ssh.host}` };
 }
@@ -1318,6 +1362,11 @@ async function waitForSsh(ep, timeoutMs = 3e4) {
   }
   throw new KvboxError(`box at ${ep.host}:${ep.port} did not answer within ${Math.round(timeoutMs / 1e3)}s`);
 }
+async function checkDirect(ep) {
+  await waitForSsh(ep, 2e3).catch(() => {
+    throw new KvboxError(`--direct: cannot reach ${ep.host}:${ep.port}; it works only on the box's host (leave it out to go through the public address)`);
+  });
+}
 var NOT_A_HOST_HINT = "kvbox-server is not installed, so this machine is not a kvbox host. Set it up with install-server.sh, or log in to the cloud with: kvbox login";
 async function lastErrorLine(logPath, from = 0) {
   const { readFile: readFile8 } = await import("fs/promises");
@@ -1381,6 +1430,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,20 +1675,27 @@ 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").option("--direct", "on the box's host: ssh to the box's private ip, not through the public address or relay").passThroughOptions().action(async (nameArg, cmdArgs, opts, cmd) => {
+  if (nameArg === void 0) askOrUsage("give the box: kvbox connect <name>");
+  if (cmdArgs[0] === "--direct") {
+    opts.direct = true;
+    cmdArgs = cmdArgs.slice(cmdArgs[1] === "--" ? 2 : 1);
+  }
   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 });
     owner = box.owner;
     const wasRunning = box.status === "running";
     if (!wasRunning) box = await wakeUp(client, box, displayName(box, me(client)));
-    ep = sshEndpoint(box, client.target);
+    ep = sshEndpoint(box, client.target, opts.direct);
     if (!wasRunning) await spin(`waiting for ${name} to accept SSH\u2026`, waitForSsh(ep));
+    else if (opts.direct) await checkDirect(ep);
   } finally {
     await client.close();
   }
@@ -1511,7 +1760,7 @@ async function runSsh(ssh, opts) {
   }).finally(() => clearTimeout(timer));
   return { status: status2, chunks, timedOut };
 }
-var execCommand = new Command3("exec").description("run a command in a box and exit with its status (kvbox exec <name> -- <cmd>)").argument("<name>", "box name").argument("<cmd...>", "command, passed to the box's shell as one string (pipes, &&, cd work)").option("-e, --env <KEY=VALUE>", "set an environment variable for the command (repeatable)", collect).option("--timeout <seconds>", "kill the command after N seconds and exit 124", positiveSeconds).option("--tty", "allocate a pseudo-terminal (for interactive tools like htop)").option("--json", 'capture output and print {"output": "...", "exit_code": N}').action(async (name, cmdArgs, opts, cmd) => {
+var execCommand = new Command3("exec").description("run a command in a box and exit with its status (kvbox exec <name> -- <cmd>)").argument("<name>", "box name").argument("<cmd...>", "command, passed to the box's shell as one string (pipes, &&, cd work)").option("-e, --env <KEY=VALUE>", "set an environment variable for the command (repeatable)", collect).option("--timeout <seconds>", "kill the command after N seconds and exit 124", positiveSeconds).option("--tty", "allocate a pseudo-terminal (for interactive tools like htop)").option("--json", 'capture output and print {"output": "...", "exit_code": N}').option("--direct", "on the box's host: ssh to the box's private ip, not through the public address or relay").action(async (name, cmdArgs, opts, cmd) => {
   const client = await clientFor(cmd.optsWithGlobals());
   let ep;
   let cert;
@@ -1524,8 +1773,9 @@ var execCommand = new Command3("exec").description("run a command in a box and e
     owner = box.owner;
     const wasRunning = box.status === "running";
     if (!wasRunning) box = await wakeUp(client, box, displayName(box, me(client)));
-    ep = sshEndpoint(box, client.target);
+    ep = sshEndpoint(box, client.target, opts.direct);
     if (!wasRunning) await spin(`waiting for ${name} to accept SSH\u2026`, waitForSsh(ep));
+    else if (opts.direct) await checkDirect(ep);
   } finally {
     await client.close();
   }
@@ -1743,6 +1993,7 @@ import { Command as Command9 } from "commander";
 
 // ../shared/src/names.ts
 import { createHmac } from "crypto";
+var DEFAULT_PROXY_DOMAIN = "kvbox.app";
 var LABEL_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 var RESERVED_SUBDOMAINS = /* @__PURE__ */ new Set([
   "admin",
@@ -1791,14 +2042,34 @@ function assertRouteName(text2) {
   if (problem) throw new KvboxError(`name ${problem}`);
   return text2;
 }
+var PLATFORM_DOMAINS = ["kvbox.sh", DEFAULT_PROXY_DOMAIN];
+function domainProblem(text2, proxyDomain) {
+  if (text2.length > 253) return `"${text2}" is longer than a domain may be`;
+  const labels = text2.split(".");
+  if (labels.length < 2 || labels.some((l) => l.length > 63 || !LABEL_RE.test(l))) return `"${text2}" is not a domain like example.com or www.example.com (lowercase, no "*", no "https://")`;
+  if (!/^[a-z]{2,}$/.test(labels.at(-1)) && !labels.at(-1).startsWith("xn--")) return `"${text2}" does not end in a top-level domain`;
+  const ours = [...PLATFORM_DOMAINS, ...proxyDomain ? [proxyDomain] : []];
+  if (ours.some((d) => text2 === d || text2.endsWith(`.${d}`))) return `"${text2}" belongs to kvbox; bring a domain of your own`;
+  return null;
+}
+function assertDomain(text2, proxyDomain) {
+  const problem = domainProblem(text2, proxyDomain);
+  if (problem) throw new KvboxError(`domain ${problem}`);
+  return 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 +2709,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 +3745,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 +3772,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 +3814,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);
@@ -3875,13 +4006,120 @@ var setCommand2 = new Command59("set").description("add or change a variable; bo
 var envCommand = new Command60("env").description("environment variables every box of yours gets when it starts (secrets too)").addCommand(lsCommand7, { isDefault: true }).addCommand(setCommand2).addCommand(rmCommand7);
 for (const cmd of envCommand.commands) cmd.option("--org <slug>", "the org's variables instead of yours");
 
+// src/commands/domain/index.ts
+import { Command as Command64 } from "commander";
+
+// src/commands/domain/add.ts
+import { Command as Command61 } from "commander";
+
+// src/commands/domain/shared.ts
+function requireCloud3(client) {
+  if (client.target.kind !== "cloud") throw new KvboxError("custom domains need the kvbox cloud: kvbox login (this host's own socket has none)");
+}
+var boxOf2 = (d, user) => user !== void 0 && d.owner !== user ? `${d.owner}/${d.box}` : d.box;
+function domainJson(d, user) {
+  return { domain: d.domain, box: boxOf2(d, user), port: d.port, status: d.status, www: d.www, url: d.url, error: d.error, records: d.records, createdAt: d.createdAt };
+}
+
+// src/commands/domain/add.ts
+var addCommand3 = new Command61("add").description("serve a box at a domain of your own, https://<domain>, with its certificate made for you").argument("<domain>", "a domain you control, like example.com or app.example.com").argument("<box>", "box name").option("--port <port>", "the box port the domain serves (default: the port of its kvbox.app address)").option("--json", "print the domain as JSON").action(async (domainArg, name, opts, cmd) => {
+  const domain = assertDomain(domainArg.trim().toLowerCase());
+  const port = opts.port === void 0 ? void 0 : parsePorts([opts.port])[0];
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    requireCloud3(client);
+    const user = me(client);
+    const box = displayName(await findBox(client, name), user);
+    const d = await spin(`adding ${domain}\u2026`, client.addDomain(box, { domain, ...port !== void 0 ? { port } : {} }));
+    if (opts.json) {
+      json(domainJson(d, user));
+      return;
+    }
+    if (d.status === "live") {
+      info(`${color.green("\u2713")} ${color.bold(d.url)} \u2192 box ${color.bold(box)} port ${d.port}`);
+      info("  the certificate is made on the first visit, which can take a few seconds");
+      return;
+    }
+    info(`${color.green("\u2713")} ${domain} added for box ${color.bold(box)} port ${d.port}, waiting for its DNS`);
+    info(`
+At the company that runs the DNS of ${domain}, add:
+`);
+    table(d.records.map((r) => ({ type: r.type, name: r.name, value: r.value })));
+    info(`
+  (the TXT record shows ${domain} is yours; keep it, it is checked again if the domain ever goes back to pending)`);
+    if (d.records.some((r) => r.type === "CNAME")) info(`  (the www record is optional: with it, www.${domain} serves the same site)`);
+    info(`
+kvbox checks every minute; ${domain} is served at ${d.url} once its records are set (kvbox domain ls).`);
+    if (d.error) info(color.dim(`  now: ${d.error}`));
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/domain/ls.ts
+import { Command as Command62 } from "commander";
+var lsCommand8 = new Command62("ls").alias("list").description("list your custom domains and whether they are live").option("--json", "print as JSON").action(async (opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    requireCloud3(client);
+    const user = me(client);
+    const domains = await client.listDomains();
+    if (opts.json) {
+      json(domains.map((d) => domainJson(d, user)));
+      return;
+    }
+    if (domains.length === 0) {
+      info("no custom domains (kvbox domain add <domain> <box>)");
+      return;
+    }
+    table(
+      domains.map((d) => ({
+        domain: d.www ? `${d.domain} (+www)` : d.domain,
+        box: boxOf2(d, user),
+        port: d.port,
+        status: d.status === "live" ? "live" : "pending dns",
+        note: d.status === "live" ? d.url : d.error ?? ""
+      }))
+    );
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/domain/rm.ts
+import { Command as Command63 } from "commander";
+var rmCommand8 = new Command63("rm").alias("remove").description("stop serving a box at a custom domain").argument("<domain>", "the domain").option("-y, --yes", "do not ask for confirmation").action(async (domainArg, opts, cmd) => {
+  const domain = domainArg.trim().toLowerCase();
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    requireCloud3(client);
+    const found = (await client.listDomains()).find((d) => d.domain === domain);
+    if (!found) throw new KvboxError(`domain ${domain}: not found (kvbox domain ls)`);
+    const box = boxOf2(found, me(client));
+    if (!await confirm(`Stop serving box ${box} at ${domain}?`, opts.yes ?? false)) {
+      info("cancelled");
+      process.exitCode = 1;
+      return;
+    }
+    await spin(`removing ${domain}\u2026`, client.removeDomain(`${found.owner}/${found.box}`, domain));
+    info(`${color.green("\u2713")} ${domain} no longer serves box ${box} (you can remove its DNS record)`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/domain/index.ts
+var domainCommand = new Command64("domain").alias("domains").description("serve a box at a domain of your own").addCommand(addCommand3).addCommand(lsCommand8).addCommand(rmCommand8);
+for (const cmd of domainCommand.commands) cmd.option("--org <slug>", "act in this org (- for your personal boxes)");
+
 // src/program.ts
 function buildProgram() {
-  const program = new Command61("kvbox").description("self-hosted Firecracker microVMs with Docker-like ergonomics").version(VERSION, "-v, --version").option("--local", "use this machine's kvbox-server over its socket, ignoring kvbox login").option("--org <slug>", "the org: where kvbox new creates, and which box a name means when it is not one of yours; before the command here, or after it").showHelpAfterError().enablePositionalOptions();
+  const program = new Command65("kvbox").description("self-hosted Firecracker microVMs with Docker-like ergonomics").version(VERSION, "-v, --version").option("--local", "use this machine's kvbox-server over its socket, ignoring kvbox login").option("--org <slug>", "the org: where kvbox new creates, and which box a name means when it is not one of yours; before the command here, or after it").showHelpAfterError().enablePositionalOptions();
   program.addCommand(vmCommand);
   program.addCommand(snapshotsCommand);
   program.addCommand(volumeCommand);
   program.addCommand(envCommand);
+  program.addCommand(domainCommand);
   program.addCommand(serverCommand);
   program.addCommand(loginCommand);
   program.addCommand(logoutCommand);
@@ -3894,9 +4132,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");