sproutboat 0.53.1 → 0.54.0

package/src/main.ts

@@ -2,19 +2,130 @@
 import { mkdir, open, readFile, rename, writeFile } from "node:fs/promises";
 import { existsSync, rmSync } from "node:fs";
 import { basename, dirname, relative, resolve } from "node:path";
+import { tmpdir } from "node:os";
 import { isBoolean, isSafeInteger, isString, jsonObject, parseJsonValue, type JsonObject } from "./json";
 import type { AssetFiles } from "./assets";
-import { parseConfig, pinBindingId, resourceRefs, type SproutboatConfig } from "./config";
+import { pinBindingId, resourceRefs, type SproutboatConfig } from "./config";
 import { validateHttpSyncSource } from "./source";
 import { buildArtifact, emitGenerated } from "./build";
 import { generateTypes, TYPES_FILE } from "./types-gen";
 import { bundleHandler, BundleError, type BundleResult } from "./bundle";
 import { runDev } from "./dev";
-import { buildStandalone, emitStandalone } from "./standalone-build";
+import { buildStandalone, emitStandalone, isReleaseBuild } from "./standalone-build";
 import { hostTarget, validateManifest, type ArtifactManifest } from "./manifest";
 import { CLI_VERSION, printDeployReport } from "./report";
-import { activeApiUrl, forgetToken, savedToken, saveToken } from "./credentials";
-import { CLI_NAME, COMMANDS, helpText, STORAGE_PRODUCTS, STORAGE_VERBS, type StorageProduct } from "./surface";
+import {
+  activeProfileName,
+  forgetToken,
+  listProfiles,
+  PROFILE_NAME,
+  savedProfile,
+  savedProfileName,
+  savedToken,
+  saveToken,
+  selectProfile,
+  useProfile,
+} from "./credentials";
+import { extractGlobalFlags, globalFlags, locateProject, setGlobalFlags } from "./global-flags";
+import { checkOptions, ENDPOINT_COMMANDS } from "./options";
+import { chooseTarget, TargetError, type Target } from "./target";
+import { configAccount, configMigrationsDir, parseProjectConfig } from "./account-field";
+import { DATA_ERROR_STATUSES } from "./data-errors";
+import {
+  cloudLogout,
+  CloudError,
+  DEFAULT_API_URL,
+  detectKind,
+  parseBody,
+  envToken,
+  fetchWhoami,
+  loginAndStore,
+  resolveSession,
+  storeGivenKey,
+  type CloudIo,
+} from "./cloud";
+import {
+  buildAndDeploy,
+  buildAssetBundle,
+  checkServiceBindings,
+  CLOUD_PROJECT_RE,
+  compileModule,
+  deployToCloud,
+  formatKiB,
+  hostFor,
+  Interrupted,
+  makeCall,
+  tailBuild,
+  waitForApply,
+} from "./cloud-deploy";
+import {
+  APPLY_USAGE,
+  applyMigrations,
+  CREATE_USAGE,
+  createMigration,
+  D1UsageError,
+  DEFAULT_MIGRATIONS_DIR,
+  EXECUTE_USAGE,
+  executeSql,
+  LIST_USAGE,
+  listMigrations,
+  localDatabasePath,
+  localRunner,
+  parseD1Flags,
+  pickBinding,
+  remoteRunner,
+  type D1Io,
+  type Runner,
+} from "./d1-cli";
+import {
+  deleteCloudSecret,
+  listCloudSecrets,
+  patchCloudSecrets,
+  putCloudSecret,
+  readSecretsFile,
+} from "./cloud-secrets";
+import { parseBulkSecrets, type BulkPlan } from "./secrets-bulk";
+import {
+  cloudTarget,
+  communityTarget,
+  DELETE_USAGE as R2_DELETE_USAGE,
+  deleteObject,
+  GET_USAGE as R2_GET_USAGE,
+  getObject,
+  OBJECT_MAX_BYTES,
+  readCapped,
+  parseObjectArgs,
+  parseObjectPath,
+  PUT_USAGE as R2_PUT_USAGE,
+  putObject,
+  R2UsageError,
+  type ObjectTarget,
+} from "./r2-objects";
+import {
+  COMMUNITY_TAIL,
+  DeploymentsUsageError,
+  fetchDeployments,
+  fetchLive,
+  formatCommunityVersion,
+  formatDeployment,
+  formatStatus,
+  LIST_USAGE as DEPLOYMENTS_LIST_USAGE,
+  parseCommunityVersions,
+  parseDeploymentsArgs,
+  STATUS_USAGE as DEPLOYMENTS_STATUS_USAGE,
+  TAIL_USAGE as DEPLOYMENTS_TAIL_USAGE,
+  tailSummary,
+} from "./deployments-cli";
+import { hostname as osHostname, platform as osPlatform, arch as osArch } from "node:os";
+import {
+  CLI_NAME,
+  COMMANDS,
+  helpText,
+  resolveCommand,
+  STORAGE_PRODUCTS,
+  STORAGE_VERBS,
+  type StorageProduct,
+} from "./surface";
 import { notifyIfOutdated } from "./update-check";
 import { controlVersionWarning } from "./api-version";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
@@ -41,26 +152,56 @@ if (internalModeAt > 0) {
   process.exit(0);
 }
 
-const defaultApiUrl = "https://dashboard.sproutboat.com";
-
-type ApiUrlSource = "SPROUTBOAT_API_URL" | "--api-url" | "saved active endpoint" | "default";
+const defaultApiUrl = DEFAULT_API_URL;
 
 /**
- * baronunread/sproutboat#204 — the single place `defaultApiUrl` and
- * `activeApiUrl()` are read. Used to be implemented three different ways
- * across `apiCredentials()`, `whoami()` and `parseLoginArgs()`, none of which
- * told the user which endpoint it picked; `whoami` could report "not logged
- * in" on a machine where `deploy` would happily target prod. Precedence: an
- * explicit `--api-url` flag, then `SPROUTBOAT_API_URL`, then the saved active
- * endpoint, then the default.
+ * baronunread/sproutboat#204 — the single place the endpoint and the stored profile are chosen. `chooseTarget`
+ * (target.ts) holds the precedence: the flags, then the environment, then the machine's active profile, then the
+ * default endpoint, and a profile and a URL that name different places are an error. The choice is also what the
+ * credential lookups use for the rest of the run.
  */
