docs: document compute auth workspace switching

prisma-compute/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prisma-compute
-description: Prisma Compute deployment and hosting guide. Use whenever the user mentions Prisma Compute, deploying or hosting a Prisma app, `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, `PRISMA_SERVICE_TOKEN`, Compute apps/deployments/logs/domains, localhost vs `0.0.0.0`, deploy port binding, or framework deploy readiness for Hono, Elysia, Next.js, TanStack Start, Astro, Nuxt, Svelte, Nest, or Turborepo.
+description: Prisma Compute deployment and hosting guide. Use whenever the user mentions Prisma Compute, deploying or hosting a Prisma app, `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, `PRISMA_SERVICE_TOKEN`, `auth workspace`, Compute apps/deployments/logs/domains, localhost vs `0.0.0.0`, deploy port binding, or framework deploy readiness for Hono, Elysia, Next.js, TanStack Start, Astro, Nuxt, Svelte, Nest, or Turborepo.
 license: MIT
 metadata:
   author: prisma
@@ -51,7 +51,8 @@ Use this skill for:
 - Deciding whether a framework is Compute-ready
 - Debugging `create-prisma --deploy`, `compute:deploy`, or `app deploy`
 - Managing Compute app logs, deployments, environment variables, branches, and domains
-- Running non-interactive deploys with browser auth or Prisma service tokens
+- Running non-interactive deploys with browser auth, multiple stored workspaces, or Prisma service tokens
+- Switching, selecting, listing, or logging out local Prisma Platform workspaces for `@prisma/cli`
 - Programmatic deployments with `@prisma/compute-sdk` or Management API integrations
 
 ## Decision Tree
@@ -76,11 +77,12 @@ Use this skill for:
 | Priority | Category | Impact | Prefix |
 |----------|----------|--------|--------|
 | 1 | Command verification | CRITICAL | `verify-` |
-| 2 | Framework readiness | CRITICAL | `framework-` |
-| 3 | Runtime host and port binding | CRITICAL | `runtime-` |
-| 4 | Branch, environment, and database wiring | HIGH | `env-` |
-| 5 | Deploy operations | HIGH | `deploy-` |
-| 6 | SDK and API automation | MEDIUM | `sdk-` |
+| 2 | Auth and workspace selection | CRITICAL | `auth-` |
+| 3 | Framework readiness | CRITICAL | `framework-` |
+| 4 | Runtime host and port binding | CRITICAL | `runtime-` |
+| 5 | Branch, environment, and database wiring | HIGH | `env-` |
+| 6 | Deploy operations | HIGH | `deploy-` |
+| 7 | SDK and API automation | MEDIUM | `sdk-` |
 
 ## Quick Rules
 
@@ -91,21 +93,33 @@ Use this skill for:
 - `verify-prisma-vs-platform-cli` - Do not assume `prisma app deploy` exists in the ORM CLI; check whether the task should use `@prisma/cli`.
 - `verify-generated-scripts` - Prefer the generated `compute:deploy` script when a project already has one.
 - `verify-public-url` - After a real deploy, smoke-test the public deployment URL instead of trusting local or readiness-only checks.
+- `verify-auth-workspace-support` - Check `@prisma/cli auth workspace --help` before using workspace list/use/logout commands against an installed package.
 
