@iann29/synapse 1.8.6 → 1.8.8

package/bin/synapse.js

@@ -30,7 +30,24 @@ async function main(argv) {
 
   const { cmd, rest } = resolve(REGISTRY, cleanArgv);
   if (!cmd) {
-    process.stderr.write(`Unknown command: ${cleanArgv.join(" ")}\n\nRun \`synapse help\` for the full list.\n`);
+    // v1.8.7: if the operator typed `synapse <prefix>` where one or
+    // more two-word commands exist under that prefix, suggest them.
+    // Turns "Unknown command: deployment" → an actionable list of
+    // verbs the operator can pick from.
+    const prefix = cleanArgv[0] + " ";
+    const verbs = [];
+    for (const name of REGISTRY.keys()) {
+      if (name.startsWith(prefix)) verbs.push(name);
+    }
+    process.stderr.write(`Unknown command: ${cleanArgv.join(" ")}\n`);
+    if (verbs.length > 0) {
+      verbs.sort();
+      process.stderr.write(`\nDid you mean one of:\n`);
+      for (const v of verbs) process.stderr.write(`  synapse ${v}\n`);
+      process.stderr.write(`\nRun \`synapse ${cleanArgv[0]} <verb> --help\` for usage.\n`);
+    } else {
+      process.stderr.write(`\nRun \`synapse help\` for the full list.\n`);
+    }
     process.exitCode = 1;
     return;
   }

package/lib/api.js

@@ -131,6 +131,60 @@ class SynapseAPI {
   cliCredentials(deploymentName) {
     return this.request("GET", `/v1/deployments/${encodeURIComponent(deploymentName)}/cli_credentials`);
   }
+
+  // ---- v1.8.7 control-plane methods ------------------------------
+
+  // GET /v1/deployments/{name}/ — single-deployment snapshot for the
+  // status command (faster than filtering listDeployments client-side
+  // when the operator already knows the name).
+  getDeployment(name) {
+    return this.request("GET", `/v1/deployments/${encodeURIComponent(name)}/`);
+  }
+
+  // GET /v1/deployments/{name}/backend_version — version of the running
+  // Convex backend inside the container. Cheap and useful in `status`.
+  // Falls back to {} if the deployment isn't ready (status: provisioning).
+  getDeploymentBackendVersion(name) {
+    return this.request("GET", `/v1/deployments/${encodeURIComponent(name)}/backend_version`);
+  }
+
+  // POST /v1/projects/{id}/create_deployment — body: { type, ha?, reference?, isDefault? }.
+  // Backend generates the deployment name; we surface it in the response.
+  createDeployment(projectId, body) {
+    return this.request("POST", `/v1/projects/${encodeURIComponent(projectId)}/create_deployment`, body);
+  }
+
+  // POST /v1/deployments/{name}/delete — irreversible; container + volume
+  // gone. Returns 200 with no body on success. The caller is responsible
+  // for typed-confirmation in the UI layer.
+  deleteDeployment(name) {
+    return this.request("POST", `/v1/deployments/${encodeURIComponent(name)}/delete`, {});
+  }
+
+  // POST /v1/deployments/{name}/reissue_admin_key — re-mints the admin
+  // key from the current instance_secret WITHOUT touching the secret.
+  // Use when stored credentials drift from the live container.
+  // Response: { deploymentName, adminKey, prefix }.
+  reissueAdminKey(name) {
+    return this.request("POST", `/v1/deployments/${encodeURIComponent(name)}/reissue_admin_key`, {});
+  }
+
+  // GET /v1/projects/{id}/list_default_environment_variables — returns
+  // { configs: [{ name, value, deploymentTypes[] }] }. We hand the raw
+  // shape back; the command formats it.
+  listProjectEnvVars(projectId) {
+    return this.request("GET", `/v1/projects/${encodeURIComponent(projectId)}/list_default_environment_variables`);
+  }
+
+  // POST /v1/projects/{id}/update_default_environment_variables — body:
+  // { changes: [{ op: "set"|"delete", name, value?, deploymentTypes? }] }.
+  // Cloud-spec shape; the backend applies the batch in a transaction so
+  // partial-failure is impossible.
+  updateProjectEnvVars(projectId, changes) {
+    return this.request("POST", `/v1/projects/${encodeURIComponent(projectId)}/update_default_environment_variables`, {
+      changes,
+    });
+  }
 }
 
 // Known envelope keys, in priority order. We try these explicitly before

package/lib/commands/_help.js

@@ -14,12 +14,13 @@ function renderRootHelp(registry, { stdout = process.stdout } = {}) {
     ["Session", ["login", "logout", "whoami"]],
     ["Project linking", ["select", "credentials"]],
     ["Day-to-day", ["dev", "deploy"]],
-    ["Visibility", ["version", "status", "doctor", "open", "logs"]],
+    ["Visibility", ["version", "status", "doctor", "open", "list", "logs"]],
     ["Deployments", "deployment"],
     ["Projects", "project"],
     ["Teams", "team"],
     ["Env vars", "env"],
     ["Domains", "domain"],
+    ["Local HTTPS dev", "https"],
     ["Escape hatch", ["convex"]],
   ];
 

package/lib/commands/_resource.js

@@ -0,0 +1,152 @@
+// Shared helpers for v1.8.7 control-plane commands.
+//
+// Every command in the new "Deployments" + "Env vars" sections needs
+// to resolve a target project — either from the linked `.synapse/
+// project.json` (no flag) or from an explicit `--project=<id>` / team
+// flag (CI / scripted runs). Centralising the logic here keeps the
+// commands themselves slim and gives us one place to update if the
+// resolution rules change.
+
+// Extracts `--project=<id>` / `--project <id>` from argv. Returns the
+// id (or null) plus the remaining args. We accept the equals form
+// and the space-separated form — operators copy-paste from various
+// shells.
+function extractProjectFlag(args) {
+  const rest = [];
+  let projectId = null;
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === "--project") {
+      projectId = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (a.startsWith("--project=")) {
+      projectId = a.slice("--project=".length);
+      continue;
+    }
+    rest.push(a);
+  }
+  return { projectId, rest };
+}
+
+// Same shape as extractProjectFlag for --team. team flag accepts either
+// a slug or an id (backend's loadTeamForRequest accepts both).
+function extractTeamFlag(args) {
+  const rest = [];
+  let teamRef = null;
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === "--team") {
+      teamRef = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (a.startsWith("--team=")) {
+      teamRef = a.slice("--team=".length);
+      continue;
+    }
+    rest.push(a);
+  }
+  return { teamRef, rest };
+}
+
+// Generic flag extractor. Boolean flags (no value) and string flags
+// (with `--name=value` form) must be DECLARED separately so the parser
+// never has to guess whether `--default value-stays` means
+// `default=true, positional=value-stays` (operator intent) or
+// `default=value-stays` (greedy heuristic).
+//
+// Both spec shapes are accepted:
+//   extractFlags(args, ["foo", "bar"])
+//       → all flags string-or-true (legacy form; used by single-arg
+//       parsers that don't have boolean/string ambiguity)
+//   extractFlags(args, { string: ["type"], boolean: ["ha", "yes"] })
+//       → strict: boolean flags NEVER consume the next token; string
+//       flags require `--name=value` OR `--name <value>` (next-token).
+//
+// Unknown flags stay in `rest` (commands surface them with a Usage
+// error).
+function extractFlags(args, spec) {
+  let stringSet;
+  let booleanSet;
+  if (Array.isArray(spec)) {
+    // Legacy shape — keep the v1.8.x behaviour for `parseFlags`-style
+    // call sites that don't differentiate.
+    stringSet = new Set(spec);
+    booleanSet = new Set();
+  } else {
+    stringSet = new Set(spec.string || []);
+    booleanSet = new Set(spec.boolean || []);
+  }
+  const known = (n) => stringSet.has(n) || booleanSet.has(n);
+
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      const name = eq >= 0 ? a.slice(2, eq) : a.slice(2);
+      if (known(name)) {
+        if (eq >= 0) {
+          // --name=value: always string (a boolean flag with `=` is
+          // unambiguous, e.g. `--yes=false`).
+          flags[name] = a.slice(eq + 1);
+          continue;
+        }
+        if (booleanSet.has(name) && !stringSet.has(name)) {
+          // Pure boolean. NEVER consumes the next token.
+          flags[name] = true;
+          continue;
+        }
+        // String (or legacy-spec) flag without `=`: consume next token
+        // if it isn't another flag. Boolean detection via the
+        // boolean-set above already short-circuited, so this branch
+        // is reached only for explicit string flags.
+        const next = args[i + 1];
+        if (next === undefined || next.startsWith("--")) {
+          flags[name] = true;
+        } else {
+          flags[name] = next;
+          i += 1;
+        }
+        continue;
+      }
+    }
+    rest.push(a);
+  }
+  return { flags, rest };
+}
+
+// Resolve the project the command should operate on. Result:
+//   { projectId, source: "flag" | "linked", projectConfig?, fallbackError? }
+// Throws when neither a flag NOR a linked project is available (the
+// error message tells the operator exactly what to do).
+function resolveProject(ctx, args) {
+  const { projectId, rest } = extractProjectFlag(args);
+  if (projectId) {
+    return { projectId, source: "flag", rest };
+  }
+  const linked = ctx.projectConfig;
+  if (linked && linked.project && linked.project.id) {
+    return {
+      projectId: linked.project.id,
+      source: "linked",
+      projectConfig: linked,
+      rest,
+    };
+  }
+  const err = new Error(
+    "No linked project in this directory. Pass --project=<id> or run `synapse select` first.",
+  );
+  err.code = "no_project";
+  throw err;
+}
+
+module.exports = {
+  extractFlags,
+  extractProjectFlag,
+  extractTeamFlag,
+  resolveProject,
+};

