@kvbox/cli 0.5.24 → 0.5.26

package/dist/kvbox.js

@@ -149,7 +149,7 @@ async function spin(message, work, opts = {}) {
 }
 
 // src/program.ts
-import { Command as Command57 } from "commander";
+import { Command as Command61 } 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.24" : 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`. */
@@ -262,6 +264,9 @@ function paths(home = kvboxHome()) {
         disk: join(dir, "disk.ext4")
       };
     },
+    /** Each owner's environment variables as the control plane last sent them (#88): env/<owner>.json, mode 600. */
+    env: join(home, "env"),
+    ownerEnv: (owner) => join(home, "env", `${owner}.json`),
     snapshot: (owner, name) => {
       const dir = join(home, "snapshots", owner, name);
       return {
@@ -492,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),
@@ -505,6 +512,26 @@ var CreateVolumeRequest = z2.object({
 var AttachVolumeRequest = z2.object({
   box: z2.string()
 });
+var EnvVarSchema = z2.object({
+  name: z2.string(),
+  value: z2.string().optional(),
+  secret: z2.boolean(),
+  updatedAt: z2.string()
+});
+var SetEnvRequest = z2.object({
+  value: z2.string(),
+  secret: z2.boolean().optional()
+});
+var EnvChangeSchema = z2.object({
+  owner: z2.string(),
+  name: z2.string(),
+  boxes: z2.number().int()
+});
+var HostEnvRequest = z2.object({
+  version: z2.number().int().min(0),
+  vars: z2.array(z2.object({ name: z2.string(), value: z2.string() }))
+});
+var HostEnvVersionsSchema = z2.array(z2.object({ owner: z2.string(), version: z2.number().int() }));
 var CreateMachineRequest = z2.object({
   name: z2.string().optional(),
   /** Ignored over the local socket (the caller is the host owner); the control plane sets it over HTTPS. */
@@ -802,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),
@@ -1137,6 +1180,16 @@ var ServerClient = class {
   deleteSnapshot(name) {
     return this.call("DELETE", `/snapshots/${encodeURIComponent(name)}`, z3.undefined());
   }
+  // ---- environment variables (#88), a control plane only: the caller's slug, or `--org`'s ----
+  listEnv() {
+    return this.call("GET", "/env", z3.array(EnvVarSchema));
+  }
+  setEnv(name, req) {
+    return this.call("PUT", `/env/${encodeURIComponent(name)}`, EnvChangeSchema, req);
+  }
+  removeEnv(name) {
+    return this.call("DELETE", `/env/${encodeURIComponent(name)}`, EnvChangeSchema);
+  }
   // ---- volumes (#52) ----
   listVolumes(opts = {}) {
     return this.call("GET", `/volumes${allQuery(opts)}`, z3.array(VolumeSchema), void 0, opts.org);
@@ -1348,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) => {
@@ -1400,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 });
@@ -1760,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);
@@ -2405,130 +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] === "[" || 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 raw = (await askLine(rl, question)).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 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);
@@ -3145,7 +3274,8 @@ var nextjsTemplate = {
    * The source lands in a staging directory and is installed and built there while the old app
    * keeps serving; only then is it swapped into place and the service restarted, so a failed
    * install or build leaves the running app alone. The unit is rewritten every time, so a changed
-   * package manager or start script takes effect. /srv/app is the kvbox user's (image v0.8.0+).
+   * package manager or start script takes effect. /srv/app is the kvbox user's (image v0.8.0+). The
+   * build runs in the deploy's SSH session, so it sees the owner's variables (`kvbox env`) too.
    */
   remote(built) {
     const c = commands(built.pm);
@@ -3157,8 +3287,12 @@ var nextjsTemplate = {
       "[Service]",
       "User=kvbox",
       `WorkingDirectory=${APP_DIR}`,
-      `ExecStart=/usr/bin/env ${c.start}`,
-      `Environment=NODE_ENV=production PORT=${PORT}`,
+      // PORT on the command line: the proxied address points at it, and nothing in the environment
+      // file below may move the app off it (env's PORT, say, copied from a .env).
+      `ExecStart=/usr/bin/env PORT=${PORT} ${c.start}`,
+      "Environment=NODE_ENV=production",
+      // The box owner's variables (#88, base v0.10.0+; the `-` makes an older box start without them).
+      "EnvironmentFile=-/etc/kvbox/env",
       "Restart=always",
       "RestartSec=2",
       "",
@@ -3560,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);
@@ -3584,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>`);
     }
@@ -3610,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);
@@ -3677,12 +3840,128 @@ var rmCommand6 = new Command55("rm").alias("remove").description("delete a volum
 var volumeCommand = new Command56("volume").aliases(["volumes", "vol"]).description("disks of their own: create one, attach it to a box at /mnt/<name>, move it to another box later").addCommand(createCommand).addCommand(lsCommand6).addCommand(attachCommand).addCommand(detachCommand).addCommand(rmCommand6);
 for (const cmd of volumeCommand.commands) cmd.option("--org <slug>", "act in this org (- for your personal volumes)");
 
+// src/commands/env/index.ts
+import { Command as Command60 } from "commander";
+
+// src/commands/env/ls.ts
+import { Command as Command57 } from "commander";
+
+// src/commands/env/shared.ts
+function requireCloud2(client) {
+  if (client.target.kind === "local") throw new KvboxError("kvbox env needs kvbox.sh: kvbox login first");
+  return client.target.org ?? client.target.user ?? "you";
+}
+function reach(boxes, verb) {
+  if (boxes === 0) return verb === "get" ? "no boxes yet, every new one gets it" : "no boxes yet";
+  return boxes === 1 ? `1 box ${verb}s it when it next starts` : `${boxes} boxes ${verb} it when they next start`;
+}
+
+// src/commands/env/ls.ts
+var lsCommand7 = new Command57("ls").alias("list").description("list the variables (a secret shows as (sealed))").option("--json", "print as JSON").action(async (opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals(), { autoStart: false });
+  try {
+    const owner = requireCloud2(client);
+    const vars = await client.listEnv();
+    if (opts.json) {
+      json(vars);
+      return;
+    }
+    if (vars.length === 0) {
+      info(`no variables for ${owner} yet; set one with: kvbox env set NAME value`);
+      return;
+    }
+    table(vars.map((v) => ({ name: v.name, value: v.secret ? color.dim("(sealed)") : v.value, updated: age(v.updatedAt) })));
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/env/rm.ts
+import { Command as Command58 } from "commander";
+var rmCommand7 = new Command58("rm").alias("remove").description("remove variables; boxes lose them when they next start").argument("<names...>", "variable names").option("-y, --yes", "do not ask for confirmation").option("--json", "print as JSON").action(async (names, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals(), { autoStart: false });
+  try {
+    const owner = requireCloud2(client);
+    if (!await confirm(`Remove ${names.join(", ")} from ${owner}'s variables?`, opts.yes ?? false)) {
+      info("cancelled");
+      process.exitCode = 1;
+      return;
+    }
+    const changes = [];
+    const failed = [];
+    for (const name of names) {
+      try {
+        const c = await spin(`removing ${name}\u2026`, client.removeEnv(name));
+        changes.push(c);
+        if (!opts.json) info(`${color.green("\u2713")} removed ${c.name} from ${owner}: ${reach(c.boxes, "lose")}`);
+      } catch (err) {
+        failed.push({ name, err });
+      }
+    }
+    if (changes.length === 0 && failed.length > 0) throw failed[0].err;
+    if (opts.json) json(changes);
+    for (const f of failed) warn(`${color.red("\u2717")} ${f.name}: ${f.err.message}`);
+    if (failed.length > 0) process.exitCode = 1;
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/env/set.ts
+import { Command as Command59 } from "commander";
+
+// ../shared/src/env.ts
+var ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var ENV_RESERVED = ["PATH", "HOME", "USER", "SHELL"];
+var ENV_MAX_VALUE_BYTES = 4096;
+function envNameProblem(name) {
+  if (!ENV_NAME_RE.test(name)) return `${JSON.stringify(name)} is not a variable name: letters, digits and _, not starting with a digit`;
+  if (ENV_RESERVED.includes(name)) return `${name} is the box's own and cannot be set`;
+  if (name.startsWith("KVBOX_")) return `${name}: names starting with KVBOX_ are kept for kvbox`;
+  return null;
+}
+function envValueProblem(value) {
+  if (/[\n\r\0]/.test(value)) return "a value is one line: no line breaks (base64 a multi-line value such as a key file)";
+  if (Buffer.byteLength(value, "utf8") > ENV_MAX_VALUE_BYTES) return `a value is at most ${ENV_MAX_VALUE_BYTES / 1024} KB`;
+  return null;
+}
+
+// src/commands/env/set.ts
+var setCommand2 = new Command59("set").description("add or change a variable; boxes get it when they next start").argument("[name]", "variable name, e.g. DATABASE_URL (asked for when left out)").argument("[value]", "its value (asked for when left out; hidden with --secret)").option("--secret", "write-only: the value is never shown again, by any command").option("--json", "print as JSON").action(async (nameArg, valueArg, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals(), { autoStart: false });
+  try {
+    const owner = requireCloud2(client);
+    const ask = interactive();
+    if ((nameArg === void 0 || valueArg === void 0) && !ask) throw new KvboxError("give the name and the value: kvbox env set NAME VALUE (or run it in a terminal to be asked)");
+    const name = nameArg ?? await text("Variable name", { validate: (a) => envNameProblem(a) ?? void 0 });
+    const nameProblem = envNameProblem(name);
+    if (nameProblem !== null) throw new KvboxError(nameProblem);
+    const value = valueArg ?? (opts.secret ? await hiddenText(`Value for ${name}`) : await text(`Value for ${name}`, { trim: false }));
+    const valueProblem = envValueProblem(value);
+    if (valueProblem !== null) throw new KvboxError(valueProblem);
+    const change = await spin(`setting ${name}\u2026`, client.setEnv(name, { value, secret: opts.secret ?? false }));
+    if (opts.json) {
+      json(change);
+      return;
+    }
+    const what = opts.secret ? `${name} (secret)` : name;
+    info(`${color.green("\u2713")} set ${what} for ${owner}: ${reach(change.boxes, "get")}`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/env/index.ts
+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/program.ts
 function buildProgram() {
-  const program = new Command57("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 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();
   program.addCommand(vmCommand);
   program.addCommand(snapshotsCommand);
   program.addCommand(volumeCommand);
+  program.addCommand(envCommand);
   program.addCommand(serverCommand);
   program.addCommand(loginCommand);
   program.addCommand(logoutCommand);
@@ -3695,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");