-### 2. Framework Readiness
+### 2. Auth and Workspace Selection
+
+- `auth-source-precedence` - A non-empty `PRISMA_SERVICE_TOKEN` is the active auth source for commands and local OAuth workspaces are ignored for execution. If it is set but empty, the CLI should fail instead of falling back to stored OAuth.
+- `auth-multi-workspace` - `auth login` can store OAuth sessions for multiple workspaces on the same machine. The active workspace pointer selects which stored OAuth grant normal commands use.
+- `auth-list-before-switch` - Use `auth workspace list --json` to inspect local sessions. Agents should prefer workspace ids from JSON over names because names can be ambiguous.
+- `auth-switch-explicitly` - Use `auth workspace use <id-or-name>` for non-interactive switching. In an interactive terminal, `auth workspace use` with no argument can open the workspace picker.
+- `auth-no-fallthrough` - If the active OAuth workspace is logged out or fails refresh, the CLI should not silently fall through to another cached workspace. Run `auth workspace use <id>` to choose the next workspace.
+- `auth-single-workspace-logout` - Use `auth workspace logout <id-or-name>` or `auth logout --workspace <id-or-name>` to remove one local OAuth workspace session. Plain `auth logout` clears all local OAuth workspace sessions.
+- `auth-service-token-switching` - While `PRISMA_SERVICE_TOKEN` is set, `auth workspace use` should be treated as unavailable; unset the env var to switch local OAuth workspaces. Workspace logout still only cleans local OAuth state.
+- `auth-storage-awareness` - Local OAuth credentials live in the platform auth file, with workspace metadata in a sidecar context file. Project pins live in `.prisma/local.json`, and CLI app/project state lives in `.prisma/cli/state.json` near `prisma.compute.ts` when present.
+
+### 3. Framework Readiness
 
 - `framework-cli-first` - Evaluate deploy readiness against current `@prisma/cli app deploy`, not against what `create-prisma` can scaffold.
 - `framework-supported-cli-deploy` - Current CLI deploy framework keys are `nextjs`, `hono`, `tanstack-start`, and `bun`; verify help/source before using any other key.
 - `framework-create-prisma-defaults-only` - `create-prisma` can provide generated defaults and `compute:deploy`, but it is not the general deploy surface for existing apps.
 - `framework-build-output` - Compute needs a server entrypoint or framework artifact, not only static output.
 
-### 3. Runtime Host and Port Binding
+### 4. Runtime Host and Port Binding
 
 - `runtime-bind-all-interfaces` - Deployed servers must bind on all interfaces (`0.0.0.0` or the framework equivalent), not hard-coded `localhost` or `127.0.0.1`.
 - `runtime-match-http-port` - The app must listen on the deployed HTTP port: read `process.env.PORT` when possible, or pass the matching `--http-port`.
 - `runtime-readiness-port-only` - Compute readiness watches listening ports; a loopback-only listener can look ready while public ingress cannot reach it.
 
-### 4. Branch, Environment, and Database
+### 5. Branch, Environment, and Database
 
 - `env-do-not-leak-secrets` - Never print full `DATABASE_URL`, service tokens, or secret values.
 - `env-deploy-loads-dotenv` - The generated deploy script passes `--env .env`; ensure production values are present before deploy.
@@ -114,13 +128,13 @@ Use this skill for:
 - `env-branch-scope` - Branch deploys, branch env vars, and branch databases must use the same branch name; pass `--branch <git-name>` explicitly when targeting a preview branch.
 - `env-production-vs-preview` - Use `--role production` for production env, `--role preview` for preview template env, and `--branch <git-name>` for branch-specific overrides.
 
-### 5. Deploy Operations
+### 6. Deploy Operations
 
 - `deploy-prod-intent` - Use `--prod --yes` only when the user intends a production deploy.
-- `deploy-noninteractive-auth` - Non-interactive deploys need either stored CLI login or a supported service token env var; never print the token.
+- `deploy-noninteractive-auth` - Non-interactive deploys need either the correct active stored OAuth workspace or a supported service token env var; never print the token.
 - `deploy-json-for-agents` - Use `--json --no-interactive` for scripts and agent-readable output.
 
-### 6. SDK and API
+### 7. SDK and API
 
 - `sdk-use-cli-first` - Prefer `@prisma/cli app deploy` for app workflows; use `create-prisma` only to scaffold a new app unless the user is building lower-level automation.
 - `sdk-result-handling` - `@prisma/compute-sdk` returns `Result` values; check `isOk()`/`isErr()` instead of relying on exceptions.
