sproutboat 0.53.1 → 0.55.0

package/src/secrets-bulk.ts

@@ -0,0 +1,51 @@
+/**
+ * `secret bulk [file]`: the input of Wrangler's command, JSON `{"NAME": "value", "OTHER": null}` (a null deletes) or a
+ * `.env` file (`NAME=value`, no deletes), read from the file or from stdin, with at most 100 entries. Names only in every
+ * message, never a value.
+ */
+import { CloudError } from "./cloud";
+import { SECRET_NAME_RE } from "./cloud-secrets";
+import { parseDotenv } from "./env-file";
+import { isString, jsonObject, parseJsonValue } from "./json";
+
+export const BULK_MAX = 100;
+
+export type BulkPlan = { set: Record<string, string>; delete: string[]; warnings: string[] };
+
+export function parseBulkSecrets(text: string, label: string): BulkPlan {
+  const set: Record<string, string> = {};
+  const remove: string[] = [];
+  const warnings: string[] = [];
+  const bad: string[] = [];
+  if (text.trim().startsWith("{")) {
+    let parsed;
+    try {
+      parsed = jsonObject(parseJsonValue(text));
+    } catch {
+      throw new CloudError(`${label}: not valid JSON; expected {"NAME": "value", "OTHER": null}`);
+    }
+    if (!parsed) throw new CloudError(`${label}: expected a JSON object of NAME: value`);
+    for (const [name, value] of Object.entries(parsed)) {
+      if (!SECRET_NAME_RE.test(name)) bad.push(name);
+      else if (value === null) remove.push(name);
+      else if (isString(value) && value !== "") set[name] = value;
+      else throw new CloudError(`${label}: the value of ${name} must be a non-empty string, or null to delete it`);
+    }
+  } else {
+    const env = parseDotenv(text, label);
+    warnings.push(...env.warnings);
+    const empty: string[] = [];
+    for (const entry of env.entries) {
+      if (!SECRET_NAME_RE.test(entry.key)) bad.push(entry.key);
+      else if (entry.value === "") empty.push(entry.key);
+      else set[entry.key] = entry.value;
+    }
+    if (empty.length > 0) warnings.push(`${label}: not sent, empty value: ${empty.join(", ")}`);
+  }
+  if (bad.length > 0)
+    throw new CloudError(`${label}: secret names must be UPPER_SNAKE_CASE; not valid: ${bad.join(", ")}`);
+  const total = Object.keys(set).length + remove.length;
+  if (total === 0) throw new CloudError(`${label}: no secrets to set or delete`);
+  if (total > BULK_MAX) throw new CloudError(`${label}: ${total} entries; at most ${BULK_MAX} per command`);
+  return { set, delete: remove, warnings };
+}

package/src/sql-split.ts

