From 6f4ad0ee110c6902c0f25c15c68fda5112d693d6 Mon Sep 17 00:00:00 2001
From: Leo-Paul Goffic <leo.goffic@altertable.ai>
Date: Wed, 16 Sep 2026 17:41:27 +0200
Subject: [PATCH 1/2] feat: add `login --service-account` and `logout
 --except-current` commands

---
 COMMANDS.md                                   |  14 +-
 cli-reference.json                            |  56 ++-
 cli/scripts/command-reference.ts              |   3 +-
 cli/src/commands/completion/lib/format.ts     |   8 +-
 cli/src/commands/completion/lib/model.ts      |   3 +-
 cli/src/commands/login/index.test.ts          | 358 +++++++++++++++++-
 cli/src/commands/login/index.ts               | 264 ++++++++++++-
 cli/src/commands/logout/index.test.ts         |  62 ++-
 cli/src/commands/logout/index.ts              |  12 +-
 cli/src/lib/command-descriptor.ts             |   9 +
 cli/src/lib/command-parser.ts                 |   3 +-
 cli/src/lib/command.test.ts                   |  32 ++
 cli/src/lib/errors.ts                         |   6 +-
 cli/src/lib/lakehouse-provision.test.ts       |  40 +-
 cli/src/lib/lakehouse-provision.ts            |  22 +-
 cli/src/lib/oauth-flow.ts                     |   8 +-
 cli/src/lib/profile-configure-core.test.ts    |   6 +-
 cli/src/lib/profile-configure-core.ts         |  60 ++-
 cli/src/lib/profile/model.test.ts             |  25 ++
 cli/src/lib/profile/model.ts                  |  18 +
 cli/src/lib/service-account-provision.test.ts |  57 +++
 cli/src/lib/service-account-provision.ts      | 181 +++++++++
 cli/src/lib/usage.ts                          |   3 +-
 23 files changed, 1187 insertions(+), 63 deletions(-)
 create mode 100644 cli/src/lib/service-account-provision.test.ts
 create mode 100644 cli/src/lib/service-account-provision.ts

diff --git a/COMMANDS.md b/COMMANDS.md
index d211d69..fed2473 100644
--- a/COMMANDS.md
+++ b/COMMANDS.md
@@ -39,12 +39,17 @@ altertable login [options]
 | `--data-plane-url <DATA-PLANE-URL>` | Data-plane base URL saved to the profile only on successful login. Default: https://api.altertable.ai |
 | `--allow-insecure-http` | Allow http:// URLs other than localhost for --control-plane-url (for development only) |
 | `--replace-profile` | Store the login session in the current profile instead of switching profiles |
+| `--svc, --service-account <LABEL>` | Create an environment-scoped service account with this label and store its access token instead of your login session |
+| `--only <CATALOG:MODE,...>` | Request a service account limited to specific catalogs, e.g. analytics:ro,staging:rw (requires --service-account). The catalog access the server actually grants is reported on success. |
+| `--readonly` | Request a service account with read-only access to every catalog (requires --service-account; cannot be combined with --only) |
 
 **Examples**
 
 ```bash
 altertable login
 altertable login --replace-profile
+altertable login --service-account "CI Bot" --only analytics:ro
+altertable login --svc "CI Bot" --readonly
 ```
 
 ### `altertable logout`
@@ -54,13 +59,20 @@ Remove stored credentials and settings for all profiles.
 **Usage**
 
 ```bash
-altertable logout
+altertable logout [options]
 ```
 
+**Options**
+
+| Option | Description |
+| --- | --- |
+| `--except-current` | Keep the current profile and remove every other profile |
+
 **Examples**
 
 ```bash
 altertable logout
+altertable logout --except-current
 ```
 
 ### `altertable profile`
diff --git a/cli-reference.json b/cli-reference.json
index c01610b..83d7715 100644
--- a/cli-reference.json
+++ b/cli-reference.json
@@ -163,11 +163,47 @@
               "repeatable": false,
               "scope": "command",
               "values": []
+            },
+            {
+              "name": "service-account",
+              "aliases": [
+                "svc"
+              ],
+              "type": "string",
+              "description": "Create an environment-scoped service account with this label and store its access token instead of your login session",
+              "required": false,
+              "repeatable": false,
+              "scope": "command",
+              "values": [],
+              "valueHint": "LABEL"
+            },
+            {
+              "name": "only",
+              "aliases": [],
+              "type": "string",
+              "description": "Request a service account limited to specific catalogs, e.g. analytics:ro,staging:rw (requires --service-account). The catalog access the server actually grants is reported on success.",
+              "required": false,
+              "repeatable": false,
+              "scope": "command",
+              "values": [],
+              "valueHint": "CATALOG:MODE,..."
+            },
+            {
+              "name": "readonly",
+              "aliases": [],
+              "type": "boolean",
+              "description": "Request a service account with read-only access to every catalog (requires --service-account; cannot be combined with --only)",
+              "required": false,
+              "repeatable": false,
+              "scope": "command",
+              "values": []
             }
           ],
           "examples": [
             "altertable login",
-            "altertable login --replace-profile"
+            "altertable login --replace-profile",
+            "altertable login --service-account \"CI Bot\" --only analytics:ro",
+            "altertable login --svc \"CI Bot\" --readonly"
           ],
           "subcommands": []
         },
@@ -176,13 +212,25 @@
           "command": "altertable logout",
           "description": "Remove stored credentials and settings for all profiles.",
           "usage": [
-            "altertable logout"
+            "altertable logout [options]"
           ],
           "aliases": [],
           "arguments": [],
-          "options": [],
+          "options": [
+            {
+              "name": "except-current",
+              "aliases": [],
+              "type": "boolean",
+              "description": "Keep the current profile and remove every other profile",
+              "required": false,
+              "repeatable": false,
+              "scope": "command",
+              "values": []
+            }
+          ],
           "examples": [
-            "altertable logout"
+            "altertable logout",
+            "altertable logout --except-current"
           ],
           "subcommands": []
         },
