@thebaycloud/cli 1.0.0 → 1.1.0

package/index.js

@@ -2,10 +2,26 @@
 "use strict";
 
 /*
- * bay — the deploy/debug surface for a coding agent.
+ * bay — the ship/debug surface for a coding agent.
  * Designed for agents, not humans: no interactive prompts, --json everywhere,
  * token auth (a human logs in once, the agent inherits the token), stdout=data,
  * stderr=logs, meaningful exit codes.
+ *
+ * THE OLD NAME STILL WORKS, EVERYWHERE, AND IS NOT DEPRECATED.
+ *
+ * The command is `bay`; package.json also installs it as `supersonic`. The
+ * config is ~/.bay; ~/.supersonic is still read. The variables are BAY_TOKEN and
+ * BAY_URL; SUPERSONIC_TOKEN and SUPERSONIC_URL are still honoured. Every one of
+ * those pairs exists because the old spelling is written into scripts, CI
+ * configs and agent prompts that nobody is going to edit, and a rename that
+ * silently stops reading them does not read as a rename — it reads as the
+ * platform signing you out and losing your account.
+ *
+ * The wire is a different question and the answer is no. `x-supersonic-*`
+ * headers, `SUPERSONIC_RUN`, `SUPERSONIC_CODE_BUCKET` and `supersonic.json` are
+ * what the CONTROL PLANE reads, not what a person types. Renaming them here
+ * would break every deploy against a server that has not been renamed on the
+ * same afternoon, so they stay until the server moves first.
  */
 
 const fs = require("fs");
@@ -16,19 +32,35 @@ const { spawn, spawnSync } = require("child_process");
 const { readEnvFiles, selectEnv, encodeEnvHeader } = require("./lib/envfile");
 const { joinExecArgs } = require("./lib/exec-args");
 const { whoHeader } = require("./lib/who");
-const { deletionRefusal } = require("./lib/confirm");
-
 const brand = require("./lib/brand");
+const { deletionRefusal } = require("./lib/confirm");
+const { configDirIn, envVarFrom } = require("./lib/home");
 
-// Copy an existing sign-in across to the new path, once, before anything reads
-// it. See lib/brand.js: a published CLI lives on other people's machines until
-// they upgrade, so nothing here may simply be renamed.
-brand.migrateConfig();
-
-const CFG_DIR = brand.configDir();
+/**
+ * Where the session lives: ~/.bay, unless ~/.supersonic is the one that exists.
+ *
+ * Not "read both and merge" — that would have two files disagreeing about which
+ * account you are, with the winner decided by the order of two lines. The rule
+ * is: the new directory if it is there, otherwise the old one if IT is there,
+ * otherwise the new one. So an existing user stays signed in and keeps writing
+ * to the file they already have, and a new one never creates the old name.
+ */
+const CFG_DIR = configDirIn(os.homedir(), fs.existsSync, path.join);
 const CFG = path.join(CFG_DIR, "config.json");
+// From lib/brand, not a second copy of it.
 const DEFAULT_URL = brand.DEFAULT_URL;
 
+/**
+ * A variable under its new name, falling back to the old one.
+ *
+ * `BAY_TOKEN` is the name now; `SUPERSONIC_TOKEN` is what is exported in every
+ * CI job that already ships to this platform. The new name wins when both are
+ * set, which is the only sane precedence: somebody who set both was migrating.
+ */
+function envVar(name) {
+  return envVarFrom(process.env, name);
+}
+
 // ---------- output ----------
 // A reader that stops reading — `bay check | head -5`, an agent piping into
 // grep — closes the pipe under us, and Node turns that into an unhandled EPIPE:
@@ -41,7 +73,7 @@ const COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
 const c = (n) => (s) => (COLOR ? `\x1b[${n}m${s}\x1b[0m` : String(s));
 const dim = c("2"), bold = c("1"), green = c("32"), red = c("31"), cyan = c("36"), yellow = c("33");
 // Set once a deploy knows its slug: every progress line is also appended to
-// ~/.bay/deploys/<slug>.log, so a build survives the terminal it was
+// <config dir>/deploys/<slug>.log, so a build survives the terminal it was
 // started in. Best-effort — a log that cannot be written must never stop a deploy.
 let deployLog = null;
 function startDeployLog(slug) {
@@ -60,12 +92,7 @@ function print(s) { process.stdout.write(s + "\n"); }         // data -> stdout
 function die(s, code = 1) { process.stderr.write(red("✗ ") + s + "\n"); process.exit(code); }
 
 /** What the last green deploy decided, written beside the project. */
-// Written under the new name, read under either: a repository that already has
-// `supersonic.lock.json` must keep being understood, or the next deploy decides
-// everything again from scratch and quietly disagrees with the file sitting
-// next to it. See lib/brand.js.
-const LOCKFILE = "bay.lock.json";
-function lockfilePath() { return brand.projectFile(process.cwd(), "lock.json"); }
+const LOCKFILE = "supersonic.lock.json";
 
 /**
  * Record the decisions a successful deploy made.
@@ -93,14 +120,14 @@ function writeLockfile(decided, slug) {
   if (!decided || typeof decided !== "object") return;
   try {
     const body = JSON.stringify({
-      $comment: "Written by bay after a successful deploy. Safe to commit, safe to delete.",
+      $comment: "Written by bay after a successful ship. Safe to commit, safe to delete.",
       slug: slug || undefined,
       decided,
     }, null, 2) + "\n";
-    const path = lockfilePath();
+    const path = require("node:path").join(process.cwd(), LOCKFILE);
     if (require("node:fs").existsSync(path) && require("node:fs").readFileSync(path, "utf8") === body) return;
     require("node:fs").writeFileSync(path, body);
-    info(dim(`  wrote ${LOCKFILE} — what this deploy decided, so you can see it and change it`));
+    info(dim(`  wrote ${LOCKFILE} — what this ship decided, so you can see it and change it`));
   } catch { /* never fail a green deploy over a note about it */ }
 }
 function json(o) { print(JSON.stringify(o, null, 2)); }
@@ -108,11 +135,19 @@ function json(o) { print(JSON.stringify(o, null, 2)); }
 // ---------- config ----------
 function loadCfg() { try { return JSON.parse(fs.readFileSync(CFG, "utf8")); } catch { return {}; } }
 function saveCfg(cfg) { fs.mkdirSync(CFG_DIR, { recursive: true }); fs.writeFileSync(CFG, JSON.stringify(cfg, null, 2)); }