@@ -129,13 +143,14 @@ Use this skill for:
 
 1. Inspect the project: package manager, template/framework, `package.json` scripts, Prisma version, Prisma client location, and existing `compute:deploy`.
 2. Verify CLI help output for the package actually being used, or run `scripts/verify-compute-surface.mjs` for the standard Compute surface check.
-3. Choose the path:
+3. Verify auth context before project/app mutations: `auth whoami --json`, and when multiple local sessions may exist, `auth workspace list --json`.
+4. Choose the path:
    - existing app deploy: generated `compute:deploy` or `@prisma/cli app build/run/deploy`
    - new app scaffold: `create-prisma`, then generated `compute:deploy` or `@prisma/cli app deploy`
    - low-level automation: `@prisma/compute-sdk` or Management API
-4. Check framework readiness plus host/port/env/runtime requirements, including project and branch scope.
-5. Run a local build or `app build` before deploying when feasible.
-6. Deploy with JSON output when automating, then smoke-test the public URL and summarize app URL, app id, deployment id, project id, and follow-up steps.
+5. Check framework readiness plus host/port/env/runtime requirements, including project and branch scope.
+6. Run a local build or `app build` before deploying when feasible.
+7. Deploy with JSON output when automating, then smoke-test the public URL and summarize app URL, app id, deployment id, project id, workspace id, and follow-up steps.
 
 ## Avoid
 
@@ -145,3 +160,5 @@ Use this skill for:
 - Do not deploy with placeholder `DATABASE_URL` values.
 - Do not assume `next start` is the Compute runtime path; Next.js deploys need standalone output.
 - Do not expose secret values from `.env`, CLI output, Management API responses, or logs.
+- Do not assume a stored OAuth login means the desired workspace is active; inspect or switch it explicitly.
+- Do not auto-switch to another cached workspace after logout or auth refresh failure.

prisma-compute/references/app-deploy-cli.md

@@ -29,30 +29,71 @@ Useful commands:
 ```bash
 bunx @prisma/cli@latest auth login
 bunx @prisma/cli@latest auth whoami
+bunx @prisma/cli@latest auth workspace list --json
+bunx @prisma/cli@latest auth workspace use <workspace-id-or-name>
+bunx @prisma/cli@latest auth workspace logout <workspace-id-or-name>
+bunx @prisma/cli@latest auth logout --workspace <workspace-id-or-name>
 bunx @prisma/cli@latest project list --json
 bunx @prisma/cli@latest project show
 bunx @prisma/cli@latest project link <project-id-or-name>
 bunx @prisma/cli@latest project create my-app
 ```
 
+Current `@prisma/cli` can keep multiple local browser-login workspace sessions. Running `auth login` again for a different workspace should add/update that workspace session and make it active; it should not delete the existing workspace session. The active workspace pointer decides which stored OAuth workspace normal commands use.
+
+For agents, prefer this flow before project/app mutations:
+
+```bash
+bunx @prisma/cli@latest auth whoami --json
+bunx @prisma/cli@latest auth workspace list --json
+bunx @prisma/cli@latest auth workspace use <workspace-id>
+```
+
+Use workspace ids from `auth workspace list --json` when possible. Names are friendlier for humans but can be ambiguous. For a human TTY, `auth workspace use` with no argument opens an interactive picker. For headless scripts, always pass an id or exact name.
+
+If the active workspace is logged out or its refresh fails, the CLI intentionally does not auto-select another cached workspace. Choose the next workspace explicitly:
+
+```bash
+bunx @prisma/cli@latest auth workspace list --json
+bunx @prisma/cli@latest auth workspace use <workspace-id>
+```
+
+To clean up one local OAuth workspace without clearing every stored workspace session:
+
+```bash
+bunx @prisma/cli@latest auth workspace logout <workspace-id-or-name>
+# equivalent:
+bunx @prisma/cli@latest auth logout --workspace <workspace-id-or-name>
+```
+
+Plain `auth logout` clears all local OAuth workspace sessions. It does not unset `PRISMA_SERVICE_TOKEN`.
+
 For a new linked project:
 
 ```bash
 bunx @prisma/cli@latest project create my-app --json
 ```
 