diff --git a/cli/scripts/command-reference.ts b/cli/scripts/command-reference.ts
index 37d5c57..92105e2 100644
--- a/cli/scripts/command-reference.ts
+++ b/cli/scripts/command-reference.ts
@@ -6,6 +6,7 @@ import {
   type AltertableCommandGroup,
 } from "@/lib/command.ts";
 import {
+  aliasFlagToken,
   visibleCommandDescriptors,
   type CommandArgumentDescriptor,
   type CommandDescriptor,
@@ -59,7 +60,7 @@ function positionalToken(argument: CliReferenceArgument): string {
 }
 
 function optionLabel(argument: CliReferenceArgument): string {
-  const aliases = argument.aliases.map((alias) => `-${alias}`);
+  const aliases = argument.aliases.map(aliasFlagToken);
   const value =
     argument.type === "string" || argument.type === "enum"
       ? ` <${argumentValueLabel(argument)}>`
diff --git a/cli/src/commands/completion/lib/format.ts b/cli/src/commands/completion/lib/format.ts
index b97236d..4b67800 100644
--- a/cli/src/commands/completion/lib/format.ts
+++ b/cli/src/commands/completion/lib/format.ts
@@ -4,6 +4,7 @@ import type {
   CompletionFlag,
   CompletionNode,
 } from "@/commands/completion/lib/spec.ts";
+import { aliasFlagToken } from "@/lib/command-descriptor.ts";
 
 const FISH_BINARY_NAME = "altertable";
 
@@ -26,7 +27,7 @@ function formatNameList(names: readonly string[]): string {
 }
 
 function flagForms(flag: CompletionFlag): string[] {
-  return flag.alias ? [`-${flag.alias}`, `--${flag.name}`] : [`--${flag.name}`];
+  return flag.alias ? [aliasFlagToken(flag.alias), `--${flag.name}`] : [`--${flag.name}`];
 }
 
 export function formatBashFlagWordList(flags: readonly CompletionFlag[]): string {
@@ -518,12 +519,13 @@ export function formatFishPathCondition(
 }
 
 function formatFishFlagCompleteLine(flag: CompletionFlag, condition?: string): string {
-  const shortFlag = flag.alias ? ` -s ${flag.alias}` : "";
+  // fish takes short flags via -s and every long form via its own -l.
+  const aliasFlag = flag.alias ? `${flag.alias.length === 1 ? " -s " : " -l "}${flag.alias}` : "";
   const description = flag.description ? ` -d '${escapeFishDescription(flag.description)}'` : "";
   const values =
     flag.values && flag.values.length > 0 ? ` -f -r -a "${flag.values.join(" ")}"` : "";
   const conditionArg = condition ? ` -n "${condition}"` : "";
-  return `complete -c ${FISH_BINARY_NAME}${shortFlag} -l ${flag.name}${description}${values}${conditionArg}`;
+  return `complete -c ${FISH_BINARY_NAME}${aliasFlag} -l ${flag.name}${description}${values}${conditionArg}`;
 }
 
 function formatFishNormalizer(model: CompletionModel): string {
diff --git a/cli/src/commands/completion/lib/model.ts b/cli/src/commands/completion/lib/model.ts
index 89d292e..ac032c1 100644
--- a/cli/src/commands/completion/lib/model.ts
+++ b/cli/src/commands/completion/lib/model.ts
@@ -4,6 +4,7 @@ import {
   type CompletionFlag,
   type CompletionNode,
 } from "@/commands/completion/lib/spec.ts";
+import { aliasFlagToken } from "@/lib/command-descriptor.ts";
 
 export type CompletionModel = {
   contexts: CompletionContext[];
@@ -21,7 +22,7 @@ export type NormalizedCompletionArgv = {
 };
 
 function flagForms(flag: CompletionFlag): string[] {
-  return flag.alias ? [`-${flag.alias}`, `--${flag.name}`] : [`--${flag.name}`];
+  return flag.alias ? [aliasFlagToken(flag.alias), `--${flag.name}`] : [`--${flag.name}`];
 }
 
 function allFlags(root: CompletionNode, contexts: readonly CompletionContext[]): CompletionFlag[] {
diff --git a/cli/src/commands/login/index.test.ts b/cli/src/commands/login/index.test.ts
index fb95311..a3cc2d4 100644
--- a/cli/src/commands/login/index.test.ts
+++ b/cli/src/commands/login/index.test.ts
@@ -1,8 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { configGet } from "@/lib/config.ts";
+import { HttpError } from "@/lib/errors.ts";
 import { storeOAuthTokens } from "@/lib/oauth-profile.ts";
 import { secretGet, secretSet } from "@/lib/secrets.ts";
 import { getActiveProfileName, profileExists, setActiveProfile } from "@/lib/profile-store.ts";
@@ -32,6 +33,17 @@ function storedAccessToken(profileName: string): string {
   return secretGet("oauth/access-token", profileName);
 }
 
+// bun-types declare rejects.toThrow() as void, so awaiting it trips the
+// await-thenable lint rule; capture the rejection explicitly instead.
+async function expectRejection(promise: Promise<unknown>, message: string): Promise<void> {
+  const error = await promise.then(
+    () => undefined,
+    (thrown: unknown) => thrown,
+  );
+  expect(error).toBeInstanceOf(Error);
+  expect((error as Error).message).toContain(message);
+}
+
 beforeEach(() => {
   testHome = mkdtempSync(join(tmpdir(), "altertable-login-test-"));
   mockFile = join(testHome, "mocks.json");
@@ -63,10 +75,44 @@ afterEach(() => {
   delete process.env.OSC_HYPERLINK;
 });
 
+const SERVICE_ACCOUNT_RESPONSE = {
+  service_account: { id: "sa-1", label: "My Service", slug: "my-service" },
+  role_assignments: [{ role: "catalog:reader", resource_kind: "catalog", resource_id: "cat-1" }],
+  service_oauth_token: "svc_access_token",
+};
+
+const CATALOG_LIST_MOCKS = [
+  {
+    urlPattern: "/environments/production/databases",
+    method: "GET",
+    body: JSON.stringify({ databases: [{ id: "cat-1", name: "Analytics", slug: "analytics" }] }),
+  },
+  {
+    urlPattern: "/environments/production/connections",
+    method: "GET",
+    body: JSON.stringify({ connections: [{ id: "cat-2", name: "Events", slug: "events" }] }),
+  },
+];
+
+function httpLogJsonPayload(logPath: string, urlSubstring: string): unknown {
+  const entry = readFileSync(logPath, "utf8")
+    .split("---\n")
+    .find((block) => block.includes(`URL=`) && block.includes(urlSubstring));
+  if (!entry) {
+    throw new Error(`No HTTP log entry for ${urlSubstring}`);
+  }
+  const payloadLine = entry.split("\n").find((line) => line.startsWith("PAYLOAD="));
+  if (!payloadLine) {
+    throw new Error(`No PAYLOAD= entry for ${urlSubstring}`);
+  }
+  return JSON.parse(payloadLine.slice("PAYLOAD=".length));
+}
+
 async function completeBrowserLogin(
   rawArgs: string[] = ["login"],
   whoami: object = DEFAULT_WHOAMI,
   accessToken = "access_token",
+  extraMocks: object[] = [],
 ) {
   writeFileSync(
     mockFile,
@@ -87,6 +133,7 @@ async function completeBrowserLogin(
         authPattern: accessToken,
         body: JSON.stringify(whoami),
       },
+      ...extraMocks,
     ]),
   );
 
@@ -96,7 +143,7 @@ async function completeBrowserLogin(
 
   let authorizeUrl: URL | undefined;
   for (let attempt = 0; attempt < 100 && !authorizeUrl; attempt += 1) {
-    const match = cli.stderr.join("\n").match(/https?:\/\/[^\s]+\/oauth\/authorize\?[^\s]+/);
+    const match = cli.stdout.join("\n").match(/https?:\/\/[^\s]+\/oauth\/authorize\?[^\s]+/);
     if (match?.[0]) authorizeUrl = new URL(match[0]);
     if (!authorizeUrl) await delay(5);
   }
@@ -129,7 +176,8 @@ describe("login command", () => {
     expect(configGet("organization_slug", "default")).toBe("altertable");
     expect(configGet("principal_email", "default")).toBe("test.user@altertable.test");
     expect(storedAccessToken("default")).toBe("access_token");
-    expect(cli.stderr.join("\n")).toContain('using profile "default"');
+    expect(cli.stdout.join("\n")).toContain('using profile "default"');
+    expect(cli.stderr).toEqual([]);
   });
 
   test("preserves an authenticated profile when signing into another organization", async () => {
@@ -239,3 +287,307 @@ describe("login command", () => {
     ).rejects.toThrow();
   });
 });
+
+describe("login --service-account", () => {
+  const serviceAccountProfile = "altertable_production_my-service";
+  let logFile = "";
+
+  beforeEach(() => {
+    logFile = join(testHome, "http.log");
+    process.env.ALTERTABLE_HTTP_LOG = logFile;
+  });
+
+  afterEach(() => {
+    delete process.env.ALTERTABLE_HTTP_LOG;
+  });
+
+  function serviceAccountMock(
+    body: object | string = SERVICE_ACCOUNT_RESPONSE,
+    status = 201,
+  ): object {
+    return {
+      urlPattern: "/environments/production/service_accounts",
+      method: "POST",
+      status,
+      body: typeof body === "string" ? body : JSON.stringify(body),
+    };
+  }
+
+  function serviceAccountMocks(body: object | string = SERVICE_ACCOUNT_RESPONSE): object[] {
+    return [serviceAccountMock(body), ...CATALOG_LIST_MOCKS];
+  }
+
+  test("provisions a service account and stores its service OAuth token", async () => {
+    const cli = await completeBrowserLogin(
+      ["login", "--service-account", "My Service", "--only", "catalog1:ro"],
+      DEFAULT_WHOAMI,
+      "access_token",
+      serviceAccountMocks(),
+    );
+
+    expect(getActiveProfileName()).toBe(serviceAccountProfile);
+    expect(profileExists(serviceAccountProfile)).toBe(true);
+    expect(configGet("principal_type", serviceAccountProfile)).toBe("ServiceAccount");
+    expect(configGet("principal_slug", serviceAccountProfile)).toBe("my-service");
+    expect(storedAccessToken(serviceAccountProfile)).toBe("svc_access_token");
+    expect(secretGet("oauth/refresh-token", serviceAccountProfile)).toBe("");
+    expect(configGet("oauth_expiry", serviceAccountProfile)).toBe("");
+    expect(secretGet("lakehouse/basic-token", serviceAccountProfile)).toBe("");
+    expect(cli.stdout.join("\n")).toContain("My Service");
+    expect(cli.stdout.join("\n")).toContain(serviceAccountProfile);
+    expect(cli.stdout.join("\n")).toMatch(/CATALOG\s+SLUG\s+ACCESS/);
+    expect(cli.stdout.join("\n")).toMatch(/Analytics\s+analytics\s+ro/);
+    expect(cli.stderr).toEqual([]);
+
+    const payload = httpLogJsonPayload(logFile, "/environments/production/service_accounts") as {
+      label: string;
+      caveats: Record<string, string>;
+    };
+    expect(payload.label).toBe("My Service");
+    expect(payload.caveats).toEqual({ catalog1: "ro" });
+    expect(payload).toHaveProperty("with_service_oauth_token");
+  });
+
+  test("--svc is accepted as an alias", async () => {
+    await completeBrowserLogin(
+      ["login", "--svc", "My Service"],
+      DEFAULT_WHOAMI,
+      "access_token",
+      serviceAccountMocks(),
+    );
+
+    expect(getActiveProfileName()).toBe(serviceAccountProfile);
+    expect(storedAccessToken(serviceAccountProfile)).toBe("svc_access_token");
+  });
+
+  test("leaves the signing-in user's own session unstored", async () => {
+    await completeBrowserLogin(
+      ["login", "--service-account", "My Service"],
+      DEFAULT_WHOAMI,
+      "access_token",
+      serviceAccountMocks(),
+    );
+
+    expect(storedAccessToken("default")).toBe("");
+    expect(secretGet("oauth/refresh-token", "default")).toBe("");
+    expect(storedAccessToken(serviceAccountProfile)).toBe("svc_access_token");
+  });
+
+  test("reports the catalogs the server granted, not the ones --only requested", async () => {
+    const cli = await completeBrowserLogin(
+      ["login", "--service-account", "My Service", "--only", "analytics:rw"],
+      DEFAULT_WHOAMI,
+      "access_token",
+      serviceAccountMocks({
+        ...SERVICE_ACCOUNT_RESPONSE,
+        role_assignments: [
+          { role: "catalog:reader", resource_kind: "catalog", resource_id: "cat-1" },
+          { role: "catalog:writer", resource_kind: "catalog", resource_id: "cat-2" },
+        ],
+      }),
+    );
+
+    const stdout = cli.stdout.join("\n");
+    expect(stdout).toContain("Catalog access");
+    expect(stdout).toMatch(/Analytics\s+analytics\s+ro/);
+    expect(stdout).toMatch(/Events\s+events\s+rw/);
+    expect(stdout).not.toContain("analytics:rw");
+  });
+
+  test("omits assignments that are not catalogs or cannot be resolved to a catalog", async () => {
+    const cli = await completeBrowserLogin(
+      ["login", "--service-account", "My Service"],
+      DEFAULT_WHOAMI,
+      "access_token",
+      serviceAccountMocks({
+        ...SERVICE_ACCOUNT_RESPONSE,
+        role_assignments: [
+          { role: "organization:member", resource_kind: "organization", resource_id: "org-1" },
+          { role: "catalog:reader", resource_kind: "catalog", resource_id: "cat-unknown" },
+        ],
+      }),
+    );
+
+    const stdout = cli.stdout.join("\n");
+    expect(stdout).not.toContain("Catalog access");
+    expect(stdout).not.toContain("org-1");
+    expect(stdout).not.toContain("cat-unknown");
+  });
+
+  test("warns when --only was requested but the server reported no role assignments", async () => {
+    const cli = await completeBrowserLogin(
+      ["login", "--service-account", "My Service", "--only", "analytics:ro"],
+      DEFAULT_WHOAMI,
+      "access_token",
+      serviceAccountMocks({ ...SERVICE_ACCOUNT_RESPONSE, role_assignments: [] }),
+    );
+
+    const stdout = cli.stdout.join("\n");
+    expect(stdout).not.toContain("Catalog access");
+    expect(stdout).toContain("could not be confirmed");
+  });
+
+  test("fails when the response omits the service OAuth token", async () => {
+    await expectRejection(
+      completeBrowserLogin(
+        ["login", "--service-account", "My Service"],
+        DEFAULT_WHOAMI,
+        "access_token",
+        [serviceAccountMock({ ...SERVICE_ACCOUNT_RESPONSE, service_oauth_token: undefined })],
+      ),
+      "service OAuth token",
+    );
+  });
+
+  test("omits caveats when --only is not set", async () => {
+    await completeBrowserLogin(
+      ["login", "--service-account", "My Service"],
+      DEFAULT_WHOAMI,
+      "access_token",
+      [serviceAccountMock()],
+    );
+
+    const payload = httpLogJsonPayload(logFile, "/environments/production/service_accounts") as {
+      caveats?: unknown;
+    };
+    expect(payload).not.toHaveProperty("caveats");
+  });
+
+  test("--readonly sends a blanket read-only caveat", async () => {
+    await completeBrowserLogin(
+      ["login", "--service-account", "My Service", "--readonly"],
+      DEFAULT_WHOAMI,
+      "access_token",
+      serviceAccountMocks(),
+    );
+
+    const payload = httpLogJsonPayload(logFile, "/environments/production/service_accounts") as {
+      caveats: unknown;
+    };
+    expect(payload.caveats).toBe("ro");
+  });
+
+  test("--readonly with --only fails before any HTTP call", async () => {
+    await expectRejection(
+      runCommandWithTestRuntime([
+        "login",
+        "--service-account",
+        "My Service",
+        "--readonly",
+        "--only",
+        "analytics:ro",
+      ]),
+      "--readonly cannot be combined with --only",
+    );
+    expect(existsSync(logFile)).toBe(false);
+  });
+
+  test("--readonly without --service-account fails before any HTTP call", async () => {
+    await expectRejection(
+      runCommandWithTestRuntime(["login", "--readonly"]),
+      "--readonly requires --service-account",
+    );
+    expect(existsSync(logFile)).toBe(false);
+  });
+
+  test("--only without --service-account fails before any HTTP call", async () => {
+    await expectRejection(
+      runCommandWithTestRuntime(["login", "--only", "catalog1:ro"]),
+      "--only requires --service-account",
+    );
+    expect(existsSync(logFile)).toBe(false);
+  });
+
+  test("--service-account with --replace-profile fails before any HTTP call", async () => {
+    await expectRejection(
+      runCommandWithTestRuntime(["login", "--service-account", "My Service", "--replace-profile"]),
+      "--replace-profile",
+    );
+    expect(existsSync(logFile)).toBe(false);
+  });
+
+  test("an empty --service-account label fails before any HTTP call", async () => {
+    await expectRejection(
+      runCommandWithTestRuntime(["login", "--service-account", "   "]),
+      "non-empty label",
+    );
+    expect(existsSync(logFile)).toBe(false);
+  });
+
+  test("malformed --only fails before any HTTP call", async () => {
+    await expectRejection(
+      runCommandWithTestRuntime([
+        "login",
+        "--service-account",
+        "My Service",
+        "--only",
+        "catalog1:read",
+      ]),
+      "catalog1:read",
+    );
+    expect(existsSync(logFile)).toBe(false);
+  });
+
+  // A URL rejected late would leave a service account minted server-side whose
+  // token was never stored, and the CLI switched to the empty profile.
+  test("a rejected --data-plane-url fails before the browser flow and mints nothing", async () => {
+    Object.defineProperty(process.stdin, "isTTY", { value: true, configurable: true });
+
+    await expectRejection(
+      runCommandWithTestRuntime([
+        "login",
+        "--service-account",
+        "My Service",
+        "--data-plane-url",
+        "http://evil.example.com",
+      ]),
+      "Insecure HTTP URL",
+    );
+
+    expect(existsSync(logFile)).toBe(false);
+    expect(profileExists(serviceAccountProfile)).toBe(false);
+    expect(getActiveProfileName()).toBe("default");
+  });
+
+  test("surfaces a 403 from the service account endpoint", async () => {
+    try {
+      await completeBrowserLogin(
+        ["login", "--service-account", "My Service", "--only", "catalog1:ro"],
+        DEFAULT_WHOAMI,
+        "access_token",
+        [
+          serviceAccountMock(
+            {
+              error: { code: "forbidden", message: "Only org admins can create service accounts" },
+            },
+            403,
+          ),
+        ],
+      );
+      expect.unreachable("login --service-account should have failed");
+    } catch (error) {
+      expect(error).toBeInstanceOf(HttpError);
+      const httpError = error as HttpError;
+      expect(httpError.message).toContain("service account");
+      expect(httpError.parsedDetail).toBe("Only org admins can create service accounts");
+    }
+  });
+
+  test("names the missing service account endpoint on 404", async () => {
+    try {
+      await completeBrowserLogin(
+        ["login", "--service-account", "My Service", "--only", "catalog1:ro"],
+        DEFAULT_WHOAMI,
+        "access_token",
+        [serviceAccountMock("<html>Not Found</html>", 404)],
+      );
+      expect.unreachable("login --service-account should have failed");
+    } catch (error) {
+      expect(error).toBeInstanceOf(HttpError);
+      const httpError = error as HttpError;
+      expect(httpError.message).toContain("service account");
+      expect(httpError.message).toContain("Not found (404)");
+      expect(httpError.details).toContain("/environments/production/service_accounts");
+    }
+  });
+});
diff --git a/cli/src/commands/login/index.ts b/cli/src/commands/login/index.ts
index ca4affc..03e5300 100644
--- a/cli/src/commands/login/index.ts
+++ b/cli/src/commands/login/index.ts
@@ -14,11 +14,23 @@ import {
   assertNoEnvConfigMode,
   createEmptyProfile,
   deriveProfileName,
+  deriveServiceAccountProfileName,
   profileHasAnyAuthConfigured,
   updateProfile,
 } from "@/lib/profile/model.ts";
 import { profileExists, resolveWorkingProfile, setActiveProfile } from "@/lib/profile-store.ts";
-import { span } from "@/ui/document.ts";
+import { secretSet } from "@/lib/secrets.ts";
+import {
+  fetchEnvironmentCatalogs,
+  parseServiceAccountCaveats,
+  provisionEnvironmentServiceAccount,
+  type EnvironmentCatalog,
+  type EnvironmentServiceAccountResponse,
+  type ServiceAccountCaveats,
+  type ServiceAccountRoleAssignment,
+} from "@/lib/service-account-provision.ts";
+import { document, section, span, table } from "@/ui/document.ts";
+import { renderDocumentText } from "@/ui/renderers/terminal.ts";
 import { renderDisplayText } from "@/ui/terminal/styles.ts";
 
 export const loginCommand = defineCommand({
@@ -26,7 +38,12 @@ export const loginCommand = defineCommand({
     name: "login",
     commandGroup: "platform",
     description: "Sign in with your browser (OAuth) and store the session.",
-    examples: ["altertable login", "altertable login --replace-profile"],
+    examples: [
+      "altertable login",
+      "altertable login --replace-profile",
+      'altertable login --service-account "CI Bot" --only analytics:ro',
+      'altertable login --svc "CI Bot" --readonly',
+    ],
   },
   args: {
     "control-plane-url": {
@@ -48,6 +65,24 @@ export const loginCommand = defineCommand({
       type: "boolean",
       description: "Store the login session in the current profile instead of switching profiles",
     },
+    "service-account": {
+      type: "string",
+      alias: "svc",
+      valueHint: "LABEL",
+      description:
+        "Create an environment-scoped service account with this label and store its access token instead of your login session",
+    },
+    only: {
+      type: "string",
+      valueHint: "CATALOG:MODE,...",
+      description:
+        "Request a service account limited to specific catalogs, e.g. analytics:ro,staging:rw (requires --service-account). The catalog access the server actually grants is reported on success.",
+    },
+    readonly: {
+      type: "boolean",
+      description:
+        "Request a service account with read-only access to every catalog (requires --service-account; cannot be combined with --only)",
+    },
   },
   run: ({ args, sink }) => runLogin(args as LoginArgs, sink),
 });
@@ -124,29 +159,27 @@ function selectLoginProfile(
   return { profileName: targetProfile, profileAction };
 }
 
-function storeLoginProfileMetadata(
-  whoami: WhoamiResponse,
-  args: LoginArgs,
-  controlPlane: string,
-): LoginProfileMetadata {
+function requireWhoamiEnvironment(whoami: WhoamiResponse): string {
   const environment = whoami.environment_slug;
 
   // OAuth login must always return an environment.
   if (!environment) {
     throw new Error("No environment returned from `whoami` post-login. Aborting.");
   }
+  return environment;
+}
 
+function storeLoginProfileMetadata(
+  whoami: WhoamiResponse,
+  args: LoginArgs,
+  controlPlane: string,
+): LoginProfileMetadata {
+  const environment = requireWhoamiEnvironment(whoami);
   const { profileName, profileAction } = selectLoginProfile(
     whoami,
     environment,
     Boolean(args["replace-profile"]),
   );
-  if (args["data-plane-url"]) {
-    assertAllowedApiBase(args["data-plane-url"], {
-      allowInsecureHttp: Boolean(args["allow-insecure-http"]),
-    });
-  }
-
   updateProfile(profileName, {
     environment,
     organizationSlug: whoami.organization?.slug,
@@ -167,6 +200,14 @@ type LoginArgs = {
   "control-plane-url"?: string;
   "allow-insecure-http"?: boolean;
   "replace-profile"?: boolean;
+  "service-account"?: string;
+  only?: string;
+  readonly?: boolean;
+};
+
+type ServiceAccountLoginRequest = {
+  label: string;
+  caveats?: ServiceAccountCaveats;
 };
 
 function resolveLoginEndpoints(
@@ -202,7 +243,187 @@ async function fetchLoginWhoami(
   return JSON.parse(body) as WhoamiResponse;
 }
 
+function applyLoginDataPlaneUrl(args: LoginArgs): void {
+  if (args["data-plane-url"]) {
+    assertAllowedApiBase(args["data-plane-url"], {
+      allowInsecureHttp: Boolean(args["allow-insecure-http"]),
+    });
+  }
+}
+
+function serviceAccountCaveats(args: LoginArgs): ServiceAccountCaveats | undefined {
+  if (args.readonly && args.only !== undefined) {
+    throw new ConfigurationError(
+      "--readonly cannot be combined with --only; --readonly already covers every catalog, and --only sets the mode per catalog.",
+    );
+  }
+  if (args.readonly) {
+    return "ro";
+  }
+  return args.only === undefined ? undefined : parseServiceAccountCaveats(args.only);
+}
+
+function parseServiceAccountLoginArgs(args: LoginArgs): ServiceAccountLoginRequest | undefined {
+  const label = args["service-account"];
+  const restrictingFlag = args.only !== undefined ? "--only" : args.readonly ? "--readonly" : "";
+  if (restrictingFlag && label === undefined) {
+    throw new ConfigurationError(`${restrictingFlag} requires --service-account.`);
+  }
+  if (label === undefined) {
+    return undefined;
+  }
+  if (args["replace-profile"]) {
+    throw new ConfigurationError(
+      "--service-account cannot be combined with --replace-profile; a service account always gets its own profile.",
+    );
+  }
+  if (label.trim().length === 0) {
+    throw new ConfigurationError("--service-account requires a non-empty label.");
+  }
+  const caveats = serviceAccountCaveats(args);
+  return {
+    label: label.trim(),
+    ...(caveats === undefined ? {} : { caveats }),
+  };
+}
+
+function activateDerivedProfile(profileName: string): void {
+  if (!profileExists(profileName)) {
+    createEmptyProfile(profileName);
+  }
+  setActiveProfile(profileName);
+  setCliContext({ ...getCliContext(), profile: profileName });
+  refreshCliRuntimeContext(getCliContext());
+}
+
+function catalogAccessMode(assignment: ServiceAccountRoleAssignment): "ro" | "rw" | null {
+  if (assignment.role === "catalog:writer") return "rw";
+  if (assignment.role === "catalog:reader") return "ro";
+  return null;
+}
+
+type CatalogAccessRow = { name: string; slug: string; access: "ro" | "rw" };
+
+/**
+ * Lists the catalogs the service account can reach, by name. Role assignments
+ * carry ids only, and assignments whose catalog is not in the lookup (or whose
+ * role is not a catalog role) are dropped rather than printed as raw ids.
+ */
+function summarizeCatalogAccess(
+  created: EnvironmentServiceAccountResponse,
+  catalogs: Map<string, EnvironmentCatalog>,
+): CatalogAccessRow[] {
+  const rows = new Map<string, CatalogAccessRow>();
+  for (const assignment of created.role_assignments ?? []) {
+    const access = catalogAccessMode(assignment);
+    const catalog = catalogs.get(assignment.resource_id);
+    if (!access || !catalog) continue;
+    const existing = rows.get(assignment.resource_id);
+    if (!existing || access === "rw") {
+      rows.set(assignment.resource_id, { ...catalog, access });
+    }
+  }
+  return [...rows.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function formatCatalogAccessTable(rows: CatalogAccessRow[]): string {
+  return renderDocumentText(
+    document(
+      section(
+        table({
+          rows,
+          columns: [
+            { header: "CATALOG", cell: (row) => [span(row.name, "strong")], flex: true },
+            { header: "SLUG", cell: (row) => [span(row.slug, "accent")] },
+            { header: "ACCESS", cell: (row) => [span(row.access, "subtle")] },
+          ],
+          emptyMessage: "",
+        }),
+      ),
+    ),
+  );
+}
+
+async function completeServiceAccountLogin(
+  oauthResponse: TokenResponse,
+  whoami: WhoamiResponse,
+  args: LoginArgs,
+  controlPlane: string,
+  managementApiBase: string,
+  request: ServiceAccountLoginRequest,
+  sink: OutputSink,
+): Promise<void> {
+  const environment = requireWhoamiEnvironment(whoami);
+  const organizationSlug = whoami.organization?.slug;
+  if (!organizationSlug) {
+    throw new ConfigurationError(
+      "Service account login needs an organization slug from whoami to name the profile.",
+    );
+  }
+
+  const created = await provisionEnvironmentServiceAccount({
+    managementApiBase,
+    accessToken: oauthResponse.access_token,
+    environment,
+    label: request.label,
+    ...(request.caveats ? { caveats: request.caveats } : {}),
+  });
+
+  const profileName = deriveServiceAccountProfileName(
+    organizationSlug,
+    environment,
+    created.service_account.slug,
+  );
+  activateDerivedProfile(profileName);
+  updateProfile(profileName, {
+    environment,
+    organizationSlug,
+    organizationName: whoami.organization?.name,
+    principalType: "ServiceAccount",
+    principalName: created.service_account.label,
+    principalSlug: created.service_account.slug,
+    ...(args["data-plane-url"] ? { dataPlane: args["data-plane-url"] } : {}),
+    controlPlane,
+  });
+
+  secretSet("oauth/access-token", created.service_oauth_token, profileName);
+
+  const catalogs = await fetchEnvironmentCatalogs({
+    managementApiBase,
+    accessToken: oauthResponse.access_token,
+    environment,
+  });
+  const catalogAccess = summarizeCatalogAccess(created, catalogs);
+  const lines = [
+    renderDisplayText([
+      span("✓", "success"),
+      span(
+        ` Created service account "${created.service_account.label}" — profile "${profileName}" is now active; environment "${environment}".`,
+      ),
+    ]),
+  ];
+  if (catalogAccess.length > 0) {
+    lines.push("", renderDisplayText([span("Catalog access", "subtle")]));
+    lines.push(formatCatalogAccessTable(catalogAccess));
+  }
+  if (request.caveats && (created.role_assignments ?? []).length === 0) {
+    lines.push(
+      renderDisplayText([
+        span(
+          "! The server reported no role assignments, so the requested restriction could not be confirmed. Check the service account's access before using this token.",
+          "warning",
+        ),
+      ]),
+    );
+  }
+  for (const line of lines) {
+    sink.writeHuman(line);
+  }
+}
+
 async function runLogin(args: LoginArgs, sink: OutputSink): Promise<void> {
+  const serviceAccountRequest = parseServiceAccountLoginArgs(args);
+  applyLoginDataPlaneUrl(args);
   assertNoEnvConfigMode();
   assertInteractiveLogin();
 
@@ -216,6 +437,19 @@ async function runLogin(args: LoginArgs, sink: OutputSink): Promise<void> {
   const oauthResponse = await runLoginFlow(sink, oauthBase);
   const whoami = await fetchLoginWhoami(oauthResponse, managementApiBase);
 
+  if (serviceAccountRequest) {
+    await completeServiceAccountLogin(
+      oauthResponse,
+      whoami,
+      args,
+      controlPlane,
+      managementApiBase,
+      serviceAccountRequest,
+      sink,
+    );
+    return;
+  }
+
   // Login succeeded and we can now persist whoami metadata and any control-plane override to the profile so later commands target it.
   const { environment, profileName, profileAction } = storeLoginProfileMetadata(
     whoami,
@@ -227,10 +461,10 @@ async function runLogin(args: LoginArgs, sink: OutputSink): Promise<void> {
 
   const identity = formatWhoamiPrincipalLine(whoami);
   const profileMessage = `${LOGIN_PROFILE_MESSAGES[profileAction]} "${profileName}"`;
-  sink.writeMetadata([
+  sink.writeHuman(
     renderDisplayText([
       span("✓", "success"),
       span(` Logged in (${identity}) — ${profileMessage}; environment "${environment}".`),
     ]),
-  ]);
+  );
 }
diff --git a/cli/src/commands/logout/index.test.ts b/cli/src/commands/logout/index.test.ts
index 2952a5e..4814e2b 100644
--- a/cli/src/commands/logout/index.test.ts
+++ b/cli/src/commands/logout/index.test.ts
@@ -1,8 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { configSet } from "@/lib/config.ts";
+import { configGet, configSet } from "@/lib/config.ts";
+import { getActiveProfileName, listProfileNames, setActiveProfile } from "@/lib/profile-store.ts";
 import { secretGet, secretSet } from "@/lib/secrets.ts";
 import { runCommandWithTestRuntime } from "@/test-utils/cli.ts";
 
@@ -33,6 +34,63 @@ describe("logout command", () => {
     expect(existsSync(join(testHome, "profiles"))).toBe(false);
   });
 
+  test("--except-current keeps the active profile and removes the others", async () => {
+    configSet("api_key_env", "production", "keeper");
+    secretSet("api-key", "atm_keeper", "keeper");
+    configSet("api_key_env", "staging", "other");
+    secretSet("api-key", "atm_other", "other");
+    setActiveProfile("keeper");
+
+    await runCommandWithTestRuntime(["logout", "--except-current"]);
+
+    expect(getActiveProfileName()).toBe("keeper");
+    expect(listProfileNames()).toEqual(["keeper"]);
+    expect(secretGet("api-key", "keeper")).toBe("atm_keeper");
+    expect(configGet("api_key_env", "keeper")).toBe("production");
+    expect(secretGet("api-key", "other")).toBe("");
+  });
+
+  // secretGet returns "" for any unknown profile, so assert on the store itself:
+  // a logout that only unlinked directories would still pass the check above.
+  test("--except-current erases the removed profiles' secrets from the store", async () => {
+    secretSet("api-key", "atm_keeper", "keeper");
+    secretSet("api-key", "atm_other", "other");
+    secretSet("oauth/access-token", "oauth_other", "other");
+    setActiveProfile("keeper");
+    expect(readFileSync(join(testHome, "credentials"), "utf8")).toContain("atm_other");
+
+    await runCommandWithTestRuntime(["logout", "--except-current"]);
+
+    const credentials = readFileSync(join(testHome, "credentials"), "utf8");
+    expect(credentials).not.toContain("atm_other");
+    expect(credentials).not.toContain("oauth_other");
+    expect(credentials).toContain("atm_keeper");
+  });
+
+  test("--except-current keeps the profile selected with --profile", async () => {
+    configSet("api_key_env", "production", "keeper");
+    secretSet("api-key", "atm_keeper", "keeper");
+    configSet("api_key_env", "staging", "other");
+    secretSet("api-key", "atm_other", "other");
+    setActiveProfile("other");
+
+    await runCommandWithTestRuntime(["--profile", "keeper", "logout", "--except-current"]);
+
+    expect(getActiveProfileName()).toBe("keeper");
+    expect(listProfileNames()).toEqual(["keeper"]);
+    expect(secretGet("api-key", "keeper")).toBe("atm_keeper");
+  });
+
+  test("--except-current succeeds when there is nothing else to clear", async () => {
+    configSet("api_key_env", "production", "default");
+    secretSet("api-key", "atm_stored", "default");
+
+    await runCommandWithTestRuntime(["logout", "--except-current"]);
+
+    expect(listProfileNames()).toEqual(["default"]);
+    expect(secretGet("api-key", "default")).toBe("atm_stored");
+  });
+
   test("refuses to run while environment configuration is active", async () => {
     configSet("api_key_env", "production", "default");
     secretSet("api-key", "atm_stored", "default");
diff --git a/cli/src/commands/logout/index.ts b/cli/src/commands/logout/index.ts
index 36b6eee..1bf0e61 100644
--- a/cli/src/commands/logout/index.ts
+++ b/cli/src/commands/logout/index.ts
@@ -7,10 +7,16 @@ export const logoutCommand = defineCommand({
     name: "logout",
     commandGroup: "platform",
     description: "Remove stored credentials and settings for all profiles.",
-    examples: ["altertable logout"],
+    examples: ["altertable logout", "altertable logout --except-current"],
   },
-  run({ sink }) {
+  args: {
+    "except-current": {
+      type: "boolean",
+      description: "Keep the current profile and remove every other profile",
+    },
+  },
+  run({ args, sink }) {
     assertNoEnvConfigMode();
-    configureRunClear(sink);
+    configureRunClear(sink, { exceptCurrent: Boolean(args["except-current"]) });
   },
 });
diff --git a/cli/src/lib/command-descriptor.ts b/cli/src/lib/command-descriptor.ts
index 7344175..ca153ff 100644
--- a/cli/src/lib/command-descriptor.ts
+++ b/cli/src/lib/command-descriptor.ts
@@ -55,6 +55,15 @@ function asStringArray(value: string | readonly string[] | undefined): string[]
   return value === undefined ? [] : [String(value)];
 }
 
+/**
+ * Single-character aliases are short flags (`-X`); longer ones are additional
+ * long flags (`--svc`). Every place that renders or parses an alias — the
+ * parser, help, generated docs, shell completions — must agree on this.
+ */
+export function aliasFlagToken(alias: string): string {
+  return alias.length === 1 ? `-${alias}` : `--${alias}`;
+}
+
 function normalizeCommandMetadata(metadata: CommandMetadata | undefined): ResolvedCommandMetadata {
   return {
     ...(metadata?.name ? { name: String(metadata.name) } : {}),
diff --git a/cli/src/lib/command-parser.ts b/cli/src/lib/command-parser.ts
index c5d32b5..7fbb74e 100644
--- a/cli/src/lib/command-parser.ts
+++ b/cli/src/lib/command-parser.ts
@@ -7,6 +7,7 @@ import {
   type CommandMetadata,
   type CommandRunResult,
 } from "@/lib/command.ts";
+import { aliasFlagToken } from "@/lib/command-descriptor.ts";
 import { createExecutionContext, type ExecutionContext } from "@/lib/execution-context.ts";
 import { EXIT_SUCCESS } from "@/lib/errors.ts";
 import { getCliRuntime } from "@/lib/runtime.ts";
@@ -93,7 +94,7 @@ function optionBindings(commandArguments: CommandArguments): Map<string, OptionB
     const binding = { name, argument };
     bindings.set(`--${name}`, binding);
     for (const alias of stringList(argument.alias)) {
-      bindings.set(`-${alias}`, binding);
+      bindings.set(aliasFlagToken(alias), binding);
     }
   }
   return bindings;
diff --git a/cli/src/lib/command.test.ts b/cli/src/lib/command.test.ts
index 8becf68..368db57 100644
--- a/cli/src/lib/command.test.ts
+++ b/cli/src/lib/command.test.ts
@@ -125,6 +125,38 @@ describe("command composition", () => {
     }
   });
 
+  test("binds single-character aliases as short flags and longer ones as long flags", async () => {
+    const runtime = createCliRuntime({ debug: false, json: false, agent: false });
+    const received: string[] = [];
+    const root = defineCommand({
+      subcommands: {
+        leaf: defineCommand({
+          args: {
+            "service-account": { type: "string", alias: "svc" },
+            columns: { type: "string", alias: "c" },
+          },
+          run({ args }) {
+            received.push(`${String(args["service-account"])}/${String(args.columns)}`);
+          },
+        }),
+      },
+    });
+
+    for (const rawArgs of [
+      ["leaf", "--service-account", "bot", "--columns", "a"],
+      ["leaf", "--svc", "bot", "-c", "a"],
+      ["leaf", "--svc=bot", "-c=a"],
+    ]) {
+      await runWithCliRuntime(runtime, () => executeCommand(root, rawArgs));
+    }
+
+    expect(received).toEqual(["bot/a", "bot/a", "bot/a"]);
+    // A long alias is not also bound as a single-dash flag.
+    expect(
+      runWithCliRuntime(runtime, () => executeCommand(root, ["leaf", "-svc", "bot"])),
+    ).rejects.toThrow("Unknown option -svc");
+  });
+
   test("accepts an option-like value when it is explicit", async () => {
     const runtime = createCliRuntime({ debug: false, json: false, agent: false });
     let received = "";
diff --git a/cli/src/lib/errors.ts b/cli/src/lib/errors.ts
index 1add3f0..3cff872 100644
--- a/cli/src/lib/errors.ts
+++ b/cli/src/lib/errors.ts
@@ -103,10 +103,12 @@ export class HttpError extends CliError {
     exitCode?: number;
     authPlane?: AuthPlane;
     retryAfterHeader?: string | null;
+    messageOverride?: string;
+    detailsOverride?: string;
   }) {
     super(`Request failed with status ${options.status}.`, {
       exitCode: options.exitCode ?? httpStatusExitCode(options.status),
-      details: options.parsedDetail,
+      details: options.detailsOverride ?? options.parsedDetail,
     });
     this.name = "HttpError";
     this.status = options.status;
@@ -115,7 +117,7 @@ export class HttpError extends CliError {
     this.url = options.url;
     this.parsedDetail = options.parsedDetail;
     this.retryAfterHeader = options.retryAfterHeader;
-    this.message = httpStatusMessage(options.status, options.authPlane);
+    this.message = options.messageOverride ?? httpStatusMessage(options.status, options.authPlane);
   }
 }
 
diff --git a/cli/src/lib/lakehouse-provision.test.ts b/cli/src/lib/lakehouse-provision.test.ts
index ef41013..3dceeb7 100644
--- a/cli/src/lib/lakehouse-provision.test.ts
+++ b/cli/src/lib/lakehouse-provision.test.ts
@@ -50,13 +50,16 @@ afterEach(() => {
   delete process.env.ALTERTABLE_HTTP_LOG;
 });
 
-function writeMocks(credentialBody: string = CREDENTIAL_BODY): void {
+function writeMocks(
+  credentialBody: string = CREDENTIAL_BODY,
+  options: { whoamiBody?: string; credentialUrlPattern?: string } = {},
+): void {
   writeFileSync(
     mockFile,
     JSON.stringify([
-      { urlPattern: "/whoami", method: "GET", body: WHOAMI_BODY },
+      { urlPattern: "/whoami", method: "GET", body: options.whoamiBody ?? WHOAMI_BODY },
       {
-        urlPattern: "/users/user-1/environments/env-1/credentials",
+        urlPattern: options.credentialUrlPattern ?? "/users/user-1/environments/env-1/credentials",
         method: "POST",
         body: credentialBody,
       },
@@ -102,6 +105,37 @@ describe("lakehouse credential auto-provisioning", () => {
     expect(logContent).toContain(`"label":"${USER_AGENT}"`);
   });
 
+  test("provisions through /service_accounts for a service account principal", async () => {
+    writeMocks(CREDENTIAL_BODY, {
+      whoamiBody: JSON.stringify({
+        principal: { id: "svc-1", type: "ServiceAccount", name: "CI Bot" },
+      }),
+      credentialUrlPattern: "/service_accounts/svc-1/environments/env-1/credentials",
+    });
+
+    const response = await sendLakehouseRequest();
+
+    expect(response).toBe("ok");
+    expect(readFileSync(logFile, "utf8")).toContain(
+      "URL=https://app.example.com/rest/v1/service_accounts/svc-1/environments/env-1/credentials",
+    );
+  });
+
+  // A principal type like "constructor" resolves to a truthy Object.prototype
+  // member under a bare lookup, which would build a nonsense credentials URL.
+  test("rejects a principal type that only exists on the object prototype", async () => {
+    writeMocks(CREDENTIAL_BODY, {
+      whoamiBody: JSON.stringify({
+        principal: { id: "weird-1", type: "constructor", name: "Weird" },
+      }),
+    });
+
+    await expectRejection(
+      sendLakehouseRequest(),
+      "Cannot auto-create lakehouse credentials for this identity",
+    );
+  });
+
   test("re-provisions when the stored credential is expired", async () => {
     writeMocks();
     secretSet(
diff --git a/cli/src/lib/lakehouse-provision.ts b/cli/src/lib/lakehouse-provision.ts
index 406346d..ec8d8c7 100644
--- a/cli/src/lib/lakehouse-provision.ts
+++ b/cli/src/lib/lakehouse-provision.ts
@@ -21,6 +21,21 @@ import { USER_AGENT } from "@/version.ts";
 
 const CREDENTIAL_LABEL = USER_AGENT;
 const CREDENTIAL_TTL_MS = 2 * 60 * 60 * 1000;
+const PRINCIPAL_CREDENTIAL_COLLECTIONS: Record<string, string> = {
+  User: "users",
+  ServiceAccount: "service_accounts",
+};
+
+// hasOwn, not a bare lookup: `principal.type` is server-supplied, and keys like
+// "constructor" would otherwise resolve to a truthy Object.prototype member.
+function principalCredentialCollection(principalType: string | undefined): string | undefined {
+  if (
+    principalType === undefined ||
+    !Object.hasOwn(PRINCIPAL_CREDENTIAL_COLLECTIONS, principalType)
+  )
+    return undefined;
+  return PRINCIPAL_CREDENTIAL_COLLECTIONS[principalType];
+}
 
 export function hasManagementCredentials(profileName: string): boolean {
   // optionalAuth only swallows ConfigurationError ("not configured");
@@ -78,9 +93,10 @@ export async function provisionLakehouseCredential(context: ExecutionContext): P
     "/whoami",
   )) as components["schemas"]["WhoamiResponse"];
   const principal = whoami.principal;
-  if (!principal?.id || principal.type !== "User") {
+  const principalCollection = principalCredentialCollection(principal?.type);
+  if (!principal?.id || !principalCollection) {
     throw new ConfigurationError(
-      "Cannot auto-create lakehouse credentials for a non-user identity. Run 'altertable profile configure'.",
+      "Cannot auto-create lakehouse credentials for this identity. Run 'altertable profile configure'.",
     );
   }
 
@@ -88,7 +104,7 @@ export async function provisionLakehouseCredential(context: ExecutionContext): P
   const created = (await sendManagementRequest(
     context,
     "POST",
-    `/users/${principal.id}/environments/${env}/credentials`,
+    `/${principalCollection}/${principal.id}/environments/${env}/credentials`,
     JSON.stringify({ label: CREDENTIAL_LABEL, expires_at: expiresAt }),
   )) as components["schemas"]["CreateCredentialResponse"];
 
diff --git a/cli/src/lib/oauth-flow.ts b/cli/src/lib/oauth-flow.ts
index e037161..4ccef27 100644
--- a/cli/src/lib/oauth-flow.ts
+++ b/cli/src/lib/oauth-flow.ts
@@ -259,13 +259,15 @@ export async function runLoginFlow(sink: OutputSink, oauthBase: string): Promise
       { redirectUri: server.redirectUri, challenge, state },
       oauthBase,
     );
-    sink.writeMetadata([renderDisplayText([span("Opening your browser to sign in…", "subtle")])]);
-    sink.writeMetadata([
+    // Login is interactive-only (no --json, no pipes), so its progress belongs on
+    // stdout; stderr stays reserved for failures.
+    sink.writeHuman(renderDisplayText([span("Opening your browser to sign in…", "subtle")]));
+    sink.writeHuman(
       renderDisplayText([
         span("If it doesn't open, visit: ", "subtle"),
         span(authorizeUrl, "accent", authorizeUrl),
       ]),
-    ]);
+    );
     openBrowser(authorizeUrl);
     const code = await server.waitForCode();
     return await exchangeCode({ code, redirectUri: server.redirectUri, verifier }, oauthBase);
diff --git a/cli/src/lib/profile-configure-core.test.ts b/cli/src/lib/profile-configure-core.test.ts
index c58a6cb..24a5eab 100644
--- a/cli/src/lib/profile-configure-core.test.ts
+++ b/cli/src/lib/profile-configure-core.test.ts
@@ -65,15 +65,15 @@ describe("configureRunSet", () => {
   });
 
   test("warns when a password is passed on argv", async () => {
-    const metadata: string[] = [];
+    const printed: string[] = [];
     const runtime = createCliRuntime({ debug: false, json: false, agent: false });
-    runtime.output.writeMetadata = (lines) => metadata.push(...lines);
+    runtime.output.writeHuman = (line) => printed.push(line);
 
     await runWithCliRuntime(runtime, () =>
       configureRunSet({ user: "alice", password: "test-password-value" }),
     );
 
-    expect(metadata.some((line) => line.includes("--password-stdin"))).toBe(true);
+    expect(printed.some((line) => line.includes("--password-stdin"))).toBe(true);
   });
 });
 
diff --git a/cli/src/lib/profile-configure-core.ts b/cli/src/lib/profile-configure-core.ts
index a66c21f..abf5c3c 100644
--- a/cli/src/lib/profile-configure-core.ts
+++ b/cli/src/lib/profile-configure-core.ts
@@ -1,13 +1,17 @@
 import { unlinkSync, rmSync, existsSync } from "node:fs";
 import { configFile, configGet, configSet, credentialsFile, kvUnset } from "@/lib/config.ts";
 import { CliError, ConfigurationError } from "@/lib/errors.ts";
-import { deriveProfileName, listProfiles } from "@/lib/profile/model.ts";
+import { deleteProfile, deriveProfileName, listProfiles } from "@/lib/profile/model.ts";
 import {
   ensureProfileExists,
+  getActiveProfileName,
+  listProfileNames,
   profileConfigFile,
   profilesDir,
   resolveWorkingProfile,
+  setActiveProfile,
 } from "@/lib/profile-store.ts";
+import { pluralizeLabel } from "@/lib/pluralize.ts";
 import { getCliContext } from "@/context.ts";
 import { secretDelete, secretSet } from "@/lib/secrets.ts";
 import { assertAllowedApiBase } from "@/lib/url-policy.ts";
@@ -108,7 +112,7 @@ export async function configureRunSet(
       Boolean(options.password) && !options.passwordStdin && !options.interactive;
     const apiKeyFromArgv = Boolean(options.apiKey) && !options.apiKeyStdin && !options.interactive;
     if (passwordFromArgv || apiKeyFromArgv) {
-      sink.writeMetadata([renderDisplayText([span(ARGV_SECRET_WARNING, "subtle")])]);
+      sink.writeHuman(renderDisplayText([span(ARGV_SECRET_WARNING, "subtle")]));
     }
 
     const hasAnyInput =
@@ -201,25 +205,55 @@ export async function configureRunSet(
     }
 
     if (hasApiKey) {
-      sink.writeMetadata([
+      sink.writeHuman(
         renderDisplayText([span(`Saved management API key for environment ${env}.`, "subtle")]),
-      ]);
+      );
     } else if (hasLakehouseBasicToken) {
-      sink.writeMetadata([renderDisplayText([span("Saved lakehouse Basic token.", "subtle")])]);
+      sink.writeHuman(renderDisplayText([span("Saved lakehouse Basic token.", "subtle")]));
     } else if (hasLakehouseCredentials) {
-      sink.writeMetadata([
+      sink.writeHuman(
         renderDisplayText([span(`Saved lakehouse credentials for user ${user}.`, "subtle")]),
-      ]);
+      );
     } else if (dataPlaneUrl) {
-      sink.writeMetadata([
-        renderDisplayText([span(`Saved data plane URL ${dataPlaneUrl}.`, "subtle")]),
-      ]);
+      sink.writeHuman(renderDisplayText([span(`Saved data plane URL ${dataPlaneUrl}.`, "subtle")]));
     }
     markCurrentProfileUpdated(profileName);
   });
 }
 
-export function configureRunClear(sink: OutputSink = getOutputSink()): void {
+export type ConfigureClearOptions = {
+  exceptCurrent?: boolean;
+};
+
+function configureClearExceptCurrent(sink: OutputSink): void {
+  const keptProfile = resolveWorkingProfile(getCliContext().profile);
+  ensureProfileExists(keptProfile);
+  if (getActiveProfileName() !== keptProfile) {
+    setActiveProfile(keptProfile);
+  }
+
+  const removed = listProfileNames().filter((name) => name !== keptProfile);
+  for (const name of removed) {
+    deleteProfile(name);
+  }
+
+  getCliRuntime().session = undefined;
+  const summary =
+    removed.length === 0
+      ? `No other profiles to clear; kept "${keptProfile}".`
+      : `Cleared ${pluralizeLabel(removed.length, "profile")}; kept "${keptProfile}".`;
+  sink.writeHuman(renderDisplayText([span(summary, "subtle")]));
+}
+
+export function configureRunClear(
+  sink: OutputSink = getOutputSink(),
+  options: ConfigureClearOptions = {},
+): void {
+  if (options.exceptCurrent) {
+    configureClearExceptCurrent(sink);
+    return;
+  }
+
   const profiles = existsSync(profilesDir()) ? listProfiles() : [];
   for (const profile of profiles) {
     configureClearLakehouseCredentials(profile.name);
@@ -249,7 +283,5 @@ export function configureRunClear(sink: OutputSink = getOutputSink()): void {
     });
   }
   getCliRuntime().session = undefined;
-  sink.writeMetadata([
-    renderDisplayText([span("Cleared all altertable configuration.", "subtle")]),
-  ]);
+  sink.writeHuman(renderDisplayText([span("Cleared all altertable configuration.", "subtle")]));
 }
diff --git a/cli/src/lib/profile/model.test.ts b/cli/src/lib/profile/model.test.ts
index dc549ab..ac5f04e 100644
--- a/cli/src/lib/profile/model.test.ts
+++ b/cli/src/lib/profile/model.test.ts
@@ -10,6 +10,7 @@ import {
   createEmptyProfile,
   deleteProfile,
   deriveProfileName,
+  deriveServiceAccountProfileName,
   inspectProfile,
   listProfiles,
   renameProfile,
@@ -48,6 +49,30 @@ describe("profile model", () => {
     expect(deriveProfileName("acme", "prod/eu")).toBe("acme_prod-eu");
   });
 
+  test("derives service account profile names from org, environment, and slug", () => {
+    expect(deriveServiceAccountProfileName("Altertable", "production", "my-service")).toBe(
+      "altertable_production_my-service",
+    );
+  });
+
+  test("rejects service account profile names with an unusable part", () => {
+    expect(() => deriveServiceAccountProfileName("altertable", "production", "")).toThrow(
+      ConfigurationError,
+    );
+    expect(() => deriveServiceAccountProfileName("altertable", "production", "---")).toThrow(
+      ConfigurationError,
+    );
+    expect(() => deriveServiceAccountProfileName("", "production", "my-service")).toThrow(
+      ConfigurationError,
+    );
+  });
+
+  test("normalizes a server-supplied slug instead of letting it escape the profiles directory", () => {
+    expect(deriveServiceAccountProfileName("altertable", "production", "../../etc")).toBe(
+      "altertable_production_etc",
+    );
+  });
+
   test("creates and updates profile metadata without credentials", () => {
     createEmptyProfile("acme_prod");
     const profile = updateProfile("acme_prod", {
diff --git a/cli/src/lib/profile/model.ts b/cli/src/lib/profile/model.ts
index 692994a..1f8340a 100644
--- a/cli/src/lib/profile/model.ts
+++ b/cli/src/lib/profile/model.ts
@@ -247,6 +247,24 @@ export function deriveProfileName(org: string, env: string): string {
   return profileName;
 }
 
+export function deriveServiceAccountProfileName(
+  org: string,
+  env: string,
+  serviceAccountSlug: string,
+): string {
+  const orgPart = normalizeProfileNamePart(org);
+  const envPart = normalizeProfileNamePart(env);
+  const slugPart = normalizeProfileNamePart(serviceAccountSlug);
+  if (!orgPart || !envPart || !slugPart) {
+    throw new ConfigurationError(
+      "Profile auto-naming requires non-empty organization, environment, and service account values.",
+    );
+  }
+  const profileName = `${orgPart}_${envPart}_${slugPart}`;
+  assertSafeProfileName(profileName);
+  return profileName;
+}
+
 function nowIso(): string {
   return new Date().toISOString();
 }
diff --git a/cli/src/lib/service-account-provision.test.ts b/cli/src/lib/service-account-provision.test.ts
new file mode 100644
index 0000000..270fdee
--- /dev/null
+++ b/cli/src/lib/service-account-provision.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { OPENAPI_OPERATIONS } from "@/generated/openapi-operations.ts";
+import { ConfigurationError } from "@/lib/errors.ts";
+import { parseServiceAccountCaveats } from "@/lib/service-account-provision.ts";
+
+// Fails the moment `bun run spec:refresh` picks the operation up, which is the
+// signal to drop the hand-written EnvironmentServiceAccountResponse envelope.
+test("the environment service account operation is still absent from the spec", () => {
+  const shipped = OPENAPI_OPERATIONS.some(
+    (operation) => operation.operationId === "createEnvironmentServiceAccount",
+  );
+  expect(shipped).toBe(false);
+});
+
+describe("parseServiceAccountCaveats", () => {
+  test("parses multiple catalog:mode entries", () => {
+    expect(parseServiceAccountCaveats("catalog1:ro,catalog2:rw")).toEqual({
+      catalog1: "ro",
+      catalog2: "rw",
+    });
+  });
+
+  test("parses a single entry", () => {
+    expect(parseServiceAccountCaveats("analytics:rw")).toEqual({ analytics: "rw" });
+  });
+
+  test("trims whitespace and lowercases the mode", () => {
+    expect(parseServiceAccountCaveats(" catalog1 : RO , catalog2: Rw ")).toEqual({
+      catalog1: "ro",
+      catalog2: "rw",
+    });
+  });
+
+  test("splits on the last colon so catalog names may contain colons", () => {
+    expect(parseServiceAccountCaveats("org:analytics:ro")).toEqual({ "org:analytics": "ro" });
+  });
+
+  test("rejects a mode other than ro or rw", () => {
+    expect(() => parseServiceAccountCaveats("catalog1:read")).toThrow(ConfigurationError);
+    expect(() => parseServiceAccountCaveats("catalog1:read")).toThrow("catalog1:read");
+  });
+
+  test("rejects an entry with no colon", () => {
+    expect(() => parseServiceAccountCaveats("catalog1")).toThrow(ConfigurationError);
+    expect(() => parseServiceAccountCaveats("catalog1")).toThrow("catalog1");
+  });
+
+  test("rejects an empty catalog name", () => {
+    expect(() => parseServiceAccountCaveats(":ro")).toThrow(ConfigurationError);
+    expect(() => parseServiceAccountCaveats(":ro")).toThrow(":ro");
+  });
+
+  test("rejects a duplicate catalog", () => {
+    expect(() => parseServiceAccountCaveats("catalog1:ro,catalog1:rw")).toThrow(ConfigurationError);
+    expect(() => parseServiceAccountCaveats("catalog1:ro,catalog1:rw")).toThrow("catalog1");
+  });
+});
diff --git a/cli/src/lib/service-account-provision.ts b/cli/src/lib/service-account-provision.ts
new file mode 100644
index 0000000..7ce8f1d
--- /dev/null
+++ b/cli/src/lib/service-account-provision.ts
@@ -0,0 +1,181 @@
+import type { components } from "@/generated/openapi-types.ts";
+import { ConfigurationError, HttpError } from "@/lib/errors.ts";
+import { httpSend } from "@/lib/http.ts";
+import { encodeManagementEndpoint } from "@/lib/management-endpoint.ts";
+import { parseApiJson } from "@/lib/parse-api-json.ts";
+
+export type ServiceAccountAccessMode = "ro" | "rw";
+
+// A bare mode applies to every catalog; the map form restricts per catalog.
+export type ServiceAccountCaveats =
+  | ServiceAccountAccessMode
+  | Record<string, ServiceAccountAccessMode>;
+
+export type ServiceAccountRoleAssignment = components["schemas"]["RoleAssignment"];
+
+// Only the envelope is hand-written: operationId createEnvironmentServiceAccount
+// is not in `@/generated/openapi-types.ts` yet. Drop this in favour of the
+// generated response type after `bun run spec:refresh`; the guard test in
+// service-account-provision.test.ts fails once the operation ships.
+export type EnvironmentServiceAccountResponse = components["schemas"]["ServiceAccountResponse"] & {
+  role_assignments: ServiceAccountRoleAssignment[];
+  service_oauth_token: string;
+};
+
+type ProvisionEnvironmentServiceAccountOptions = {
+  managementApiBase: string;
+  accessToken: string;
+  environment: string;
+  label: string;
+  caveats?: ServiceAccountCaveats;
+};
+
+type EnvironmentCatalogLookupOptions = {
+  managementApiBase: string;
+  accessToken: string;
+  environment: string;
+};
+
+type CatalogIdentity = { id?: string; slug?: string; name?: string };
+
+export type EnvironmentCatalog = { name: string; slug: string };
+
+export function parseServiceAccountCaveats(
+  value: string,
+): Record<string, ServiceAccountAccessMode> {
+  const caveats: Record<string, ServiceAccountAccessMode> = {};
+  for (const rawEntry of value.split(",")) {
+    const entry = rawEntry.trim();
+    const separatorIndex = entry.lastIndexOf(":");
+    if (separatorIndex === -1) {
+      throw new ConfigurationError(
+        `Invalid --only entry "${entry}": expected catalog:ro or catalog:rw.`,
+      );
+    }
+
+    const catalog = entry.slice(0, separatorIndex).trim();
+    const mode = entry
+      .slice(separatorIndex + 1)
+      .trim()
+      .toLowerCase();
+    if (!catalog) {
+      throw new ConfigurationError(`Invalid --only entry "${entry}": catalog name is required.`);
+    }
+    if (mode !== "ro" && mode !== "rw") {
+      throw new ConfigurationError(`Invalid --only entry "${entry}": mode must be ro or rw.`);
+    }
+    if (caveats[catalog] !== undefined) {
+      throw new ConfigurationError(
+        `Invalid --only entry "${entry}": catalog "${catalog}" is duplicated.`,
+      );
+    }
+    caveats[catalog] = mode;
+  }
+  return caveats;
+}
+
+/**
+ * Re-raises an HTTP failure as a new error carrying the operation and the
+ * request line, so the caught error is left untouched for anything else
+ * holding it.
+ */
+function withServiceAccountRequestContext(error: unknown): unknown {
+  if (!(error instanceof HttpError)) {
+    return error;
+  }
+  const request = `${error.method} ${error.url}`;
+  return new HttpError({
+    status: error.status,
+    body: error.body,
+    method: error.method,
+    url: error.url,
+    parsedDetail: error.parsedDetail ?? request,
+    detailsOverride: error.details ? `${error.details}\n${request}` : request,
+    messageOverride: `Failed to create environment service account: ${error.message}`,
+    exitCode: error.exitCode,
+    retryAfterHeader: error.retryAfterHeader,
+  });
+}
+
+export async function provisionEnvironmentServiceAccount(
+  options: ProvisionEnvironmentServiceAccountOptions,
+): Promise<EnvironmentServiceAccountResponse> {
+  const requestBody: {
+    label: string;
+    with_service_oauth_token: true;
+    caveats?: ServiceAccountCaveats;
+  } = {
+    label: options.label,
+    with_service_oauth_token: true,
+  };
+  if (options.caveats) {
+    requestBody.caveats = options.caveats;
+  }
+
+  let response: string;
+  try {
+    response = await httpSend({
+      method: "POST",
+      url: `${options.managementApiBase}${encodeManagementEndpoint(`/environments/${options.environment}/service_accounts`)}`,
+      authHeader: `Authorization: Bearer ${options.accessToken}`,
+      body: JSON.stringify(requestBody),
+      contentType: "application/json",
+      authPlane: "management",
+    });
+  } catch (error) {
+    throw withServiceAccountRequestContext(error);
+  }
+  const created = parseApiJson(response) as EnvironmentServiceAccountResponse;
+
+  if (!created.service_oauth_token) {
+    throw new ConfigurationError(
+      "Service account creation response was missing a service OAuth token.",
+    );
+  }
+  if (!created.service_account?.slug) {
+    throw new ConfigurationError("Service account creation response was missing a slug.");
+  }
+
+  return created;
+}
+
+function collectCatalogs(
+  target: Map<string, EnvironmentCatalog>,
+  entries: CatalogIdentity[],
+): void {
+  for (const entry of entries) {
+    if (!entry.id || (!entry.name && !entry.slug)) {
+      continue;
+    }
+    target.set(entry.id, {
+      name: entry.name ?? entry.slug ?? "",
+      slug: entry.slug ?? "",
+    });
+  }
+}
+
+/**
+ * Maps catalog ids to their names so role assignments can be reported with
+ * catalog names instead of raw ids. Best effort: the service account already
+ * exists by the time this runs, so a failed lookup must not fail the login.
+ */
+export async function fetchEnvironmentCatalogs(
+  options: EnvironmentCatalogLookupOptions,
+): Promise<Map<string, EnvironmentCatalog>> {
+  const catalogs = new Map<string, EnvironmentCatalog>();
+  for (const kind of ["databases", "connections"] as const) {
+    try {
+      const response = await httpSend({
+        method: "GET",
+        url: `${options.managementApiBase}${encodeManagementEndpoint(`/environments/${options.environment}/${kind}`)}`,
+        authHeader: `Authorization: Bearer ${options.accessToken}`,
+        authPlane: "management",
+      });
+      const parsed = parseApiJson(response) as Record<string, CatalogIdentity[] | undefined>;
+      collectCatalogs(catalogs, parsed[kind] ?? []);
+    } catch {
+      continue;
+    }
+  }
+  return catalogs;
+}
diff --git a/cli/src/lib/usage.ts b/cli/src/lib/usage.ts
index 27ded46..2f2e03d 100644
--- a/cli/src/lib/usage.ts
+++ b/cli/src/lib/usage.ts
@@ -1,6 +1,7 @@
 import type { Command } from "@/lib/command.ts";
 import { ALTERTABLE_COMMAND_GROUPS, type AltertableCommandGroup } from "@/lib/command.ts";
 import {
+  aliasFlagToken,
   resolveCommandDescriptor,
   visibleCommandDescriptors,
   type CommandArgumentDescriptor,
@@ -165,7 +166,7 @@ function valueHint(argument: CommandArgumentDescriptor): string | undefined {
 }
 
 function flagLabel(argument: CommandArgumentDescriptor): string {
-  const aliases = argument.aliases.map((alias) => `-${alias}`);
+  const aliases = argument.aliases.map(aliasFlagToken);
   const longFlag = `--${argument.name}`;
   const hint = valueHint(argument);
   const value = hint ? ` <${hint}>` : "";

From 57720be99618c0a6f4141e97b5b508e4e7e53a1a Mon Sep 17 00:00:00 2001
From: Leo-Paul Goffic <leo.goffic@altertable.ai>
Date: Thu, 17 Sep 2026 12:44:37 +0200
Subject: [PATCH 2/2] PR feedback

---
 COMMANDS.md                                   |   9 +-
 cli-reference.json                            |  24 +-
 cli/openapi/openapi.yaml                      | 854 ++++++++++++++----
 .../commands/api/lib/http-conformance.test.ts |   2 +-
 cli/src/commands/login/index.test.ts          |  67 +-
 cli/src/commands/login/index.ts               |  81 +-
 cli/src/generated/openapi-operations.ts       |   7 +-
 cli/src/generated/openapi-types.ts            | 523 ++++++++---
 cli/src/lib/command-descriptor.ts             |   2 +-
 cli/src/lib/errors.ts                         |  11 +
 cli/src/lib/service-account-provision.test.ts |  44 +-
 cli/src/lib/service-account-provision.ts      |  75 +-
 12 files changed, 1227 insertions(+), 472 deletions(-)

diff --git a/COMMANDS.md b/COMMANDS.md
index fed2473..1cf14ff 100644
--- a/COMMANDS.md
+++ b/COMMANDS.md
@@ -39,17 +39,16 @@ altertable login [options]
 | `--data-plane-url <DATA-PLANE-URL>` | Data-plane base URL saved to the profile only on successful login. Default: https://api.altertable.ai |
 | `--allow-insecure-http` | Allow http:// URLs other than localhost for --control-plane-url (for development only) |
 | `--replace-profile` | Store the login session in the current profile instead of switching profiles |
-| `--svc, --service-account <LABEL>` | Create an environment-scoped service account with this label and store its access token instead of your login session |
-| `--only <CATALOG:MODE,...>` | Request a service account limited to specific catalogs, e.g. analytics:ro,staging:rw (requires --service-account). The catalog access the server actually grants is reported on success. |
-| `--readonly` | Request a service account with read-only access to every catalog (requires --service-account; cannot be combined with --only) |
+| `--service-account <LABEL>` | Create an environment-scoped service account with this label and store its access token instead of your login session |
+| `--scope <MODE\|CATALOG:MODE,...>` | Request a service account limited to `ro` or `rw` on every catalog, or to specific catalogs, e.g. `analytics:ro,staging:rw` (requires --service-account). The catalog access the server actually grants is reported on success. |
 
 **Examples**
 
 ```bash
 altertable login
 altertable login --replace-profile
-altertable login --service-account "CI Bot" --only analytics:ro
-altertable login --svc "CI Bot" --readonly
+altertable login --service-account "CI Bot" --scope analytics:ro
+altertable login --service-account "CI Bot" --scope ro
 ```
 
 ### `altertable logout`
diff --git a/cli-reference.json b/cli-reference.json
index 83d7715..44513b0 100644
--- a/cli-reference.json
+++ b/cli-reference.json
@@ -166,9 +166,7 @@
             },
             {
               "name": "service-account",
-              "aliases": [
-                "svc"
-              ],
+              "aliases": [],
               "type": "string",
               "description": "Create an environment-scoped service account with this label and store its access token instead of your login session",
               "required": false,
@@ -178,32 +176,22 @@
               "valueHint": "LABEL"
             },
             {
-              "name": "only",
+              "name": "scope",
               "aliases": [],
               "type": "string",
-              "description": "Request a service account limited to specific catalogs, e.g. analytics:ro,staging:rw (requires --service-account). The catalog access the server actually grants is reported on success.",
+              "description": "Request a service account limited to `ro` or `rw` on every catalog, or to specific catalogs, e.g. `analytics:ro,staging:rw` (requires --service-account). The catalog access the server actually grants is reported on success.",
               "required": false,
               "repeatable": false,
               "scope": "command",
               "values": [],
-              "valueHint": "CATALOG:MODE,..."
-            },
-            {
-              "name": "readonly",
-              "aliases": [],
-              "type": "boolean",
-              "description": "Request a service account with read-only access to every catalog (requires --service-account; cannot be combined with --only)",
-              "required": false,
-              "repeatable": false,
-              "scope": "command",
-              "values": []
+              "valueHint": "MODE|CATALOG:MODE,..."
             }
           ],
           "examples": [
             "altertable login",
             "altertable login --replace-profile",
-            "altertable login --service-account \"CI Bot\" --only analytics:ro",
-            "altertable login --svc \"CI Bot\" --readonly"
+            "altertable login --service-account \"CI Bot\" --scope analytics:ro",
+            "altertable login --service-account \"CI Bot\" --scope ro"
           ],
           "subcommands": []
         },
diff --git a/cli/openapi/openapi.yaml b/cli/openapi/openapi.yaml
index 6f06500..71c2dd1 100644
--- a/cli/openapi/openapi.yaml
+++ b/cli/openapi/openapi.yaml
@@ -51,9 +51,13 @@ components:
         slug:
           type: string
         region:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         endpoint:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         provider:
           type: string
           enum:
@@ -109,22 +113,25 @@ components:
           type: string
           enum:
             - postgres
-            - bigquery
+            - big_query
             - redshift
             - snowflake
             - mariadb
             - mysql
             - supabase
-            - buckettables
-            - icebergtables
-            - r2catalog
-            - s3tables
+            - bucket_tables
+            - iceberg_tables
+            - r2_catalog
+            - s3_tables
             - glue
             - duckdb
+            - mongo
         read_only:
           type: boolean
         description:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         labels:
           type: array
           items:
@@ -139,6 +146,11 @@ components:
         updated_at:
           type: string
           format: date-time
+        config:
+          anyOf:
+            - type: object
+              additionalProperties: {}
+            - type: "null"
       required:
         - id
         - name
@@ -154,94 +166,212 @@ components:
       type: object
       properties:
         dataset:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         project_id_override:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
     ConnectionBucketTablesConfig:
       type: object
       properties:
         bucket_id:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         file_format:
-          type: string
-          enum:
-            - parquet
-            - csv
-            - json
+          anyOf:
+            - type: string
+              enum:
+                - parquet
+                - csv
+                - json
+            - type: "null"
         assume_immutable:
-          type: boolean
-        tables: {}
+          anyOf:
+            - type: boolean
+            - type: "null"
+        tables:
+          type: object
+          additionalProperties:
+            type: string
       required:
         - tables
     ConnectionDuckDBConfig:
       type: object
       properties:
         bucket_id:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         path:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
     ConnectionGlueConfig:
       type: object
       properties:
         warehouse:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         default_region:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         role_arn:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
     ConnectionIcebergTablesConfig:
       type: object
       properties:
         bucket_id:
-          type: string
-        tables: {}
+          anyOf:
+            - type: string
+            - type: "null"
+        tables:
+          type: object
+          additionalProperties:
+            type: string
       required:
         - tables
+    ConnectionMongoConfig:
+      type: object
+      properties:
+        host:
+          anyOf:
+            - type: string
+            - type: "null"
+        port:
+          anyOf:
+            - type: integer
+            - type: "null"
+        database:
+          anyOf:
+            - type: string
+            - type: "null"
+        username:
+          anyOf:
+            - type: string
+            - type: "null"
+        password:
+          anyOf:
+            - type: string
+            - type: "null"
+        ssh_tunnel:
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionSshTunnel"
+            - type: "null"
+        srv:
+          anyOf:
+            - type: boolean
+            - type: "null"
+        tls:
+          anyOf:
+            - type: boolean
+            - type: "null"
+        auth_source:
+          anyOf:
+            - type: string
+            - type: "null"
     ConnectionMysqlConfig:
       type: object
       properties:
         host:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         port:
-          type: integer
+          anyOf:
+            - type: integer
+            - type: "null"
         database:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         username:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         password:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         schema:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         ssh_tunnel:
-          "$ref": "#/components/schemas/ConnectionSshTunnel"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionSshTunnel"
+            - type: "null"
+        ssl_mode:
+          anyOf:
+            - type: string
+              enum:
+                - disabled
+                - preferred
+                - verify_identity
+            - type: "null"
     ConnectionPostgresConfig:
       type: object
       properties:
         host:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         port:
-          type: integer
+          anyOf:
+            - type: integer
+            - type: "null"
         database:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         username:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         password:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         schema:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         ssh_tunnel:
-          "$ref": "#/components/schemas/ConnectionSshTunnel"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionSshTunnel"
+            - type: "null"
         sslmode:
-          type: string
+          anyOf:
+            - type: string
+              enum:
+                - disable
+                - allow
+                - prefer
+                - require
+                - verify-ca
+                - verify-full
+            - type: "null"
     ConnectionR2CatalogConfig:
       type: object
       properties:
         warehouse:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         endpoint:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         token:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
     ConnectionResponse:
       type: object
       properties:
@@ -253,52 +383,90 @@ components:
       type: object
       properties:
         warehouse:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         default_region:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         aws_access_key_id:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         aws_secret_access_key:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
     ConnectionSnowflakeConfig:
       type: object
       properties:
         account_url:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         warehouse:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         username:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         password:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         database:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
     ConnectionSshTunnel:
       type: object
       properties:
         bastion_host:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         bastion_port:
-          type: integer
+          anyOf:
+            - type: integer
+            - type: "null"
         bastion_username:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
     ConnectionStandardConfig:
       type: object
       properties:
         host:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         port:
-          type: integer
+          anyOf:
+            - type: integer
+            - type: "null"
         database:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         username:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         password:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         schema:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         ssh_tunnel:
-          "$ref": "#/components/schemas/ConnectionSshTunnel"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionSshTunnel"
+            - type: "null"
     ConnectionsListResponse:
       type: object
       properties:
@@ -318,9 +486,13 @@ components:
         secret_access_key:
           type: string
         region:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         endpoint:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
       required:
         - name
         - access_key_id
@@ -334,48 +506,81 @@ components:
           type: string
           enum:
             - postgres
-            - bigquery
+            - big_query
             - redshift
             - snowflake
             - mariadb
             - mysql
             - supabase
-            - buckettables
-            - icebergtables
-            - r2catalog
-            - s3tables
+            - bucket_tables
+            - iceberg_tables
+            - r2_catalog
+            - s3_tables
             - glue
             - duckdb
+            - mongo
         read_only:
-          type: boolean
+          anyOf:
+            - type: boolean
+            - type: "null"
         label_ids:
-          type: array
-          items:
-            type: string
+          anyOf:
+            - type: array
+              items:
+                type: string
+            - type: "null"
         description:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         standard_config:
-          "$ref": "#/components/schemas/ConnectionStandardConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionStandardConfig"
+            - type: "null"
         mysql_config:
-          "$ref": "#/components/schemas/ConnectionMysqlConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionMysqlConfig"
+            - type: "null"
         postgres_config:
-          "$ref": "#/components/schemas/ConnectionPostgresConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionPostgresConfig"
+            - type: "null"
+        mongo_config:
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionMongoConfig"
+            - type: "null"
         bigquery_config:
-          "$ref": "#/components/schemas/ConnectionBigQueryConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionBigQueryConfig"
+            - type: "null"
         snowflake_config:
-          "$ref": "#/components/schemas/ConnectionSnowflakeConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionSnowflakeConfig"
+            - type: "null"
         bucket_tables_config:
-          "$ref": "#/components/schemas/ConnectionBucketTablesConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionBucketTablesConfig"
+            - type: "null"
         iceberg_tables_config:
-          "$ref": "#/components/schemas/ConnectionIcebergTablesConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionIcebergTablesConfig"
+            - type: "null"
         duckdb_config:
-          "$ref": "#/components/schemas/ConnectionDuckDBConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionDuckDBConfig"
+            - type: "null"
         r2_catalog_config:
-          "$ref": "#/components/schemas/ConnectionR2CatalogConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionR2CatalogConfig"
+            - type: "null"
         s3_tables_config:
-          "$ref": "#/components/schemas/ConnectionS3TablesConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionS3TablesConfig"
+            - type: "null"
         glue_config:
-          "$ref": "#/components/schemas/ConnectionGlueConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionGlueConfig"
+            - type: "null"
       required:
         - name
         - engine
@@ -383,10 +588,14 @@ components:
       type: object
       properties:
         label:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         expires_at:
-          type: string
-          format: date-time
+          anyOf:
+            - type: string
+              format: date-time
+            - type: "null"
     CreateCredentialResponse:
       type: object
       properties:
@@ -403,17 +612,27 @@ components:
         name:
           type: string
         bucket_id:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         read_only:
-          type: boolean
+          anyOf:
+            - type: boolean
+            - type: "null"
         label_ids:
-          type: array
-          items:
-            type: string
+          anyOf:
+            - type: array
+              items:
+                type: string
+            - type: "null"
         snapshot_retention_days:
-          type: integer
+          anyOf:
+            - type: integer
+            - type: "null"
         description:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
       required:
         - name
     CreateEnvironmentRequest:
@@ -427,16 +646,49 @@ components:
             - hetzner
             - aws
         cloud_provider_hetzner_region:
-          type: string
-          enum:
-            - fsn1
+          anyOf:
+            - type: string
+              enum:
+                - fsn1
+            - type: "null"
         cloud_provider_aws_region:
-          type: string
-          enum:
-            - eu-west-1
+          anyOf:
+            - type: string
+              enum:
+                - eu-west-1
+            - type: "null"
+        compute_units:
+          anyOf:
+            - type: integer
+            - type: "null"
       required:
         - name
         - cloud_provider
+    CreateEnvironmentServiceAccountRequest:
+      type: object
+      properties:
+        label:
+          type: string
+        caveats:
+          anyOf:
+            - oneOf:
+                - type: string
+                  enum:
+                    - ro
+                    - rw
+                - type: object
+                  additionalProperties:
+                    type: string
+                    enum:
+                      - ro
+                      - rw
+            - type: "null"
+        with_service_oauth_token:
+          anyOf:
+            - type: boolean
+            - type: "null"
+      required:
+        - label
     CreateServiceAccountRequest:
       type: object
       properties:
@@ -444,6 +696,13 @@ components:
           type: string
       required:
         - label
+    CreateUserRequest:
+      type: object
+      properties:
+        email:
+          type: string
+      required:
+        - email
     Credential:
       type: object
       properties:
@@ -463,14 +722,20 @@ components:
           type: string
           format: date-time
         expires_at:
-          type: string
-          format: date-time
+          anyOf:
+            - type: string
+              format: date-time
+            - type: "null"
         revoked_at:
-          type: string
-          format: date-time
+          anyOf:
+            - type: string
+              format: date-time
+            - type: "null"
         last_rotated_at:
-          type: string
-          format: date-time
+          anyOf:
+            - type: string
+              format: date-time
+            - type: "null"
       required:
         - id
         - label
@@ -500,7 +765,9 @@ components:
         built_in:
           type: boolean
         description:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         labels:
           type: array
           items:
@@ -510,7 +777,9 @@ components:
         bucket_id:
           type: string
         snapshot_retention_days:
-          type: integer
+          anyOf:
+            - type: integer
+            - type: "null"
         environment_id:
           type: string
         created_at:
@@ -563,6 +832,8 @@ components:
             - aws
         cloud_provider_region:
           type: string
+        compute_units:
+          type: integer
         created_at:
           type: string
           format: date-time
@@ -575,6 +846,7 @@ components:
         - slug
         - cloud_provider
         - cloud_provider_region
+        - compute_units
         - created_at
         - updated_at
     EnvironmentResponse:
@@ -584,6 +856,22 @@ components:
           "$ref": "#/components/schemas/Environment"
       required:
         - environment
+    EnvironmentServiceAccountResponse:
+      type: object
+      properties:
+        service_account:
+          "$ref": "#/components/schemas/ServiceAccount"
+        role_assignments:
+          type: array
+          items:
+            "$ref": "#/components/schemas/RoleAssignment"
+        service_oauth_token:
+          anyOf:
+            - type: string
+            - type: "null"
+      required:
+        - service_account
+        - role_assignments
     Label:
       type: object
       properties:
@@ -623,9 +911,13 @@ components:
         name:
           type: string
         email:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         slug:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
       required:
         - id
         - type
@@ -668,11 +960,13 @@ components:
             - organization:writer
             - organization:admin
         resource_kind:
-          type: string
-          enum:
-            - organization
-            - environment
-            - catalog
+          anyOf:
+            - type: string
+              enum:
+                - organization
+                - environment
+                - catalog
+            - type: "null"
         resource_id:
           type: string
       required:
@@ -702,65 +996,126 @@ components:
       type: object
       properties:
         name:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         access_key_id:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         secret_access_key:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         region:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         endpoint:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
     UpdateConnectionRequest:
       type: object
       properties:
         name:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         read_only:
-          type: boolean
+          anyOf:
+            - type: boolean
+            - type: "null"
         label_ids:
-          type: array
-          items:
-            type: string
+          anyOf:
+            - type: array
+              items:
+                type: string
+            - type: "null"
         description:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         standard_config:
-          "$ref": "#/components/schemas/ConnectionStandardConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionStandardConfig"
+            - type: "null"
         mysql_config:
-          "$ref": "#/components/schemas/ConnectionMysqlConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionMysqlConfig"
+            - type: "null"
         postgres_config:
-          "$ref": "#/components/schemas/ConnectionPostgresConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionPostgresConfig"
+            - type: "null"
+        mongo_config:
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionMongoConfig"
+            - type: "null"
         bigquery_config:
-          "$ref": "#/components/schemas/ConnectionBigQueryConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionBigQueryConfig"
+            - type: "null"
         snowflake_config:
-          "$ref": "#/components/schemas/ConnectionSnowflakeConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionSnowflakeConfig"
+            - type: "null"
         bucket_tables_config:
-          "$ref": "#/components/schemas/ConnectionBucketTablesConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionBucketTablesConfig"
+            - type: "null"
         iceberg_tables_config:
-          "$ref": "#/components/schemas/ConnectionIcebergTablesConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionIcebergTablesConfig"
+            - type: "null"
         duckdb_config:
-          "$ref": "#/components/schemas/ConnectionDuckDBConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionDuckDBConfig"
+            - type: "null"
         r2_catalog_config:
-          "$ref": "#/components/schemas/ConnectionR2CatalogConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionR2CatalogConfig"
+            - type: "null"
         s3_tables_config:
-          "$ref": "#/components/schemas/ConnectionS3TablesConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionS3TablesConfig"
+            - type: "null"
         glue_config:
-          "$ref": "#/components/schemas/ConnectionGlueConfig"
+          anyOf:
+            - "$ref": "#/components/schemas/ConnectionGlueConfig"
+            - type: "null"
     UpdateDatabaseRequest:
       type: object
       properties:
         name:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
         read_only:
-          type: boolean
+          anyOf:
+            - type: boolean
+            - type: "null"
         label_ids:
-          type: array
-          items:
-            type: string
+          anyOf:
+            - type: array
+              items:
+                type: string
+            - type: "null"
         snapshot_retention_days:
-          type: integer
+          anyOf:
+            - type: integer
+            - type: "null"
         description:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
+    UpdateEnvironmentRequest:
+      type: object
+      properties:
+        compute_units:
+          type: integer
+      required:
+        - compute_units
     UpdateRoleAssignmentsRequest:
       type: object
       properties:
@@ -781,13 +1136,25 @@ components:
       type: object
       properties:
         id:
+          anyOf:
+            - type: string
+            - type: "null"
+        invitation_id:
+          anyOf:
+            - type: string
+            - type: "null"
+        iac_id:
           type: string
         email:
           type: string
         name:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
       required:
         - id
+        - invitation_id
+        - iac_id
         - email
         - name
     UserResponse:
@@ -807,7 +1174,9 @@ components:
         authentication_scope:
           type: string
         environment_slug:
-          type: string
+          anyOf:
+            - type: string
+            - type: "null"
       required:
         - principal
         - organization
@@ -1068,6 +1437,71 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/Error" }
 
+  /environments/{environment_id}/service_accounts:
+    post:
+      operationId: createEnvironmentServiceAccount
+      summary: Create a service account scoped to a single environment
+      description: |
+        Creates a service account whose roles are confined to the given environment. `caveats`
+        defaults to read-only on the whole environment; pass `"rw"` for read-write, or an object
+        mapping catalog names to `"ro"`/`"rw"` to grant access per catalog. Authenticate with the
+        Altertable CLI and pass `with_service_oauth_token: true` to receive a one-time
+        `service_oauth_token` for the new service account; it expires at the same time as the
+        CLI token used to create it.
+      tags: [Service Accounts]
+      parameters:
+        - name: environment_id
+          in: path
+          required: true
+          description: Environment UUID or slug
+          schema:
+            type: string
+            examples:
+              - "019d7223-796e-7917-8d7e-ca256daa7979"
+              - "production"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateEnvironmentServiceAccountRequest"
+            examples:
+              environmentReadOnly:
+                summary: Read-only on the whole environment
+                value:
+                  label: CI Deploy
+              withServiceOauthToken:
+                summary: Issue a follow-up CLI OAuth token for the service account
+                value:
+                  label: CI Deploy
+                  with_service_oauth_token: true
+              perCatalog:
+                summary: Read on one catalog, write on another
+                value:
+                  label: CI Deploy
+                  caveats:
+                    analytics: ro
+                    staging: rw
+      responses:
+        "201":
+          description: Service account created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnvironmentServiceAccountResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "422":
+          description: Validation failed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
   /environments/{environment_id}/buckets:
     get:
       operationId: listBuckets
@@ -1465,13 +1899,47 @@ paths:
         "403": { $ref: "#/components/responses/Forbidden" }
         "404": { $ref: "#/components/responses/NotFound" }
 
+  /users:
+    post:
+      operationId: createUser
+      summary: Invite a user to the organization
+      description: Creates or reuses a pending invitation. The returned iac_id is the stable Terraform identity.
+      tags: [Users]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/CreateUserRequest" }
+      responses:
+        "200":
+          description: Existing pending invitation
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UserResponse" }
+        "201":
+          description: Invitation created
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UserResponse" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "422":
+          description: Validation failed or the email is already an organization member
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+
   /users/{id}:
     get:
       operationId: getUser
-      summary: Get a user in the organization by ID
+      summary: Get a user or invitation by Terraform identity
       tags: [Users]
       parameters:
-        - { name: id, in: path, required: true, schema: { type: string } }
+        - name: id
+          in: path
+          required: true
+          description: Opaque iac_id returned by the user API; either a user UUID or invitation_id=<UUID>
+          schema: { type: string }
       responses:
         "200":
           description: User
@@ -1481,6 +1949,25 @@ paths:
         "401": { $ref: "#/components/responses/Unauthorized" }
         "403": { $ref: "#/components/responses/Forbidden" }
         "404": { $ref: "#/components/responses/NotFound" }
+    delete:
+      operationId: deleteUser
+      summary: Cancel an invitation or remove a user from the organization
+      tags: [Users]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Opaque iac_id returned by the user API
+          schema: { type: string }
+      responses:
+        "204": { description: User or invitation is absent }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "422":
+          description: The authenticated principal cannot remove itself
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
 
   /users/{user_id}/role_assignments:
     get:
@@ -1488,7 +1975,13 @@ paths:
       summary: List a user's direct role assignments
       tags: [Role Assignments]
       parameters:
-        - { name: user_id, in: path, required: true, schema: { type: string } }
+        - {
+            name: user_id,
+            in: path,
+            required: true,
+            description: Opaque user iac_id,
+            schema: { type: string },
+          }
       responses:
         "200":
           description: Role assignments
@@ -1503,7 +1996,13 @@ paths:
       summary: Replace a user's role assignments
       tags: [Role Assignments]
       parameters:
-        - { name: user_id, in: path, required: true, schema: { type: string } }
+        - {
+            name: user_id,
+            in: path,
+            required: true,
+            description: Opaque user iac_id,
+            schema: { type: string },
+          }
       requestBody:
         required: true
         content:
@@ -1523,6 +2022,27 @@ paths:
           content:
             application/json:
               schema: { $ref: "#/components/schemas/Error" }
+    delete:
+      operationId: resetUserRoleAssignments
+      summary: Reset a user's role assignments to organization:member
+      tags: [Role Assignments]
+      parameters:
+        - {
+            name: user_id,
+            in: path,
+            required: true,
+            description: Opaque user iac_id,
+            schema: { type: string },
+          }
+      responses:
+        "204": { description: Role assignments reset }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "422":
+          description: Validation failed
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
 
   /service_accounts/{service_account_id}/role_assignments:
     get:
@@ -1565,6 +2085,22 @@ paths:
           content:
             application/json:
               schema: { $ref: "#/components/schemas/Error" }
+    delete:
+      operationId: resetServiceAccountRoleAssignments
+      summary: Reset a service account's role assignments to organization:member
+      tags: [Role Assignments]
+      parameters:
+        - { name: service_account_id, in: path, required: true, schema: { type: string } }
+      responses:
+        "204": { description: Role assignments reset }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "404": { $ref: "#/components/responses/NotFound" }
+        "422":
+          description: Validation failed
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
 
   /users/{user_id}/environments/{environment_id}/credentials:
     post:
@@ -1572,7 +2108,13 @@ paths:
       summary: Create a credential for a user (returns the password once)
       tags: [Credentials]
       parameters:
-        - { name: user_id, in: path, required: true, schema: { type: string } }
+        - {
+            name: user_id,
+            in: path,
+            required: true,
+            description: Opaque user iac_id,
+            schema: { type: string },
+          }
         - { name: environment_id, in: path, required: true, schema: { type: string } }
       requestBody:
         required: false
@@ -1600,7 +2142,13 @@ paths:
       summary: Get a user's credential (no secret)
       tags: [Credentials]
       parameters:
-        - { name: user_id, in: path, required: true, schema: { type: string } }
+        - {
+            name: user_id,
+            in: path,
+            required: true,
+            description: Opaque user iac_id,
+            schema: { type: string },
+          }
         - { name: environment_id, in: path, required: true, schema: { type: string } }
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
diff --git a/cli/src/commands/api/lib/http-conformance.test.ts b/cli/src/commands/api/lib/http-conformance.test.ts
index ac700d7..c5ec4de 100644
--- a/cli/src/commands/api/lib/http-conformance.test.ts
+++ b/cli/src/commands/api/lib/http-conformance.test.ts
@@ -48,7 +48,7 @@ afterEach(() => {
 
 describe("openapi HTTP conformance", () => {
   test("covers all generated operations", () => {
-    expect(OPENAPI_OPERATIONS.length).toBe(35);
+    expect(OPENAPI_OPERATIONS.length).toBe(40);
   });
 
   test("every operation is reachable via executeApiHttp", async () => {
diff --git a/cli/src/commands/login/index.test.ts b/cli/src/commands/login/index.test.ts
index a3cc2d4..ad96f14 100644
--- a/cli/src/commands/login/index.test.ts
+++ b/cli/src/commands/login/index.test.ts
@@ -319,7 +319,7 @@ describe("login --service-account", () => {
 
   test("provisions a service account and stores its service OAuth token", async () => {
     const cli = await completeBrowserLogin(
-      ["login", "--service-account", "My Service", "--only", "catalog1:ro"],
+      ["login", "--service-account", "My Service", "--scope", "catalog1:ro"],
       DEFAULT_WHOAMI,
       "access_token",
       serviceAccountMocks(),
@@ -348,18 +348,6 @@ describe("login --service-account", () => {
     expect(payload).toHaveProperty("with_service_oauth_token");
   });
 
-  test("--svc is accepted as an alias", async () => {
-    await completeBrowserLogin(
-      ["login", "--svc", "My Service"],
-      DEFAULT_WHOAMI,
-      "access_token",
-      serviceAccountMocks(),
-    );
-
-    expect(getActiveProfileName()).toBe(serviceAccountProfile);
-    expect(storedAccessToken(serviceAccountProfile)).toBe("svc_access_token");
-  });
-
   test("leaves the signing-in user's own session unstored", async () => {
     await completeBrowserLogin(
       ["login", "--service-account", "My Service"],
@@ -373,9 +361,9 @@ describe("login --service-account", () => {
     expect(storedAccessToken(serviceAccountProfile)).toBe("svc_access_token");
   });
 
-  test("reports the catalogs the server granted, not the ones --only requested", async () => {
+  test("reports the catalogs the server granted, not the ones --scope requested", async () => {
     const cli = await completeBrowserLogin(
-      ["login", "--service-account", "My Service", "--only", "analytics:rw"],
+      ["login", "--service-account", "My Service", "--scope", "analytics:rw"],
       DEFAULT_WHOAMI,
       "access_token",
       serviceAccountMocks({
@@ -414,9 +402,9 @@ describe("login --service-account", () => {
     expect(stdout).not.toContain("cat-unknown");
   });
 
-  test("warns when --only was requested but the server reported no role assignments", async () => {
+  test("warns when --scope was requested but the server reported no role assignments", async () => {
     const cli = await completeBrowserLogin(
-      ["login", "--service-account", "My Service", "--only", "analytics:ro"],
+      ["login", "--service-account", "My Service", "--scope", "analytics:ro"],
       DEFAULT_WHOAMI,
       "access_token",
       serviceAccountMocks({ ...SERVICE_ACCOUNT_RESPONSE, role_assignments: [] }),
@@ -435,11 +423,11 @@ describe("login --service-account", () => {
         "access_token",
         [serviceAccountMock({ ...SERVICE_ACCOUNT_RESPONSE, service_oauth_token: undefined })],
       ),
-      "service OAuth token",
+      "assertion failed retrieving service_account.service_oauth_token",
     );
   });
 
-  test("omits caveats when --only is not set", async () => {
+  test("omits the scope when --scope is not set", async () => {
     await completeBrowserLogin(
       ["login", "--service-account", "My Service"],
       DEFAULT_WHOAMI,
@@ -453,9 +441,9 @@ describe("login --service-account", () => {
     expect(payload).not.toHaveProperty("caveats");
   });
 
-  test("--readonly sends a blanket read-only caveat", async () => {
+  test("--scope ro sends a blanket read-only scope", async () => {
     await completeBrowserLogin(
-      ["login", "--service-account", "My Service", "--readonly"],
+      ["login", "--service-account", "My Service", "--scope", "ro"],
       DEFAULT_WHOAMI,
       "access_token",
       serviceAccountMocks(),
@@ -467,33 +455,10 @@ describe("login --service-account", () => {
     expect(payload.caveats).toBe("ro");
   });
 
-  test("--readonly with --only fails before any HTTP call", async () => {
-    await expectRejection(
-      runCommandWithTestRuntime([
-        "login",
-        "--service-account",
-        "My Service",
-        "--readonly",
-        "--only",
-        "analytics:ro",
-      ]),
-      "--readonly cannot be combined with --only",
-    );
-    expect(existsSync(logFile)).toBe(false);
-  });
-
-  test("--readonly without --service-account fails before any HTTP call", async () => {
-    await expectRejection(
-      runCommandWithTestRuntime(["login", "--readonly"]),
-      "--readonly requires --service-account",
-    );
-    expect(existsSync(logFile)).toBe(false);
-  });
-
-  test("--only without --service-account fails before any HTTP call", async () => {
+  test("--scope without --service-account fails before any HTTP call", async () => {
     await expectRejection(
-      runCommandWithTestRuntime(["login", "--only", "catalog1:ro"]),
-      "--only requires --service-account",
+      runCommandWithTestRuntime(["login", "--scope", "catalog1:ro"]),
+      "--scope requires --service-account",
     );
     expect(existsSync(logFile)).toBe(false);
   });
@@ -514,13 +479,13 @@ describe("login --service-account", () => {
     expect(existsSync(logFile)).toBe(false);
   });
 
-  test("malformed --only fails before any HTTP call", async () => {
+  test("malformed --scope fails before any HTTP call", async () => {
     await expectRejection(
       runCommandWithTestRuntime([
         "login",
         "--service-account",
         "My Service",
-        "--only",
+        "--scope",
         "catalog1:read",
       ]),
       "catalog1:read",
@@ -552,7 +517,7 @@ describe("login --service-account", () => {
   test("surfaces a 403 from the service account endpoint", async () => {
     try {
       await completeBrowserLogin(
-        ["login", "--service-account", "My Service", "--only", "catalog1:ro"],
+        ["login", "--service-account", "My Service", "--scope", "catalog1:ro"],
         DEFAULT_WHOAMI,
         "access_token",
         [
@@ -576,7 +541,7 @@ describe("login --service-account", () => {
   test("names the missing service account endpoint on 404", async () => {
     try {
       await completeBrowserLogin(
-        ["login", "--service-account", "My Service", "--only", "catalog1:ro"],
+        ["login", "--service-account", "My Service", "--scope", "catalog1:ro"],
         DEFAULT_WHOAMI,
         "access_token",
         [serviceAccountMock("<html>Not Found</html>", 404)],
diff --git a/cli/src/commands/login/index.ts b/cli/src/commands/login/index.ts
index 03e5300..3850fcf 100644
--- a/cli/src/commands/login/index.ts
+++ b/cli/src/commands/login/index.ts
@@ -1,5 +1,5 @@
 import { defineCommand } from "@/lib/command.ts";
-import { ConfigurationError } from "@/lib/errors.ts";
+import { assertRetrieved, ConfigurationError } from "@/lib/errors.ts";
 import { getCliContext, isJsonOutput, setCliContext } from "@/context.ts";
 import { assertAllowedApiBase } from "@/lib/url-policy.ts";
 import { refreshCliRuntimeContext, type OutputSink } from "@/lib/runtime.ts";
@@ -22,12 +22,13 @@ import { profileExists, resolveWorkingProfile, setActiveProfile } from "@/lib/pr
 import { secretSet } from "@/lib/secrets.ts";
 import {
   fetchEnvironmentCatalogs,
-  parseServiceAccountCaveats,
+  parseServiceAccountScope,
   provisionEnvironmentServiceAccount,
   type EnvironmentCatalog,
   type EnvironmentServiceAccountResponse,
-  type ServiceAccountCaveats,
+  type ServiceAccountAccessMode,
   type ServiceAccountRoleAssignment,
+  type ServiceAccountScope,
 } from "@/lib/service-account-provision.ts";
 import { document, section, span, table } from "@/ui/document.ts";
 import { renderDocumentText } from "@/ui/renderers/terminal.ts";
@@ -41,8 +42,8 @@ export const loginCommand = defineCommand({
     examples: [
       "altertable login",
       "altertable login --replace-profile",
-      'altertable login --service-account "CI Bot" --only analytics:ro',
-      'altertable login --svc "CI Bot" --readonly',
+      'altertable login --service-account "CI Bot" --scope analytics:ro',
+      'altertable login --service-account "CI Bot" --scope ro',
     ],
   },
   args: {
@@ -67,21 +68,15 @@ export const loginCommand = defineCommand({
     },
     "service-account": {
       type: "string",
-      alias: "svc",
       valueHint: "LABEL",
       description:
         "Create an environment-scoped service account with this label and store its access token instead of your login session",
     },
-    only: {
+    scope: {
       type: "string",
-      valueHint: "CATALOG:MODE,...",
+      valueHint: "MODE|CATALOG:MODE,...",
       description:
-        "Request a service account limited to specific catalogs, e.g. analytics:ro,staging:rw (requires --service-account). The catalog access the server actually grants is reported on success.",
-    },
-    readonly: {
-      type: "boolean",
-      description:
-        "Request a service account with read-only access to every catalog (requires --service-account; cannot be combined with --only)",
+        "Request a service account limited to `ro` or `rw` on every catalog, or to specific catalogs, e.g. `analytics:ro,staging:rw` (requires --service-account). The catalog access the server actually grants is reported on success.",
     },
   },
   run: ({ args, sink }) => runLogin(args as LoginArgs, sink),
@@ -160,13 +155,7 @@ function selectLoginProfile(
 }
 
 function requireWhoamiEnvironment(whoami: WhoamiResponse): string {
-  const environment = whoami.environment_slug;
-
-  // OAuth login must always return an environment.
-  if (!environment) {
-    throw new Error("No environment returned from `whoami` post-login. Aborting.");
-  }
-  return environment;
+  return assertRetrieved(whoami.environment_slug, "login", "whoami.environment_slug");
 }
 
 function storeLoginProfileMetadata(
@@ -186,8 +175,8 @@ function storeLoginProfileMetadata(
     organizationName: whoami.organization?.name,
     principalType: whoami.principal?.type,
     principalName: whoami.principal?.name,
-    principalEmail: whoami.principal?.email,
-    principalSlug: whoami.principal?.slug,
+    principalEmail: whoami.principal?.email ?? undefined,
+    principalSlug: whoami.principal?.slug ?? undefined,
     ...(args["data-plane-url"] ? { dataPlane: args["data-plane-url"] } : {}),
     controlPlane,
   });
@@ -201,13 +190,12 @@ type LoginArgs = {
   "allow-insecure-http"?: boolean;
   "replace-profile"?: boolean;
   "service-account"?: string;
-  only?: string;
-  readonly?: boolean;
+  scope?: string;
 };
 
 type ServiceAccountLoginRequest = {
   label: string;
-  caveats?: ServiceAccountCaveats;
+  scope?: ServiceAccountScope;
 };
 
 function resolveLoginEndpoints(
@@ -251,23 +239,10 @@ function applyLoginDataPlaneUrl(args: LoginArgs): void {
   }
 }
 
-function serviceAccountCaveats(args: LoginArgs): ServiceAccountCaveats | undefined {
-  if (args.readonly && args.only !== undefined) {
-    throw new ConfigurationError(
-      "--readonly cannot be combined with --only; --readonly already covers every catalog, and --only sets the mode per catalog.",
-    );
-  }
-  if (args.readonly) {
-    return "ro";
-  }
-  return args.only === undefined ? undefined : parseServiceAccountCaveats(args.only);
-}
-
 function parseServiceAccountLoginArgs(args: LoginArgs): ServiceAccountLoginRequest | undefined {
   const label = args["service-account"];
-  const restrictingFlag = args.only !== undefined ? "--only" : args.readonly ? "--readonly" : "";
-  if (restrictingFlag && label === undefined) {
-    throw new ConfigurationError(`${restrictingFlag} requires --service-account.`);
+  if (args.scope !== undefined && label === undefined) {
+    throw new ConfigurationError("--scope requires --service-account.");
   }
   if (label === undefined) {
     return undefined;
@@ -280,10 +255,9 @@ function parseServiceAccountLoginArgs(args: LoginArgs): ServiceAccountLoginReque
   if (label.trim().length === 0) {
     throw new ConfigurationError("--service-account requires a non-empty label.");
   }
-  const caveats = serviceAccountCaveats(args);
   return {
     label: label.trim(),
-    ...(caveats === undefined ? {} : { caveats }),
+    ...(args.scope === undefined ? {} : { scope: parseServiceAccountScope(args.scope) }),
   };
 }
 
@@ -296,13 +270,15 @@ function activateDerivedProfile(profileName: string): void {
   refreshCliRuntimeContext(getCliContext());
 }
 
-function catalogAccessMode(assignment: ServiceAccountRoleAssignment): "ro" | "rw" | null {
+function catalogAccessMode(
+  assignment: ServiceAccountRoleAssignment,
+): ServiceAccountAccessMode | null {
   if (assignment.role === "catalog:writer") return "rw";
   if (assignment.role === "catalog:reader") return "ro";
   return null;
 }
 
-type CatalogAccessRow = { name: string; slug: string; access: "ro" | "rw" };
+type CatalogAccessRow = { name: string; slug: string; access: ServiceAccountAccessMode };
 
 /**
  * Lists the catalogs the service account can reach, by name. Role assignments
@@ -354,19 +330,18 @@ async function completeServiceAccountLogin(
   sink: OutputSink,
 ): Promise<void> {
   const environment = requireWhoamiEnvironment(whoami);
-  const organizationSlug = whoami.organization?.slug;
-  if (!organizationSlug) {
-    throw new ConfigurationError(
-      "Service account login needs an organization slug from whoami to name the profile.",
-    );
-  }
+  const organizationSlug = assertRetrieved(
+    whoami.organization?.slug,
+    "login",
+    "whoami.organization.slug",
+  );
 
   const created = await provisionEnvironmentServiceAccount({
     managementApiBase,
     accessToken: oauthResponse.access_token,
     environment,
     label: request.label,
-    ...(request.caveats ? { caveats: request.caveats } : {}),
+    ...(request.scope ? { scope: request.scope } : {}),
   });
 
   const profileName = deriveServiceAccountProfileName(
@@ -406,7 +381,7 @@ async function completeServiceAccountLogin(
     lines.push("", renderDisplayText([span("Catalog access", "subtle")]));
     lines.push(formatCatalogAccessTable(catalogAccess));
   }
-  if (request.caveats && (created.role_assignments ?? []).length === 0) {
+  if (request.scope && (created.role_assignments ?? []).length === 0) {
     lines.push(
       renderDisplayText([
         span(
diff --git a/cli/src/generated/openapi-operations.ts b/cli/src/generated/openapi-operations.ts
index 23f8925..637508a 100644
--- a/cli/src/generated/openapi-operations.ts
+++ b/cli/src/generated/openapi-operations.ts
@@ -24,6 +24,7 @@ export const OPENAPI_OPERATIONS: OpenapiOperation[] = [
   { operationId: "deleteDatabase", method: "DELETE", path: "/environments/{environment_id}/databases/{id}", summary: "Delete a database" },
   { operationId: "getDatabase", method: "GET", path: "/environments/{environment_id}/databases/{id}", summary: "Get a database by ID or slug" },
   { operationId: "updateDatabase", method: "PATCH", path: "/environments/{environment_id}/databases/{id}", summary: "Update a database" },
+  { operationId: "createEnvironmentServiceAccount", method: "POST", path: "/environments/{environment_id}/service_accounts", summary: "Create a service account scoped to a single environment" },
   { operationId: "deleteEnvironment", method: "DELETE", path: "/environments/{id}", summary: "Delete an environment" },
   { operationId: "getEnvironment", method: "GET", path: "/environments/{id}", summary: "Get an environment by ID or slug" },
   { operationId: "createServiceAccount", method: "POST", path: "/service_accounts", summary: "Create a service account" },
@@ -33,12 +34,16 @@ export const OPENAPI_OPERATIONS: OpenapiOperation[] = [
   { operationId: "createServiceAccountCredential", method: "POST", path: "/service_accounts/{service_account_id}/environments/{environment_id}/credentials", summary: "Create a credential for a service account (returns the password once)" },
   { operationId: "revokeServiceAccountCredential", method: "DELETE", path: "/service_accounts/{service_account_id}/environments/{environment_id}/credentials/{id}", summary: "Revoke a service account's credential" },
   { operationId: "getServiceAccountCredential", method: "GET", path: "/service_accounts/{service_account_id}/environments/{environment_id}/credentials/{id}", summary: "Get a service account's credential (no secret)" },
+  { operationId: "resetServiceAccountRoleAssignments", method: "DELETE", path: "/service_accounts/{service_account_id}/role_assignments", summary: "Reset a service account's role assignments to organization:member" },
   { operationId: "getServiceAccountRoleAssignments", method: "GET", path: "/service_accounts/{service_account_id}/role_assignments", summary: "List a service account's direct role assignments" },
   { operationId: "setServiceAccountRoleAssignments", method: "PUT", path: "/service_accounts/{service_account_id}/role_assignments", summary: "Replace a service account's role assignments" },
-  { operationId: "getUser", method: "GET", path: "/users/{id}", summary: "Get a user in the organization by ID" },
+  { operationId: "createUser", method: "POST", path: "/users", summary: "Invite a user to the organization" },
+  { operationId: "deleteUser", method: "DELETE", path: "/users/{id}", summary: "Cancel an invitation or remove a user from the organization" },
+  { operationId: "getUser", method: "GET", path: "/users/{id}", summary: "Get a user or invitation by Terraform identity" },
   { operationId: "createUserCredential", method: "POST", path: "/users/{user_id}/environments/{environment_id}/credentials", summary: "Create a credential for a user (returns the password once)" },
   { operationId: "revokeUserCredential", method: "DELETE", path: "/users/{user_id}/environments/{environment_id}/credentials/{id}", summary: "Revoke a user's credential" },
   { operationId: "getUserCredential", method: "GET", path: "/users/{user_id}/environments/{environment_id}/credentials/{id}", summary: "Get a user's credential (no secret)" },
+  { operationId: "resetUserRoleAssignments", method: "DELETE", path: "/users/{user_id}/role_assignments", summary: "Reset a user's role assignments to organization:member" },
   { operationId: "getUserRoleAssignments", method: "GET", path: "/users/{user_id}/role_assignments", summary: "List a user's direct role assignments" },
   { operationId: "setUserRoleAssignments", method: "PUT", path: "/users/{user_id}/role_assignments", summary: "Replace a user's role assignments" },
   { operationId: "lookupUser", method: "GET", path: "/users/lookup", summary: "Look up a user in the organization by email" },
diff --git a/cli/src/generated/openapi-types.ts b/cli/src/generated/openapi-types.ts
index 3404a0c..879e559 100644
--- a/cli/src/generated/openapi-types.ts
+++ b/cli/src/generated/openapi-types.ts
@@ -92,6 +92,31 @@ export interface paths {
         patch: operations["updateServiceAccount"];
         trace?: never;
     };
+    "/environments/{environment_id}/service_accounts": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create a service account scoped to a single environment
+         * @description Creates a service account whose roles are confined to the given environment. `caveats`
+         *     defaults to read-only on the whole environment; pass `"rw"` for read-write, or an object
+         *     mapping catalog names to `"ro"`/`"rw"` to grant access per catalog. Authenticate with the
+         *     Altertable CLI and pass `with_service_oauth_token: true` to receive a one-time
+         *     `service_oauth_token` for the new service account; it expires at the same time as the
+         *     CLI token used to create it.
+         */
+        post: operations["createEnvironmentServiceAccount"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/environments/{environment_id}/buckets": {
         parameters: {
             query?: never;
@@ -220,6 +245,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/users": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Invite a user to the organization
+         * @description Creates or reuses a pending invitation. The returned iac_id is the stable Terraform identity.
+         */
+        post: operations["createUser"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/users/{id}": {
         parameters: {
             query?: never;
@@ -227,11 +272,12 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get a user in the organization by ID */
+        /** Get a user or invitation by Terraform identity */
         get: operations["getUser"];
         put?: never;
         post?: never;
-        delete?: never;
+        /** Cancel an invitation or remove a user from the organization */
+        delete: operations["deleteUser"];
         options?: never;
         head?: never;
         patch?: never;
@@ -249,7 +295,8 @@ export interface paths {
         /** Replace a user's role assignments */
         put: operations["setUserRoleAssignments"];
         post?: never;
-        delete?: never;
+        /** Reset a user's role assignments to organization:member */
+        delete: operations["resetUserRoleAssignments"];
         options?: never;
         head?: never;
         patch?: never;
@@ -267,7 +314,8 @@ export interface paths {
         /** Replace a service account's role assignments */
         put: operations["setServiceAccountRoleAssignments"];
         post?: never;
-        delete?: never;
+        /** Reset a service account's role assignments to organization:member */
+        delete: operations["resetServiceAccountRoleAssignments"];
         options?: never;
         head?: never;
         patch?: never;
@@ -359,8 +407,8 @@ export interface components {
             id: string;
             name: string;
             slug: string;
-            region?: string;
-            endpoint?: string;
+            region?: string | null;
+            endpoint?: string | null;
             /** @enum {string} */
             provider: "s3" | "r2" | "gcs" | "custom";
             built_in: boolean;
@@ -381,9 +429,9 @@ export interface components {
             name: string;
             slug: string;
             /** @enum {string} */
-            engine: "postgres" | "bigquery" | "redshift" | "snowflake" | "mariadb" | "mysql" | "supabase" | "buckettables" | "icebergtables" | "r2catalog" | "s3tables" | "glue" | "duckdb";
+            engine: "postgres" | "big_query" | "redshift" | "snowflake" | "mariadb" | "mysql" | "supabase" | "bucket_tables" | "iceberg_tables" | "r2_catalog" | "s3_tables" | "glue" | "duckdb" | "mongo";
             read_only: boolean;
-            description?: string;
+            description?: string | null;
             labels: components["schemas"]["Label"][];
             catalog: string;
             environment_id: string;
@@ -391,84 +439,102 @@ export interface components {
             created_at: string;
             /** Format: date-time */
             updated_at: string;
+            config?: {
+                [key: string]: unknown;
+            } | null;
         };
         ConnectionBigQueryConfig: {
-            dataset?: string;
-            project_id_override?: string;
+            dataset?: string | null;
+            project_id_override?: string | null;
         };
         ConnectionBucketTablesConfig: {
-            bucket_id?: string;
-            /** @enum {string} */
-            file_format?: "parquet" | "csv" | "json";
-            assume_immutable?: boolean;
-            tables: unknown;
+            bucket_id?: string | null;
+            file_format?: ("parquet" | "csv" | "json") | null;
+            assume_immutable?: boolean | null;
+            tables: {
+                [key: string]: string;
+            };
         };
         ConnectionDuckDBConfig: {
-            bucket_id?: string;
-            path?: string;
+            bucket_id?: string | null;
+            path?: string | null;
         };
         ConnectionGlueConfig: {
-            warehouse?: string;
-            default_region?: string;
-            role_arn?: string;
+            warehouse?: string | null;
+            default_region?: string | null;
+            role_arn?: string | null;
         };
         ConnectionIcebergTablesConfig: {
-            bucket_id?: string;
-            tables: unknown;
+            bucket_id?: string | null;
+            tables: {
+                [key: string]: string;
+            };
+        };
+        ConnectionMongoConfig: {
+            host?: string | null;
+            port?: number | null;
+            database?: string | null;
+            username?: string | null;
+            password?: string | null;
+            ssh_tunnel?: components["schemas"]["ConnectionSshTunnel"] | null;
+            srv?: boolean | null;
+            tls?: boolean | null;
+            auth_source?: string | null;
         };
         ConnectionMysqlConfig: {
-            host?: string;
-            port?: number;
-            database?: string;
-            username?: string;
-            password?: string;
-            schema?: string;
-            ssh_tunnel?: components["schemas"]["ConnectionSshTunnel"];
+            host?: string | null;
+            port?: number | null;
+            database?: string | null;
+            username?: string | null;
+            password?: string | null;
+            schema?: string | null;
+            ssh_tunnel?: components["schemas"]["ConnectionSshTunnel"] | null;
+            ssl_mode?: ("disabled" | "preferred" | "verify_identity") | null;
         };
         ConnectionPostgresConfig: {
-            host?: string;
-            port?: number;
-            database?: string;
-            username?: string;
-            password?: string;
-            schema?: string;
-            ssh_tunnel?: components["schemas"]["ConnectionSshTunnel"];
-            sslmode?: string;
+            host?: string | null;
+            port?: number | null;
+            database?: string | null;
+            username?: string | null;
+            password?: string | null;
+            schema?: string | null;
+            ssh_tunnel?: components["schemas"]["ConnectionSshTunnel"] | null;
+            sslmode?: ("disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full") | null;
         };
         ConnectionR2CatalogConfig: {
-            warehouse?: string;
-            endpoint?: string;
-            token?: string;
+            warehouse?: string | null;
+            endpoint?: string | null;
+            token?: string | null;
         };
         ConnectionResponse: {
             connection: components["schemas"]["Connection"];
         };
         ConnectionS3TablesConfig: {
-            warehouse?: string;
-            default_region?: string;
-            aws_access_key_id?: string;
-            aws_secret_access_key?: string;
+            warehouse?: string | null;
+            default_region?: string | null;
+            aws_access_key_id?: string | null;
+            aws_secret_access_key?: string | null;
         };
         ConnectionSnowflakeConfig: {
-            account_url?: string;
-            warehouse?: string;
-            username?: string;
-            password?: string;
-            database?: string;
+            account_url?: string | null;
+            warehouse?: string | null;
+            username?: string | null;
+            password?: string | null;
+            database?: string | null;
         };
         ConnectionSshTunnel: {
-            bastion_host?: string;
-            bastion_port?: number;
-            bastion_username?: string;
+            bastion_host?: string | null;
+            bastion_port?: number | null;
+            bastion_username?: string | null;
         };
         ConnectionStandardConfig: {
-            host?: string;
-            port?: number;
-            database?: string;
-            username?: string;
-            password?: string;
-            schema?: string;
-            ssh_tunnel?: components["schemas"]["ConnectionSshTunnel"];
+            host?: string | null;
+            port?: number | null;
+            database?: string | null;
+            username?: string | null;
+            password?: string | null;
+            schema?: string | null;
+            ssh_tunnel?: components["schemas"]["ConnectionSshTunnel"] | null;
         };
         ConnectionsListResponse: {
             connections: components["schemas"]["Connection"][];
@@ -477,32 +543,32 @@ export interface components {
             name: string;
             access_key_id: string;
             secret_access_key: string;
-            region?: string;
-            endpoint?: string;
+            region?: string | null;
+            endpoint?: string | null;
         };
         CreateConnectionRequest: {
             name: string;
             /** @enum {string} */
-            engine: "postgres" | "bigquery" | "redshift" | "snowflake" | "mariadb" | "mysql" | "supabase" | "buckettables" | "icebergtables" | "r2catalog" | "s3tables" | "glue" | "duckdb";
-            read_only?: boolean;
-            label_ids?: string[];
-            description?: string;
-            standard_config?: components["schemas"]["ConnectionStandardConfig"];
-            mysql_config?: components["schemas"]["ConnectionMysqlConfig"];
-            postgres_config?: components["schemas"]["ConnectionPostgresConfig"];
-            bigquery_config?: components["schemas"]["ConnectionBigQueryConfig"];
-            snowflake_config?: components["schemas"]["ConnectionSnowflakeConfig"];
-            bucket_tables_config?: components["schemas"]["ConnectionBucketTablesConfig"];
-            iceberg_tables_config?: components["schemas"]["ConnectionIcebergTablesConfig"];
-            duckdb_config?: components["schemas"]["ConnectionDuckDBConfig"];
-            r2_catalog_config?: components["schemas"]["ConnectionR2CatalogConfig"];
-            s3_tables_config?: components["schemas"]["ConnectionS3TablesConfig"];
-            glue_config?: components["schemas"]["ConnectionGlueConfig"];
+            engine: "postgres" | "big_query" | "redshift" | "snowflake" | "mariadb" | "mysql" | "supabase" | "bucket_tables" | "iceberg_tables" | "r2_catalog" | "s3_tables" | "glue" | "duckdb" | "mongo";
+            read_only?: boolean | null;
+            label_ids?: string[] | null;
+            description?: string | null;
+            standard_config?: components["schemas"]["ConnectionStandardConfig"] | null;
+            mysql_config?: components["schemas"]["ConnectionMysqlConfig"] | null;
+            postgres_config?: components["schemas"]["ConnectionPostgresConfig"] | null;
+            mongo_config?: components["schemas"]["ConnectionMongoConfig"] | null;
+            bigquery_config?: components["schemas"]["ConnectionBigQueryConfig"] | null;
+            snowflake_config?: components["schemas"]["ConnectionSnowflakeConfig"] | null;
+            bucket_tables_config?: components["schemas"]["ConnectionBucketTablesConfig"] | null;
+            iceberg_tables_config?: components["schemas"]["ConnectionIcebergTablesConfig"] | null;
+            duckdb_config?: components["schemas"]["ConnectionDuckDBConfig"] | null;
+            r2_catalog_config?: components["schemas"]["ConnectionR2CatalogConfig"] | null;
+            s3_tables_config?: components["schemas"]["ConnectionS3TablesConfig"] | null;
+            glue_config?: components["schemas"]["ConnectionGlueConfig"] | null;
         };
         CreateCredentialRequest: {
-            label?: string;
-            /** Format: date-time */
-            expires_at?: string;
+            label?: string | null;
+            expires_at?: string | null;
         };
         CreateCredentialResponse: {
             credential: components["schemas"]["Credential"];
@@ -510,24 +576,33 @@ export interface components {
         };
         CreateDatabaseRequest: {
             name: string;
-            bucket_id?: string;
-            read_only?: boolean;
-            label_ids?: string[];
-            snapshot_retention_days?: number;
-            description?: string;
+            bucket_id?: string | null;
+            read_only?: boolean | null;
+            label_ids?: string[] | null;
+            snapshot_retention_days?: number | null;
+            description?: string | null;
         };
         CreateEnvironmentRequest: {
             name: string;
             /** @enum {string} */
             cloud_provider: "hetzner" | "aws";
-            /** @enum {string} */
-            cloud_provider_hetzner_region?: "fsn1";
-            /** @enum {string} */
-            cloud_provider_aws_region?: "eu-west-1";
+            cloud_provider_hetzner_region?: "fsn1" | null;
+            cloud_provider_aws_region?: "eu-west-1" | null;
+            compute_units?: number | null;
+        };
+        CreateEnvironmentServiceAccountRequest: {
+            label: string;
+            caveats?: (("ro" | "rw") | {
+                [key: string]: "ro" | "rw";
+            }) | null;
+            with_service_oauth_token?: boolean | null;
         };
         CreateServiceAccountRequest: {
             label: string;
         };
+        CreateUserRequest: {
+            email: string;
+        };
         Credential: {
             id: string;
             label: string;
@@ -537,12 +612,9 @@ export interface components {
             environment_id: string;
             /** Format: date-time */
             created_at: string;
-            /** Format: date-time */
-            expires_at?: string;
-            /** Format: date-time */
-            revoked_at?: string;
-            /** Format: date-time */
-            last_rotated_at?: string;
+            expires_at?: string | null;
+            revoked_at?: string | null;
+            last_rotated_at?: string | null;
         };
         CredentialResponse: {
             credential: components["schemas"]["Credential"];
@@ -553,11 +625,11 @@ export interface components {
             slug: string;
             read_only: boolean;
             built_in: boolean;
-            description?: string;
+            description?: string | null;
             labels: components["schemas"]["Label"][];
             catalog: string;
             bucket_id: string;
-            snapshot_retention_days?: number;
+            snapshot_retention_days?: number | null;
             environment_id: string;
             /** Format: date-time */
             created_at: string;
@@ -577,6 +649,7 @@ export interface components {
             /** @enum {string} */
             cloud_provider: "hetzner" | "aws";
             cloud_provider_region: string;
+            compute_units: number;
             /** Format: date-time */
             created_at: string;
             /** Format: date-time */
@@ -585,6 +658,11 @@ export interface components {
         EnvironmentResponse: {
             environment: components["schemas"]["Environment"];
         };
+        EnvironmentServiceAccountResponse: {
+            service_account: components["schemas"]["ServiceAccount"];
+            role_assignments: components["schemas"]["RoleAssignment"][];
+            service_oauth_token?: string | null;
+        };
         Label: {
             id: string;
             name: string;
@@ -600,8 +678,8 @@ export interface components {
             /** @enum {string} */
             type: "User" | "ServiceAccount";
             name: string;
-            email?: string;
-            slug?: string;
+            email?: string | null;
+            slug?: string | null;
         };
         RoleAssignment: {
             role: string;
@@ -614,8 +692,7 @@ export interface components {
         RoleInput: {
             /** @enum {string} */
             role: "catalog:reader" | "catalog:writer" | "environment:member" | "environment:reader" | "environment:writer" | "organization:member" | "organization:reader" | "organization:writer" | "organization:admin";
-            /** @enum {string} */
-            resource_kind?: "organization" | "environment" | "catalog";
+            resource_kind?: ("organization" | "environment" | "catalog") | null;
             resource_id: string;
         };
         ServiceAccount: {
@@ -627,35 +704,39 @@ export interface components {
             service_account: components["schemas"]["ServiceAccount"];
         };
         UpdateBucketRequest: {
-            name?: string;
-            access_key_id?: string;
-            secret_access_key?: string;
-            region?: string;
-            endpoint?: string;
+            name?: string | null;
+            access_key_id?: string | null;
+            secret_access_key?: string | null;
+            region?: string | null;
+            endpoint?: string | null;
         };
         UpdateConnectionRequest: {
-            name?: string;
-            read_only?: boolean;
-            label_ids?: string[];
-            description?: string;
-            standard_config?: components["schemas"]["ConnectionStandardConfig"];
-            mysql_config?: components["schemas"]["ConnectionMysqlConfig"];
-            postgres_config?: components["schemas"]["ConnectionPostgresConfig"];
-            bigquery_config?: components["schemas"]["ConnectionBigQueryConfig"];
-            snowflake_config?: components["schemas"]["ConnectionSnowflakeConfig"];
-            bucket_tables_config?: components["schemas"]["ConnectionBucketTablesConfig"];
-            iceberg_tables_config?: components["schemas"]["ConnectionIcebergTablesConfig"];
-            duckdb_config?: components["schemas"]["ConnectionDuckDBConfig"];
-            r2_catalog_config?: components["schemas"]["ConnectionR2CatalogConfig"];
-            s3_tables_config?: components["schemas"]["ConnectionS3TablesConfig"];
-            glue_config?: components["schemas"]["ConnectionGlueConfig"];
+            name?: string | null;
+            read_only?: boolean | null;
+            label_ids?: string[] | null;
+            description?: string | null;
+            standard_config?: components["schemas"]["ConnectionStandardConfig"] | null;
+            mysql_config?: components["schemas"]["ConnectionMysqlConfig"] | null;
+            postgres_config?: components["schemas"]["ConnectionPostgresConfig"] | null;
+            mongo_config?: components["schemas"]["ConnectionMongoConfig"] | null;
+            bigquery_config?: components["schemas"]["ConnectionBigQueryConfig"] | null;
+            snowflake_config?: components["schemas"]["ConnectionSnowflakeConfig"] | null;
+            bucket_tables_config?: components["schemas"]["ConnectionBucketTablesConfig"] | null;
+            iceberg_tables_config?: components["schemas"]["ConnectionIcebergTablesConfig"] | null;
+            duckdb_config?: components["schemas"]["ConnectionDuckDBConfig"] | null;
+            r2_catalog_config?: components["schemas"]["ConnectionR2CatalogConfig"] | null;
+            s3_tables_config?: components["schemas"]["ConnectionS3TablesConfig"] | null;
+            glue_config?: components["schemas"]["ConnectionGlueConfig"] | null;
         };
         UpdateDatabaseRequest: {
-            name?: string;
-            read_only?: boolean;
-            label_ids?: string[];
-            snapshot_retention_days?: number;
-            description?: string;
+            name?: string | null;
+            read_only?: boolean | null;
+            label_ids?: string[] | null;
+            snapshot_retention_days?: number | null;
+            description?: string | null;
+        };
+        UpdateEnvironmentRequest: {
+            compute_units: number;
         };
         UpdateRoleAssignmentsRequest: {
             roles: components["schemas"]["RoleInput"][];
@@ -664,9 +745,11 @@ export interface components {
             label: string;
         };
         User: {
-            id: string;
+            id: string | null;
+            invitation_id: string | null;
+            iac_id: string;
             email: string;
-            name: string;
+            name: string | null;
         };
         UserResponse: {
             user: components["schemas"]["User"];
@@ -675,7 +758,7 @@ export interface components {
             principal: components["schemas"]["Principal"];
             organization: components["schemas"]["Organization"];
             authentication_scope: string;
-            environment_slug?: string;
+            environment_slug?: string | null;
         };
     };
     responses: {
@@ -950,6 +1033,45 @@ export interface operations {
             };
         };
     };
+    createEnvironmentServiceAccount: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Environment UUID or slug */
+                environment_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateEnvironmentServiceAccountRequest"];
+            };
+        };
+        responses: {
+            /** @description Service account created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["EnvironmentServiceAccountResponse"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description Validation failed */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     listBuckets: {
         parameters: {
             query?: never;
@@ -1450,11 +1572,56 @@ export interface operations {
             404: components["responses"]["NotFound"];
         };
     };
+    createUser: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateUserRequest"];
+            };
+        };
+        responses: {
+            /** @description Existing pending invitation */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UserResponse"];
+                };
+            };
+            /** @description Invitation created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UserResponse"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description Validation failed or the email is already an organization member */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     getUser: {
         parameters: {
             query?: never;
             header?: never;
             path: {
+                /** @description Opaque iac_id returned by the user API; either a user UUID or invitation_id=<UUID> */
                 id: string;
             };
             cookie?: never;
@@ -1475,11 +1642,44 @@ export interface operations {
             404: components["responses"]["NotFound"];
         };
     };
+    deleteUser: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Opaque iac_id returned by the user API */
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description User or invitation is absent */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description The authenticated principal cannot remove itself */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     getUserRoleAssignments: {
         parameters: {
             query?: never;
             header?: never;
             path: {
+                /** @description Opaque user iac_id */
                 user_id: string;
             };
             cookie?: never;
@@ -1505,6 +1705,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
+                /** @description Opaque user iac_id */
                 user_id: string;
             };
             cookie?: never;
@@ -1538,6 +1739,38 @@ export interface operations {
             };
         };
     };
+    resetUserRoleAssignments: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Opaque user iac_id */
+                user_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Role assignments reset */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description Validation failed */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     getServiceAccountRoleAssignments: {
         parameters: {
             query?: never;
@@ -1601,11 +1834,44 @@ export interface operations {
             };
         };
     };
+    resetServiceAccountRoleAssignments: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                service_account_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Role assignments reset */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description Validation failed */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     createUserCredential: {
         parameters: {
             query?: never;
             header?: never;
             path: {
+                /** @description Opaque user iac_id */
                 user_id: string;
                 environment_id: string;
             };
@@ -1645,6 +1911,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
+                /** @description Opaque user iac_id */
                 user_id: string;
                 environment_id: string;
                 id: string;
diff --git a/cli/src/lib/command-descriptor.ts b/cli/src/lib/command-descriptor.ts
index ca153ff..bb60eda 100644
--- a/cli/src/lib/command-descriptor.ts
+++ b/cli/src/lib/command-descriptor.ts
@@ -57,7 +57,7 @@ function asStringArray(value: string | readonly string[] | undefined): string[]
 
 /**
  * Single-character aliases are short flags (`-X`); longer ones are additional
- * long flags (`--svc`). Every place that renders or parses an alias — the
+ * long flags (`--alias`). Every place that renders or parses an alias — the
  * parser, help, generated docs, shell completions — must agree on this.
  */
 export function aliasFlagToken(alias: string): string {
diff --git a/cli/src/lib/errors.ts b/cli/src/lib/errors.ts
index 3cff872..4541b9a 100644
--- a/cli/src/lib/errors.ts
+++ b/cli/src/lib/errors.ts
@@ -51,6 +51,17 @@ export class CliError extends Error {
   }
 }
 
+export function assertRetrieved<T>(
+  value: T | null | undefined,
+  operation: string,
+  path: string,
+): T {
+  if (value === undefined || value === null || value === "") {
+    throw new CliError(`${operation} failed: assertion failed retrieving ${path}`);
+  }
+  return value;
+}
+
 export class ConfigurationError extends CliError {
   constructor(message: string, options: CliErrorOptions = {}) {
     super(message, { ...options, exitCode: options.exitCode ?? EXIT_CONFIG });
diff --git a/cli/src/lib/service-account-provision.test.ts b/cli/src/lib/service-account-provision.test.ts
index 270fdee..880bd2c 100644
--- a/cli/src/lib/service-account-provision.test.ts
+++ b/cli/src/lib/service-account-provision.test.ts
@@ -1,57 +1,53 @@
 import { describe, expect, test } from "bun:test";
-import { OPENAPI_OPERATIONS } from "@/generated/openapi-operations.ts";
 import { ConfigurationError } from "@/lib/errors.ts";
-import { parseServiceAccountCaveats } from "@/lib/service-account-provision.ts";
-
-// Fails the moment `bun run spec:refresh` picks the operation up, which is the
-// signal to drop the hand-written EnvironmentServiceAccountResponse envelope.
-test("the environment service account operation is still absent from the spec", () => {
-  const shipped = OPENAPI_OPERATIONS.some(
-    (operation) => operation.operationId === "createEnvironmentServiceAccount",
-  );
-  expect(shipped).toBe(false);
-});
+import { parseServiceAccountScope } from "@/lib/service-account-provision.ts";
+
+describe("parseServiceAccountScope", () => {
+  test("parses a bare mode as a blanket scope", () => {
+    expect(parseServiceAccountScope("ro")).toBe("ro");
+    expect(parseServiceAccountScope("rw")).toBe("rw");
+    expect(parseServiceAccountScope(" RO ")).toBe("ro");
+  });
 
-describe("parseServiceAccountCaveats", () => {
   test("parses multiple catalog:mode entries", () => {
-    expect(parseServiceAccountCaveats("catalog1:ro,catalog2:rw")).toEqual({
+    expect(parseServiceAccountScope("catalog1:ro,catalog2:rw")).toEqual({
       catalog1: "ro",
       catalog2: "rw",
     });
   });
 
   test("parses a single entry", () => {
-    expect(parseServiceAccountCaveats("analytics:rw")).toEqual({ analytics: "rw" });
+    expect(parseServiceAccountScope("analytics:rw")).toEqual({ analytics: "rw" });
   });
 
   test("trims whitespace and lowercases the mode", () => {
-    expect(parseServiceAccountCaveats(" catalog1 : RO , catalog2: Rw ")).toEqual({
+    expect(parseServiceAccountScope(" catalog1 : RO , catalog2: Rw ")).toEqual({
       catalog1: "ro",
       catalog2: "rw",
     });
   });
 
   test("splits on the last colon so catalog names may contain colons", () => {
-    expect(parseServiceAccountCaveats("org:analytics:ro")).toEqual({ "org:analytics": "ro" });
+    expect(parseServiceAccountScope("org:analytics:ro")).toEqual({ "org:analytics": "ro" });
   });
 
   test("rejects a mode other than ro or rw", () => {
-    expect(() => parseServiceAccountCaveats("catalog1:read")).toThrow(ConfigurationError);
-    expect(() => parseServiceAccountCaveats("catalog1:read")).toThrow("catalog1:read");
+    expect(() => parseServiceAccountScope("catalog1:read")).toThrow(ConfigurationError);
+    expect(() => parseServiceAccountScope("catalog1:read")).toThrow("catalog1:read");
   });
 
   test("rejects an entry with no colon", () => {
-    expect(() => parseServiceAccountCaveats("catalog1")).toThrow(ConfigurationError);
-    expect(() => parseServiceAccountCaveats("catalog1")).toThrow("catalog1");
+    expect(() => parseServiceAccountScope("catalog1")).toThrow(ConfigurationError);
+    expect(() => parseServiceAccountScope("catalog1")).toThrow("catalog1");
   });
 
   test("rejects an empty catalog name", () => {
-    expect(() => parseServiceAccountCaveats(":ro")).toThrow(ConfigurationError);
-    expect(() => parseServiceAccountCaveats(":ro")).toThrow(":ro");
+    expect(() => parseServiceAccountScope(":ro")).toThrow(ConfigurationError);
+    expect(() => parseServiceAccountScope(":ro")).toThrow(":ro");
   });
 
   test("rejects a duplicate catalog", () => {
-    expect(() => parseServiceAccountCaveats("catalog1:ro,catalog1:rw")).toThrow(ConfigurationError);
-    expect(() => parseServiceAccountCaveats("catalog1:ro,catalog1:rw")).toThrow("catalog1");
+    expect(() => parseServiceAccountScope("catalog1:ro,catalog1:rw")).toThrow(ConfigurationError);
+    expect(() => parseServiceAccountScope("catalog1:ro,catalog1:rw")).toThrow("catalog1");
   });
 });
diff --git a/cli/src/lib/service-account-provision.ts b/cli/src/lib/service-account-provision.ts
index 7ce8f1d..d263dae 100644
--- a/cli/src/lib/service-account-provision.ts
+++ b/cli/src/lib/service-account-provision.ts
@@ -1,5 +1,5 @@
 import type { components } from "@/generated/openapi-types.ts";
-import { ConfigurationError, HttpError } from "@/lib/errors.ts";
+import { assertRetrieved, ConfigurationError, HttpError } from "@/lib/errors.ts";
 import { httpSend } from "@/lib/http.ts";
 import { encodeManagementEndpoint } from "@/lib/management-endpoint.ts";
 import { parseApiJson } from "@/lib/parse-api-json.ts";
@@ -7,27 +7,25 @@ import { parseApiJson } from "@/lib/parse-api-json.ts";
 export type ServiceAccountAccessMode = "ro" | "rw";
 
 // A bare mode applies to every catalog; the map form restricts per catalog.
-export type ServiceAccountCaveats =
+export type ServiceAccountScope =
   | ServiceAccountAccessMode
   | Record<string, ServiceAccountAccessMode>;
 
 export type ServiceAccountRoleAssignment = components["schemas"]["RoleAssignment"];
 
-// Only the envelope is hand-written: operationId createEnvironmentServiceAccount
-// is not in `@/generated/openapi-types.ts` yet. Drop this in favour of the
-// generated response type after `bun run spec:refresh`; the guard test in
-// service-account-provision.test.ts fails once the operation ships.
-export type EnvironmentServiceAccountResponse = components["schemas"]["ServiceAccountResponse"] & {
-  role_assignments: ServiceAccountRoleAssignment[];
-  service_oauth_token: string;
-};
+// The spec leaves `service_oauth_token` optional because the endpoint only issues
+// one when asked; this module always asks and rejects a response without it.
+export type EnvironmentServiceAccountResponse =
+  components["schemas"]["EnvironmentServiceAccountResponse"] & {
+    service_oauth_token: string;
+  };
 
 type ProvisionEnvironmentServiceAccountOptions = {
   managementApiBase: string;
   accessToken: string;
   environment: string;
   label: string;
-  caveats?: ServiceAccountCaveats;
+  scope?: ServiceAccountScope;
 };
 
 type EnvironmentCatalogLookupOptions = {
@@ -40,16 +38,19 @@ type CatalogIdentity = { id?: string; slug?: string; name?: string };
 
 export type EnvironmentCatalog = { name: string; slug: string };
 
-export function parseServiceAccountCaveats(
-  value: string,
-): Record<string, ServiceAccountAccessMode> {
-  const caveats: Record<string, ServiceAccountAccessMode> = {};
+export function parseServiceAccountScope(value: string): ServiceAccountScope {
+  const bareMode = value.trim().toLowerCase();
+  if (bareMode === "ro" || bareMode === "rw") {
+    return bareMode;
+  }
+
+  const scope: Record<string, ServiceAccountAccessMode> = {};
   for (const rawEntry of value.split(",")) {
     const entry = rawEntry.trim();
     const separatorIndex = entry.lastIndexOf(":");
     if (separatorIndex === -1) {
       throw new ConfigurationError(
-        `Invalid --only entry "${entry}": expected catalog:ro or catalog:rw.`,
+        `Invalid --scope entry "${entry}": expected ro, rw, catalog:ro or catalog:rw.`,
       );
     }
 
@@ -59,19 +60,19 @@ export function parseServiceAccountCaveats(
       .trim()
       .toLowerCase();
     if (!catalog) {
-      throw new ConfigurationError(`Invalid --only entry "${entry}": catalog name is required.`);
+      throw new ConfigurationError(`Invalid --scope entry "${entry}": catalog name is required.`);
     }
     if (mode !== "ro" && mode !== "rw") {
-      throw new ConfigurationError(`Invalid --only entry "${entry}": mode must be ro or rw.`);
+      throw new ConfigurationError(`Invalid --scope entry "${entry}": mode must be ro or rw.`);
     }
-    if (caveats[catalog] !== undefined) {
+    if (scope[catalog] !== undefined) {
       throw new ConfigurationError(
-        `Invalid --only entry "${entry}": catalog "${catalog}" is duplicated.`,
+        `Invalid --scope entry "${entry}": catalog "${catalog}" is duplicated.`,
       );
     }
-    caveats[catalog] = mode;
+    scope[catalog] = mode;
   }
-  return caveats;
+  return scope;
 }
 
 /**
@@ -103,13 +104,13 @@ export async function provisionEnvironmentServiceAccount(
   const requestBody: {
     label: string;
     with_service_oauth_token: true;
-    caveats?: ServiceAccountCaveats;
+    caveats?: ServiceAccountScope;
   } = {
     label: options.label,
     with_service_oauth_token: true,
   };
-  if (options.caveats) {
-    requestBody.caveats = options.caveats;
+  if (options.scope) {
+    requestBody.caveats = options.scope;
   }
 
   let response: string;
@@ -125,18 +126,18 @@ export async function provisionEnvironmentServiceAccount(
   } catch (error) {
     throw withServiceAccountRequestContext(error);
   }
-  const created = parseApiJson(response) as EnvironmentServiceAccountResponse;
-
-  if (!created.service_oauth_token) {
-    throw new ConfigurationError(
-      "Service account creation response was missing a service OAuth token.",
-    );
-  }
-  if (!created.service_account?.slug) {
-    throw new ConfigurationError("Service account creation response was missing a slug.");
-  }
-
-  return created;
+  const created = parseApiJson(
+    response,
+  ) as components["schemas"]["EnvironmentServiceAccountResponse"];
+
+  const token = assertRetrieved(
+    created.service_oauth_token,
+    "login",
+    "service_account.service_oauth_token",
+  );
+  assertRetrieved(created.service_account?.slug, "login", "service_account.slug");
+
+  return { ...created, service_oauth_token: token };
 }
 
 function collectCatalogs(