package/lib/commands/deployment-create.js

@@ -0,0 +1,122 @@
+// `synapse deployment create [--type=dev|prod|preview|custom] [--ha]
+//   [--default] [--project=<id>] [--json]`
+//
+// Provisions a new Convex backend container under the linked (or
+// --project=) project. The backend generates the deployment name
+// (animal-adjective-NNNN) — we don't accept it as an arg, matching
+// Convex Cloud's contract.
+//
+// Safety: prod creation prompts for `--yes` (or stdin "yes") because
+// the container is real, gets a host port, and counts against quota.
+// dev creates straight through.
+
+const colors = require("../colors");
+const { extractFlags, resolveProject } = require("./_resource");
+const { confirm } = require("../prompts");
+
+const VALID_TYPES = new Set(["dev", "prod", "preview", "custom"]);
+
+module.exports = {
+  name: "deployment create",
+  summary: "Create a new Convex deployment under the linked project.",
+  usage:
+    "synapse deployment create [--type=dev|prod|preview|custom] [--ha] [--default] [--project=<id>] [--yes] [--json]",
+  description: `Provisions a real Convex backend container. The backend generates the deployment name (animal-adjective-NNNN); you receive it in the response.
+
+Flags:
+  --type=<dev|prod|preview|custom>  Deployment type. Default: dev.
+  --ha                              Provision HA (2 replicas + Postgres + S3).
+                                    Requires SYNAPSE_HA_ENABLED on the host.
+  --default                         Mark as the project's default deployment.
+  --project=<id>                    Operate on a non-linked project.
+  --yes                             Skip the prod-confirmation prompt.
+  --json                            Machine-readable output.
+
+Examples:
+  synapse deployment create
+  synapse deployment create --type=prod --yes
+  synapse deployment create --type=dev --ha --default --project=<uuid>`,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["type", "project"],
+      boolean: ["ha", "default", "yes"],
+    });
+    if (rest.length > 0) {
+      throw new Error(
+        `Unexpected positional: ${rest[0]}. The backend generates the deployment name; flags only.`,
+      );
+    }
+    // resolveProject reads from --project= via extractProjectFlag. We
+    // already consumed --project above; thread it back through args so
+    // resolveProject can see it.
+    const resolveArgs = flags.project ? [`--project=${flags.project}`] : [];
+    const { projectId, source } = resolveProject(ctx, resolveArgs);
+
+    const type = (flags.type || "dev").toLowerCase();
+    if (!VALID_TYPES.has(type)) {
+      throw new Error(
+        `Invalid --type: ${type}. Must be one of: ${[...VALID_TYPES].join(", ")}.`,
+      );
+    }
+    const ha = flags.ha === true || flags.ha === "true";
+    const isDefault = flags.default === true || flags.default === "true";
+    const yes = flags.yes === true || flags.yes === "true";
+
+    // Prod confirmation. Mirrors `synapse deploy`'s prompt — operator
+    // muscle-memory expects the same friction. Skipped in --json mode
+    // (CI scripts must pass --yes explicitly anyway).
+    if (type === "prod" && !yes && !ctx.out.json) {
+      const confirmed = await confirm(
+        `Create a NEW PROD deployment under ${source === "linked" ? "this directory's linked project" : projectId}? [y/N] `,
+        { defaultAnswer: false },
+      );
+      if (!confirmed) {
+        ctx.out.info("Aborted.");
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (type === "prod" && !yes && ctx.out.json) {
+      // Fail closed in JSON mode so a script can't accidentally
+      // provision prod without an explicit --yes.
+      throw new Error(
+        "Refusing to create a prod deployment in --json mode without --yes.",
+      );
+    }
+
+    if (!ctx.out.json) {
+      ctx.out.info(
+        `Creating ${type}${ha ? " (HA)" : ""}${isDefault ? " [default]" : ""} deployment in project ${projectId}…`,
+      );
+    }
+    const body = { type };
+    if (ha) body.ha = true;
+    if (isDefault) body.isDefault = true;
+    const created = await ctx.api.createDeployment(projectId, body);
+
+    ctx.out.result(
+      {
+        projectId,
+        projectSource: source,
+        deployment: created,
+      },
+      (_d, { stdout }) => {
+        stdout.write(
+          `${colors.green("Created")} ${colors.bold(created.name)} ${colors.dim(`(${created.deploymentType || type})`)}\n`,
+        );
+        if (created.deploymentUrl || created.url) {
+          stdout.write(colors.dim(`URL: ${created.deploymentUrl || created.url}\n`));
+        }
+        if (created.status) {
+          stdout.write(colors.dim(`Status: ${created.status}\n`));
+        }
+        stdout.write(
+          colors.dim(
+            `Tip: run \`synapse deployment status ${created.name} --watch\` to track readiness, or \`synapse select\` to link this directory to it.\n`,
+          ),
+        );
+      },
+    );
+  },
+};

