feat(cli): add --api-key option to auth login

apps/docs/content/docs/cli/cli-reference.mdx

@@ -43,6 +43,10 @@ Authentication and session inspection.
 			flag: "--organization <idOrSlug>",
 			description: "Selects the active organization without prompting. Required for non-TTY logins when you belong to multiple orgs.",
 		},
+		{
+			flag: "--api-key <key>",
+			description: "Store a Superset API key (`sk_live_…`) at `~/.superset/config.json` instead of running the OAuth flow.",
+		},
 	]}
 >
 Authenticate via browser OAuth and store a session token at
@@ -57,6 +61,16 @@ superset auth login
 superset auth login --organization acme
 ```
 
+To sign in with an API key — useful for CI or any environment where the
+OAuth browser flow isn't an option — pass `--api-key`. The CLI validates
+the key, stores it at `~/.superset/config.json`, and clears any prior
+OAuth session.
+
+```bash
+superset auth login --api-key sk_live_…
+superset auth login --api-key sk_live_… --organization acme
+```
+
 <CommandReturns>
 The newly authenticated user and active organization.
 
@@ -82,8 +96,9 @@ The newly authenticated user and active organization.
 </Command>
 
 <Command name="superset auth logout">
-Clear the stored session. Does not call the API and does not clear the
-active organization (your preferred org persists across re-logins).
+Clear stored credentials — both an OAuth session and a stored API key.
+Does not call the API and does not clear the active organization (your
+preferred org persists across re-logins).
 
 ```bash
 superset auth logout
@@ -132,7 +147,7 @@ Auth: Session (expires in 32 min)
   name: string;
   organizationId: string;
   organizationName: string;
-  authSource: "flag" | "env" | "oauth";
+  authSource: "override" | "config" | "oauth";
 }
 ```
 </JsonOutput>

apps/docs/content/docs/cli/getting-started.mdx

@@ -60,7 +60,15 @@ superset auth login --organization acme
 ```
 
 For CI or other non-interactive environments — where there's no browser to
-complete the OAuth flow — use an API key instead:
+complete the OAuth flow — use an API key instead. You can either store it
+once with `auth login --api-key`:
+
+```bash
+superset auth login --api-key sk_live_…
+superset auth whoami
+```
+
+…or set `SUPERSET_API_KEY` per-invocation without writing anything to disk:
 
 ```bash
 export SUPERSET_API_KEY=sk_live_…

packages/cli/CLI_SPEC_TARGET.md

@@ -213,18 +213,28 @@ Authenticate via browser OAuth and store a session token locally.
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <idOrSlug>` | When stdout is non-TTY and the user belongs to multiple orgs | Selects the active organization without prompting. Optional but supported when stdout is a TTY (skips the picker). |
+| `--api-key <key>` | No | Store a Superset API key (`sk_live_…`) at `~/.superset/config.json` instead of running the OAuth flow. Validates via `user.me` before writing. Mutually exclusive with the OAuth flow — passing this clears any stored `auth` session. |
 
-Flow:
+Flow (OAuth):
 
 1. Loopback callback server on `127.0.0.1:51789` or `51790`.
 2. Opens `${WEB_URL}/cli/authorize?...`. `WEB_URL` is a build-time constant
    (overridable at runtime via `SUPERSET_WEB_URL` for development).
 3. Web posts to `/api/cli/create-code`.
 4. CLI receives the code on the loopback callback (5-minute timeout).
 5. CLI exchanges via `/api/cli/exchange`.
-6. CLI stores `auth.accessToken` and `auth.expiresAt`.
+6. CLI stores `auth.accessToken` and `auth.expiresAt`, clears `apiKey`.
 7. CLI calls `user.me`, `user.myOrganizations`.
 
+Flow (`--api-key`):
+
+1. CLI validates the supplied key by calling `user.me` with the key in the
+   `x-api-key` header.
+2. On success, CLI writes `apiKey` to `~/.superset/config.json` and
+   deletes any stored OAuth `auth`. On failure, CLI exits 1 without
+   writing.
+3. CLI continues with the same org-selection rules as the OAuth flow.
+
 Org selection rules:
 
 - Single organization → selected automatically.
@@ -243,13 +253,16 @@ Output:
 }
 ```
 
-Side effects: writes `~/.superset/config.json` with `auth` and
-`organizationId`. Spinner is guarded by `process.stdout.isTTY`.
+Side effects: writes `~/.superset/config.json`. The OAuth flow writes
+`auth` (and clears any stored `apiKey`); the `--api-key` flow writes
+`apiKey` (and clears any stored `auth`). Both write `organizationId`
+when an org is selected. Spinner is guarded by `process.stdout.isTTY`.
 
 ### `superset auth logout`
 
-Clear `auth` from `~/.superset/config.json`. Does not call the API. Does not
-clear `organizationId` — the user's preferred org persists across re-logins.
+Clear `auth` and `apiKey` from `~/.superset/config.json`. Does not call
+the API. Does not clear `organizationId` — the user's preferred org
+persists across re-logins.
 
 Output:
 
@@ -272,7 +285,7 @@ Output:
   name: string;
   organizationId: string;
   organizationName: string;
-  authSource: "flag" | "env" | "oauth";
+  authSource: "override" | "config" | "oauth";
 }
 ```