-For non-interactive or CI work, first verify the supported auth mechanism in current help/docs. If only browser login is available, tell the user that a human login step is required before scripted deploy.
-
-Current `@prisma/cli` source accepts a workspace service token through `PRISMA_SERVICE_TOKEN` before falling back to stored browser-login credentials:
+For non-interactive or CI work, first verify the supported auth mechanism in current help/docs. Current `@prisma/cli` accepts a workspace service token through `PRISMA_SERVICE_TOKEN`. A non-empty service token takes precedence over stored browser-login credentials, so local OAuth workspace switching does not affect command execution while the env var is set. `auth workspace list --json` may still show local OAuth sessions, but they are not switchable until the service-token env var is unset.
 
 ```bash
 test -n "${PRISMA_SERVICE_TOKEN:-}" && echo "PRISMA_SERVICE_TOKEN is set"
 bunx @prisma/cli@latest auth whoami
 bunx @prisma/cli@latest app deploy --json --no-interactive --prod --yes --env .env
 ```
 
+If `PRISMA_SERVICE_TOKEN` is set but empty, unset it or provide a real token. The CLI should fail instead of silently falling back to local OAuth credentials.
+
 Do not print the token value. Historical standalone Compute CLI examples and low-level SDK snippets may use `PRISMA_API_TOKEN`; do not assume that name works for `@prisma/cli app deploy` unless the current CLI source/help confirms it.
 
+Local auth storage is useful for debugging but should not be printed verbatim:
+
+- `PRISMA_COMPUTE_AUTH_FILE` can override the auth file path.
+- On macOS, the default OAuth credentials file is `~/Library/Application Support/prisma/auth.json`.
+- Workspace metadata and the active workspace pointer live beside it as `auth.context.json`.
+- Project pins live in `.prisma/local.json`.
+- Local CLI state such as selected app and known live deployment lives in `.prisma/cli/state.json`, rooted near `prisma.compute.ts` when a config is discovered.
+
 ## Project, Branch, Database, and Env Scope
 
 Compute deploys resolve a target project, app, and branch. Be explicit when the user's intent is not the already linked default project/app:

prisma-compute/references/troubleshooting.md

@@ -10,6 +10,7 @@ Run:
 bunx @prisma/cli@latest --help
 bunx @prisma/cli@latest app deploy --help
 bunx @prisma/cli@latest auth whoami
+bunx @prisma/cli@latest auth workspace list --json
 ```
 
 Then inspect:
@@ -59,15 +60,40 @@ Symptoms:
 - `project list` fails
 - `auth whoami` fails
 - browser login was not completed
+- commands use the wrong workspace after a second login
+- another workspace is stored locally but commands behave signed out
 - `PRISMA_SERVICE_TOKEN` is missing, empty, expired, or lacks workspace/project permissions
 
 Fix:
 
 ```bash
 bunx @prisma/cli@latest auth login
 bunx @prisma/cli@latest auth whoami
+bunx @prisma/cli@latest auth workspace list --json
 ```
 
+If multiple local OAuth workspaces exist, switch explicitly. Prefer ids from JSON:
+
+```bash
+bunx @prisma/cli@latest auth workspace use <workspace-id>
+bunx @prisma/cli@latest auth whoami --json
+bunx @prisma/cli@latest project list --json
+```
+
+For a human terminal, `auth workspace use` with no argument opens an interactive picker. In non-interactive or `--json` mode, use `auth workspace use <id-or-name>` instead.
+
+If the active workspace was logged out or its token refresh failed, the CLI intentionally stays signed out for OAuth commands rather than falling through to another cached workspace. Recover by running `auth workspace list --json` and then `auth workspace use <workspace-id>`.
+
+To remove only one local OAuth workspace session:
+
+```bash
+bunx @prisma/cli@latest auth workspace logout <workspace-id-or-name>
+# or:
+bunx @prisma/cli@latest auth logout --workspace <workspace-id-or-name>
+```
+
+Use plain `auth logout` only when you want to clear all local OAuth workspace sessions.
+
 For CI, current `@prisma/cli` can authenticate with `PRISMA_SERVICE_TOKEN`:
 
 ```bash
