@supatype/cli 0.2.1 → 0.3.1

package/src/cache-identity-scope.ts

@@ -0,0 +1,92 @@
+/**
+ * Whether an access rule's outcome varies by *who* is asking.
+ *
+ * This decides whether a model may declare `cache: { public: true }`. A public cache entry is
+ * global — one response served to every caller — so on a table whose read rule varies by caller it
+ * serves one user's rows to another.
+ *
+ * **Row-dependence is not the same question, and getting that wrong in either direction is a bug.**
+ * `Lte<"published_at", Now>` varies by row and by time but not by caller, so a shared entry is
+ * exactly right for it: that is the case public caching exists to serve. Refusing it would make the
+ * feature useless. Allowing `Owner<"user_id">` would make it a data leak.
+ *
+ * ## This is the second implementation of one rule
+ *
+ * supatype-server already answers this at runtime, in
+ * `internal/studiobootstrap.IsIdentityDependent`, to decide whether a response may be cached under
+ * a shared scope. This one answers it at *push* time, where the error can name the model and the
+ * rule instead of a request quietly not being cached.
+ *
+ * Two implementations of one rule drift, and the drift is silent: the push says "shareable" and the
+ * runtime says "not", or worse the other way round. `tests/fixtures/identity-scope-corpus.json` is
+ * the defence — a shared corpus of rules and expected answers that both sides run against. Change
+ * this file and you change that corpus; the Go side reads the same cases.
+ */
+
+/** A rule node, in the shape the extractor emits and the server parses. */
+export interface AccessRuleNode {
+  type?: string
+  left?: AccessOperand
+  right?: AccessOperand
+  operand?: AccessOperand
+  rules?: AccessRuleNode[]
+  rule?: AccessRuleNode
+}
+
+export interface AccessOperand {
+  kind?: string
+}
+
+/**
+ * The operands whose value differs per caller. Columns, literals and the temporal operands
+ * (`Now` and friends) are the same for everyone, so they are not here.
+ */
+const IDENTITY_OPERANDS = new Set(["authUid", "authRole", "claim"])
+
+function operandIsIdentityDependent(o: AccessOperand | undefined): boolean {
+  if (!o) return false
+  return IDENTITY_OPERANDS.has(o.kind ?? "")
+}
+
+export function isIdentityDependent(rule: AccessRuleNode | undefined | null): boolean {
+  // No rule at all is not a caller-varying rule. An absent `access.read` means the table's
+  // readability is decided elsewhere, and treating that as identity-dependent would refuse public
+  // caching on every model that never wrote one.
+  if (!rule) return false
+
+  switch (rule.type) {
+    case "public":
+    case "private":
+      return false
+
+    // "Any authenticated user" still distinguishes signed-in from anonymous, so a shared entry
+    // could serve a member's view to a stranger.
+    case "authenticated":
+    case "role":
+    case "owner":
+      return true
+
+    // Membership is per caller by construction.
+    case "in":
+    case "exists":
+      return true
+
+    case "compare":
+      return operandIsIdentityDependent(rule.left) || operandIsIdentityDependent(rule.right)
+
+    case "nullCheck":
+      return operandIsIdentityDependent(rule.operand)
+
+    case "any":
+    case "all":
+      return (rule.rules ?? []).some(isIdentityDependent)
+
+    case "not":
+      return rule.rule ? isIdentityDependent(rule.rule) : false
+
+    default:
+      // An unrecognised rule is assumed to depend on identity. Guessing the other way would share
+      // a cache entry across callers on the strength of not recognising something.
+      return true
+  }
+}

package/src/cache-provider.ts