-async function resolveApiUrl(explicitApiUrl?: string): Promise<{ apiUrl: string; source: ApiUrlSource }> {
-  if (explicitApiUrl) return { apiUrl: explicitApiUrl.replace(/\/$/, ""), source: "--api-url" };
-  const envUrl = process.env.SPROUTBOAT_API_URL;
-  if (envUrl) return { apiUrl: envUrl.replace(/\/$/, ""), source: "SPROUTBOAT_API_URL" };
-  const saved = await activeApiUrl();
-  if (saved) return { apiUrl: saved.replace(/\/$/, ""), source: "saved active endpoint" };
-  return { apiUrl: defaultApiUrl, source: "default" };
+async function resolveApiUrl(
+  explicitApiUrl?: string,
+  options: { allowNewProfile?: boolean } = {},
+): Promise<{ apiUrl: string; source: string; target: Target }> {
+  const profiles: Record<string, { apiUrl: string }> = {};
+  for (const { name, profile } of await listProfiles()) profiles[name] = { apiUrl: profile.apiUrl };
+  let target: Target;
+  try {
+    target = chooseTarget({
+      flagUrl: explicitApiUrl ?? globalFlags().apiUrl,
+      flagProfile: globalFlags().profile,
+      envUrl: process.env.SPROUTBOAT_API_URL || undefined,
+      envProfile: process.env.SPROUTBOAT_PROFILE || undefined,
+      profiles,
+      activeProfile: await activeProfileName(),
+      defaultUrl: defaultApiUrl,
+      allowNew: options.allowNewProfile,
+    });
+  } catch (error) {
+    if (error instanceof TargetError) fail(error.message);
+    throw error;
+  }
+  selectProfile(target.profile?.name);
+  return { apiUrl: target.apiUrl, source: target.source, target };
+}
+
+/** The two lines that say where a command is about to act: which profile, and which endpoint. */
+async function printTarget(target: Target): Promise<void> {
+  const profile = target.profile;
+  const name = profile?.name ?? (await savedProfileName(target.apiUrl));
+  const why = profile
+    ? `${profile.source}${profile.exists ? "" : ", new"}`
+    : name
+      ? "the stored login for this endpoint"
+      : "nothing stored for this endpoint";
+  const credential = envToken();
+  console.log(
+    `profile   ${name ?? "-"}  ${dim(`(${why}${credential ? `; the credential comes from ${credential.source}` : ""})`)}`,
+  );
+  const sourceLabel =
+    target.source === "profile" ? `profile ${profile?.name}` : target.source === "default" ? "default" : target.source;
+  console.log(`endpoint  ${target.apiUrl}  ${dim(`(${sourceLabel})`)}`);
 }
 
 /** Warn at most once per run: every API response carries the headers, and one
@@ -207,25 +348,43 @@ function usageError(what: string, usage: string): never {
   process.exit(2);
 }
 
+/** The project directory and config file, from a positional directory and `--config`. */
+function locate(directory?: string) {
+  try {
+    return locateProject(directory);
+  } catch (error) {
+    if (error instanceof Error) return fail(error.message);
+    throw error;
+  }
+}
+
 /** Read the project identity and configuration without touching application code.
  * Management commands must remain usable when a local checkout is incomplete. */
-async function readProjectConfig(directory = process.cwd()) {
-  const projectDirectory = resolve(directory);
-  const configPath = resolve(projectDirectory, "sproutboat.jsonc");
+async function readProjectConfig(directory?: string) {
+  const { directory: projectDirectory, configPath } = locate(directory);
   let configSource: string;
   try {
     configSource = await readFile(configPath, "utf8");
   } catch {
-    fail(`no sproutboat.jsonc found in ${projectDirectory}`);
+    fail(
+      globalFlags().config === undefined
+        ? `no sproutboat.jsonc found in ${projectDirectory}`
+        : `no config file at ${configPath}`,
+    );
   }
-  const parsed = parseConfig(configSource);
+  const parsed = parseProjectConfig(configSource);
   if (!parsed.ok) fail(parsed.errors.join("\n"));
   for (const warning of parsed.warnings) console.warn(amber(`! ${warning}`));
-  return { directory: projectDirectory, config: parsed.value };
+  return {
+    directory: projectDirectory,
+    config: parsed.value,
+    account: configAccount(configSource),
+    migrationsDir: configMigrationsDir(configSource),
+  };
 }
 
 /** Full build input: configuration plus entry point, resolved imports and checks. */
-async function readProject(directory = process.cwd()) {
+async function readProject(directory?: string) {
   const project = await readProjectConfig(directory);
   const sourcePath = resolve(project.directory, project.config.main);
   let source: string;
@@ -378,9 +537,10 @@ async function buildStandaloneBinary(
   target: BuildTarget,
   withRestore = false,
   deployFiles = false,
+  release = false,
 ) {
   const project = await readProject(directory);
-  console.log(dim(`Building a standalone ${project.config.name} (${target})…`));
+  console.log(dim(`Building a standalone ${project.config.name} (${target}, ${release ? "release, LTO" : "no LTO"})…`));
   try {
     const result = await buildStandalone({
       projectDir: project.directory,
@@ -389,9 +549,14 @@ async function buildStandaloneBinary(
       source: project.bundle.code,
       target,
       withRestore,
+      release,
     });
     console.log(ok(`built ${result.outPath} (${(result.bytes / 1_000_000).toFixed(1)} MB)`));
     console.log(dim(`  run it: ${result.outPath}   ·   state lands in ./${project.config.name}.data`));
+    if (!release)
+      console.log(
+        dim("  built without LTO (faster to build, slower to serve); add --release for the binary you publish"),
+      );
     if (target === "linux-arm64") console.log(dim("  linux-arm64: runs on an aarch64 Linux box, not on this machine"));
     if (deployFiles && isLinuxTarget(target)) {
       const written = await writeDeployFiles({ name: project.config.name, target, binary: result.outPath });
@@ -430,24 +595,43 @@ async function emitOnly(directory: string | undefined, target: BuildTarget, stan
   }
 }
 
+/** The standalone source unit the Cloud compile starts from (what `build --standalone --emit-only` prints). */
+async function emitStandaloneUnit(directory: string | undefined): Promise<string> {
+  const project = await readProject(directory);
+  try {
+    const { generatedPath } = await emitStandalone(
+      {
+        projectDir: project.directory,
+        config: project.config,
+        sourcePath: project.sourcePath,
+        source: project.bundle.code,
+        target: "linux-x86_64",
+      },
+      { forCloud: true },
+    );
+    return generatedPath;
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
 /** #62 — build for this machine, run it against a real broker, rebuild on save. */
-const DEV_USAGE = "dev [project-dir] [--port <n>] [--no-watch] [--env <name>] [--env-file <file>]...";
+const DEV_USAGE = "dev [project-dir] [--port <n>] [--no-watch] [-e, --env <name>] [--env-file <file>]...";
 
 async function dev(args: string[]) {
   let directory: string | undefined;
   let portArg: string | undefined;
-  let envName: string | undefined;
-  const envFiles: string[] = [];
+  // --env and --env-file are global flags, already taken out of `args` (global-flags.ts).
+  const envName = globalFlags().env;
+  const envFiles = globalFlags().envFiles.map((file) => resolve(file));
   for (let at = 0; at < args.length; at += 1) {
     const arg = args[at];
     if (arg === "--no-watch") continue;
-    if (arg === "--port" || arg === "--env" || arg === "--env-file") {
+    if (arg === "--port") {
       const value = args[at + 1];
       if (value === undefined || value.startsWith("--")) usageError(`${arg} needs a value`, DEV_USAGE);
       at += 1;
-      if (arg === "--port") portArg = value;
-      else if (arg === "--env") envName = value;
-      else envFiles.push(resolve(value));
+      portArg = value;
     } else if (!arg.startsWith("--") && directory === undefined) directory = arg;
   }
   const port = Number(portArg ?? 8787);
@@ -481,9 +665,11 @@ async function dev(args: string[]) {
 async function run(args: string[]) {
   const result = parseRunArgs(args);
   if ("error" in result) usageError(result.error, RUN_USAGE);
+  // --env-file is a global flag, already taken out of `args` (global-flags.ts).
+  result.args.envFiles.unshift(...globalFlags().envFiles);
   let plan;
   try {
-    plan = await planRun(result.args, { cwd: process.cwd(), inherited: process.env });
+    plan = await planRun(result.args, { cwd: process.cwd(), inherited: process.env, config: globalFlags().config });
   } catch (error) {
     if (error instanceof RunError || error instanceof EnvFileError || error instanceof MissingSecretsError)
       fail(error.message);
@@ -517,10 +703,10 @@ const PROVISION_FIELDS = [
  * deploy, and the id is written back into `sproutboat.jsonc`. `--no-provision`
  * skips this — those bindings then get an ephemeral deploy-scoped store.
  */
-async function provisionBindings(directory = process.cwd()): Promise<void> {
-  const configPath = resolve(directory, "sproutboat.jsonc");
+async function provisionBindings(directory?: string): Promise<void> {
+  const { configPath } = locate(directory);
   let source = await readFile(configPath, "utf8");
-  const parsed = parseConfig(source);
+  const parsed = parseProjectConfig(source);
   if (!parsed.ok) return; // build() re-reads and reports the config error
 
   const bare: Array<{ field: string; kind: string; binding: string }> = [];
@@ -552,7 +738,25 @@ async function provisionBindings(directory = process.cwd()): Promise<void> {
 
 /** #79 — wrangler parity: drop the stored credential for an endpoint. */
 async function logout(args: string[]) {
-  const { apiUrl } = await parseLoginArgs(args);
+  const { apiUrl, account, target } = await parseLoginArgs(args);
+  await printTarget(target);
+  if ((await savedProfile(apiUrl))?.kind === "cloud") {
+    const outcome = await guard(() => cloudLogout(apiUrl, account));
+    if (outcome.kind === "none") {
+      console.log(`no stored login for ${account ? `the team "${account}" on ` : ""}${apiUrl}`);
+      return;
+    }
+    const how =
+      outcome.server === "revoked"
+        ? "revoked its key on the server"
+        : outcome.server === "already-gone"
+          ? "its key was already revoked on the server"
+          : "could not reach the server, so the key may still be live: delete it under Settings, API keys";
+    console.log(ok(`logged out of ${outcome.slug} on ${apiUrl} (${how})`));
+    if (outcome.remaining.length > 0) console.log(dim(`still logged in to: ${outcome.remaining.join(", ")}`));
+    if (envToken()) console.log(dim("SPROUTBOAT_API_TOKEN is set in this shell and still applies"));
+    return;
+  }
   const result = await forgetToken(apiUrl);
   if (!result.removed) {
     console.log(`no stored credential for ${apiUrl}`);
@@ -563,17 +767,75 @@ async function logout(args: string[]) {
     console.log(dim("no active endpoint remains — the next command falls through to the default"));
 }
 
+/** `profile list` and `profile use <name>`: the stored profiles, and which one a command uses by default. */
+async function profile(args: string[]) {
+  const sub = args[0] ?? "list";
+  if (sub === "use") {
+    const name = args[1];
+    if (!name || args.length > 2) usageError("profile use needs a profile name", "profile <list | use <name>>");
+    if (!(await useProfile(name))) {
+      const known = (await listProfiles()).map((entry) => entry.name);
+      fail(
+        `no profile named "${name}"${known.length > 0 ? ` (profiles: ${known.join(", ")})` : ""}; create it with \`sproutboat login --profile ${name}\``,
+      );
+    }
+    console.log(ok(`${name} is now the default profile`));
+    return;
+  }
+  if (sub !== "list" || args.length > 1)
+    usageError(`profile: unknown subcommand "${sub}"`, "profile <list | use <name>>");
+  const entries = await listProfiles();
+  if (entries.length === 0) {
+    console.log("no profiles stored; run `sproutboat login`");
+    return;
+  }
+  const width = Math.max(...entries.map((entry) => entry.name.length));
+  for (const { name, active, profile: stored } of entries) {
+    const kind = stored.kind === "cloud" ? "Cloud" : stored.kind === "community" ? "Community" : "";
+    const team = stored.kind === "cloud" && stored.team ? ` team ${stored.team}` : "";
+    console.log(`${active ? "*" : " "} ${name.padEnd(width)}  ${stored.apiUrl}  ${dim(`${kind}${team}`.trim())}`);
+  }
+  console.log(dim("* is the default profile; pick another for one command with --profile <name>"));
+}
+
 /**
  * #79 — wrangler parity: which endpoint, and who the stored token belongs to.
  * The account comes from the control plane, so this also proves the token still
  * works rather than only reporting what is on disk.
  */
-async function whoami() {
-  const { apiUrl, source } = await resolveApiUrl();
-  const token = process.env.SPROUTBOAT_TOKEN || (await savedToken(apiUrl));
-  console.log(`endpoint  ${apiUrl}  (${source})`);
+async function whoami(args: string[]) {
+  const { apiUrl, target, account: wanted } = await parseLoginArgs(args);
+  const fromEnv = envToken();
+  const saved = await savedProfile(apiUrl);
+  await printTarget(target);
+  const kind = saved?.kind ?? (fromEnv ? await kindOf(apiUrl) : undefined);
+  if (kind === "cloud") {
+    const team = wanted ?? saved?.team ?? Object.keys(saved?.teams ?? {})[0];
+    const token = fromEnv?.token ?? (team ? saved?.teams[team]?.token : undefined) ?? saved?.token;
+    if (!token) {
+      const hint = wanted
+        ? `not logged in to the team "${wanted}"; run \`sproutboat login --account ${wanted}\``
+        : "not logged in; run `sproutboat login`";
+      console.log(`account   ${rose(hint)}`);
+      process.exitCode = 1;
+      return;
+    }
+    const who = await guard(() => fetchWhoami(apiUrl, token, fromEnv !== undefined));
+    console.log(`kind      Sproutboat Cloud`);
+    console.log(`team      ${who.slug}${who.name !== who.slug ? ` (${who.name})` : ""}`);
+    console.log(
+      `key       ${who.keyName || who.keyId}  ${dim(fromEnv ? `token from ${fromEnv.source}` : "stored login")}`,
+    );
+    if (who.permissions) console.log(`access    ${who.permissions}`);
+    if (who.person) console.log(`email     ${who.person.email}`);
+    const stored = Object.keys(saved?.teams ?? {});
+    if (!fromEnv && stored.length > 1) console.log(dim(`logged in to ${stored.length} teams: ${stored.join(", ")}`));
+    return;
+  }
+  const token = fromEnv?.token || (await savedToken(apiUrl));
   if (!token) {
     console.log(`account   ${dim("no stored token — run `sproutboat login`")}`);
+    process.exitCode = 1;
     return;
   }
 
@@ -582,6 +844,7 @@ async function whoami() {
     console.log(
       `account   ${rose(response.status === 401 ? "token rejected — run `sproutboat login`" : `control plane said ${response.status}`)}`,
     );
+    process.exitCode = 1;
     return;
   }
   const account = jsonObject(parseJsonValue(await response.text()));
@@ -592,8 +855,20 @@ async function whoami() {
 }
 
 async function deploy(args: string[]) {
-  const artifactIndex = args.indexOf("--artifact");
+  const flags = takeFlags(args, DEPLOY_FLAGS);
   const dryRun = args.includes("--dry-run");
+  const { apiUrl: targetUrl, target } = await resolveApiUrl(flags["--api-url"]);
+  await printTarget(target);
+  const kind = await deployKind(targetUrl, dryRun);
+  if (kind === "cloud") {
+    if (args.includes("--artifact"))
+      fail("--artifact deploys a prebuilt Community artifact; the Cloud builds your source: run deploy without it");
+    await guard(() => deployCloud(args, targetUrl, flags));
+    return;
+  }
+  if (flags["--secrets-file"] !== undefined)
+    fail("--secrets-file is for the Cloud; on this endpoint set secrets with `sproutboat secrets put <NAME>`");
+  const artifactIndex = args.indexOf("--artifact");
   const directory = args.find((arg, index) => !arg.startsWith("--") && index !== artifactIndex + 1);
   let projectName: string;
   let artifactDir: string;
@@ -635,8 +910,7 @@ async function deploy(args: string[]) {
     console.log("\n--dry-run: not uploading.");
     return;
   }
-  const { apiUrl, token, source } = await apiCredentials();
-  console.log(`endpoint  ${apiUrl}  (${source})`);
+  const { apiUrl, token } = await apiCredentials(flags["--api-url"]);
   const form = new FormData();
   form.set("manifest", new File([await manifest.arrayBuffer()], "manifest.json", { type: "application/json" }));
   form.set("sprout", new File([await sprout.arrayBuffer()], "sprout", { type: "application/octet-stream" }));
@@ -726,34 +1000,50 @@ async function waitForHealthy(url: string, timeoutMs: number): Promise<boolean>
   return false;
 }
 
-async function parseLoginArgs(args: string[]) {
-  let explicitApiUrl: string | undefined;
+async function parseLoginArgs(args: string[], options: { allowNewProfile?: boolean } = {}) {
   let token: string | undefined;
+  let account: string | undefined;
+  // --api-url is a global flag (global-flags.ts); resolveApiUrl reads it.
   for (let index = 0; index < args.length; index += 2) {
     const value = args[index + 1];
-    if (args[index] === "--api-url" && value) explicitApiUrl = value;
-    else if (args[index] === "--token" && value) token = value;
-    else usageError(`login: unexpected argument "${args[index]}"`, "login [--api-url <url>] [--token <token>]");
+    if (args[index] === "--token" && value) token = value;
+    else if (args[index] === "--account" && value) account = value;
+    else
+      usageError(
+        `unexpected argument "${args[index]}"`,
+        "login [--api-url <url>] [--token <token>] [--account <team>]",
+      );
   }
-  const { apiUrl, source } = await resolveApiUrl(explicitApiUrl);
-  return { apiUrl, source, token };
+  const { apiUrl, source, target } = await resolveApiUrl(undefined, options);
+  return { apiUrl, source, target, token, account };
 }
 
-/** Announce a login that left the machine's active endpoint pointed elsewhere. */
-function reportActiveEndpoint(apiUrl: string, active: string): void {
-  if (active !== apiUrl)
-    console.log(dim(`active endpoint remains ${active} — \`sproutboat logout\` it first to switch`));
+/** Say which profile a login went to, and when it left the machine's default profile pointed elsewhere. */
+function reportSaved(saved: { profile: string; activeProfile: string; activeApiUrl: string }): void {
+  console.log(dim(`  stored as the profile "${saved.profile}"`));
+  if (saved.activeProfile !== saved.profile)
+    console.log(
+      dim(
+        `  the default profile stays "${saved.activeProfile}" (${saved.activeApiUrl}); use --profile ${saved.profile}, or \`sproutboat profile use ${saved.profile}\``,
+      ),
+    );
 }
 
 async function login(args: string[]) {
-  const { apiUrl, source, token: directToken } = await parseLoginArgs(args);
-  console.log(`endpoint  ${apiUrl}  (${source})`);
+  const { apiUrl, target, token: directToken, account } = await parseLoginArgs(args, { allowNewProfile: true });
+  await printTarget(target);
+  const kind = await kindOf(apiUrl);
+  if (kind === undefined && !directToken) fail(`cannot reach ${apiUrl}; check the address and your network`);
+  if (kind === "cloud") {
+    await guard(() => cloudLogin(apiUrl, directToken, account));
+    return;
+  }
   // Self-hosted / non-interactive: skip the browser flow and store the token
   // the admin already holds (e.g. SPROUTBOAT_BOOTSTRAP_TOKEN).
   if (directToken) {
-    const { activeApiUrl: active } = await saveToken(apiUrl, directToken);
+    const saved = await saveToken(apiUrl, directToken, kind);
     console.log(`Saved credentials for ${apiUrl}.`);
-    reportActiveEndpoint(apiUrl, active);
+    reportSaved(saved);
     return;
   }
   const response = await fetch(`${apiUrl}/api/cli/authorizations`, { method: "POST" });
@@ -786,21 +1076,427 @@ async function login(args: string[]) {
     if (!exchange.ok) fail(`login failed (${exchange.status}): ${result}`);
     const token = parseToken(result);
     if (!token) fail("login response did not include a CLI token");
-    const { activeApiUrl: active } = await saveToken(apiUrl, token);
+    const saved = await saveToken(apiUrl, token, "community");
     console.log(ok("login approved — credentials saved for this endpoint"));
-    reportActiveEndpoint(apiUrl, active);
+    reportSaved(saved);
     return;
   }
   fail("login expired before approval");
 }
 
-async function apiCredentials() {
-  const { apiUrl, source } = await resolveApiUrl();
-  const token = process.env.SPROUTBOAT_TOKEN || (await savedToken(apiUrl));
-  if (!token) fail("not logged in; run sproutboat login or set SPROUTBOAT_TOKEN for this command");
+const DEPLOY_FLAGS = ["--api-url", "--account", "--module", "--sproutd", "--generation", "--secrets-file"] as const;
+type DeployFlag = (typeof DEPLOY_FLAGS)[number];
+
+function guardSync(step: () => void): void {
+  try {
+    step();
+  } catch (error) {
+    if (error instanceof CloudError) return fail(error.message);
+    throw error;
+  }
+}
+
+async function readSecretsFileOrFail(path: string) {
+  try {
+    return await readSecretsFile(path);
+  } catch (error) {
+    if (error instanceof CloudError || error instanceof EnvFileError) return fail(error.message);
+    throw error;
+  }
+}
+
+/** Run a Cloud step; its CloudError becomes a printed failure. */
+async function guard<T>(step: () => Promise<T>): Promise<T> {
+  try {
+    return await step();
+  } catch (error) {
+    if (error instanceof CloudError) return fail(error.message);
+    throw error;
+  }
+}
+
+/** Remove `--name value` pairs from `args` (in place) and return their values. */
+function takeFlags<Name extends string>(args: string[], names: readonly Name[]) {
+  const values: { [flag in Name]?: string } = {};
+  for (const name of names) {
+    const at = args.indexOf(name);
+    if (at < 0) continue;
+    const value = args[at + 1];
+    if (value === undefined || value.startsWith("--"))
+      usageError(`${name} needs a value`, "deploy [project-dir] [${name} <value>]");
+    values[name] = value;
+    args.splice(at, 2);
+  }
+  return values;
+}
+
+/** Cloud or Community, or undefined when the endpoint cannot be reached. */
+async function kindOf(apiUrl: string) {
+  try {
+    return await detectKind(apiUrl);
+  } catch {
+    return undefined;
+  }
+}
+
+async function deployKind(apiUrl: string, dryRun: boolean) {
+  const stored = envToken() ? undefined : (await savedProfile(apiUrl))?.kind;
+  if (stored) return stored;
+  const kind = await kindOf(apiUrl);
+  if (kind === undefined && !dryRun) fail(`cannot reach ${apiUrl}; check the address and your network`);
+  return kind ?? "community";
+}
+
+function openInBrowser(url: string): boolean {
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const headless =
+    process.platform === "linux" &&
+    (!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY) || process.env.SSH_CONNECTION);
+  if (headless || !Bun.which(opener)) return false;
+  try {
+    Bun.spawn(opener === "cmd" ? ["cmd", "/c", "start", "", url] : [opener, url], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function terminalIo(): CloudIo {
+  return {
+    log: (line) => console.log(line),
+    warn: (line) => console.warn(amber(line)),
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    openUrl: openInBrowser,
+    sleep: (ms) => Bun.sleep(ms),
+    choose: async (question, choices) => {
+      const { createInterface } = await import("node:readline/promises");
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      try {
+        console.log(question);
+        choices.forEach((choice, at) => console.log(`  ${at + 1}) ${choice}`));
+        for (;;) {
+          const answer = (await rl.question("> ")).trim();
+          const picked = choices[Number(answer) - 1] ?? choices.find((choice) => choice === answer);
+          if (picked) return picked;
+        }
+      } finally {
+        rl.close();
+      }
+    },
+  };
+}
+
+async function cloudLogin(apiUrl: string, directToken: string | undefined, account: string | undefined) {
+  if (directToken) {
+    const stored = await storeGivenKey(apiUrl, directToken);
+    console.log(ok(`saved the key for ${stored.slug} on ${apiUrl}`));
+    return;
+  }
+  const cancel = () => {
+    console.log("\nlogin cancelled");
+    process.exit(130);
+  };
+  process.once("SIGINT", cancel);
+  const done = await loginAndStore({
+    apiUrl,
+    io: terminalIo(),
+    hostname: osHostname(),
+    os: `${osPlatform()} ${osArch()}`,
+    account,
+  });
+  process.off("SIGINT", cancel);
+  console.log(
+    ok(
+      `logged in to ${bold(done.slug)}${done.team.role ? ` as ${done.team.role}` : ""} with the key "${done.keyName}"`,
+    ),
+  );
+  console.log(dim("  revoke it any time under Settings, API keys, or with `sproutboat logout`"));
+  reportSaved(done);
+}
+
+async function deployCloud(args: string[], apiUrl: string, flags: ReturnType<typeof takeFlags<DeployFlag>>) {
+  const dryRun = args.includes("--dry-run");
+  const io = terminalIo();
+  const directory = args.find((arg) => !arg.startsWith("--"));
+  const project = await readProjectConfig(directory);
+  const name = project.config.name;
+  if (!CLOUD_PROJECT_RE.test(name))
+    fail(`"${name}" is not a valid Cloud app name (3 to 32 characters: lowercase letters, digits, dashes)`);
+
+  const account = flags["--account"] ?? project.account;
+  let session: Awaited<ReturnType<typeof resolveSession>> | undefined;
+  try {
+    session = await resolveSession({
+      apiUrl,
+      io,
+      account,
+      login: async (hint) => {
+        if (dryRun) throw new CloudError("not logged in (--dry-run does not start a login)");
+        process.once("SIGINT", () => process.exit(130));
+        return loginAndStore({ apiUrl, io, hostname: osHostname(), os: `${osPlatform()} ${osArch()}`, account: hint });
+      },
+    });
+  } catch (error) {
+    if (!dryRun || !(error instanceof CloudError)) throw error;
+    io.warn(`! ${error.message}; the plan below uses a placeholder team`);
+  }
+  const team = session?.slug ?? account ?? "<team>";
+  const hosts = [hostFor(name, team)];
+
+  const cfg = project.config;
+  const unsent = Object.entries({
+    kv_namespaces: cfg.kv_namespaces?.length,
+    d1_databases: cfg.d1_databases?.length,
+    r2_buckets: cfg.r2_buckets?.length,
+    queues: cfg.queues?.length,
+    analytics_engine_datasets: cfg.analytics_engine_datasets?.length,
+    durable_objects: Object.keys(cfg.durable_objects ?? {}).length,
+    ratelimiters: cfg.ratelimiters?.length,
+    "triggers.crons": cfg.triggers?.crons?.length,
+  })
+    .filter(([, count]) => (count ?? 0) > 0)
+    .map(([key]) => key);
+  if (unsent.length > 0)
+    io.warn(
+      `! ${unsent.join(", ")} in sproutboat.jsonc are not sent to the Cloud by the CLI yet; the app runs without them`,
+    );
+
+  const services = cfg.services ?? [];
+  guardSync(() => checkServiceBindings(name, services, cfg.compatibility_date));
+  let secretValues: Record<string, string> | undefined;
+  const secretsFile = flags["--secrets-file"];
+  if (secretsFile !== undefined) {
+    const read = await readSecretsFileOrFail(resolve(secretsFile));
+    for (const warning of read.warnings) io.warn(`! ${warning}`);
+    secretValues = read.values;
+  }
+
+  const assets = project.config.assets ? buildAssetBundle(project.directory, project.config.assets) : undefined;
+  // Regular deploys build in the Cloud from the bundled source. --module (a prebuilt module) and --sproutd with
+  // --generation (compile here) are the operator paths; the Cloud refuses a module from a team key.
+  let modulePath = flags["--module"];
+  const compiled =
+    modulePath === undefined && Boolean(flags["--sproutd"] ?? flags["--generation"] ?? process.env.SPROUTBOAT_SPROUTD);
+  const fromSource = modulePath === undefined && !compiled;
+  if (compiled) {
+    modulePath = resolve(tmpdir(), `sproutboat-${name}-${process.pid}.so`);
+    console.log(dim("Compiling the module (sproutd)…"));
+    await compileModule({
+      project: name,
+      emit: () => emitStandaloneUnit(directory),
+      sproutd: flags["--sproutd"] ?? process.env.SPROUTBOAT_SPROUTD,
+      generation: flags["--generation"] ?? process.env.SPROUTBOAT_GENERATION,
+      out: modulePath,
+      bun: process.versions.bun ? process.execPath : (Bun.which("bun") ?? "bun"),
+    });
+  } else if (modulePath !== undefined && !existsSync(modulePath)) fail(`no such module: ${modulePath}`);
+
+  console.log(`app       ${bold(name)}`);
+  console.log(`team      ${team}${session ? "" : dim("  (not resolved)")}`);
+  console.log(`endpoint  ${apiUrl}`);
+  console.log(`route     https://${hosts[0]}`);
+  if (assets) console.log(`assets    ${assets.files} files`);
+  if (services.length > 0)
+    console.log(`services  ${services.map((entry) => `${entry.binding} -> ${entry.service}`).join(", ")}`);
+  if (secretValues) console.log(`secrets   ${Object.keys(secretValues).length} from ${secretsFile} (set, others kept)`);
+  if (fromSource) console.log(`build     in the Cloud, from your bundled source`);
+  if (dryRun) {
+    console.log("\n--dry-run: not uploading.");
+    if (fromSource) console.log(dim("  A real deploy bundles your source, uploads it and has the Cloud build it."));
+    if (compiled) rmSync(modulePath!, { force: true });
+    return;
+  }
+  const tokenFromEnv = session!.source !== "stored login";
+  const noWait = args.includes("--no-wait");
+  const printResult = (result: {
+    created: boolean;
+    generation: number | undefined;
+    url: string | undefined;
+    applied: boolean | "skipped";
+    buildId?: string;
+  }) => {
+    if (result.generation === undefined) {
+      console.log(`\n${leaf("🌱")} ${bold(leaf(`Build queued for ${name}`))}`);
+      console.log(dim(`  status  ${apiUrl}/v1/builds/${result.buildId}`));
+      return;
+    }
+    console.log(`\n${leaf("🌱")} ${bold(leaf(`${result.created ? "Created" : "Updated"} ${name}`))}`);
+    if (result.url) {
+      console.log(`  ${bold(result.url)}`);
+    }
+    console.log(dim(`  generation ${result.generation}  ·  team ${team}`));
+    if (result.applied === false) {
+      fail(
+        `generation ${result.generation} is saved but no host has applied it after 120 s; it applies when a host is available (check with: sproutboat whoami, or the dashboard)`,
+      );
+    }
+  };
+  if (fromSource) {
+    const sourcePath = await emitStandaloneUnit(directory);
+    console.log(`  Bundling   ${cfg.main} (${formatKiB(Bun.file(sourcePath).size)})`);
+    const controller = new AbortController();
+    const interrupt = () => controller.abort();
+    process.once("SIGINT", interrupt);
+    try {
+      const result = await buildAndDeploy(
+        {
+          apiUrl,
+          token: session!.token,
+          tokenFromEnv,
+          project: name,
+          services,
+          compatibilityDate: cfg.compatibility_date,
+          secrets: secretValues,
+          hosts,
+          sourcePath,
+          cli: { version: CLI_VERSION },
+          assets,
+          noWait,
+        },
+        io,
+        controller.signal,
+      );
+      printResult(result);
+    } catch (error) {
+      if (error instanceof Interrupted) {
+        console.error(error.message);
+        process.exit(130);
+      }
+      throw error;
+    } finally {
+      process.off("SIGINT", interrupt);
+    }
+    return;
+  }
+  try {
+    const result = await deployToCloud(
+      {
+        apiUrl,
+        token: session!.token,
+        tokenFromEnv,
+        project: name,
+        hosts,
+        modulePath: modulePath!,
+        assets,
+        noWait,
+        services,
+        compatibilityDate: cfg.compatibility_date,
+        secrets: secretValues,
+      },
+      io,
+    );
+    printResult(result);
+  } finally {
+    if (compiled) rmSync(modulePath!, { force: true });
+  }
+}
+
+async function apiCredentials(explicitApiUrl?: string) {
+  const { apiUrl, source } = await resolveApiUrl(explicitApiUrl);
+  const token = envToken()?.token || (await savedToken(apiUrl));
+  if (!token) fail("not logged in; run sproutboat login or set SPROUTBOAT_API_TOKEN for this command");
   return { apiUrl, token, source };
 }
 
+/**
+ * `deployments list | status | tail <id>`. A Cloud deployment is a build; a Community one is a version. `tail` follows a
+ * build server-side and never cancels it, which is what a deploy detached with Ctrl-C needs.
+ */
+async function deployments(args: string[]) {
+  const sub = args.shift();
+  if (sub !== "list" && sub !== "status" && sub !== "tail")
+    usageError(
+      sub ? `deployments: unknown subcommand "${sub}"` : "deployments: missing subcommand",
+      "deployments <list | status | tail <id>>",
+    );
+  const usage =
+    sub === "list" ? DEPLOYMENTS_LIST_USAGE : sub === "status" ? DEPLOYMENTS_STATUS_USAGE : DEPLOYMENTS_TAIL_USAGE;
+  let parsed: ReturnType<typeof parseDeploymentsArgs>;
+  try {
+    parsed = parseDeploymentsArgs(args, usage);
+  } catch (error) {
+    if (error instanceof DeploymentsUsageError) return usageError(error.message, error.usage);
+    throw error;
+  }
+  const { positional, flags } = parsed;
+  const id = positional[0];
+  if (sub === "tail" && !id) usageError("deployments tail: missing <id>", usage);
+  if (positional.length > (sub === "tail" ? 1 : 0)) usageError(`unexpected argument "${positional.at(-1)}"`, usage);
+  const project = await readProjectConfig();
+  const app = project.config.name;
+  const { apiUrl: targetUrl } = await resolveApiUrl();
+  const kind = await deployKind(targetUrl, false);
+
+  if (kind !== "cloud") {
+    if (sub === "tail") return fail(COMMUNITY_TAIL);
+    const { apiUrl, token } = await apiCredentials();
+    const body = await responseText(
+      await fetch(`${apiUrl}/api/projects/${app}/deployments`, { headers: { "x-api-key": token } }),
+      "could not list deployments",
+    );
+    const list = parseJsonValue(body);
+    const versions = parseCommunityVersions(
+      Array.isArray(list)
+        ? list.flatMap((entry) => {
+            const item = jsonObject(entry);
+            return item ? [item] : [];
+          })
+        : [],
+    );
+    if (sub === "status") {
+      const active = versions.find((version) => version.active);
+      if (flags.json) console.log(JSON.stringify(active ?? null, null, 2));
+      else console.log(active ? formatCommunityVersion(active) : `${app} has no active deployment`);
+      return;
+    }
+    const shown = versions.slice(0, flags.limit);
+    if (flags.json) console.log(JSON.stringify(shown, null, 2));
+    else console.log(shown.length ? shown.map(formatCommunityVersion).join("\n\n") : "no deployments");
+    return;
+  }
+
+  await guard(async () => {
+    const credentials = await cloudCredentials(targetUrl, flags.account ?? project.account);
+    if (sub === "tail") {
+      // Ctrl-C only stops following: the build keeps going, and tail can be run again.
+      const controller = new AbortController();
+      let detached = false;
+      process.once("SIGINT", () => {
+        detached = true;
+        controller.abort();
+      });
+      let view;
+      try {
+        view = await tailBuild(credentials, id!, terminalIo(), controller.signal);
+      } catch (error) {
+        if (detached || error instanceof Interrupted) {
+          console.error(
+            `detached: the deployment keeps running; \`sproutboat deployments tail ${id}\` follows it again`,
+          );
+          process.exit(130);
+        }
+        throw error;
+      }
+      console.log(tailSummary(view));
+      if (view.state !== "ready") process.exitCode = 1;
+      return;
+    }
+    if (sub === "status") {
+      const live = await fetchLive(credentials, app);
+      const { deployments: recent } = live ? await fetchDeployments(credentials, app, 1) : { deployments: [] };
+      if (flags.json) console.log(JSON.stringify({ application: app, live, latest: recent[0] ?? null }, null, 2));
+      else console.log(formatStatus(app, live, recent[0]));
+      return;
+    }
+    const { deployments: recent } = await fetchDeployments(credentials, app, flags.limit);
+    if (flags.json) console.log(JSON.stringify(recent, null, 2));
+    else console.log(recent.length ? recent.map(formatDeployment).join("\n\n") : `no deployments of ${app} yet`);
+  });
+}
+
 async function versions(args: string[]) {
   const sub = args[0];
   if (sub !== "list" && sub !== "view") {
@@ -1011,7 +1707,11 @@ async function domains(args: string[]) {
 }
 
 async function secrets(args: string[]) {
-  const sub = args[0] && ["list", "put", "delete"].includes(args[0]) ? args.shift()! : "list";
+  const sub = args[0] && ["list", "put", "delete", "bulk"].includes(args[0]) ? args.shift()! : "list";
+  // `--no-deploy`: change the secrets without waiting for a host to apply them as a new version.
+  const noDeploy = args.includes("--no-deploy");
+  if (noDeploy) args.splice(args.indexOf("--no-deploy"), 1);
+  const flags = takeFlags(args, ["--account"] as const);
 
   // `--value` is opt-in; without it the value comes from stdin, so a secret does
   // not land in shell history. It is also what disambiguates the positionals:
@@ -1019,14 +1719,26 @@ async function secrets(args: string[]) {
   // and read the value as the project directory.
   let inlineValue: string | undefined;
   const positional: string[] = [];
+  const grammar = `secrets ${sub} ${sub === "list" ? "" : sub === "bulk" ? "[file.json | file.env] " : "<NAME> "}[project-dir] [--api-url <url>] [--account <team>]`;
   for (let index = 0; index < args.length; index += 1) {
-    if (args[index] === "--value") inlineValue = args[(index += 1)];
-    else positional.push(args[index]);
+    const arg = args[index];
+    if (arg === "--value" || arg.startsWith("--value=")) {
+      if (sub !== "put") usageError(`secrets ${sub} does not take --value`, grammar);
+      inlineValue = arg === "--value" ? args[(index += 1)] : arg.slice("--value=".length);
+      if (inlineValue === undefined) usageError("--value needs a value", grammar);
+    } else if (arg.startsWith("-") && arg !== "-") usageError(`unknown option ${arg.split("=")[0]}`, grammar);
+    else positional.push(arg);
   }
 
+  if (sub === "bulk") return bulkSecrets(positional, flags, noDeploy);
   const name = sub === "list" ? undefined : positional.shift();
   if (sub !== "list" && !name) usageError(`secrets ${sub}: missing <NAME>`, `secrets ${sub} <NAME> [project-dir]`);
   if (name && !/^[A-Z][A-Z0-9_]*$/.test(name)) fail("secret name must be UPPER_SNAKE_CASE");
+  const { apiUrl: targetUrl } = await resolveApiUrl();
+  if ((await deployKind(targetUrl, false)) === "cloud") {
+    await guard(() => cloudSecrets(sub, name, inlineValue, positional[0], targetUrl, flags["--account"], noDeploy));
+    return;
+  }
   const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(positional[0]), apiCredentials()]);
   const base = `${apiUrl}/api/projects/${project.config.name}/secrets`;
   const auth = { "x-api-key": token };
@@ -1054,7 +1766,306 @@ async function secrets(args: string[]) {
     }),
     "put rejected",
   );
-  console.log(ok(`set ${name} — applies on the next deploy or sprout restart`));
+  console.log(
+    ok(
+      `set ${name}; self-hosted Community applies it on the next deploy or restart of the app (it has no redeploy route yet)`,
+    ),
+  );
+}
+
+/**
+ * `secrets bulk [file]`: the input of `wrangler secret bulk` (JSON with null to delete, or .env; stdin when no file).
+ * On a Cloud endpoint it is one PATCH and so one new version; on self-hosted Community it is one call per name.
+ */
+async function bulkSecrets(positional: string[], flags: ReturnType<typeof takeFlags<"--account">>, noDeploy: boolean) {
+  const file = positional.shift();
+  const directory = positional[0];
+  if (file === undefined && process.stdin.isTTY)
+    usageError(
+      "secrets bulk: missing <file>, and nothing is piped on stdin",
+      "secrets bulk [file.json | file.env] [project-dir]",
+    );
+  let text: string;
+  try {
+    text = file === undefined ? await Bun.stdin.text() : await readFile(resolve(file), "utf8");
+  } catch {
+    return fail(`${file}: cannot read the file`);
+  }
+  let plan: BulkPlan | undefined;
+  guardSync(() => {
+    plan = parseBulkSecrets(text, file ?? "stdin");
+  });
+  const bulk = plan!;
+  for (const warning of bulk.warnings) console.warn(amber(`! ${warning}`));
+  const sets = Object.keys(bulk.set).length;
+  const summary = `${sets} set, ${bulk.delete.length} deleted`;
+  const { apiUrl: targetUrl } = await resolveApiUrl();
+  const project = await readProjectConfig(directory);
+  const app = project.config.name;
+  if ((await deployKind(targetUrl, false)) === "cloud") {
+    await guard(async () => {
+      const credentials = await cloudCredentials(targetUrl, flags["--account"] ?? project.account);
+      const generation = await patchCloudSecrets(credentials, app, bulk);
+      await finishCloudSecretChange({ credentials, app, generation, noDeploy, what: `${summary} on ${app}` });
+    });
+    return;
+  }
+  const { apiUrl, token } = await apiCredentials();
+  const base = `${apiUrl}/api/projects/${app}/secrets`;
+  const auth = { "x-api-key": token };
+  for (const [secretName, value] of Object.entries(bulk.set))
+    await responseText(
+      await fetch(`${base}/${secretName}`, {
+        method: "PUT",
+        headers: { ...auth, "content-type": "application/json" },
+        body: JSON.stringify({ value }),
+      }),
+      `put ${secretName} rejected`,
+    );
+  for (const secretName of bulk.delete)
+    await responseText(
+      await fetch(`${base}/${secretName}`, { method: "DELETE", headers: auth }),
+      `delete ${secretName} rejected`,
+    );
+  console.log(ok(`${summary}; self-hosted Community applies them on the next deploy or restart of the app`));
+}
+
+/**
+ * After a secrets write on the Cloud: it is a new record generation, which a host applies as a new version of the
+ * running module (the same module, the new secrets). Wait for that, as `wrangler secret put` deploys at once, unless
+ * --no-deploy asks to return as soon as the write is stored.
+ */
+async function finishCloudSecretChange(input: {
+  credentials: Awaited<ReturnType<typeof cloudCredentials>>;
+  app: string;
+  generation: number | undefined;
+  noDeploy: boolean;
+  what: string;
+}) {
+  const { credentials, app, generation, noDeploy, what } = input;
+  if (generation === undefined || noDeploy) {
+    console.log(ok(`${what}; applies when a host picks up the new record`));
+    return;
+  }
+  const io = terminalIo();
+  const applied = await waitForApply(makeCall(credentials), { project: app }, generation, io);
+  if (applied) console.log(ok(`${what}; a new version is live (generation ${generation})`));
+  else
+    console.log(
+      amber(`! ${what}; generation ${generation} is saved, but no host has applied it yet: it goes live when one does`),
+    );
+}
+
+/** The signed-in session for a Cloud endpoint as the credentials every Cloud call takes; logs in first when it can. */
+async function cloudCredentials(apiUrl: string, account: string | undefined) {
+  const io = terminalIo();
+  const session = await resolveSession({
+    apiUrl,
+    io,
+    account,
+    login: (hint) =>
+      loginAndStore({ apiUrl, io, hostname: osHostname(), os: `${osPlatform()} ${osArch()}`, account: hint }),
+  });
+  return { apiUrl, token: session.token, tokenFromEnv: session.source !== "stored login" };
+}
+
+/** `secrets` against a Sproutboat Cloud app: by name, apart from deploys, which never wipe them (Wrangler's model). */
+async function cloudSecrets(
+  sub: string,
+  name: string | undefined,
+  inlineValue: string | undefined,
+  directory: string | undefined,
+  apiUrl: string,
+  accountFlag: string | undefined,
+  noDeploy: boolean,
+) {
+  const project = await readProjectConfig(directory);
+  const app = project.config.name;
+  const credentials = await cloudCredentials(apiUrl, accountFlag ?? project.account);
+  if (sub === "list") {
+    const names = await listCloudSecrets(credentials, app);
+    console.log(names.length ? names.join("\n") : "no secrets");
+    return;
+  }
+  if (sub === "delete") {
+    const generation = await deleteCloudSecret(credentials, app, name!);
+    await finishCloudSecretChange({ credentials, app, generation, noDeploy, what: `removed ${name} from ${app}` });
+    return;
+  }
+  const value = inlineValue ?? (await Bun.stdin.text()).replace(/\r?\n$/, "");
+  if (!value) fail("no value: pipe it on stdin, or pass --value <value>");
+  const generation = await putCloudSecret(credentials, app, name!, value);
+  await finishCloudSecretChange({ credentials, app, generation, noDeploy, what: `set ${name} on ${app}` });
+}
+
+async function confirmOnTerminal(question: string): Promise<boolean> {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return !/^n/i.test((await rl.question(`${question} [Y/n] `)).trim());
+  } finally {
+    rl.close();
+  }
+}
+
+/** `d1 execute` and `d1 migrations create | list | apply`: the local dev database unless --remote, as in Wrangler. */
+async function d1Contents(args: string[]) {
+  const area = args.shift()!;
+  let sub = "execute";
+  if (area === "migrations") {
+    const word = args.shift();
+    if (word !== "create" && word !== "list" && word !== "apply")
+      usageError(
+        word ? `d1 migrations: unknown subcommand "${word}"` : "d1 migrations: missing subcommand",
+        "d1 migrations <create | list | apply> <database> ...",
+      );
+    sub = word;
+  }
+  const usage =
+    sub === "execute" ? EXECUTE_USAGE : sub === "create" ? CREATE_USAGE : sub === "list" ? LIST_USAGE : APPLY_USAGE;
+  let parsed: ReturnType<typeof parseD1Flags>;
+  try {
+    parsed = parseD1Flags(args, usage);
+  } catch (error) {
+    if (error instanceof D1UsageError) return usageError(error.message, error.usage);
+    throw error;
+  }
+  const { positional, flags } = parsed;
+  const [database, message] = positional;
+  if (!database) usageError(`${sub === "execute" ? "d1 execute" : `d1 migrations ${sub}`}: missing <database>`, usage);
+  if (sub === "create" && (!message || positional.length > 2))
+    usageError("d1 migrations create: missing <name>", usage);
+  if (sub !== "create" && positional.length > 1) usageError(`unexpected argument "${positional[1]}"`, usage);
+  if (sub === "create" && (flags.local || flags.remote))
+    usageError("d1 migrations create works on files only; drop --local and --remote", usage);
+
+  const project = await readProjectConfig();
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const io: D1Io = {
+    log: (line) => console.log(line),
+    note: (line) => console.error(line),
+    interactive,
+    confirm: confirmOnTerminal,
+  };
+  try {
+    await guard(() => d1Run());
+  } catch (error) {
+    if (error instanceof D1UsageError) usageError(error.message, error.usage);
+    throw error;
+  }
+
+  async function d1Run() {
+    const binding = pickBinding(project.config, database!);
+    const dir = resolve(project.directory, project.migrationsDir ?? DEFAULT_MIGRATIONS_DIR);
+    if (sub === "create") {
+      await createMigration(dir, message!, io);
+      return;
+    }
+    let runner: Runner;
+    if (flags.remote) {
+      const { apiUrl: targetUrl } = await resolveApiUrl();
+      const app = project.config.name;
+      if ((await deployKind(targetUrl, false)) === "cloud") {
+        const credentials = await cloudCredentials(targetUrl, flags.account ?? project.account);
+        const call = makeCall(credentials);
+        runner = remoteRunner({
+          label: `${app} database ${binding.binding}`,
+          project: app,
+          binding: binding.binding,
+          community: false,
+          send: async (body) => {
+            const reply = await call({
+              method: "POST",
+              path: `/v1/apps/${app}/d1/${binding.binding}/query`,
+              json: body,
+              ok: DATA_ERROR_STATUSES,
+            });
+            return { status: reply.status, body: reply.body, headers: reply.headers };
+          },
+        });
+      } else {
+        const { apiUrl, token } = await apiCredentials();
+        runner = remoteRunner({
+          label: `${app} database ${binding.binding}`,
+          project: app,
+          binding: binding.binding,
+          community: true,
+          send: async (body) => {
+            const response = await fetch(`${apiUrl}/api/projects/${app}/d1/${binding.binding}/query`, {
+              method: "POST",
+              headers: { "x-api-key": token, "content-type": "application/json" },
+              body: JSON.stringify(body),
+            });
+            return { status: response.status, body: parseBody(await response.text().catch(() => "")) };
+          },
+        });
+      }
+    } else {
+      runner = localRunner(localDatabasePath(project.directory, binding, flags.persistTo));
+    }
+    if (sub === "execute") await executeSql({ flags, runner, remote: flags.remote, io, cwd: process.cwd() });
+    else if (sub === "list") await listMigrations(runner, dir, io);
+    else await applyMigrations(runner, dir, io);
+  }
+}
+
+/** `r2 object get | put | delete <bucket>/<key>`: remote only; on the Cloud the bucket is a binding of the project. */
+async function r2Object(args: string[]) {
+  args.shift(); // "object"
+  const sub = args.shift();
+  if (sub !== "get" && sub !== "put" && sub !== "delete")
+    usageError(
+      sub ? `r2 object: unknown subcommand "${sub}"` : "r2 object: missing subcommand",
+      "r2 object <get | put | delete> <bucket>/<key>",
+    );
+  const usage = sub === "get" ? R2_GET_USAGE : sub === "put" ? R2_PUT_USAGE : R2_DELETE_USAGE;
+  try {
+    const { positional, flags } = parseObjectArgs(args, usage);
+    if (positional.length > 1) usageError(`unexpected argument "${positional[1]}"`, usage);
+    const { bucket, key } = parseObjectPath(positional[0], usage);
+    const project = await readProjectConfig();
+    const app = project.config.name;
+    const { apiUrl: targetUrl } = await resolveApiUrl();
+    let target: ObjectTarget;
+    if ((await deployKind(targetUrl, false)) === "cloud") {
+      const bindings = (project.config.r2_buckets ?? []).map((entry) => (isString(entry) ? entry : entry.binding));
+      if (!bindings.includes(bucket))
+        fail(
+          bindings.length === 0
+            ? `sproutboat.jsonc has no r2_buckets, so there is no bucket "${bucket}" (add "r2_buckets": ["${bucket}"])`
+            : `no R2 binding "${bucket}" in sproutboat.jsonc (it has: ${bindings.join(", ")})`,
+        );
+      const credentials = await guard(() => cloudCredentials(targetUrl, flags.account ?? project.account));
+      target = cloudTarget(credentials.apiUrl, credentials.token, app, bucket);
+    } else {
+      const { apiUrl, token } = await apiCredentials();
+      const rows = await storageRows(`${apiUrl}/api/r2`, { "x-api-key": token }, STORAGE_PRODUCTS[2]);
+      target = communityTarget(apiUrl, token, app, bucket, idForName(rows, bucket, STORAGE_PRODUCTS[2]));
+    }
+    const io = {
+      log: (line: string) => console.log(line),
+      note: (line: string) => console.error(line),
+      stdout: { write: (bytes: Uint8Array) => void process.stdout.write(bytes) },
+    };
+    await guard(async () => {
+      if (sub === "get") await getObject(target, key, flags, io, process.cwd());
+      else if (sub === "delete") await deleteObject(target, key, io);
+      else
+        await putObject(target, key, flags, io, process.cwd(), () =>
+          readCapped(
+            Bun.stdin.stream(),
+            OBJECT_MAX_BYTES,
+            () =>
+              new CloudError(
+                `the piped object is larger than ${OBJECT_MAX_BYTES / 1024 / 1024} MiB, the most the Cloud takes`,
+              ),
+          ),
+        );
+    });
+  } catch (error) {
+    if (error instanceof R2UsageError) usageError(error.message, error.usage);
+    throw error;
+  }
 }
 
 /**
@@ -1086,6 +2097,9 @@ function idForName(rows: JsonObject[], name: string, product: StorageProduct): s
 async function storage(key: string, args: string[]) {
   const product = STORAGE_PRODUCTS.find((entry) => entry.name === key)!;
   const sub = args[0] && STORAGE_VERBS.some((verb) => verb === args[0]) ? args.shift()! : "list";
+  // The five verbs take names, never options (the contents commands and `checkOptions` handle the others).
+  const stray = args.find((arg) => arg.startsWith("-") && arg !== "-");
+  if (stray) usageError(`${key}: unknown option ${stray.split("=")[0]}`, usageOf(key));
   const { apiUrl, token } = await apiCredentials();
   const base = `${apiUrl}/api/${product.name}`;
   const auth = { "x-api-key": token };
@@ -1430,8 +2444,14 @@ async function toolchain(args: string[]): Promise<void> {
 }
 
 /** `sproutboat <command> --help`: that command's full usage line + summary, exit 0. */
-function commandHelp(name: string): never {
+/** The grammar line of a command, for usage errors. */
+function usageOf(name: string): string {
   const found = COMMANDS.find((c) => c.name === name);
+  return found?.args ? `${name} ${found.args}` : name;
+}
+
+function commandHelp(name: string): never {
+  const found = COMMANDS.find((c) => c.name === resolveCommand(name));
   if (!found) usage();
   console.log(`${dim(`usage: ${CLI_NAME} ${name}${found.args ? ` ${found.args}` : ""}`)}\n\n${found.summary}`);
   process.exit(0);
@@ -1444,7 +2464,7 @@ const FISH_COMPLETION = (names: string) => `complete -c ${CLI_NAME} -n "__fish_u
 
 /** `sproutboat complete [shell]`: a static completion script for the top-level commands. */
 function complete(shell?: string): void {
-  const names = COMMANDS.map((c) => c.name).join(" ");
+  const names = COMMANDS.flatMap((c) => [c.name, ...(c.aliases ?? [])]).join(" ");
   const scripts = { bash: BASH_COMPLETION(names), zsh: ZSH_COMPLETION(names), fish: FISH_COMPLETION(names) };
   const key = shell ?? process.env.SHELL?.split("/").pop() ?? "bash";
   const script = key === "bash" || key === "zsh" || key === "fish" ? scripts[key] : undefined;
@@ -1452,19 +2472,60 @@ function complete(shell?: string): void {
   console.log(script);
 }
 
-const [command, ...args] = process.argv.slice(2);
-if (command === undefined || command === "help" || command === "-h" || command === "--help") help();
-if (command === "--version" || command === "-v") {
+const GLOBAL_USAGE =
+  "<command> [-c, --config <file>] [--cwd <dir>] [-e, --env <name>] [--env-file <file>]... [--profile <name>] [--api-url <url>] [-v, --version]";
+const parsedArgv = extractGlobalFlags(process.argv.slice(2));
+if ("error" in parsedArgv) usageError(parsedArgv.error, GLOBAL_USAGE);
+const globals = parsedArgv.flags;
+if (globals.version) {
   console.log(`sproutboat ${CLI_VERSION}`);
   process.exit(0);
 }
+if (globals.cwd !== undefined) {
+  try {
+    process.chdir(globals.cwd);
+  } catch {
+    fail(`--cwd: no such directory: ${globals.cwd}`);
+  }
+}
+setGlobalFlags(globals);
+const [command, ...args] = parsedArgv.rest;
+if (command === undefined || command === "help" || command === "-h" || command === "--help") help();
 if (args.includes("-h") || args.includes("--help")) commandHelp(command);
 
+// A flag a command cannot honour is an error, not a quiet no-op: `deploy --env staging` must not deploy.
+if (globals.env !== undefined && command !== "dev")
+  usageError(
+    `${command} does not use --env: it only selects .dev.vars.<name> and the .env.<name> files for \`dev\`, and sproutboat.jsonc has no environments`,
+    GLOBAL_USAGE,
+  );
+if (globals.envFiles.length > 0 && command !== "dev" && command !== "run")
+  usageError(`${command} does not read env files; --env-file is for \`dev\` and \`run\``, GLOBAL_USAGE);
+if (globals.profile !== undefined && !PROFILE_NAME.test(globals.profile))
+  usageError(`"${globals.profile}" is not a profile name (letters, digits, . _ -; at most 64)`, GLOBAL_USAGE);
+if (globals.apiUrl !== undefined) {
+  if (!ENDPOINT_COMMANDS.has(command))
+    usageError(
+      `${command} does not talk to a control plane, so --api-url means nothing here; to choose where the other commands go use --profile <name> or SPROUTBOAT_API_URL`,
+      GLOBAL_USAGE,
+    );
+  if (!/^https?:\/\/[^\s/]+/i.test(globals.apiUrl))
+    usageError(
+      `--api-url "${globals.apiUrl}" is not an http(s) URL, such as https://dash.sproutboat.com`,
+      GLOBAL_USAGE,
+    );
+}
+// What each command accepts: an unknown flag is an error, `--flag=value` becomes `--flag value`, and a URL is never
+// read as a project directory (options.ts).
+const checked = checkOptions(command, args);
+if ("error" in checked) usageError(`${command}: ${checked.error}`, usageOf(command));
+args.splice(0, args.length, ...checked.args);
+
 // A local log needs no network: skip the version check for it (#268).
 if (!(command === "tail" && args.some((arg) => arg === "--file" || arg.startsWith("--file="))))
   await notifyIfOutdated(CLI_VERSION);
 
-switch (command) {
+switch (resolveCommand(command)) {
   case "init":
     await init(args[0]);
     break;
@@ -1508,7 +2569,8 @@ switch (command) {
         "build --standalone --target linux-x64 --deploy-files [project-dir]",
       );
     if (args.includes("--emit-only")) await emitOnly(directory, target, args.includes("--standalone"));
-    else if (args.includes("--standalone")) await buildStandaloneBinary(directory, target, withRestore, deployFiles);
+    else if (args.includes("--standalone"))
+      await buildStandaloneBinary(directory, target, withRestore, deployFiles, isReleaseBuild(args));
     else await build(directory, target);
     break;
   }
@@ -1522,11 +2584,17 @@ switch (command) {
     await logout(args);
     break;
   case "whoami":
-    await whoami();
+    await whoami(args);
+    break;
+  case "profile":
+    await profile(args);
     break;
   case "deploy":
     await deploy(args);
     break;
+  case "deployments":
+    await deployments(args);
+    break;
   case "versions":
     await versions(args);
     break;
@@ -1544,7 +2612,13 @@ switch (command) {
     else await storage(command, args);
     break;
   case "d1":
+    if (["execute", "migrations"].includes(args[0] ?? "")) await d1Contents(args);
+    else await storage(command, args);
+    break;
   case "r2":
+    if (args[0] === "object") await r2Object(args);
+    else await storage(command, args);
+    break;
   case "queues":
     await storage(command, args);
     break;