-function baseUrl() { return (brand.envAny("URL") || loadCfg().url || DEFAULT_URL).replace(/\/$/, ""); }
-function token() { return brand.envAny("TOKEN") || loadCfg().token || ""; }
+function baseUrl() { return (envVar("URL") || loadCfg().url || DEFAULT_URL).replace(/\/$/, ""); }
+function token() { return envVar("TOKEN") || loadCfg().token || ""; }
 
 // ---------- api ----------
-async function api(pathname, { method = "GET", body, stream = false } = {}) {
+/**
+ * @param {object} [opts]
+ * @param {boolean} [opts.quiet] Don't narrate a 200-with-an-error-field. Some
+ *   routes — the database one — answer 200 and put the failure in the body,
+ *   because for them "this database does not exist" is an answer rather than a
+ *   transport failure. Their callers print it themselves, and without this the
+ *   reader sees the same sentence twice, once dim and once red.
+ */
+async function api(pathname, { method = "GET", body, stream = false, quiet = false } = {}) {
   const tok = token();
   if (!tok) die("not authenticated — run: bay login");
   const res = await fetch(baseUrl() + pathname, {
@@ -129,7 +164,7 @@ async function api(pathname, { method = "GET", body, stream = false } = {}) {
   if (stream) return res;
   const data = await res.json().catch(() => ({}));
   if (!res.ok && data.error) die(data.error);
-  if (data.error) info(dim("! " + data.error));
+  if (data.error && !quiet) info(dim("! " + data.error));
   return data;
 }
 
@@ -142,7 +177,7 @@ function openBrowser(url) {
 
 // ---------- commands ----------
 async function login(args) {
-  const url = (args.url || brand.envAny("URL") || DEFAULT_URL).replace(/\/$/, "");
+  const url = (args.url || envVar("URL") || DEFAULT_URL).replace(/\/$/, "");
   // Explicit token (agents / CI / headless).
   if (args.token) {
     const ok = await validToken(url, String(args.token));
@@ -157,7 +192,7 @@ async function login(args) {
 // Create an account without leaving the terminal: opens the browser to sign up,
 // then the web hands a token back and the agent can continue straight to deploy.
 async function signup(args) {
-  const url = (args.url || brand.envAny("URL") || DEFAULT_URL).replace(/\/$/, "");
+  const url = (args.url || envVar("URL") || DEFAULT_URL).replace(/\/$/, "");
   await loopbackAuth(url, "/signup", "signed up");
 }
 
@@ -213,7 +248,7 @@ async function ensureAuth() {
   const url = baseUrl();
   info(dim("Not signed in — opening a browser to sign in (just this once)…"));
   const tok = await runLoopback(url, "/cli");
-  if (!tok) die("sign-in timed out — run `bay login`, then `bay deploy` again");
+  if (!tok) die("sign-in timed out — run `bay login`, then `bay ship` again");
   saveCfg({ ...loadCfg(), url, token: tok });
   info(green("✓ ") + "signed in — continuing…");
 }
@@ -233,9 +268,9 @@ async function whoami(args) {
   // just that a token exists.
   const res = await fetch(baseUrl() + "/api/account", { headers: { Authorization: "Bearer " + tok } });
   const acct = res.ok ? await res.json().catch(() => ({})) : {};
-  if (args.json) return json({ loggedIn: res.ok, url: baseUrl(), email: acct.email || null, plan: acct.plan || null, source: brand.envAny("TOKEN") ? "env" : "config" });
+  if (args.json) return json({ loggedIn: res.ok, url: baseUrl(), email: acct.email || null, plan: acct.plan || null, source: envVar("TOKEN") ? "env" : "config" });
   if (!res.ok) return die("token invalid — run: bay login");
-  const src = process.env.BAY_TOKEN ? "env token" : "saved token";
+  const src = envVar("TOKEN") ? "env token" : "saved token";
   const who = acct.email ? " as " + acct.email : "";
   const plan = acct.plan ? ` · ${acct.plan}` : "";
   print(`logged in to ${baseUrl()}${who}${plan} (${src})`);
@@ -250,7 +285,7 @@ async function apps(args) {
   const d = await api("/api/apps");
   const list = d.apps || [];
   if (args.json) return json(list);
-  if (!list.length) { info("no apps yet — deploy one with: bay deploy"); return; }
+  if (!list.length) { info("no apps yet — ship one with: bay ship"); return; }
   for (const a of list) {
     // The list endpoint has always sent `status: "building"` for a deploy in
     // flight and the CLI has always thrown it away, so an app that was building
@@ -259,7 +294,7 @@ async function apps(args) {
     const building = a.status === "building";
     const dot = a.ready ? green("●") : building ? yellow("◐") : red("○");
     const note = building ? dim(`  ${a.stage || "deploying…"}`) : "";
-    print(`${dot} ${bold(a.slug.padEnd(22))} ${dim(a.url || `${a.slug}.thebay.cloud`)}${note}`);
+    print(`${dot} ${bold(a.slug.padEnd(22))} ${dim(a.url || `${a.slug}.${brand.DOMAIN}`)}${note}`);
   }
 }
 
@@ -273,7 +308,9 @@ async function status(args) {
   // answer to a question it could not yet answer.
   const dot = d.ready ? green("● live") : d.deploying ? yellow("◐ deploying") : red("○ down");
   print(`${bold(app)}  ${dot}${d.deploying && d.stage ? dim(` · ${d.stage}`) : ""}`);
-  print(dim("  url      ") + `${app}.thebay.cloud`);
+  // The server's own answer, for the same reason `open` asks for it: the root is
+  // not this file's to know.
+  print(dim("  url      ") + (d.url || `https://${app}.${brand.DOMAIN}`));
   print(dim("  revision ") + (d.revision || "—"));
   print(dim("  image    ") + (d.image ? d.image.split("/").pop() : "—"));
   print(dim("  region   ") + (d.region || "—"));
@@ -291,40 +328,105 @@ async function status(args) {
   }
 }
 
+/**
+ * `bay logs` — the same reader the dashboard uses.
+ *
+ * A FILTER, not a line count. An app printing a thousand lines an hour makes
+ * "the last sixty" the wrong question, so: a bare level, `key=value` for a facet,
+ * and anything else is a search.
+ *
+ *   bay logs                      the last hundred, newest first
+ *   bay logs error                errors only
+ *   bay logs --source edge        requests
+ *   bay logs --follow             a live tail
+ *   bay logs checkout --follow    a live tail, filtered
+ *
+ * `--follow` is a real stream now. It used to poll every 2.5 seconds and
+ * de-duplicate against a Set of every line it had seen — which meant lines
+ * arrived in clumps, memory grew until the Set was thrown away wholesale, and a
+ * line could still be missed if it landed between two polls with the same text.
+ */
 async function logs(args) {
   const app = needApp(args);
   const qs = new URLSearchParams();
-  if (args.severity) qs.set("severity", args.severity);
+
+  // Free words are the search. `bay logs error` is the level, because that is
+  // what somebody means by it.
+  const words = (args._ || []).slice(1).filter((w) => w !== app);
+  const levels = ["debug", "info", "warn", "error"];
+  const text = [];
+  for (const w of words) {
+    if (levels.includes(String(w).toLowerCase())) qs.set("level", String(w).toLowerCase());
+    else text.push(w);
+  }
+  if (text.length) qs.set("q", text.join(" "));
+
+  if (args.source) qs.set("source", args.source);
+  if (args.level) qs.set("level", args.level);
+  // `--severity ERROR` is what this took before the log view existed.
+  if (args.severity) qs.set("level", String(args.severity).toLowerCase().replace("warning", "warn"));
+  if (args.status) qs.set("status", String(args.status));
+  if (args.path) qs.set("path", args.path);
+  if (args.face) qs.set("face", args.face);
+  if (args.window) qs.set("window", args.window);
+  if (args.since) qs.set("window", args.since);
   if (args.limit) qs.set("limit", String(args.limit));
-  if (args.since) qs.set("since", args.since);
-  const q = qs.toString() ? "?" + qs.toString() : "";
 
   if (args.follow) {
-    let seen = new Set();
     info(dim(`tailing ${app} — ctrl-c to stop`));
-    for (;;) {
-      const d = await api(`/api/apps/${app}/logs${q}`);
-      for (const l of d.logs || []) {
-        const key = l.time + l.message;
-        if (seen.has(key)) continue;
-        seen.add(key);
-        print(logLine(l));
+    const res = await api(`/api/apps/${app}/logs/tail?${qs}`, { stream: true });
+    if (!res.ok || !res.body) die("could not open the tail");
+    // SSE by hand: frames are separated by a blank line, and a frame we do not
+    // recognise (the heartbeat comment) is skipped rather than parsed.
+    let buf = "";
+    for await (const chunk of res.body) {
+      buf += Buffer.from(chunk).toString("utf8");
+      let cut;
+      while ((cut = buf.indexOf("\n\n")) !== -1) {
+        const frame = buf.slice(0, cut);
+        buf = buf.slice(cut + 2);
+        const ev = /^event: (.+)$/m.exec(frame);
+        const data = /^data: (.*)$/m.exec(frame);
+        if (!ev || !data) continue;
+        if (ev[1] === "row") { try { print(logLine(JSON.parse(data[1]))); } catch { /* not a row */ } }
+        else if (ev[1] === "broken") {
+          // A tail that stops silently looks exactly like an app that went quiet.
+          try { info(red("the tail stopped: " + JSON.parse(data[1]).why)); } catch { /* ignore */ }
+          return;
+        }
       }
-      if (seen.size > 2000) seen = new Set();
-      await new Promise((r) => setTimeout(r, 2500));
     }
+    return;
   }
 
-  const d = await api(`/api/apps/${app}/logs${q}`);
-  if (args.json) return json(d.logs || []);
-  if (!(d.logs || []).length) { info("no logs in that window"); return; }
-  for (const l of d.logs) print(logLine(l));
+  const d = await api(`/api/apps/${app}/logs/query?${qs}`);
+  const rows = d.rows || [];
+  if (args.json) return json(rows);
+  if (!rows.length) {
+    // "Nothing since" and "no logs" are different facts: a file tail has no
+    // history, so an app that has printed nothing has no lines and is not broken.
+    info(`nothing since ${(d.since || "").slice(0, 19).replace("T", " ")}`);
+    return;
+  }
+  // Oldest first on a terminal: you read down the page, and the newest line
+  // should be the one left above your prompt.
+  for (const r of rows.slice().reverse()) print(logLine(r));
+  if (d.cursor) info(dim("older lines exist — narrow with a filter, or raise --limit"));
 }
 
+/** One row, from the shared reader. Falls back to the old shape so an older
+ *  control plane still prints. */
 function logLine(l) {
-  const sev = (l.severity || "").toUpperCase();
-  const tag = sev === "ERROR" || sev === "CRITICAL" ? red(sev) : sev === "WARNING" ? cyan(sev) : dim(sev || "INFO");
-  return `${dim((l.time || "").slice(11, 19))} ${tag} ${l.message}`;
+  const at = dim(String(l.at || l.time || "").slice(11, 19));
+  const level = String(l.level || l.severity || "info").toLowerCase();
+  const tag = level.startsWith("err") || level === "critical" ? red("ERROR")
+    : level.startsWith("warn") ? cyan("WARN ")
+    : dim(level === "debug" ? "DEBUG" : "INFO ");
+  const src = l.source && l.source !== "app" ? dim(` ${l.source}`) : "";
+  const body = l.http
+    ? `${l.http.method} ${l.http.path} ${l.http.status} ${l.http.ms}ms`
+    : l.msg ?? l.message ?? "";
+  return `${at} ${tag}${src} ${body}`;
 }
 
 async function errors(args) {
@@ -342,10 +444,25 @@ async function diagnose(args) {
   const d = await api(`/api/apps/${app}/diagnose`, { method: "POST", body: { error: args.error } });
   if (args.json) return json(d);
   if (d.healthy) { print(green("✓ ") + d.message); return; }
+
+  // A DIAGNOSIS WITHOUT A PROMPT IS STILL A DIAGNOSIS.
+  //
+  // The server answers `{healthy:false, message:"… is still deploying — nothing
+  // to diagnose until it lands"}` for a build that has not finished, and this
+  // used to fall through to `(no prompt returned)` and throw the message away. A
+  // deploy report recorded exactly that: twelve minutes into a stalled build, the
+  // command whose job is to explain the failure printed an empty prompt and no
+  // reason.
+  if (!d.fixPrompt) {
+    if (d.message) { info(d.message); return; }
+    info("nothing to diagnose — no failure was recorded for this app");
+    return;
+  }
+
   info(dim("diagnosing: ") + (d.subject || d.error || "").slice(0, 200));
   print("");
   print(bold("Fix prompt (paste into your coding agent):"));
-  print(d.fixPrompt || "(no prompt returned)");
+  print(d.fixPrompt);
 }
 
 async function env(args) {
@@ -354,7 +471,10 @@ async function env(args) {
   if (!sub) {
     const d = await api(`/api/apps/${app}/env`);
     if (args.json) return json(d.keys || []);
-    if (!(d.keys || []).length) { info("no env vars set"); return; }
+    // The note, when there is one. "No env vars set" and "we could not read them"
+    // are opposite facts, and printing the first about the second is how a deploy
+    // report came to record a variable as missing that was actually there.
+    if (!(d.keys || []).length) { info(d.note || "no env vars set"); return; }
     for (const k of d.keys) print(k);
     return;
   }
@@ -381,6 +501,335 @@ async function env(args) {
   die(`unknown env subcommand: ${sub}`);
 }
 
+// ---------- the rest of the platform ----------
+//
+// Everything below exists because the answer to "can I do that from the CLI?"
+// has to be yes. A command that sends someone to the dashboard for one setting
+// sends an AGENT nowhere at all: it cannot open a browser, cannot click, and
+// cannot tell its user what it could not do. Domains, access, the database, the
+// connected repository, the plan and the tokens were all dashboard-only, and
+// each of them is a place an agent-driven deploy stopped.
+//
+// None of them needed a new endpoint. The control plane resolves a Bearer token
+// exactly where it resolves a session cookie (apps/web/lib/session.ts), so every
+// route the dashboard calls already answers a CLI that asks.
+
+/**
+ * The custom domains attached to one app: read them, attach one, detach one.
+ *
+ * The DNS record is printed by `printRecord` from what the SERVER decided, never
+ * from a rule this file carries. An apex cannot be a CNAME and a subdomain
+ * should be one, and that decision lives in apps/web/lib/dns-record.ts — a copy
+ * here would agree today and, the first time its public-suffix list grows, tell
+ * somebody to create a record their registrar refuses.
+ */
+async function domains(args) {
+  const app = needApp(args);
+  const [, sub, host] = args._;
+
+  if (!sub) {
+    const d = await api(`/api/apps/${app}/domains`);
+    if (args.json) return json(d);
+    const list = d.domains || [];
+    if (!list.length) {
+      info(`no domain connected — ${bold(`bay domains ${app} add <hostname>`)}`);
+      if (d.allowed === false) info(dim("custom domains are not on this account's plan"));
+      return;
+    }
+    for (const dom of list) printDomain(dom, d.dns);
+    // Said once, under the list, and only when it is true. A private app cannot
+    // answer at a domain it does not own the cookie for — the edge sends those
+    // visitors back to the platform address — so a domain that is `live` and an
+    // app that is private is a working certificate onto a redirect.
+    if (d.visibility && d.visibility !== "public") {
+      print("");
+      info(dim(`${app} is ${d.visibility}: visitors at a custom domain are sent back to its platform address to sign in.`));
+      info(dim(`make it public with: bay share ${app} public`));
+    }
+    return;
+  }
+
+  if (sub === "add") {
+    if (!host) die(`usage: bay domains ${app} add <hostname>`);
+    const d = await api(`/api/apps/${app}/domains`, { method: "POST", body: { hostname: host } });
+    if (args.json) return json(d);
+    print(green("✓ ") + `${d.domain.hostname} is attached to ${app}`);
+    printDomain(d.domain, d.dns);
+    return;
+  }
+
+  if (sub === "remove" || sub === "rm") {
+    if (!host) die(`usage: bay domains ${app} remove <hostname>`);
+    const d = await api(`/api/apps/${app}/domains?hostname=${encodeURIComponent(host)}`, { method: "DELETE" });
+    if (args.json) return json(d);
+    print(green("✓ ") + `${host} detached — its certificate is gone, so stop pointing DNS at us`);
+    return;
+  }
+
+  die(`unknown: domains ${sub}\nusage: bay domains <app> [add <hostname> | remove <hostname>]`);
+}
+
+/** One domain, its state, and — while it is not live — the record to create. */
+function printDomain(d, dns) {
+  const state = {
+    live: () => `${green("● live")}`,
+    securing: () => `${yellow("◐ securing")} ${dim("— the certificate is being issued, usually a few minutes")}`,
+    pending_dns: () => `${yellow("○ waiting")} ${dim("— for the DNS record below")}`,
+    failed: () => `${red("✗ failed")}`,
+  }[d.status];
+  print(`${bold(d.hostname)}  ${state ? state() : dim(d.status)}`);
+  if (d.detail) print(dim("  " + d.detail));
+  if (d.status !== "live") printRecord(d, dns);
+}
+
+/**
+ * The record, as the fields a DNS panel actually asks for.
+ *
+ * `guessed` is printed rather than hidden. It means the server could not place
+ * the name against its suffix list and fell back to `A`, which works everywhere
+ * — but somebody moving a subdomain would rather know they can use a CNAME.
+ */
+function printRecord(d, dns) {
+  const r = d.record;
+  if (!r) {
+    // An older control plane, which sends `dns` without deciding the record. Both
+    // options, plainly, rather than a rule this file would have to keep.
+    if (!dns) return;
+    print(dim("  create ONE of these where your DNS is managed:"));
+    print(dim("    A     @    ") + dns.ip + dim("   (at the root of the domain)"));
+    print(dim("    CNAME <sub> ") + dns.cname + dim("   (for a subdomain)"));
+    return;
+  }
+  print(dim("  create this record where your DNS is managed:"));
+  print(dim("    type  ") + r.type);
+  print(dim("    name  ") + r.name + (r.name === "@" ? dim("   (the root of the domain)") : ""));
+  print(dim("    value ") + r.value);
+  if (r.guessed) print(dim("    (A works at any name; a subdomain could also use a CNAME to " + (dns ? dns.cname : "its platform address") + ")"));
+}
+
+/**
+ * Who can open the app: the visibility, the people, and the rules.
+ *
+ * `bay share <app>` alone shows it. Everything else is one word — a
+ * visibility, or add/remove with an address or a @domain — and the parsing is in
+ * lib/share-args.js, because reading `acme.com` as a person instead of as a
+ * company is a mistake that would not look like one afterwards.
+ */
+async function share(args) {
+  const app = needApp(args);
+  const { parseShare, shareBody } = require("./lib/share-args");
+  const action = parseShare(args._.slice(1));
+  if (action.kind === "error") die(action.why);
+
+  const path = `/api/apps/${app}/share`;
+  const d =
+    action.kind === "show" ? await api(path)
+      : action.kind === "visibility" ? await api(path, { method: "POST", body: { visibility: action.visibility } })
+        : await api(path, { method: "POST", body: shareBody(action) });
+
+  if (args.json) return json(d);
+
+  if (action.kind === "add") {
+    print(green("✓ ") + (action.audience === "email"
+      ? `${action.value} can open ${app} — they have been emailed the link`
+      : `anyone with an @${action.value} address can open ${app}`));
+  }
+  if (action.kind === "remove") print(green("✓ ") + `removed ${action.value}`);
+  printAccess(app, d);
+}
+
+function printAccess(app, d) {
+  const said = {
+    private: `${red("● private")} ${dim("— only you")}`,
+    shared: `${yellow("● shared")} ${dim("— you, and the people and rules below")}`,
+    public: `${green("● public")} ${dim("— anyone with the link, no sign-in")}`,
+  }[d.visibility];
+  print(`${bold(app)}  ${said || dim(String(d.visibility))}`);
+
+  for (const email of d.grants || []) print(dim("  person ") + email);
+  for (const domain of d.domains || []) print(dim("  rule   ") + `everyone @${domain}`);
+  // Said once, under the rules, because it is the difference between a rule that
+  // works and a person who cannot get in: a rule admits an address the identity
+  // provider PROVED — Google, or a verified GitHub address. Somebody who signed
+  // up with a password at the same domain is refused, and the page they see says
+  // to sign in with Google instead.
+  if ((d.domains || []).length) info(dim("  a rule admits verified addresses only — password signups at that domain are not let in"));
+
+  // A pending request is somebody who is currently looking at a locked door. It
+  // is the only line here that is waiting on the reader, so it says the command
+  // that answers it.
+  for (const email of d.requests || []) {
+    print(`${yellow("  asking")} ${email} ${dim(`— bay share ${app} add ${email}`)}`);
+  }
+
+  if (d.workspaceDomain && !(d.domains || []).includes(d.workspaceDomain)) {
+    info(dim(`  everyone at your company: bay share ${app} add @${d.workspaceDomain}`));
+  }
+}
+
+/**
+ * The app's database, read-only, from here.
+ *
+ * `db <app>` lists the tables, `db <app> <table>` reads rows, and `--sql`
+ * asks one SELECT. Read-only is the server's rule, not a convention this file
+ * follows: the route refuses anything that does not begin with SELECT, and
+ * refuses a second statement. Which is the right rule — a CLI that could DROP a
+ * production table on a typo'd argument is not a tool an agent should be handed.
+ */
+async function db(args) {
+  const app = needApp(args);
+  const [, table] = args._;
+  const { renderTable } = require("./lib/rows");
+
+  if (args.sql) {
+    const d = await api(`/api/apps/${app}/db`, { method: "POST", body: { sql: String(args.sql) }, quiet: true });
+    if (args.json) return json(d);
+    if (d.error) die(d.error);
+    if (!(d.rows || []).length) { info("no rows"); return; }
+    for (const l of renderTable(d.columns, d.rows)) print(l);
+    return;
+  }
+
+  if (!table) {
+    const d = await api(`/api/apps/${app}/db`, { quiet: true });
+    if (args.json) return json(d);
+    if (d.error) die(d.error);
+    const list = d.tables || [];
+    if (!list.length) { info("this database has no tables yet"); return; }
+    info(dim(d.database));
+    for (const t of list) {
+      const n = t.rowsExact ? String(t.rows) : `~${t.rows}`;
+      print(`${bold(t.name.padEnd(28))} ${dim(n.padStart(8) + " rows  " + t.columns + " cols")}`);
+    }
+    info(dim(`\nread one: bay db ${app} <table>`));
+    return;
+  }
+
+  const qs = new URLSearchParams({ table });
+  if (args.limit) qs.set("limit", String(args.limit));
+  if (args.offset) qs.set("offset", String(args.offset));
+  const d = await api(`/api/apps/${app}/db?${qs.toString()}`, { quiet: true });
+  if (args.json) return json(d);
+  if (d.error) die(d.error);
+  const names = (d.columns || []).map((c) => (typeof c === "string" ? c : c.name));
+  for (const l of renderTable(names, d.rows || [])) print(l);
+  // The count is the reason `--limit`/`--offset` exist, so it is said even when
+  // one page is the whole table.
+  const shown = (d.rows || []).length;
+  info(dim(`${shown} of ${d.totalExact ? d.total : "~" + d.total} rows${d.orderedBy ? ", " + d.orderedBy : ""}`));
+}
+
+/**
+ * The repository this app follows, and whether a push to it ships.
+ *
+ * Connecting one is still a browser flow — it installs a GitHub App, which is
+ * GitHub's consent screen and cannot be automated away. Everything after that
+ * is here: which branch, whether pushes deploy, and disconnecting.
+ */
+async function git(args) {
+  const app = needApp(args);
+  const [, sub] = args._;
+  const path = `/api/apps/${app}/git`;
+
+  if (sub === "disconnect") {
+    const d = await api(path, { method: "DELETE" });
+    if (args.json) return json(d);
+    print(green("✓ ") + `${app} no longer follows a repository — it keeps running, and reship still works`);
+    return;
+  }
+
+  const wantsBranch = typeof args.branch === "string";
+  const wantsAuto = args.auto !== undefined;
+  if (wantsBranch || wantsAuto) {
+    const body = {};
+    if (wantsBranch) body.branch = args.branch;
+    if (wantsAuto) {
+      const on = args.auto === true || /^(on|yes|true)$/i.test(String(args.auto));
+      const off = /^(off|no|false)$/i.test(String(args.auto));
+      if (!on && !off) die(`--auto takes on or off, not "${args.auto}"`);
+      body.autoDeploy = on;
+    }
+    const d = await api(path, { method: "PUT", body });
+    if (args.json) return json(d);
+    print(green("✓ ") + `${d.repo} · ${d.branch} · ${d.autoDeploy ? "ships on push" : "manual"}`);
+    return;
+  }
+
+  const d = await api(path);
+  if (args.json) return json(d);
+  if (!d.connected) {
+    info(`${app} follows no repository`);
+    info(dim(`connect one at ${baseUrl()}/apps/${app} — it installs a GitHub App, which needs a browser`));
+    return;
+  }
+  print(`${bold(d.repo)}  ${dim(d.url)}`);
+  print(dim("  branch ") + d.branch);
+  print(dim("  push   ") + (d.autoDeploy ? green("ships automatically") : "does nothing until you reship"));
+}
+
+/**
+ * The plan, and every meter that can stop a deploy.
+ *
+ * `whoami` says which account. This says what that account may still do — which
+ * is the question behind every 402 the API returns, and the one an agent should
+ * be able to answer before it starts an eleven-minute build.
+ */
+async function plan(args) {
+  const d = await api("/api/account");
+  if (args.json) return json(d);
+
+  print(`${bold(d.plan || "free")}${d.locked ? red("  · locked") : ""}${d.email ? dim("  " + d.email) : ""}`);
+  const u = d.usage || {};
+  // null is the wire form of unlimited — see the `cap()` in the account route.
+  const meter = (label, used, max) =>
+    print(dim("  " + label.padEnd(12)) + `${used ?? 0}${max === null || max === undefined ? dim(" of unlimited") : dim(" of " + max)}`);
+  meter("apps", u.apps, u.maxApps);
+  meter("public", u.publicApps, u.maxPublicApps);
+  meter("builds", u.builds, u.monthlyBuilds);
+  meter("agent runs", u.agentRuns, u.monthlyAgentRuns);
+
+  const f = d.features || {};
+  const has = (on, name) => (on ? green("✓ ") + name : dim("· " + name));
+  print("  " + [has(f.autoFix, "auto-fix"), has(f.customDomains, "custom domains"), has(f.canRemoveBadge, "badge off")].join("   "));
+  info(dim(`\nchange plan: ${baseUrl()}/settings`));
+}
+
+/**
+ * Every CLI holding a key to this account, and the way to take one back.
+ *
+ * A token is minted in a browser — that is the whole point of the loopback flow
+ * — but revoking one must not need the same browser. A laptop that is gone, a CI
+ * runner that was decommissioned, a token pasted into the wrong terminal: those
+ * are moments when a person wants one command, not a dashboard.
+ */
+async function tokens(args) {
+  const [sub, id] = args._;
+
+  if (sub === "revoke") {
+    if (!id) die("usage: bay tokens revoke <id>   (ids come from: bay tokens)");
+    const d = await api("/api/account/tokens", { method: "POST", body: { revoke: id } });
+    if (args.json) return json(d);
+    // `ok` is read rather than assumed. This route answers 404 for an id that is
+    // not yours, which `api` turns into a refusal — but its sibling
+    // /api/cli/token answers 200 with `ok: false` for the same case, and a
+    // command that printed ✓ on that would be telling somebody a key had been
+    // taken back when it had not.
+    if (d.ok === false) die(`no token ${id} on this account — check: bay tokens`);
+    print(green("✓ ") + `revoked ${id} — that CLI is signed out`);
+    return;
+  }
+
+  const d = await api("/api/account/tokens");
+  const list = d.tokens || [];
+  if (args.json) return json(list);
+  if (!list.length) { info("no CLI tokens on this account"); return; }
+  for (const t of list) {
+    const last = t.last_used_at ? new Date(t.last_used_at).toISOString().slice(0, 10) : "never";
+    print(`${dim(t.id)}  ${bold((t.name || "cli").padEnd(20))} ${dim("added " + String(t.created_at).slice(0, 10) + " · last used " + last)}`);
+  }
+  info(dim("\nrevoke one: bay tokens revoke <id>"));
+}
+
 /**
  * The repair agent's fix, as a patch, on stdout and nothing else.
  *
@@ -444,9 +893,19 @@ async function exec(args) {
   if (d.exitCode) { info(red(`exited ${d.exitCode}`)); process.exitCode = d.exitCode; }
 }
 
+/**
+ * Open the app in a browser, at the address the SERVER says it has.
+ *
+ * This used to build `https://<app>.supersonic.cv` here. That is one root
+ * hardcoded into a published npm package: it survives a rebrand, it ignores
+ * every custom domain the app has, and it cannot be corrected without a release.
+ * The app row knows its own URL — ask it, and fall back to the old spelling only
+ * if the answer is missing.
+ */
 async function open(args) {
   const app = needApp(args);
-  const url = `https://${app}.thebay.cloud`;
+  const d = await api(`/api/apps/${app}`);
+  const url = d.url || `https://${app}.${brand.DOMAIN}`;
   info(`opening ${url}`);
   openBrowser(url);
 }
@@ -555,7 +1014,26 @@ const REMOVED_DEPLOY_FLAGS = ["dev-cmd", "dev-port", "no-preview"];
  * "deploying — your app will be live at" and reports success for the thing it did
  * not ask for.
  */
-const SHIP_FLAGS = ["run", "wait", "no-env", "github", "repo", "prebuilt", "json", "help"];
+const SHIP_FLAGS = ["name", "run", "wait", "no-env", "github", "repo", "prebuilt", "json", "help"];
+
+/**
+ * What the app is called.
+ *
+ * The folder's name by default, which is right nearly always — you ship from the
+ * project's root and that is what the project is called. `--name` exists because
+ * the dashboard asks for a name before it hands you this command, and a name the
+ * user typed there has to survive into the deploy; without the flag the CLI would
+ * refuse the whole command (SHIP_FLAGS above is a hard list) and the name would be
+ * silently the folder's anyway.
+ *
+ * The server decides the SLUG from this — see resolveSlug — and reuses the one it
+ * already gave a deploy of the same name, which is what makes a redeploy land on
+ * the same address instead of creating a second app beside the first.
+ */
+function appNameFrom(args) {
+  const raw = typeof args.name === "string" && args.name.trim() ? args.name : path.basename(process.cwd());
+  return raw.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "") || "app";
+}
 
 async function deploy(args) {
   if (args.help) return usage(true);
@@ -589,12 +1067,12 @@ async function deploy(args) {
   if (args.github || args.repo) {
     let repo = args.repo;
     if (!repo) { repo = await gitOrigin(); if (!repo) die("no git remote 'origin' found here — pass --repo <url>"); }
-    info(cyan("▸ ") + "deploying from " + bold(repo));
+    info(cyan("▸ ") + "shipping from " + bold(repo));
     const res = await api("/api/deploy", { method: "POST", body: { repo }, stream: true });
     return consumeDeploy(res, args);
   }
   // Default: deploy this folder straight from your computer — no git, no setup.
-  const appName = path.basename(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "") || "app";
+  const appName = appNameFrom(args);
 
   // The fast path: your machine already has this project and builds it in seconds, so
   // build here and send only the result. Uploading sources and rebuilding them in the
@@ -639,24 +1117,29 @@ async function deploy(args) {
 async function urlFirstDeploy(args) {
   let repo = args.repo;
   if (args.github && !repo) { repo = await gitOrigin(); }
-  const folderName = path.basename(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "") || "app";
+  const folderName = appNameFrom(args);
 
   // 1) reserve the slug → a URL right away (live immediately, any stack)
-  const r = await api("/api/deploy/reserve", { method: "POST", body: repo ? { repo } : { name: folderName } });
+  // The repo names the app when it is a repo deploy, exactly as before — a
+  // folder name sent alongside would change the slug every existing GitHub
+  // deploy resolves to. `--name` overrides either, because it was typed.
+  const reserveBody = repo ? { repo } : { name: folderName };
+  if (args.name) reserveBody.name = folderName;
+  const r = await api("/api/deploy/reserve", { method: "POST", body: reserveBody });
   const { slug, url } = r;
   // Not "✓ live". Nothing has been built yet — this is the moment the slug was
   // reserved, and the build can still fail. Eight agents in a row read that
   // checkmark as "done", stopped watching, and reported a working deploy for an
   // app that never came up. The URL is real and does work from here (it serves a
   // build page), so it stays; what leaves is the claim that the app is on it.
-  print(dim("⧗ ") + "deploying — your app will be live at " + bold(url));
+  print(dim("⧗ ") + "shipping — your app will be live at " + bold(url));
 
   // Default: DON'T hold the caller hostage for the whole build. A coding agent
   // that runs `bay deploy` should get the live URL and its prompt back in
   // ~1s, not sit blocked for two minutes. So the build is handed to a detached
   // background worker that keeps the deploy connection open (the server keeps
   // building, CPU allocated, until it lands) and logs to
-  // ~/.bay/deploys/<slug>.log. Pass --wait to stay attached and stream the
+  // <config dir>/deploys/<slug>.log. Pass --wait to stay attached and stream the
   // build here instead.
   if (!args.wait) {
     const logDir = path.join(CFG_DIR, "deploys");
@@ -826,7 +1309,7 @@ async function runBuildAndWait({ slug, url, repo, folderName, args }) {
  * build after the foreground command has already returned the live URL. */
 async function deployWorker() {
   const slug = process.env.SS_BG_SLUG, url = process.env.SS_BG_URL;
-  if (!slug || !url) die("deploy worker: missing context");
+  if (!slug || !url) die("ship worker: missing context");
   await runBuildAndWait({
     slug, url,
     repo: process.env.SS_BG_REPO || "",
@@ -950,9 +1433,13 @@ function packageDir(dir) {
 async function redeploy(args) {
   const app = needApp(args);
   const d = await api(`/api/apps/${app}`);
-  if (!d.repo) die(`${app} was deployed from a computer — run \`bay deploy\` in its folder to ship an update`);
-  info(cyan("▸ ") + "redeploying " + bold(app));
-  const res = await api("/api/deploy", { method: "POST", body: { repo: d.repo }, stream: true });
+  if (!d.repo) die(`${app} was shipped from a computer — run \`bay ship\` in its folder to send an update`);
+  info(cyan("▸ ") + "reshipping " + bold(app));
+  // The slug travels, because the server would otherwise resolve one from the
+  // repo URL — and an app created under a name of its own (the dashboard asks
+  // for one) does not answer to that name, so the redeploy would build a
+  // SECOND app beside the one being redeployed.
+  const res = await api("/api/deploy", { method: "POST", body: { repo: d.repo, slug: app }, stream: true });
   return consumeDeploy(res, args, app);
 }
 
@@ -995,7 +1482,11 @@ const BODY_LIMIT = 32 * 1024 * 1024;
 function encryptSource(buf, pass) {
   const { createCipheriv, scryptSync } = require("node:crypto");
   const iv = require("node:crypto").randomBytes(16);
-  const cipher = createCipheriv("aes-256-cbc", scryptSync(pass, "bay-deploy-run", 32), iv);
+  // The salt is NOT renamed, and must not be. It is half of a key the control
+  // plane derives with the same literal (apps/web/lib/deploy-runs.ts, KEY_SALT):
+  // change it here and every upload decrypts to garbage on a server that still
+  // says the old word.
+  const cipher = createCipheriv("aes-256-cbc", scryptSync(pass, "supersonic-deploy-run", 32), iv);
   return Buffer.concat([iv, cipher.update(buf), cipher.final()]);
 }
 
@@ -1026,7 +1517,7 @@ async function uploadSourceToBucket(body) {
     headers: { "Content-Type": "application/octet-stream" },
     body: sealed,
   });
-  if (!put.ok) die(`upload failed (${put.status}) — the code never left your machine, so nothing was deployed`);
+  if (!put.ok) die(`upload failed (${put.status}) — the code never left your machine, so nothing was shipped`);
   return { object: spot.object, key };
 }
 
@@ -1130,7 +1621,7 @@ async function consumeDeploy(res, args, knownSlug) {
   if (slug) {
     const deploy = await followDeployOnServer(slug);
     if (deploy?.status === "live") {
-      const url = deploy.url || `https://${slug}.thebay.cloud`;
+      const url = deploy.url || `https://${slug}.${brand.DOMAIN}`;
       if (args.json) json({ ok: true, slug, url, runId });
       else print(green("✓ live: ") + url);
       process.exit(0);
@@ -1151,7 +1642,7 @@ async function consumeDeploy(res, args, knownSlug) {
   // here: it is all the information there is.
   const lost = streamError ? ` (the connection failed: ${streamError})` : "";
   if (args.json) json({ ok: false, error: "deploy stream ended without a result", streamError });
-  die(`the deploy ended without confirming it went live${lost} — the build may have failed or timed out. Check: bay apps  ·  bay logs <app>`);
+  die(`the ship ended without confirming it went live${lost} — the build may have failed or timed out. Check: bay apps  ·  bay logs <app>`);
 }
 
 // ---------- helpers ----------
@@ -1170,25 +1661,30 @@ function usage(all = false) {
     print(`${bold("bay")} — publish your app in one command
 
 ${bold("just run this in your project folder:")}
-  ${green("bay ship")}            publish this folder and print the live URL
-                             (opens a browser to sign in the first time;
-                              ${dim("`deploy` is the same command")})
+  ${green("bay ship")}              publish this folder and print the live URL
+                        (opens a browser to sign in the first time;
+                         ${dim("`bay deploy` is the same command")})
 
 ${bold("before you ship")} ${dim("(local, ~2s, no cloud)")}
-  bay init            write a draft supersonic.json from this repo
-  bay check           what each phase would run, and what would fail
+  bay init              write a draft supersonic.json from this repo
+  bay check             what each phase would run, and what would fail
 
 ${bold("when something's wrong")}
-  bay logs <app>      recent logs
-  bay diagnose <app>  AI fix-prompt for your coding agent
-  bay apps            list your apps
-  bay open <app>      open the app in a browser
-  bay login           sign in manually
+  bay logs <app>        recent logs
+  bay diagnose <app>    AI fix-prompt for your coding agent
+  bay apps              list your apps
+  bay open <app>        open the app in a browser
+  bay login             sign in manually
+
+${bold("the rest of the platform")} ${dim("(nothing here needs the dashboard)")}
+  bay share <app> public          who can open it
+  bay domains <app> add <host>    connect a domain you own
+  bay db <app>                    read its database
 
 ${dim("more commands: bay help --all  ·  --json on any command for machine output")}`);
     return;
   }
-  print(`${bold("bay")} — deploy & debug from your coding agent
+  print(`${bold("bay")} — ship & debug from your coding agent
 
 ${bold("setup")}
   bay signup                            create an account (opens browser, one time)
@@ -1202,13 +1698,14 @@ ${bold("author")} ${dim("(local: no cloud, no build, no model — about two seco
 
 ${bold("ship")} ${dim("(URL-first: a live link in ~0.1s, the build drawn on it while it runs)")}
   bay ship                               ship this folder — live URL now, build behind it
-  ${dim("(`deploy` does the same thing and always will — every flag below works with either)")}
-  bay ship --run "<prod start cmd>"    how to run it in PROD — you know the stack
-                                                  e.g. --run "uvicorn main:app --host 0.0.0.0 --port $PORT"
-  bay ship --wait                      stay attached and stream the build (default: returns once live)
-  bay ship --no-env                    don't carry .env up (default: sets vars your app doesn't have yet)
-  bay ship --github [--repo <url>]     deploy from GitHub / a git URL instead
-  bay ship --prebuilt                  old path: build here, upload the result
+  bay ship --name <name>                 what to call it (default: this folder's name)
+  ${dim("(`bay deploy` does the same thing and always will — every flag here works with either)")}
+  bay ship --run "<prod start cmd>"      how to run it in PROD — you know the stack
+                                         e.g. --run "uvicorn main:app --host 0.0.0.0 --port $PORT"
+  bay ship --wait                        stay attached and stream the build (default: returns once live)
+  bay ship --no-env                      don't carry .env up (default: sets vars your app doesn't have yet)
+  bay ship --github [--repo <url>]       ship from GitHub / a git URL instead
+  bay ship --prebuilt                    old path: build here, upload the result
   bay reship <app>                       rebuild from the app's source
   bay patch <app>                        the repair agent's fix, to pipe into git apply
   bay rollback <app>                     roll back to the previous version
@@ -1228,6 +1725,33 @@ ${bold("config")}
   bay env <app> unset KEY                remove env var(s)
   bay open <app>                         open the app in a browser
 
+${bold("who can open it")}
+  bay share <app>                        the visibility, the people, the rules, who is asking
+  bay share <app> private|shared|public  change it
+  bay share <app> add ada@acme.com       invite one person (they get an email)
+  bay share <app> add @acme.com          everyone with an address there
+  bay share <app> remove <email|@domain>
+
+${bold("its own address")}
+  bay domains <app>                      what is attached, and the DNS record to create
+  bay domains <app> add acme.com         attach a domain you own
+  bay domains <app> remove acme.com
+
+${bold("its data")}
+  bay db <app>                           the tables, with row counts
+  bay db <app> <table> [--limit 50] [--offset 0]
+  bay db <app> --sql "select ..."        one read-only statement
+
+${bold("shipping from GitHub")}
+  bay git <app>                          the repo it follows, and whether a push ships
+  bay git <app> --branch main --auto on
+  bay git <app> disconnect
+
+${bold("the account")}
+  bay plan                               plan, every limit, and what is left of it
+  bay tokens                             every CLI signed in to this account
+  bay tokens revoke <id>                 take one back
+
 ${dim("global: --json for machine-readable output · $BAY_TOKEN overrides login")}`);
 }
 
@@ -1256,7 +1780,7 @@ function parse(argv) {
  * prompt, README and script that already exists, so it does not get deprecated,
  * warned about, or removed. Two words, one command, forever.
  */
-const COMMANDS = { signup, login, logout, whoami, apps, status, logs, errors, diagnose, env, patch, rollback, exec, open, init, check, ship: deploy, deploy, reship: redeploy, redeploy, delete: del, rm: del, "__deploy-worker": deployWorker };
+const COMMANDS = { signup, login, logout, whoami, apps, status, logs, errors, diagnose, env, domains, domain: domains, share, access: share, db, git, plan, account: plan, tokens, patch, rollback, exec, open, init, check, ship: deploy, deploy, reship: redeploy, redeploy, delete: del, rm: del, "__deploy-worker": deployWorker };
 
 (async () => {
   const [, , cmd, ...rest] = process.argv;