@@ -0,0 +1,61 @@
+/**
+ * Which RESP server this stack runs: one decision, in one place.
+ *
+ * The response cache and Kong's ACME certificates share a RESP server. Since P1 that can be
+ * pg_keyspace inside the Postgres container — one stateful service instead of two, no second
+ * image to keep patched, and a cache whose memory is accounted for in the database's own
+ * reservation. That is now the default rather than the option.
+ *
+ * **Valkey stays selectable**, and stays the answer for `database.external`: pg_keyspace is loaded
+ * through `shared_preload_libraries`, which is a property of a Postgres this stack starts. Against
+ * a database Supatype does not manage there is nothing to configure, so the fallback is not a
+ * preference — it is the only thing that can run.
+ *
+ * A resolver rather than a default written into the config type, because the answer depends on
+ * more than one field: the same absent `cache.provider` means pg_keyspace beside a managed
+ * database and Valkey beside an external one. A default baked into the parser would have to be
+ * either wrong for one of them or applied twice, and applied twice is how the compose file and the
+ * native path end up disagreeing about which server is running — a cache that silently never hits
+ * and, with TLS on, a Kong that cannot store its certificate.
+ */
+import { pinnedVersion } from "./binary-cache.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+
+export type CacheProvider = "valkey" | "pg_keyspace"
+
+/**
+ * The provider this project runs, explicit or resolved.
+ *
+ * An explicit `cache.provider` is honoured exactly — including `"valkey"`, which is how a project
+ * keeps the sidecar it has. `validateProjectConfig` has already refused the one explicit
+ * combination that cannot run (pg_keyspace against `database.external`), so this never overrides
+ * what someone wrote.
+ *
+ * The two things that resolve an absent one to Valkey are both cases where this cannot know that a
+ * keyspace would work:
+ *
+ *  - **`database.external`**: pg_keyspace is loaded through `shared_preload_libraries`, and there
+ *    is no container here to set that on.
+ *  - **A pinned `versions.postgres`**: the keyspace is served by the image, and the entrypoint
+ *    honours `SUPATYPE_KEYSPACE_ENABLED` only from the release that introduced it. An older image
+ *    ignores the variable and starts with no RESP listener, which is not an error anywhere — the
+ *    stack comes up and the cache never hits. A pin says this project's image is fixed, and a
+ *    default must not assume something about a fixed image it cannot check. Unpinned tracks
+ *    latest, which carries the toggle by definition.
+ *
+ * A project on a pin that *does* carry the toggle says `cache: { provider: "pg_keyspace" }` and
+ * gets it — which is also the only instruction anyone needs, and is better than a version floor
+ * here that would have to be right about a release number in another repository.
+ */
+export function cacheProvider(config: SupatypeProjectConfig): CacheProvider {
+  const declared = config.cache?.provider
+  if (declared === "valkey" || declared === "pg_keyspace") return declared
+  if (config.database?.external) return "valkey"
+  if (pinnedVersion("postgres", config) !== undefined) return "valkey"
+  return "pg_keyspace"
+}
+
+/** Whether the RESP keyspace is served by the Postgres this stack starts. */
+export function keyspaceInPostgres(config: SupatypeProjectConfig): boolean {
+  return cacheProvider(config) === "pg_keyspace"
+}

package/src/cli-version-embedded.ts

@@ -9,4 +9,4 @@
 // Annotated `string`, not left to inference: once a release stamps a value here, the
 // inferred literal type makes the `!== ""` test in cliPackageVersion() a compile error
 // (TS2367, no overlap), so the build would only fail during a release.
-export const EMBEDDED_CLI_VERSION: string = "0.2.1"
+export const EMBEDDED_CLI_VERSION: string = "0.3.1"

package/src/commands/add.ts

@@ -101,5 +101,5 @@ function printDomainNextSteps(cwd: string, domain: string): void {
     `Platform URL: https://${domain}`,
   ])
   plain("  App, REST, Auth, Storage, Realtime, Functions, and Studio, one HTTPS domain.")
-  plain("  Certificates persist in the valkey-data volume.\n")
+  plain("  Certificates outlive restarts — in the keyspace's durable store, or the valkey-data volume.\n")
 }

package/src/commands/admin.ts