package/lib/commands/deployment-delete.js

@@ -0,0 +1,117 @@
+// `synapse deployment delete <name> [--yes] [--confirm=<name>] [--json]`
+//
+// Destroys the container + storage volume. Irreversible.
+//
+// Safety levels:
+//   - dev: single `--yes` confirms (or interactive y/N prompt)
+//   - prod: typed-confirmation REQUIRED — operator must re-type the
+//     deployment name. `--yes` is NOT enough for prod (mirrors the
+//     dashboard's v1.7.2 typed-confirm flow). Non-interactive callers
+//     pass `--confirm=<exact-name>` instead.
+//
+// The deployment type is fetched from the backend before the delete
+// fires so we know whether to ask for typed-confirm. One extra GET is
+// cheap and prevents the "I thought this was dev" footgun.
+
+const colors = require("../colors");
+const { extractFlags } = require("./_resource");
+const { confirm, typedConfirm } = require("../prompts");
+const { SynapseAPIError } = require("../api");
+
+module.exports = {
+  name: "deployment delete",
+  summary: "Delete a deployment (container + volume — irreversible).",
+  usage:
+    "synapse deployment delete <name> [--yes] [--confirm=<name>] [--json]",
+  description: `Calls POST /v1/deployments/{name}/delete. The container is destroyed and the storage volume is wiped. Production deployments require typed confirmation — re-type the deployment name.
+
+Flags:
+  --yes                Skip the y/N prompt for dev deployments.
+  --confirm=<name>     Pre-supply the typed confirmation (CI usage). For
+                       prod deployments this is mandatory in --json mode.
+  --json               Machine-readable output.
+
+Examples:
+  synapse deployment delete brave-dolphin-1060
+  synapse deployment delete brave-dolphin-1060 --yes              # dev only
+  synapse deployment delete wise-otter-2200 --confirm=wise-otter-2200`,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["confirm"],
+      boolean: ["yes", "json"],
+    });
+    const name = rest[0];
+    if (!name) {
+      throw new Error(
+        "Usage: synapse deployment delete <name> [--yes|--confirm=<name>]",
+      );
+    }
+    if (rest.length > 1) {
+      throw new Error(`Unexpected positional: ${rest[1]}.`);
+    }
+    const yes = flags.yes === true || flags.yes === "true";
+    const typed = typeof flags.confirm === "string" ? flags.confirm : null;
+
+    // Look up the deployment to learn its type. 404 here is the most
+    // common operator typo case — surface a clear error before any
+    // destructive call.
+    let dep;
+    try {
+      dep = await ctx.api.getDeployment(name);
+    } catch (err) {
+      if (err instanceof SynapseAPIError && err.status === 404) {
+        throw new Error(
+          `Deployment "${name}" not found. Run \`synapse list deployments\` to see your deployments.`,
+        );
+      }
+      throw err;
+    }
+    const type = dep.deploymentType || dep.type || "unknown";
+
+    if (type === "prod") {
+      // Typed-confirmation MANDATORY. --yes alone does not bypass it.
+      if (!typed && ctx.out.json) {
+        throw new Error(
+          `Refusing to delete prod deployment "${name}" in --json mode without --confirm=${name}.`,
+        );
+      }
+      const ok = await typedConfirm("delete", name, { typed });
+      if (!ok) {
+        ctx.out.info(`Aborted (confirmation didn't match "${name}").`);
+        process.exitCode = 1;
+        return;
+      }
+    } else {
+      // Dev / preview / custom — y/N prompt unless --yes was passed.
+      if (!yes && !typed && !ctx.out.json) {
+        const confirmed = await confirm(
+          `Delete ${type} deployment ${colors.bold(name)}? [y/N] `,
+          { defaultAnswer: false },
+        );
+        if (!confirmed) {
+          ctx.out.info("Aborted.");
+          process.exitCode = 1;
+          return;
+        }
+      }
+      if (!yes && !typed && ctx.out.json) {
+        throw new Error(
+          `Refusing to delete "${name}" in --json mode without --yes.`,
+        );
+      }
+    }
+
+    if (!ctx.out.json) {
+      ctx.out.info(`Deleting ${type} deployment ${name}…`);
+    }
+    await ctx.api.deleteDeployment(name);
+
+    ctx.out.result(
+      { deleted: true, name, type },
+      (_d, { stdout }) => {
+        stdout.write(`${colors.red("Deleted")} ${colors.bold(name)} ${colors.dim(`(${type})`)}\n`);
+      },
+    );
+  },
+};