@@ -0,0 +1,68 @@
+/**
+ * Split a SQL script into its statements, the way `d1 execute --file` and a migration need them one by one: at a
+ * semicolon that is not inside a quoted string, a quoted identifier, a comment or the body of a trigger. Statements are
+ * returned trimmed, without the final semicolon, and empty ones (a stray `;`, a trailing comment) are dropped.
+ */
+export function splitSql(script: string): string[] {
+  const statements: string[] = [];
+  let current = "";
+  let depth = 0; // BEGIN ... END nesting inside CREATE TRIGGER (and CASE ... END inside it)
+  let word = "";
+  const flushWord = () => {
+    const upper = word.toUpperCase();
+    if (
+      upper === "BEGIN" &&
+      /^\s*CREATE\s+(TEMP(ORARY)?\s+)?TRIGGER\b/i.test(stripComments(current.slice(0, current.length - word.length)))
+    )
+      depth++;
+    else if (upper === "CASE" && depth > 0) depth++;
+    else if (upper === "END" && depth > 0) depth--;
+    word = "";
+  };
+  const push = () => {
+    if (stripComments(current).trim() !== "") statements.push(current.trim());
+    current = "";
+  };
+  for (let i = 0; i < script.length; i++) {
+    const ch = script[i]!;
+    if (word && !/[A-Za-z0-9_]/.test(ch)) flushWord();
+    if (ch === "'" || ch === '"' || ch === "`" || ch === "[") {
+      flushWord();
+      const close = ch === "[" ? "]" : ch;
+      let j = i + 1;
+      for (; j < script.length; j++) {
+        if (script[j] === close) {
+          if (close !== "]" && script[j + 1] === close) j++; // doubled quote is an escaped quote
+          else break;
+        }
+      }
+      current += script.slice(i, j + 1);
+      i = j;
+    } else if (ch === "-" && script[i + 1] === "-") {
+      flushWord();
+      const end = script.indexOf("\n", i);
+      const stop = end < 0 ? script.length : end;
+      current += script.slice(i, stop);
+      i = stop - 1;
+    } else if (ch === "/" && script[i + 1] === "*") {
+      flushWord();
+      const end = script.indexOf("*/", i + 2);
+      const stop = end < 0 ? script.length : end + 2;
+      current += script.slice(i, stop);
+      i = stop - 1;
+    } else if (ch === ";" && depth === 0) {
+      flushWord();
+      push();
+    } else {
+      if (/[A-Za-z0-9_]/.test(ch)) word += ch;
+      current += ch;
+    }
+  }
+  flushWord();
+  push();
+  return statements;
+}
+
+function stripComments(sql: string): string {
+  return sql.replace(/--[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+}

package/src/standalone-build.ts

@@ -15,8 +15,21 @@ import type { Bindings } from "./wrap";
 export type StandaloneBuildInput = BuildInput & {
   /** Where to write the executable. Defaults to `<projectDir>/dist/<name>`. */
   outPath?: string;
+  /**
+   * The release build: `-flto -O3`, the binary to publish. Off by default: units still compile at -O3 but
+   * the link skips LTO, which is 1.5 to 2x faster cold and links in ~90 MB instead of 1.1 to 1.6 GB, at some
+   * request throughput (docs/standalone.md, "Dev and release builds").
+   */
+  release?: boolean;
 };
 
+/** `--release` or `SPROUTBOAT_RELEASE=1` (`0`, empty or unset: not a release build). */
+export function isReleaseBuild(args: string[], env: Record<string, string | undefined> = process.env): boolean {
+  if (args.includes("--release")) return true;
+  const value = env.SPROUTBOAT_RELEASE;
+  return value !== undefined && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+}
+
 export type StandaloneBuildResult = { outPath: string; bytes: number };
 
 /**
@@ -50,14 +63,19 @@ function assertStandaloneSupported(input: BuildInput): void {
  * compiles, at the same path. Every check that fails a standalone build fails
  * this too; nothing native is acquired or compiled and no binary is copied out.
  */
-export async function emitStandalone(input: BuildInput): Promise<{ generatedPath: string }> {
-  assertStandaloneSupported(input);
+export async function emitStandalone(
+  input: BuildInput,
+  /** The Cloud compiles this unit and its hosts supply service bindings, so a deploy to the Cloud keeps them. */
+  options: { forCloud?: boolean } = {},
+): Promise<{ generatedPath: string }> {
+  if (!options.forCloud) assertStandaloneSupported(input);
   return emitGenerated({ ...input, transport: "embedded" });
 }
 
 export async function buildStandalone(input: StandaloneBuildInput): Promise<StandaloneBuildResult> {
   assertStandaloneSupported(input);
-  const artifact = await buildArtifact({ ...input, transport: "embedded" });
+  const { release, ...rest } = input;
+  const artifact = await buildArtifact({ ...rest, transport: "embedded", lto: release === true });
 
   // The sprout *is* the binary: assets and bindings are compiled into it, and
   // everything else it needs (port, data dir, secrets) arrives at run time.

package/src/surface.ts

@@ -6,19 +6,23 @@
 import { bold, dim, leaf } from "./style";
 
 export const CLI_NAME = "sproutboat";
-export const TAGLINE = "Deploy JavaScript handlers as tiny native binaries on your own VPS.";
-export const DOCS_URL = "https://docs.sproutboat.com";
+export const TAGLINE = "Build and deploy JavaScript handlers as tiny native binaries.";
+export const DOCS_URL = "https://sproutboat.com/docs";
 
 export type Group = "Develop" | "Ship" | "Storage" | "Configure" | "Account";
 
 export type Command = {
   name: string;
+  /** Other names that run the same command (`secret` for `secrets`, as in Wrangler). */
+  aliases?: readonly string[];
   /** Full argument grammar — used by SURFACE.md and the one-line usage string. */
   args: string;
   /** Short argument hint shown in the grouped help list (falls back to `args`). */
   brief?: string;
   group: Group;
   emoji: string;
+  /** One short line (about 60 characters) for the grouped help list. Detail lives in `summary`, shown by `<command> --help`. */
+  short: string;
   summary: string;
 };
 
@@ -42,8 +46,8 @@ export type StorageProduct = {
 };
 
 export const STORAGE_PRODUCTS: readonly StorageProduct[] = [
-  { name: "kv", noun: "namespace", plural: "KV namespaces", emoji: "🗄" },
-  { name: "d1", noun: "database", plural: "D1 databases", emoji: "🛢" },
+  { name: "kv", noun: "namespace", plural: "KV namespaces", emoji: "🗄\uFE0F" },
+  { name: "d1", noun: "database", plural: "D1 databases", emoji: "🛢\uFE0F" },
   { name: "r2", noun: "bucket", plural: "R2 buckets", emoji: "🪣" },
   { name: "queues", noun: "queue", plural: "queues", emoji: "📨" },
 ];
@@ -53,54 +57,82 @@ export const STORAGE_VERBS = ["list", "create", "info", "rename", "delete"] as c
 
 const STORAGE_ARGS = "<list | create <name> | info <name> | rename <name> <new> | delete <name>>";
 
+/** What each storage command offers, in the words the grouped help uses. */
+const STORAGE_SHORT = {
+  kv: "Manage KV namespaces, keys, bulk data and exports",
+  d1: "Manage D1 databases, run SQL, apply migrations",
+  r2: "Manage R2 buckets, and get, put or delete objects",
+  queues: "Manage queues",
+} satisfies Record<StorageProduct["name"], string>;
+
 const storageCommands: readonly Command[] = STORAGE_PRODUCTS.map((product) => ({
   name: product.name,
   group: "Storage" as const,
   emoji: product.emoji,
-  args: product.name === "kv" ? `${STORAGE_ARGS} | <key | bulk | export> ...` : STORAGE_ARGS,
-  brief: `<${STORAGE_VERBS.join(" | ")}>`,
-  summary: `${product.plural[0].toUpperCase()}${product.plural.slice(1)}. \`create\` prints the id to bind from sproutboat.jsonc${product.name === "kv" ? "; key and bulk operations manage contents, and export writes a restorable JSON dump" : ""}${product.name === "queues" ? "; consumers deliver in batches with retries, and stop after 5 attempts" : ""}.`,
+  short: STORAGE_SHORT[product.name],
+  args:
+    product.name === "kv"
+      ? `${STORAGE_ARGS} | <key | bulk | export> ...`
+      : product.name === "d1"
+        ? `${STORAGE_ARGS} | execute <database> (--command <sql> | --file <path>) [--json] [--local | --remote] | migrations <create | list | apply> <database> ...`
+        : product.name === "r2"
+          ? `${STORAGE_ARGS} | object <get <bucket>/<key> [--file <path> | --pipe] | put <bucket>/<key> (--file <path> | --pipe) [--content-type <t>] [--cache-control <v>] ... | delete <bucket>/<key>>`
+          : STORAGE_ARGS,
+  brief: "<command>",
+  summary: `${product.plural[0].toUpperCase()}${product.plural.slice(1)}. \`create\` prints the id to bind from sproutboat.jsonc${product.name === "kv" ? "; key and bulk operations manage contents, and export writes a restorable JSON dump" : ""}${product.name === "d1" ? `; \`execute\` runs SQL against the local dev database (.sproutboat/dev/d1/<BINDING>.sqlite) unless --remote, as in Wrangler, and prints JSON when stdout is not a terminal; \`migrations create <database> <name>\` writes migrations/NNNN_<name>.sql (migrations_dir in sproutboat.jsonc changes the folder), \`migrations list\` shows the ones not applied, and \`migrations apply\` applies them in order, each with its row in the d1_migrations table in one transaction, after a confirmation in a terminal. <database> is the binding name from d1_databases. --remote needs a Sproutboat Cloud endpoint (app:write to change data, app:read for SELECT only); self-hosted Community has no remote D1 route yet and says so` : ""}${product.name === "r2" ? "; `object get | put | delete <bucket>/<key>` read and write the objects of a Cloud app's bucket (<bucket> is the binding name from r2_buckets) with Wrangler's flags (--file, --pipe, --content-type, --content-disposition, --content-encoding, --content-language, --cache-control, --expires; `get` without --file writes ./<key>), 64 MiB per object, remote only (--local is refused). A key is 1 to 1024 bytes with no control character, backslash, or empty, . or .. segment, checked before anything is sent. The key needs the data:read grant to get and data:write to put or delete (the error says which it lacks and how to get it). On self-hosted Community `get` reads through the existing route by bucket name, and `put` and `delete` say they are not supported yet" : ""}${product.name === "queues" ? "; consumers deliver in batches with retries, and stop after 5 attempts" : ""}.`,
 }));
 
+/** The command a typed name runs: an alias maps to its command, anything else is returned as typed. */
+export const resolveCommand = (name: string): string =>
+  COMMANDS.find((c) => c.name === name || c.aliases?.includes(name))?.name ?? name;
+
 export const COMMANDS: readonly Command[] = [
   {
     name: "init",
     group: "Develop",
     emoji: "🌱",
-    args: "[name]",
+    short: "Scaffold a new project",
+    args: "[name] [--template <name>] [--list-templates] [--git | --no-git] [--install | --no-install] [-y, --yes]",
+    brief: "[name]",
     summary:
-      "Scaffold sproutboat.jsonc, src/index.js and package.json (sproutboat devDependency, dev and deploy scripts) in ./<name>.",
+      "Scaffold a project in ./<name> (the last path segment is the app's name), with the shape of `npm create cloudflare`. Without --template it writes sproutboat.jsonc, src/index.js and package.json (sproutboat devDependency, dev, deploy and check scripts). `--template <name>` writes a starter instead, standard Workers TypeScript with tests, a README and a current worker-configuration.d.ts: realtime-room (a chat room on Durable Objects and hibernating WebSockets), api-d1 (a JSON API on D1 with migrations and validation), site-api (a static site and its API in one Worker) or jobs (a cron trigger, a queue and KV); `--list-templates` prints them with their descriptions. In a terminal it asks for the template, the directory, whether to install dependencies and whether to use git (both default to yes); `-y` takes every default without asking, and anywhere else nothing runs that a flag did not ask for. `--install` runs the project's package manager (npm, pnpm, yarn or bun, by lockfile, else the tool that launched the CLI); `--git` runs `git init` and makes a first commit, and does nothing inside an existing repository. It never overwrites a file.",
   },
   {
     name: "check",
     group: "Develop",
     emoji: "🔍",
+    short: "Validate the config and entry point",
     args: "[project-dir]",
+    brief: "[project-dir]",
     summary: "Validate the config and entry point without building.",
   },
   {
     name: "types",
     group: "Develop",
     emoji: "🧾",
-    args: "[project-dir]",
+    short: "Write worker-configuration.d.ts for your editor",
+    args: "[path] [--env-interface <name>] [--strict-vars[=false]] [--include-runtime[=false]] [--include-env[=false]] [--check]",
+    brief: "[path]",
     summary:
-      "Write sproutboat-env.d.ts from the config, so an editor knows what `env` holds. `dev` and `deploy` refresh it when the config is newer.",
+      'Generate the project\'s `Env` as TypeScript from sproutboat.jsonc, like `wrangler types`: the file is worker-configuration.d.ts unless <path> names another; it declares `interface Env` (and `Cloudflare.Env`, which `import { env } from "cloudflare:workers"` reads) with a type per binding, literal types for vars (--strict-vars=false makes them `string`), and a Durable Object binding typed with its class when the entry is TypeScript. It references the runtime types shipped with the CLI (--include-runtime=false leaves that out, for a project that brings its own) instead of copying them in, and there is no --include-main-module. Type a handler as `export default { ... } satisfies ExportedHandler<Env>`. --check exits 1 when the file is missing or out of date, by the hash in its first lines. KV, D1, R2, Durable Object and Fetcher types follow the compatibility date, as the runtime does. `dev` and `deploy` refresh the default file when it was written by a plain `sproutboat types` and the config has moved on; they leave one made with other flags alone. A positional that is an existing directory is still read as the project directory. The file earlier releases wrote, sproutboat-env.d.ts, is removed when it is still as generated.',
   },
   {
     name: "dev",
     group: "Develop",
     emoji: "⚡",
-    args: "[project-dir] [--port <n>] [--no-watch] [--env <name>] [--env-file <file>]...",
-    brief: "[project-dir] [--port <n>]",
+    short: "Run the app locally, rebuilding on save",
+    args: "[project-dir] [--port <n>] [--ip <address>] [--no-watch] [-e, --env <name>] [--env-file <file>]...",
+    brief: "[project-dir]",
     summary:
-      "Run the project on this machine against a real broker, rebuilding on save. Secrets come from .dev.vars or the .env files (never both), as in Wrangler; a declared secret with no value is a warning.",
+      "Run the project on this machine with local storage, rebuilding on save. It listens on 127.0.0.1 unless `--ip` names another address (`--ip 0.0.0.0` is reachable from other machines on the network, as in Wrangler). Secrets come from .dev.vars or the .env files (never both), as in Wrangler; a declared secret with no value is a warning.",
   },
   {
     name: "run",
     group: "Develop",
-    emoji: "🚀",
+    emoji: "🏃",
+    short: "Launch a built standalone binary",
     args: "[project-dir] [--binary <file>] [--env-file <file>]... [--port <n>] [--data-dir <dir>] [--require <NAME,...>] [--check]",
-    brief: "[--env-file <file>] [--port <n>]",
+    brief: "[project-dir]",
     summary:
       "Launch a standalone binary with its port, data directory and declared secrets supplied at launch, never baked in. Precedence: --port/--data-dir, then the --env-file files (later overrides earlier), then the environment. A missing declared secret fails the launch, like wrangler deploy; --check validates without starting.",
   },
@@ -108,15 +140,17 @@ export const COMMANDS: readonly Command[] = [
     name: "build",
     group: "Develop",
     emoji: "🔨",
-    args: "[project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--deploy-files] [--with-restore] [--emit-only]",
+    short: "Compile the app to a native binary",
+    args: "[project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--release] [--deploy-files] [--with-restore] [--emit-only]",
     brief: "[project-dir]",
     summary:
-      "Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally, not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process; add `--target linux-arm64` for an aarch64 box (the default is `linux-x64`) and `--deploy-files` to write a Dockerfile, a systemd socket and service, a fly.toml and a push script beside it. `--with-restore` adds an offline `APP ltx-restore --generation DIR --output NEW_DB [--txid N]` startup command to a standalone executable; it runs before app initialization. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled.",
+      "Compile the app to a native binary (Porffor + Zig), cross-compiled for Linux x64 by default. `--target host` builds for this machine instead, to run locally, not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no separate storage process; add `--target linux-arm64` for an aarch64 box (the default is `linux-x64`) and `--deploy-files` to write a Dockerfile, a systemd socket and service, a fly.toml and a push script beside it. `--release` makes a standalone build the full `-flto -O3` one to publish; without it the link skips LTO (1.5 to 2x faster cold, ~90 MB link memory instead of 1.1 to 1.6 GB, fewer requests per second); `SPROUTBOAT_RELEASE=1` does the same, and a non-standalone build is always the release build. `--with-restore` adds an offline `APP ltx-restore --generation DIR --output NEW_DB [--txid N]` startup command to a standalone executable; it runs before app initialization. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled.",
   },
   {
     name: "toolchain",
     group: "Develop",
     emoji: "🩺",
+    short: "Check the compiler toolchain",
     args: "doctor [--json]",
     brief: "doctor",
     summary:
@@ -127,24 +161,37 @@ export const COMMANDS: readonly Command[] = [
     name: "deploy",
     group: "Ship",
     emoji: "🚀",
-    args: "[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]",
-    brief: "[project-dir] [--dry-run]",
+    short: "Build the app and publish it",
+    args: "[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] [--api-url <url>] [--account <team>] [--module <file.so>] [--sproutd <dir> --generation <dir>] [--secrets-file <file>]",
+    brief: "[project-dir]",
     summary:
-      "Build (unless --artifact), auto-provision id-less storage bindings and pin their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves id-less bindings as ephemeral deploy-scoped stores.",
+      "Build (unless --artifact), create the storage bindings that have no id yet and write their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves those bindings as temporary stores that last only for the deploy. On a Sproutboat Cloud endpoint (the default, https://dash.sproutboat.com) it bundles the project, uploads the source by sha256 (skipped when unchanged) and the assets by hash, has the Cloud build it while streaming the build log (Ctrl-C cancels the build), waits for a host to apply the generation the build wrote and prints https://<app>.<team>.sproutboat.app; --no-wait returns once the build is accepted and prints /v1/builds/<id>, and --dry-run says it would build in the Cloud. --module and --sproutd with --generation are the operator paths (an uploaded or locally compiled module, refused for team keys); regular deploys do not need them. On the Cloud, `services` in sproutboat.jsonc become service bindings to the team's Cloud apps of those names (each must be deployed first; compatibility_date 2026-11-18 or later; an app cannot bind itself), resolved before anything is uploaded; --secrets-file <file> (.dev.vars or .env format) sets those secrets once the build is ready (and cannot be combined with --no-wait), and a deploy never removes secrets it does not name (manage them with `secrets`); logged out in a terminal it starts the login, with no terminal it needs SPROUTBOAT_API_TOKEN.",
+  },
+  {
+    name: "deployments",
+    group: "Ship",
+    emoji: "🚢",
+    short: "List deployments, show what is live, follow a build",
+    args: "<list | status | tail <id>> [--json] [--api-url <url>] [--account <team>]",
+    brief: "<list | status | tail>",
+    summary:
+      "The deployments of the project in this directory. `list` shows the 10 most recent, newest first, with the live one marked; `status` shows what is live and whether a host applied it; both take --json. On a Cloud endpoint a deployment is a build: `tail <id>` follows it server-side (its log, then its end state), from its first line, so a deploy that was detached with Ctrl-C can be picked up again; Ctrl-C stops following and never cancels the build. On self-hosted Community a deployment is a version (as in `versions list`), `status` shows the active one, and `tail` says there is nothing to follow, since a deploy there is finished when `deploy` returns.",
   },
   {
     name: "versions",
     group: "Ship",
     emoji: "📜",
-    args: "<list | view <version-id>> [project-dir]",
+    short: "List or view deployed versions",
+    args: "<list | view <version-id>> [project-dir] [--api-url <url>]",
     brief: "<list | view>",
     summary: "List the project's deployed versions, or show one version's artifact and bindings.",
   },
   {
     name: "rollback",
     group: "Ship",
-    emoji: "⏮",
-    args: "<version-id> [project-dir]",
+    emoji: "⏪",
+    short: "Re-activate a previous version",
+    args: "<version-id> [project-dir] [--api-url <url>]",
     brief: "<version-id>",
     summary: "Re-activate a previous version.",
   },
@@ -152,10 +199,21 @@ export const COMMANDS: readonly Command[] = [
     name: "tail",
     group: "Ship",
     emoji: "📡",
-    args: "[project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] [--file <log|-> [--lines <n>] [--no-follow]]",
-    brief: "[--status 5xx] [--search <text>]",
+    short: "Stream live requests, logs and exceptions",
+    args: "[project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] [--file <log|-> [--lines <n>] [--no-follow]] [--api-url <url>]",
+    brief: "[project-dir]",
     summary:
-      "Stream live request events, console output and exceptions (like wrangler tail); --recent prints the last 100 request records, --sprout the running sprout + broker stdout/stderr. --file follows the JSON records a standalone binary writes with SB_LOG=json (no login needed).",
+      "Stream live request events, console output and exceptions (like wrangler tail); --recent prints the last 100 request records, --sprout the running app's own stdout and stderr logs. --file follows the JSON records a standalone binary writes with SB_LOG=json (no login needed).",
+  },
+
+  {
+    name: "delete",
+    group: "Ship",
+    emoji: "🗑️",
+    short: "Delete the app and all its versions",
+    args: "[project-dir] [--name <project>] --yes [--api-url <url>]",
+    brief: "[project-dir]",
+    summary: "Delete the project, every version, and its route.",
   },
 
   ...storageCommands,
@@ -164,55 +222,70 @@ export const COMMANDS: readonly Command[] = [
     name: "domains",
     group: "Configure",
     emoji: "🌐",
-    args: "<list | add <host> | verify <host> | delete <host>> [project-dir]",
+    short: "Attach custom domains",
+    args: "<list | add <host> | verify <host> | delete <host>> [project-dir] [--api-url <url>] [--account <team>]",
     brief: "<list | add | verify | delete>",
-    summary: "Attach a custom domain to the project (TXT-verified). No sub-command lists.",
+    summary:
+      "List the project's domains, or attach one (TXT-verified). On the Cloud only list works: custom domains are added by an operator, and deploys keep them.",
   },
   {
     name: "secrets",
+    aliases: ["secret"],
     group: "Configure",
     emoji: "🔑",
-    args: "<list | put <NAME> [--value <value>] | delete <NAME>> [project-dir]",
-    brief: "<list | put | delete>",
+    short: "Manage encrypted secrets",
+    args: "<list | put <NAME> [--value <value>] | delete <NAME> | bulk [file.json | file.env]> [project-dir] [--no-deploy] [--api-url <url>] [--account <team>]",
+    brief: "<list | put | delete | bulk>",
     summary:
-      "Manage encrypted project secrets (read as env.NAME). `put` reads the value from stdin unless --value is given, so it stays out of shell history; applies on next deploy.",
-  },
-  {
-    name: "delete",
-    group: "Configure",
-    emoji: "🗑",
-    args: "[project-dir] [--name <project>] --yes",
-    brief: "[project-dir] --yes",
-    summary: "Delete the project, every version, and its route.",
+      'Manage encrypted project secrets (read as env.NAME); `secret` is the same command, as in Wrangler. `put` reads the value from stdin unless --value is given, so it stays out of shell history. `bulk` takes the file of `wrangler secret bulk`: JSON {"NAME": "value", "OLD": null} (null deletes) or a .env file, from the file or stdin, at most 100 entries. On a Cloud endpoint secrets are per app and independent of deploys: put, delete and bulk act on the deployed app, and by default wait for a host to apply them as a new version of the running module (like wrangler secret, which deploys at once); --no-deploy returns as soon as the change is stored. Permissions secret:write and secret:list; an app that is not deployed yet says to deploy first or pass --secrets-file on the first deploy. Self-hosted Community applies secrets on the next deploy or restart of the app and has no redeploy route yet, so --no-deploy changes nothing there.',
   },
-
   {
     name: "login",
     group: "Account",
     emoji: "🔓",
-    args: "[--api-url <url>] [--token <token>]",
-    brief: "[--token <token>]",
-    summary: "Device-code browser flow, or store <token> for <url> directly.",
+    short: "Sign in",
+    args: "[--api-url <url>] [--token <token>] [--account <team>]",
+    brief: "",
+    summary:
+      "Sign in, as the profile named by --profile (the first login makes `default`). On the Cloud: the device-code flow (RFC 8628), which prints a code and a link, opens the browser when it can, and stores an account API key named `CLI on <hostname>` for the team you approve (--account preselects it). Elsewhere the browser flow, or store <token> for <url> directly.",
   },
   {
     name: "logout",
     group: "Account",
     emoji: "🔒",
-    args: "[--api-url <url>]",
-    summary: "Forget the stored credential for the active endpoint, or for <url>.",
+    short: "Forget the stored credential",
+    args: "[--api-url <url>] [--account <team>]",
+    brief: "",
+    summary:
+      "Forget the stored credential of the profile in use, or for <url>. On the Cloud it also revokes the key on the server (the default team, or --account).",
   },
   {
     name: "whoami",
     group: "Account",
     emoji: "👤",
-    args: "",
-    summary: "Show the active endpoint and the account the stored token belongs to.",
+    short: "Show the profile and account you use",
+    args: "[--api-url <url>] [--account <team>]",
+    brief: "",
+    summary:
+      "Show the profile and endpoint in use, and the account or team the credential belongs to (exits 1 when not logged in or the key is rejected).",
+  },
+  {
+    name: "profile",
+    group: "Account",
+    emoji: "🪪",
+    short: "List login profiles or pick the default",
+    args: "<list | use <name>>",
+    brief: "<list | use>",
+    summary:
+      "A profile is an endpoint, its stored credential and a default team. `list` shows them and marks the default, which a command uses when nothing else names one; `use <name>` makes another profile the default. `login --profile <name>` creates one, and `--profile <name>` or SPROUTBOAT_PROFILE picks one for a single command.",
   },
   {
     name: "complete",
     group: "Account",
-    emoji: "⌨",
+    emoji: "⌨️",
+    short: "Print a shell completion script",
     args: "[bash | zsh | fish]",
+    brief: "[shell]",
     summary: "Print a shell completion script for the top-level commands (defaults to $SHELL).",
   },
 ];
@@ -220,8 +293,36 @@ export const COMMANDS: readonly Command[] = [
 export type EnvVar = { name: string; purpose: string };
 
 export const ENV_VARS: readonly EnvVar[] = [
-  { name: "SPROUTBOAT_API_URL", purpose: "Control-plane URL. Overrides the saved active endpoint." },
-  { name: "SPROUTBOAT_TOKEN", purpose: "API token. Overrides the saved credential for the endpoint." },
+  {
+    name: "SPROUTBOAT_API_URL",
+    purpose:
+      "Control-plane URL, the same as --api-url (which wins). Overrides the active profile's endpoint; it must match SPROUTBOAT_PROFILE when both are set.",
+  },
+  {
+    name: "SPROUTBOAT_PROFILE",
+    purpose:
+      "Stored login profile to use, like --profile (which wins). Its endpoint and credential apply unless --api-url or SPROUTBOAT_API_TOKEN overrides them.",
+  },
+  {
+    name: "SPROUTBOAT_API_TOKEN",
+    purpose:
+      "API token (an account API key on the Cloud), like CLOUDFLARE_API_TOKEN. Always wins over the stored login; use it in CI.",
+  },
+  {
+    name: "SPROUTBOAT_TOKEN",
+    purpose: "Older name for SPROUTBOAT_API_TOKEN; SPROUTBOAT_API_TOKEN wins when both are set.",
+  },
+  {
+    name: "SPROUTBOAT_ACCOUNT",
+    purpose:
+      "Cloud team (its URL name) a deploy targets, like account_id. Overridden by --account and the account field of sproutboat.jsonc.",
+  },
+  {
+    name: "SPROUTBOAT_SPROUTD",
+    purpose:
+      "Operators only: sproutd checkout whose compile-app turns the app into a Cloud module (same as --sproutd). Regular deploys are built by the Cloud and do not need it.",
+  },
+  { name: "SPROUTBOAT_GENERATION", purpose: "Built sproutd generation to compile against (same as --generation)." },
   { name: "SPROUTBOAT_ZIG", purpose: "Path to a Zig binary to use instead of downloading the pinned one." },
   {
     name: "SPROUTBOAT_ZIG_URL",
@@ -251,7 +352,11 @@ export const ENV_VARS: readonly EnvVar[] = [
   {
     name: "SPROUTBOAT_PORFFOR_CHANNEL",
     purpose:
-      "Porffor channel for standalone builds: `alpha-22` (default) or `alpha-19` (the previous compiler, kept as a fallback for one release).",
+      "Porffor channel for standalone builds: `alpha-23` (default), `alpha-22` or `alpha-19` (the oldest compiler, kept as a fallback for one release).",
+  },
+  {
+    name: "SPROUTBOAT_RELEASE",
+    purpose: "Same as `build --standalone --release`: link with LTO. Any value but empty, `0` or `false` turns it on.",
   },
   {
     name: "SPROUTBOAT_FLTO",
@@ -282,7 +387,11 @@ export const ENV_VARS: readonly EnvVar[] = [
     name: "SPROUTBOAT_BINDINGS_JSON",
     purpose: "The artifact's bindings.json, read by the wrapper to emit the `__sbInstallBindings` line.",
   },
-  { name: "SPROUTBOAT_CONFIG_DIR", purpose: "Directory for credentials.json (default ~/.config/sproutboat)." },
+  {
+    name: "SPROUTBOAT_CONFIG_DIR",
+    purpose:
+      "Directory for credentials.json (default ~/Library/Preferences/sproutboat on macOS, ~/.config/sproutboat elsewhere; the old macOS place is still read).",
+  },
   {
     name: "NO_COLOR",
     purpose:
@@ -355,11 +464,30 @@ export function usageLine(): string {
   return `usage: ${CLI_NAME} <${parts.join(" | ")}>`;
 }
 
-/** First sentence of a summary — enough for the at-a-glance command list. */
-function firstSentence(text: string): string {
-  const end = text.indexOf(". ");
-  return end === -1 ? text.replace(/\.$/, "") : text.slice(0, end);
-}
+export type GlobalFlag = { flags: string; purpose: string; type: string };
+
+/** Flags every command accepts, listed by `sproutboat --help`. */
+export const GLOBAL_FLAGS: readonly GlobalFlag[] = [
+  { flags: "-c, --config", purpose: "Path to the project's config file", type: "string" },
+  { flags: "    --cwd", purpose: "Run as if sproutboat was started in this directory", type: "string" },
+  {
+    flags: "-e, --env",
+    purpose: "Environment for `dev`: selects the .dev.vars.<name> and .env.<name> files",
+    type: "string",
+  },
+  {
+    flags: "    --env-file",
+    purpose: "Path to an .env file to load; repeat it, and later files override earlier ones",
+    type: "array",
+  },
+  { flags: "-h, --help", purpose: "Show help", type: "boolean" },
+  {
+    flags: "    --profile",
+    purpose: "Use a stored login profile (default: SPROUTBOAT_PROFILE, else the active profile)",
+    type: "string",
+  },
+  { flags: "-v, --version", purpose: "Show version number", type: "boolean" },
+];
 
 /** Wrangler-style grouped help: `sproutboat` with no command, or `--help`. */
 export function helpText(): string {
@@ -371,14 +499,14 @@ export function helpText(): string {
     lines.push("", leaf(group.toUpperCase()));
     for (const command of COMMANDS.filter((c) => c.group === group)) {
       const invocation = `${command.name} ${command.brief ?? command.args}`.trim();
-      lines.push(`  ${invocation.padEnd(width)}  ${command.emoji}  ${firstSentence(command.summary)}`);
+      lines.push(`  ${invocation.padEnd(width)}  ${command.emoji}  ${command.short}`);
     }
   }
 
-  lines.push(
-    "",
-    dim(`Run \`${CLI_NAME} <command>\` with no/invalid args to see that command's full usage.`),
-    dim(`Docs: ${DOCS_URL}`),
-  );
+  const flagWidth = Math.max(...GLOBAL_FLAGS.map((flag) => flag.flags.length));
+  lines.push("", leaf("GLOBAL FLAGS"));
+  for (const flag of GLOBAL_FLAGS) lines.push(`  ${flag.flags.padEnd(flagWidth)}  ${flag.purpose}  [${flag.type}]`);
+
+  lines.push("", dim(`Run \`${CLI_NAME} <command> --help\` for a command's options.`), dim(`Docs: ${DOCS_URL}`));
   return lines.join("\n");
 }