@@ -363,12 +363,7 @@ export async function ensureFirstAdminWithQuery(
 
   const credentials = await resolveAdminCredentials(options, cwd)
   if (!credentials) {
-    if (!isInteractive()) {
-      info(
-        "No admin users found. Set SUPATYPE_ADMIN_EMAIL / SUPATYPE_ADMIN_PASSWORD in .env, " +
-          "or run: supatype admin create-user",
-      )
-    }
+    if (!isInteractive()) info(missingAdminCredentialsHint(cwd, options))
     return
   }
 
@@ -397,6 +392,28 @@ function logFirstAdminCreated(email: string, role: string): void {
   info("Log in at /admin after starting the dev server.")
 }
 
+/**
+ * What to say when there is no admin and no credentials to make one with.
+ *
+ * Naming both variables is wrong in the common case. `clearAdminSeedPassword` retires the seed
+ * password once it has been used, so a project that has ever created an admin keeps the email and
+ * has no password, and a later run against a reset database then reports both as missing. That
+ * reads as "you never set these" when in fact this tool consumed one of them, which is a dead end
+ * for anyone who knows they set it.
+ */
+function missingAdminCredentialsHint(cwd: string, options: EnsureFirstAdminOptions): string {
+  const email = options.email ?? readEnvValue(cwd, ADMIN_EMAIL_ENV, "").trim()
+  const create = "or run: supatype admin create-user"
+  if (!email) {
+    return `No admin users found. Set ${ADMIN_EMAIL_ENV} / ${ADMIN_PASSWORD_ENV} in .env, ${create}`
+  }
+  return (
+    `No admin users found. .env has ${ADMIN_EMAIL_ENV}="${email}" but no ${ADMIN_PASSWORD_ENV}: ` +
+    `it is a one-time seed and is removed once an admin has been created. ` +
+    `Set ${ADMIN_PASSWORD_ENV} again to seed one, ${create}`
+  )
+}
+
 async function resolveAdminCredentials(
   options: EnsureFirstAdminOptions,
   cwd: string,

package/src/commands/cache.ts

@@ -1,5 +1,5 @@
 /**
- * supatype cache: list and clean cached component binaries + REST Valkey cache.
+ * supatype cache: list and clean cached component binaries + the REST response cache.
  */
 
 import type { Command } from "commander"
@@ -135,7 +135,7 @@ export function registerCache(program: Command): void {
 
   const rest = cache
     .command("rest")
-    .description("Manage REST API response cache in Valkey")
+    .description("Manage the server-side REST API response cache")
 
   rest
     .command("list")
@@ -170,7 +170,7 @@ export function registerCache(program: Command): void {
 
   rest
     .command("get <key>")
-    .description("Show one cache entry (full Valkey key)")
+    .description("Show one cache entry (full key)")
     .option("--json", "Output JSON")
     .action(async (key: string, opts: { json?: boolean }) => {
       const cwd = process.cwd()

package/src/commands/cloud.ts

@@ -1,3 +1,4 @@
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { readFileSync, writeFileSync, existsSync } from "node:fs"
 import { resolve } from "node:path"
@@ -91,7 +92,7 @@ export async function pushSchemaToLinkedProject(
     process.exit(1)
   }
 
-  const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+  const ast = withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config)
   info(`Pushing schema to ${target.mode} project ${target.projectRef} (${target.environment})...`)
 
   const result = await targetSchemaPush(target, ast, {

package/src/commands/deploy.ts

@@ -11,6 +11,7 @@
  *   supatype deploy logs <version>, show build logs
  */
 
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { existsSync, readdirSync, statSync, createReadStream, mkdirSync, cpSync } from "node:fs"
 import { join, relative } from "node:path"
@@ -74,7 +75,7 @@ export function registerDeploy(program: Command): void {
 
       // Step 1: Schema push (unless --app-only or --skip-build, or already done via cloud.json)
       if (!opts.appOnly && !opts.skipBuild && !schemaDone) {
-        const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+        const ast = withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config)
 
         if (opts.local) {
           step("Schema Push (local)")

package/src/commands/dev.ts

@@ -10,6 +10,7 @@
  * Deno is not provisioned by the CLI on those paths.
  */
 
+import { keyspaceInPostgres } from "../cache-provider.js"
 import type { Command } from "commander"
 import { spawnSync } from "node:child_process"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
@@ -26,6 +27,7 @@ import {
 } from "../project-config.js"
 import { discoverTsFunctionsInDir, writeDevFunctionsRouter } from "../functions-router-gen.js"
 import { fieldMaskingTierFromProject } from "../field-masking-tier.js"
+import { projectHasVersionedModels } from "../model-versioning.js"
 import { signJwt } from "../jwt.js"
 import {
   devAuthenticatorPassword,
@@ -55,9 +57,13 @@ import { registerDevShutdown } from "../dev-shutdown.js"
 import { patchRouteManifest } from "../route-manifest.js"
 import { resolveRealtimeLaunch } from "../realtime-launch.js"
 import { writeAppViteEnv } from "../app-vite-env.js"
-import { ensureValkeySidecar, stopValkeySidecar } from "../valkey-sidecar.js"
+import { ensureValkeySidecar, probeTcp, stopValkeySidecar } from "../valkey-sidecar.js"
 import {
+  firstFreePort,
   initdb,
+  KEYSPACE_PORT_BASE,
+  KEYSPACE_PORT_SPAN,
+  nativeKeyspaceLibraryPresent,
   nativeMaskLibraryPresent,
   start as pgStart,
   stop as pgStop,
@@ -193,13 +199,46 @@ export function registerDev(program: Command): void {
       // pgBinDir is set on the native path and used to add DLL search path for
       // PostgREST on Windows (PostgREST links against libpq + SSL from MinGW).
       let pgBinDir: string | null = null
+      // The port the native Postgres serves RESP on, or null when this archive
+      // has no pg_keyspace and the Valkey sidecar is what the cache talks to.
+      let keyspacePort: number | null = null
 
       {
         // native: resolve pg bin dir and manage with pg_ctl
         pgBinDir = await resolvePgBinDir(config)
         const dataDir = config.database.data_dir ?? join(stateRoot, "data")
         mkdirSync(dataDir, { recursive: true })
-        const pgOpts = { pgBinDir, dataDir, port: pgPort, logPath: join(logsDir, "postgres.log") }
+        // The RESP keyspace, when this archive carries it: one process instead
+        // of a Postgres and a Valkey container. The port is chosen rather than
+        // fixed because 6379 is the first thing a developer's own Redis or a
+        // leftover sidecar takes, and a keyspace that cannot bind its port
+        // fails inside the postmaster log where nobody is looking.
+        //
+        // `cache.provider: "valkey"` is honoured here too, and this is the only place it could
+        // be: the native path asks the archive what it carries rather than the config what it
+        // wants, so a project that deliberately kept the sidecar would otherwise find Postgres
+        // serving RESP anyway and the sidecar never started.
+        const wantsPgKeyspace = keyspaceInPostgres(config)
+        keyspacePort =
+          wantsPgKeyspace && nativeKeyspaceLibraryPresent(pgBinDir)
+            ? await firstFreePort(KEYSPACE_PORT_BASE, KEYSPACE_PORT_SPAN)
+            : null
+        if (wantsPgKeyspace && nativeKeyspaceLibraryPresent(pgBinDir) && keyspacePort === null) {
+          console.warn(
+            `[supatype] ⚠  No free port in ${KEYSPACE_PORT_BASE}-${KEYSPACE_PORT_BASE + KEYSPACE_PORT_SPAN - 1} ` +
+              "for the Postgres keyspace — starting without it.",
+          )
+        }
+
+        const pgOpts = {
+          pgBinDir,
+          dataDir,
+          port: pgPort,
+          logPath: join(logsDir, "postgres.log"),
+          ...(keyspacePort !== null
+            ? { keyspacePort, keyspaceDatabase: projectName }
+            : {}),
+        }
 
         console.log("[supatype] Initialising Postgres data directory...")
         initdb(pgOpts)
@@ -399,7 +438,27 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
               ? "ses"
               : "smtp"
 
-      const valkeySidecar = ensureValkeySidecar(projectName)
+      // Postgres serves RESP itself when the archive had pg_keyspace and the
+      // port came up. The probe is not ceremony: shared memory limits, a
+      // preload ordering mistake or a port taken between the check and the
+      // start all leave a Postgres that is running and a keyspace that is not,
+      // and the difference is a cache that silently never hits.
+      const nativeKeyspaceAddr =
+        keyspacePort !== null && (await probeTcp("127.0.0.1", keyspacePort))
+          ? `127.0.0.1:${keyspacePort}`
+          : null
+      if (keyspacePort !== null && nativeKeyspaceAddr === null) {
+        console.warn(
+          `[supatype] ⚠  Postgres has pg_keyspace but is not serving RESP on :${keyspacePort} — ` +
+            "see logs/postgres.log. Falling back to the Valkey sidecar.",
+        )
+      }
+      if (nativeKeyspaceAddr) {
+        console.log(`[supatype] Keyspace served by Postgres (${nativeKeyspaceAddr}).`)
+      }
+      const valkeySidecar = nativeKeyspaceAddr
+        ? { addr: nativeKeyspaceAddr, containerName: null, started: false }
+        : ensureValkeySidecar(projectName)
 
       const serverEnv: Record<string, string> = {
         // supatype-server outer layer
@@ -513,12 +572,14 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
           // a non-default pg_schema pushed correctly and then answered PGRST106 on every request.
           // Native dev has no masking extension either, so a schema with field rules is served from
           // `api` here too: the case an "is the database external" rule would have got wrong.
-          PGRST_DB_SCHEMA: apiSchemaList(
-            config,
+          PGRST_DB_SCHEMA: apiSchemaList(config, {
             // The installed archive decides: one downloaded before the masking library was bundled
             // has no extension, so its field rules are enforced by views instead.
-            fieldMaskingTierFromProject(cwd, config, nativeMaskLibraryPresent(pgBinDir)),
-          ),
+            tier: fieldMaskingTierFromProject(cwd, config, nativeMaskLibraryPresent(pgBinDir)),
+            // A versioned model adds the generated `draft` schema, or `.draft()` would answer
+            // PGRST106 against a stack that had migrated the views into place.
+            drafts: projectHasVersionedModels(cwd, config),
+          }),
           // Parity with self-host, which has always set this. Unqualified names in column defaults
           // (`uuid_generate_v4()`) resolve here, and with a non-public pg_schema the request schema
           // alone does not reach them.

package/src/commands/diff.ts

@@ -1,3 +1,4 @@
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { loadConfig, loadSchemaAst } from "../config.js"
 import { resolveRuntimeProvider, schemaPathFromProject } from "../project-config.js"
@@ -19,7 +20,7 @@ export function registerDiff(program: Command): void {
       const pgSchema = schemaPgSchema(cwd)
 
       const ast = await withSpinner("Loading schema", async () =>
-        loadSchemaAst(schemaPathFromProject(config, cwd), cwd),
+        withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config),
       )
 
       const linked = loadProjectLink(cwd)

package/src/commands/functions.ts

@@ -141,9 +141,13 @@ function scaffoldFunction(cwd: string, name: string): void {
   const indexContent = `// ${name}, Supatype Edge Function
 // Docs: https://supatype.com/docs/edge-functions
 
-export default async function handler(req: Request): Promise<Response> {
+import type { FunctionContext } from "../_shared/context.ts"
+
+export default async function handler(req: Request, ctx: FunctionContext): Promise<Response> {
   const { method } = req
-  const url = Deno.env.get("SUPATYPE_URL")
+  // From the context, not the environment. Per-invocation values are passed in, which is what lets
+  // the worker run your functions concurrently instead of one at a time.
+  const { url } = ctx
 
   // Example: read request body for POST requests
   if (method === "POST") {

package/src/commands/init.ts

@@ -70,7 +70,7 @@ const STORAGE_PROVIDER_OPTIONS: {
   label: string
   hint: string
 }[] = [
-  { value: "local", label: "Local", hint: "storage you host yourself (MinIO)" },
+  { value: "local", label: "Local", hint: "storage you host yourself (SeaweedFS)" },
   { value: "s3", label: "S3", hint: "external bucket (AWS S3 or compatible)" },
 ]
 
@@ -1164,7 +1164,7 @@ function storageConfigLines(
   if (storageProduction === "s3" && storageLocal !== "s3") {
     lines.push(`  // Production storage: external S3 bucket, set production S3_* in .env`)
   } else if (storageProduction === "local" && storageLocal === "s3") {
-    lines.push(`  // Production storage: MinIO on your server (included in self-host compose)`)
+    lines.push(`  // Production storage: SeaweedFS on your server (included in self-host compose)`)
   }
   return lines
 }
@@ -1305,7 +1305,7 @@ S3_SECRET_KEY=`
     }
     return `${localStorageEnvSection("local")}
 
-# Production storage (MinIO on your server)
+# Production storage (SeaweedFS on your server)
 # Included in the self-host compose stack, no extra configuration needed.`
   }
 
@@ -1323,8 +1323,8 @@ S3_BUCKET=
 S3_ACCESS_KEY=
 S3_SECRET_KEY=`
   }
-  return `# Storage (local development, MinIO)
-S3_ENDPOINT=http://localhost:9000
+  return `# Storage (local development, SeaweedFS)
+S3_ENDPOINT=http://localhost:8333
 S3_ACCESS_KEY=supatype
 S3_SECRET_KEY=supatype-secret`
 }
@@ -1338,7 +1338,7 @@ S3_BUCKET=
 S3_ACCESS_KEY=
 S3_SECRET_KEY=`
   }
-  return `# Storage (production, MinIO on your server)
+  return `# Storage (production, SeaweedFS on your server)
 # Included in the self-host compose stack, no extra configuration needed.`
 }
 
@@ -1372,9 +1372,13 @@ function helloFunctionTemplate(): string {
   return `// hello: Supatype Edge Function
 // Docs: https://supatype.com/docs/edge-functions
 
-export default async function handler(req: Request): Promise<Response> {
+import type { FunctionContext } from "../_shared/context.ts"
+
+export default async function handler(req: Request, ctx: FunctionContext): Promise<Response> {
   const { method } = req
-  const url = Deno.env.get("SUPATYPE_URL")
+  // From the context, not the environment. Per-invocation values are passed in, which is what lets
+  // the worker run your functions concurrently instead of one at a time.
+  const { url } = ctx
 
   if (method === "POST") {
     const body = await req.json()
@@ -1507,7 +1511,7 @@ function printNextSteps(args: {
       selfHostSteps.push("supatype self-host compose up -d   # Kong provisions HTTPS automatically")
       selfHostSteps.push(`Your Supatype platform goes live at https://${domain}`)
       selfHostSteps.push(
-        "Your app, REST, Auth, Storage, Realtime, Functions, and Studio, all behind one HTTPS domain (certs persist in valkey-data)",
+        "Your app, REST, Auth, Storage, Realtime, Functions, and Studio, all behind one HTTPS domain (certificates outlive restarts)",
       )
     } else {
       selfHostSteps.push(

package/src/commands/keys.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander"
-import { readFileSync, existsSync, writeFileSync } from "node:fs"
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { resolve } from "node:path"
+import { readEnvFile, upsertEnvFile } from "../env-file.js"
 import { signJwt } from "../jwt.js"
 import { error, plain } from "../ui/messages.js"
 
@@ -10,7 +11,9 @@ export function registerKeys(program: Command): void {
     .description("Generate ANON_KEY and SERVICE_ROLE_KEY JWTs from your JWT_SECRET")
     .option("--secret <secret>", "JWT secret (defaults to JWT_SECRET env var or value in .env)")
     .option("--exp-years <years>", "Token expiry in years (default: 10)", "10")
-    .action((opts: { secret?: string; expYears: string }) => {
+    .option("--write", "Write the keys into .env in the current directory instead of printing them")
+    .option("--force", "With --write, replace every key already in .env rather than filling blanks")
+    .action((opts: { secret?: string; expYears: string; write?: boolean; force?: boolean }) => {
       const secret = opts.secret ?? resolveSecret()
       if (!secret) {
         error("JWT_SECRET not found. Set it in .env or pass --secret <value>")
@@ -23,19 +26,116 @@ export function registerKeys(program: Command): void {
         process.exit(1)
       }
 
-      const now = Math.floor(Date.now() / 1000)
-      const exp = now + expYears * 365 * 24 * 60 * 60
+      const { anonKey, serviceKey } = signKeyPair(secret, expYears)
 
-      const anonKey = signJwt({ iss: "supatype", role: "anon", iat: now, exp }, secret)
-      const serviceKey = signJwt({ iss: "supatype", role: "service_role", iat: now, exp }, secret)
+      if (opts.write) {
+        const written = writeKeysToEnv(
+          process.cwd(),
+          { anonKey, serviceKey },
+          opts.force === true,
+        )
+        if (written.path === null) {
+          error("No .env here to write to. Create one, or drop --write to print the keys.")
+          process.exit(1)
+        }
+        plain(`\nKeys valid for ${expYears} years, written to ${written.path}:\n`)
+        // The names come back from the writer rather than being restated here, which is the whole
+        // point of there being one list.
+        for (const key of written.written) plain(`  ${key}`)
+        if (written.kept.length > 0) {
+          plain(`\nLeft alone, because they already hold a value:\n`)
+          for (const key of written.kept) plain(`  ${key}`)
+          plain("\nRe-run with --force to replace them.")
+        }
+        plain("\nDo not commit .env to source control.")
+        return
+      }
 
       plain(`\nGenerated keys (valid for ${expYears} years):\n`)
       plain("ANON_KEY=" + anonKey)
       plain("SERVICE_ROLE_KEY=" + serviceKey)
-      plain("\nAdd these to your .env file. Do not commit .env to source control.")
+      plain("\nAdd these to your .env file, or re-run with --write. Do not commit .env to source control.")
     })
 }
 
+/**
+ * Every env name a minted key pair is written to, in one place.
+ *
+ * Shared with `supatype dev`, which writes the same pair when it starts a stack. They used to hold
+ * separate lists, so a front end's prefix could be written by one and forgotten by the other, and
+ * which names your `.env` ended up with depended on whichever command you happened to run last.
+ *
+ * The URL names are only included when there is a URL to write, because an empty
+ * `VITE_SUPATYPE_URL` is worse than an absent one: the client reads it, finds a blank string, and
+ * requests against the page origin without saying why.
+ */
+export function anonKeyEnvUpdates(
+  anonKey: string,
+  serviceKey: string,
+  apiUrl?: string | undefined,
+): Record<string, string> {
+  return {
+    ANON_KEY: anonKey,
+    SERVICE_ROLE_KEY: serviceKey,
+    VITE_SUPATYPE_ANON_KEY: anonKey,
+    PUBLIC_SUPATYPE_ANON_KEY: anonKey,
+    EXPO_PUBLIC_SUPATYPE_ANON_KEY: anonKey,
+    ...(apiUrl !== undefined && {
+      VITE_SUPATYPE_URL: apiUrl,
+      PUBLIC_SUPATYPE_URL: apiUrl,
+      EXPO_PUBLIC_SUPATYPE_URL: apiUrl,
+    }),
+  }
+}
+
+export interface WriteKeysResult {
+  /** The .env written, or null when there is none here. */
+  path: string | null
+  written: string[]
+  kept: string[]
+}
+
+/**
+ * Write a minted pair into `dir`'s .env.
+ *
+ * Blanks only by default. An anon key already in `.env` is held by clients this command cannot
+ * reach, and reissuing it locks them out, so filling what is empty is the useful half and
+ * replacing what is not is a decision someone has to make out loud. `--force` is how they make it,
+ * and it rewrites every name this owns rather than only the empty ones.
+ *
+ * `--force` does not rewrite the file. `.env` also holds `JWT_SECRET`, which these keys are
+ * derived from, along with the database password and whatever else the project keeps there;
+ * replacing the file would leave a project whose keys cannot be regenerated and whose stack cannot
+ * start. Every line this command does not own is left exactly as it was, comments included.
+ */
+export function writeKeysToEnv(
+  dir: string,
+  keys: { anonKey: string; serviceKey: string },
+  force: boolean,
+): WriteKeysResult {
+  const envPath = resolve(dir, ".env")
+  if (!existsSync(envPath)) return { path: null, written: [], kept: [] }
+
+  const existing = readEnvFile(dir)
+  const apiUrl = existing["PUBLIC_SUPATYPE_URL"] || existing["API_EXTERNAL_URL"] || undefined
+  const candidates = anonKeyEnvUpdates(keys.anonKey, keys.serviceKey, apiUrl)
+
+  const updates: Record<string, string> = {}
+  const kept: string[] = []
+  for (const [name, value] of Object.entries(candidates)) {
+    // Blank counts as absent: a template ships `ANON_KEY=` and that is exactly the line to fill.
+    const current = existing[name]?.trim() ?? ""
+    if (!force && current !== "") {
+      kept.push(name)
+      continue
+    }
+    updates[name] = value
+  }
+
+  if (Object.keys(updates).length > 0) upsertEnvFile(dir, updates)
+  return { path: envPath, written: Object.keys(updates), kept }
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 /** Mint a long-lived anon + service_role JWT pair from a secret. */
@@ -91,6 +191,11 @@ function upsertEnvVar(content: string, key: string, value: string): string {
   return `${content}${sep}${key}=${value}\n`
 }
 
+/** Whether `.env` declares `key` at all, with or without a value. */
+function hasEnvLine(content: string, key: string): boolean {
+  return new RegExp(`^${key}=`, "m").test(content)
+}
+
 function readEnvVar(content: string, key: string): string | undefined {
   const re = new RegExp(`^${key}=(.*)$`, "m")
   const match = re.exec(content)