package/lib/commands/deployment-rotate-key.js

@@ -0,0 +1,173 @@
+// `synapse deployment rotate-key <name> [--yes] [--confirm=<name>] [--write] [--json]`
+//
+// Calls POST /v1/deployments/{name}/reissue_admin_key. Re-mints the
+// admin_key from the current INSTANCE_SECRET (no container restart).
+//
+// What this does NOT do:
+//   - It does NOT rotate INSTANCE_SECRET (so existing deploy keys keep
+//     working). To actually invalidate a leaked credential you'd need
+//     to recreate the deployment.
+//   - It does NOT auto-update the operator's .env.local. We surface a
+//     --write flag that opt-in does it (using the same writer as
+//     `synapse select`), but the default is "show the key and let the
+//     operator paste it".
+//
+// Safety:
+//   - prod deployments REQUIRE typed-confirm (--confirm=<name>) since
+//     rotating mid-flight breaks the iframed Convex Dashboard until the
+//     operator hits "Refresh credentials".
+//   - dev: `--yes` suffices.
+
+const colors = require("../colors");
+const { extractFlags } = require("./_resource");
+const { confirm, typedConfirm } = require("../prompts");
+const { SynapseAPIError } = require("../api");
+const { writeProjectEnv } = require("../env-file");
+
+module.exports = {
+  name: "deployment rotate-key",
+  summary: "Re-mint a deployment's admin key (cures stale credentials).",
+  usage:
+    "synapse deployment rotate-key <name> [--yes] [--confirm=<name>] [--write] [--json]",
+  description: `Calls POST /v1/deployments/{name}/reissue_admin_key. Used when the stored admin_key drifts out of sync with the running container (symptom: "deployment URL or admin key is invalid" inside the Convex Dashboard iframe).
+
+The deployment's INSTANCE_SECRET is NOT rotated — existing deploy keys keep working. If you need to invalidate a leaked credential, delete + recreate the deployment.
+
+Flags:
+  --yes               Skip the y/N prompt (dev only).
+  --confirm=<name>    Pre-supply the typed confirmation for prod.
+  --write             Also rewrite .env.local in the current directory
+                      IF this is the linked dev deployment.
+  --json              Machine-readable output.
+
+Examples:
+  synapse deployment rotate-key brave-dolphin-1060 --yes
+  synapse deployment rotate-key wise-otter-2200 --confirm=wise-otter-2200 --write`,
+
+  async run(args, ctx) {
+    const { flags, rest } = extractFlags(args, {
+      string: ["confirm"],
+      boolean: ["yes", "write", "json"],
+    });
+    const name = rest[0];
+    if (!name) {
+      throw new Error(
+        "Usage: synapse deployment rotate-key <name> [--yes|--confirm=<name>]",
+      );
+    }
+    if (rest.length > 1) {
+      throw new Error(`Unexpected positional: ${rest[1]}.`);
+    }
+    const yes = flags.yes === true || flags.yes === "true";
+    const write = flags.write === true || flags.write === "true";
+    const typed = typeof flags.confirm === "string" ? flags.confirm : null;
+
+    let dep;
+    try {
+      dep = await ctx.api.getDeployment(name);
+    } catch (err) {
+      if (err instanceof SynapseAPIError && err.status === 404) {
+        throw new Error(
+          `Deployment "${name}" not found. Run \`synapse list deployments\` to see your deployments.`,
+        );
+      }
+      throw err;
+    }
+    const type = dep.deploymentType || dep.type || "unknown";
+
+    // Adopted deployments can't be rotated — backend will 400, but we
+    // catch it earlier with a clearer message.
+    if (dep.adopted) {
+      throw new Error(
+        `Cannot rotate key for "${name}" — it's an adopted (external) deployment. Rotate the admin key on the source side and re-adopt.`,
+      );
+    }
+
+    if (type === "prod") {
+      if (!typed && ctx.out.json) {
+        throw new Error(
+          `Refusing to rotate prod key for "${name}" in --json mode without --confirm=${name}.`,
+        );
+      }
+      const ok = await typedConfirm("rotate-key", name, { typed });
+      if (!ok) {
+        ctx.out.info(`Aborted (confirmation didn't match "${name}").`);
+        process.exitCode = 1;
+        return;
+      }
+    } else {
+      if (!yes && !typed && !ctx.out.json) {
+        const confirmed = await confirm(
+          `Rotate admin key for ${type} deployment ${colors.bold(name)}? [y/N] `,
+          { defaultAnswer: false },
+        );
+        if (!confirmed) {
+          ctx.out.info("Aborted.");
+          process.exitCode = 1;
+          return;
+        }
+      }
+      if (!yes && !typed && ctx.out.json) {
+        throw new Error(
+          `Refusing to rotate "${name}" in --json mode without --yes.`,
+        );
+      }
+    }
+
+    if (!ctx.out.json) {
+      ctx.out.info(`Rotating admin key for ${name}…`);
+    }
+    const res = await ctx.api.reissueAdminKey(name);
+
+    // Optional .env.local rewrite. Only fires when:
+    //   - --write was passed
+    //   - the rotated deployment is the linked dev deployment in CWD
+    //   - we can fetch fresh credentials to wire in the new url+key
+    let envWritten = null;
+    if (write) {
+      const linked = ctx.projectConfig;
+      const matchedDev = linked?.deployments?.dev?.name === name;
+      if (!matchedDev) {
+        if (!ctx.out.json) {
+          ctx.out.warn(
+            "--write skipped: this is not the linked dev deployment in the current directory.",
+          );
+        }
+      } else {
+        const creds = await ctx.api.cliCredentials(name);
+        envWritten = writeProjectEnv(ctx.cwd, creds, {
+          team: { slug: linked.team?.slug, name: linked.team?.name },
+          project: { slug: linked.project?.slug, name: linked.project?.name },
+          target: "dev",
+        });
+      }
+    }
+
+    ctx.out.result(
+      {
+        rotated: true,
+        deploymentName: res.deploymentName || name,
+        prefix: res.prefix,
+        // Full new key. Same exposure profile as `synapse credentials`
+        // — operator already had this on disk before rotation; the
+        // surface is unchanged.
+        adminKey: res.adminKey,
+        envWritten,
+      },
+      (_d, { stdout }) => {
+        stdout.write(
+          `${colors.green("Rotated")} ${colors.bold(name)} ${colors.dim(`(prefix ${res.prefix})`)}\n`,
+        );
+        stdout.write(colors.dim("New admin key (paste into .env.local or pass --write):\n"));
+        stdout.write(res.adminKey + "\n");
+        if (envWritten) {
+          stdout.write(colors.green(`Updated ${envWritten}\n`));
+        } else if (write) {
+          stdout.write(
+            colors.dim("Hint: pass --write only when rotating the linked dev deployment.\n"),
+          );
+        }
+      },
+    );
+  },
+};