@@ -76,10 +102,39 @@ bunx @prisma/cli@latest auth whoami
 bunx @prisma/cli@latest app deploy --json --no-interactive --prod --yes --env .env
 ```
 
+If `PRISMA_SERVICE_TOKEN` is set and non-empty, it is the active auth source and local OAuth workspace switching is unavailable for command execution. Unset `PRISMA_SERVICE_TOKEN` before using `auth workspace use` to change local OAuth workspace context.
+
 If `PRISMA_SERVICE_TOKEN` is set but empty, the CLI errors before trying browser-login credentials. Unset it or provide a valid workspace service token. Never echo, log, or paste the token value; only check whether it is present.
 
 Older `@prisma/compute-cli` and SDK examples may use `PRISMA_API_TOKEN`. Treat that as legacy or SDK-specific until the current `@prisma/cli` source/help says otherwise.
 
+Local storage hints for debugging:
+
+- Override auth storage with `PRISMA_COMPUTE_AUTH_FILE` when isolating tests.
+- Default macOS OAuth credential file: `~/Library/Application Support/prisma/auth.json`.
+- Active workspace metadata sidecar: `~/Library/Application Support/prisma/auth.context.json`.
+- Project binding: `.prisma/local.json`.
+- Local app/project state: `.prisma/cli/state.json`, usually next to the discovered `prisma.compute.ts`.
+
+Do not print credential files or token values into logs.
+
+## Project Setup Fails
+
+Symptoms:
+
+- `PROJECT_SETUP_REQUIRED`
+- non-interactive deploy cannot choose a Project
+- deploy was expected to create a Project but did not
+
+Fix:
+
+```bash
+bunx @prisma/cli@latest app deploy --project <id-or-name> --json --no-interactive
+bunx @prisma/cli@latest app deploy --create-project <name> --yes
+```
+
+Do not rely on `--yes` alone to choose Project scope. `--project`, `--create-project`, and `PRISMA_PROJECT_ID` are mutually exclusive.
+
 ## Missing or Placeholder `DATABASE_URL`
 
 Symptoms:

prisma-compute/scripts/verify-compute-surface.mjs

@@ -36,6 +36,22 @@ const checks = [
       ["has app logs", /\blogs\b/],
     ],
   },
+  {
+    label: "@prisma/cli@latest auth workspace",
+    packageName: "@prisma/cli@latest",
+    args: ["auth", "workspace", "--help"],
+    probes: [
+      ["has workspace list", /\blist\b/],
+      ["has workspace use", /\buse\b/],
+      ["has workspace logout", /\blogout\b/],
+    ],
+  },
+  {
+    label: "@prisma/cli@latest auth logout",
+    packageName: "@prisma/cli@latest",
+    args: ["auth", "logout", "--help"],
+    probes: [["has --workspace", /--workspace\b/]],
+  },
   {
     label: "@prisma/cli@latest app deploy",
     packageName: "@prisma/cli@latest",
@@ -157,7 +173,7 @@ function firstUsefulLines(output) {
     .split("\n")
     .map((line) => line.trim())
     .filter((line) => line.length > 0)
-    .filter((line) => /(--deploy|--framework|--entry|--http-port|--env|--branch|--db|--no-db|--role|--project|--prod|app deploy|project env|database create|version|create-prisma|hono|elysia|next|tanstack|bun)/i.test(line))
+    .filter((line) => /(--deploy|--framework|--entry|--http-port|--env|--branch|--db|--no-db|--role|--project|--prod|--workspace|app deploy|auth workspace|auth logout|workspace|project env|database create|version|create-prisma|hono|elysia|next|tanstack|bun)/i.test(line))
     .slice(0, 12);
 }