@purveyors/cli 0.25.0 → 0.30.0

package/README.md

@@ -11,7 +11,7 @@ Use `purvey --help` for quick command discovery, `purvey context` for the dense
 - Official binary: `purvey`
 - Package: `@purveyors/cli`
 - Runtime: Node.js 20+
-- No pre-existing session required: `auth`, `config`, `context`, `manifest`
+- No pre-existing credentials required: `auth`, `config`, `context`, `manifest`
 - Viewer role required: `catalog` (excluding structured process filters on `catalog search`)
 - Member role required: `price-index`, `procurement`, `inventory`, `roast`, `sales`, `tasting`
 - Mixed public and entitled access: `market` public teaser slices are unauthenticated; filtered slices require Parchment Intelligence access
@@ -71,7 +71,7 @@ purvey auth login
 
 # If automatic browser callback handling fails or you paste a bad URL, paste the full callback URL back into the terminal. The CLI keeps waiting until a valid callback is received.
 
-# 2. Confirm the session and role
+# 2. Confirm the stored API key and role
 purvey auth status
 
 # 3. Search the catalog (viewer role for basic filters, member role for structured process filters)
@@ -133,17 +133,21 @@ Export discipline:
 
 ## Authentication and access model
 
-No pre-existing session is required for `auth`, `config`, `context`, or `manifest`.
+No pre-existing credentials are required for `auth`, `config`, `context`, or `manifest`.
 
-All remote data commands require a valid authenticated session:
+Remote data commands require a valid owner-bound API key with the required scope:
 
 - `catalog` requires the `viewer` role by default
-- `catalog search` structured process filters require the `member` role under the current session-authenticated CLI path
+- `catalog search` structured process filters require the `member` role
 - `market` has public teaser slices for `signals --summary`, unfiltered retail `stats`, and process/retail/month `metadata`; all filtered or non-public slices require Parchment Intelligence access enforced server-side
-- `price-index`, `procurement`, `inventory`, `roast`, `sales`, and `tasting` require the `member` role under the session-authenticated CLI path
+- `price-index`, `procurement`, `inventory`, `roast`, `sales`, and `tasting` require the `member` role
 
 `purvey` uses Google OAuth through purveyors.io.
 
+Set `PARCHMENT_API_KEY` (or `PURVEYORS_API_KEY`) to authenticate SDK-backed catalog,
+inventory, roast, sales, tasting-read, market, price-index, and procurement operations
+without using the API key created by `purvey auth login`. Environment credentials take precedence.
+
 Interactive login:
 
 ```bash
@@ -179,16 +183,16 @@ Credentials are stored at `~/.config/purvey/credentials.json`.
 
 ### Auth roles
 
-| Role     | Access                                                                                                                                                                                                       |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `viewer` | `catalog search`, `catalog get`, `catalog stats`, excluding structured process filters                                                                                                                       |
-| `member` | All viewer commands, `catalog similar`, structured process filters on `catalog search`, plus `price-index`, `procurement`, `inventory`, `roast`, `sales`, `tasting` under the session-authenticated CLI path |
+| Role     | Access                                                                                                                                                                                                                        |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `viewer` | `catalog search`, `catalog get`, `catalog stats`, excluding structured process filters                                                                                                                                        |
+| `member` | All viewer commands, `catalog similar`, structured process filters on `catalog search`, plus `price-index`, `procurement`, `inventory`, `roast`, `sales`, and `tasting` through the scoped key created by `purvey auth login` |
 
-Market Index teaser slices are public. Filtered `market signals`, origin/process/wholesale `market stats`, and non-public `market metadata` slices require Parchment Intelligence access; API-key and session-token denial is enforced by the canonical API.
+Market Index teaser slices are public. Filtered `market signals`, origin/process/wholesale `market stats`, and non-public `market metadata` slices require Parchment Intelligence access; API-key denial is enforced by the canonical API. The stored login key carries `catalog:read`, which is also the canonical read scope for Market Index, Price Index, and procurement.
 
-`auth`, `config`, `context`, and `manifest` remain available without a pre-existing session.
+`auth`, `config`, `context`, and `manifest` remain available without pre-existing credentials.
 
-Commands that require a higher role exit with code `3` on auth failure. That includes not being signed in, an expired session, or an insufficient role.
+Commands that require a higher role exit with code `3` on auth failure. That includes missing, revoked, or invalid credentials and an insufficient role.
 
 ## Output contract and scripting
 
@@ -246,15 +250,15 @@ The JSON error envelope includes:
 
 All `purvey` commands exit with a numeric code your scripts can check with `$?`.
 
-| Code | Meaning                                                          |
-| ---- | ---------------------------------------------------------------- |
-| `0`  | Success                                                          |
-| `1`  | Unexpected or unclassified error                                 |
-| `2`  | Invalid argument or bad input                                    |
-| `3`  | Auth error: not logged in, expired session, or insufficient role |
-| `4`  | Not found                                                        |
-| `5`  | Dependency conflict                                              |
-| `6`  | Local config error                                               |
+| Code | Meaning                                                            |
+| ---- | ------------------------------------------------------------------ |
+| `0`  | Success                                                            |
+| `1`  | Unexpected or unclassified error                                   |
+| `2`  | Invalid argument or bad input                                      |
+| `3`  | Auth error: missing, revoked, or invalid key; or insufficient role |
+| `4`  | Not found                                                          |
+| `5`  | Dependency conflict                                                |
+| `6`  | Local config error                                                 |
 
 Scripting pattern:
 
@@ -342,7 +346,6 @@ Notes:
 
 - Fields: `supplier`, `country`, `processing_base_method`, `fermentation_type`, `drying_method`, `grade`, `wholesale`
 - `--all`; use all visible catalog rows instead of the default stocked-only scope.
-- `--sample-size <n>`; catalog rows to sample before counting, default `5000`, max `5000`
 - `--limit <n>`; default `60`, max `100`
 
 `catalog rank` options:
@@ -403,14 +406,14 @@ purvey catalog get 1182 --include-proof --json
 Notes:
 
 - Catalog commands require an authenticated `viewer` role by default.
-- Structured process filters on `catalog search` require an authenticated `member` role under the current session-authenticated CLI path.
+- Structured process filters on `catalog search` require an authenticated `member` role.
 - Structured process filters use the canonical `/v1/catalog` query contract names while preserving the legacy `--process` label filter.
 - `--include-proof` is an opt-in API-backed catalog read. It consumes the canonical proof summary returned by `/v1/catalog?include=proof`; the CLI does not compute proof fields locally or duplicate web/API proof logic.
 - `--include-proof` rejects CLI-only filters that `/v1/catalog` cannot yet preserve exactly, such as `--flavor`, `--supplier`, `--drying-method`, and `--sort newest`.
-- If you want proof output against an API-key deployment, set `PARCHMENT_API_KEY` or `PURVEYORS_API_KEY` before running the command. Otherwise the CLI uses your logged-in Purveyors session token.
+- If you want proof output against a specific API-key deployment, set `PARCHMENT_API_KEY` or `PURVEYORS_API_KEY`. Otherwise the CLI uses the key created by `purvey auth login`.
 - `catalog get` and `catalog similar` both take `coffee_catalog.catalog_id`.
 - `catalog rank` and `catalog rank-premium` read `coffee_catalog.purveyor_score` as the canonical quality signal; the CLI does not recompute the upstream Purveyor Score model.
-- `catalog facets` and `catalog rank` are generic agent/client intelligence surfaces. Their responses include `stocked_only`/`scope` and sample metadata so callers do not mistake all-visible scope, sampled rarity, or sampled counts for whole-catalog guarantees.
+- `catalog facets` and `catalog rank` are generic agent/client intelligence surfaces. Facet counts come from the canonical API across the selected stocked/all-visible scope; ranking responses include sample metadata so callers do not mistake sampled rarity for whole-catalog guarantees.
 - Catalog intelligence responses include `meta.sample_limited`, `meta.sample_order`, `meta.truncated`, and rows-examined style metadata where relevant so agents can distinguish ranked samples from full supplier aggregates. Supplier aggregate responses also include `meta.rows_examined`.
 - Supplier aggregate commands summarize catalog row counts, stocked counts, Purveyor Score coverage, average score, average confidence, price range, origin/process coverage, and representative top coffees with score qualifiers.
 - `catalog similar` uses the beta canonical `/v1/catalog/{id}/similar` API contract, not the legacy direct RPC path.
@@ -497,7 +500,7 @@ Notes:
 
 - `market` commands are backed by canonical Parchment API endpoints through `@purveyors/sdk`; the CLI does not compute Market Index intelligence locally.
 - Public teaser slices: `signals --summary`, `stats` with no origin/process and `market=retail`, and `metadata` at dimension=process/no-origin/market=retail/grain=month.
-- Any filtered or non-public market slice requires Parchment Intelligence access, enforced server-side for both API-key and session-token calls.
+- Any filtered or non-public market slice requires Parchment Intelligence access, enforced server-side for API-key calls.
 - `--json` returns the API response verbatim.
 
 ### procurement
@@ -564,7 +567,6 @@ Notes:
 
 `inventory delete <id>` options:
 
-- `--force`; cascade dependent roasts and sales
 - `--yes`; skip confirmation prompt
 
 Examples:
@@ -579,9 +581,9 @@ purvey inventory delete 7 --yes
 
 Notes:
 
-- Inventory commands require an authenticated `member` role.
+- Inventory commands require an owner-bound member API key with the corresponding inventory scope.
 - Inventory `id` is `green_coffee_inv.id`, not `catalog_id`.
-- `inventory delete` may require `--force` if dependent roasts or sales exist.
+- `inventory delete` refuses to cascade. Delete dependent roasts or sales explicitly first.
 
 ### roast
 
@@ -677,7 +679,7 @@ Notes:
 
 `sales list` filters:
 
-- `--roast-id <id>`
+- `--coffee-id <id>`; green coffee inventory ID
 - `--date-start <YYYY-MM-DD>`
 - `--date-end <YYYY-MM-DD>`
 - `--buyer <name>`
@@ -686,7 +688,7 @@ Notes:
 
 `sales record` flags:
 
-- `--roast-id <id>`; exact selector mode
+- `--roast-id <id>`; resolve the sale inventory and batch from a roast profile
 - `--coffee-id <id>`; resolved selector mode, requires `--batch-name`
 - `--batch-name <name>`; resolved selector mode, requires `--coffee-id`
 - `--oz <amount>`; required in flag mode
@@ -719,8 +721,8 @@ purvey sales delete 5 --yes
 Notes:
 
 - Sales commands require an authenticated `member` role.
-- Use exactly one selector mode for `sales record`: exact `--roast-id`, or resolved `--coffee-id` plus `--batch-name`.
-- If resolved mode matches multiple roasts, rerun with `--roast-id`.
+- Use exactly one selector mode for `sales record`: `--roast-id`, or `--coffee-id` plus `--batch-name`.
+- Sales retain inventory and batch, not roast ID. Duplicate batch names on one inventory item are rejected even when selected through `--roast-id`.
 - `--price` is total sale price, not per-ounce price.
 
 ### tasting
@@ -759,9 +761,9 @@ purvey tasting rate --form
 
 Notes:
 
-- Tasting commands require an authenticated `member` role.
+- Tasting reads accept an owner-bound `tasting:read` API key.
 - `tasting get` combines supplier notes with your own notes when available.
-- `tasting rate` writes scores back to your inventory row.
+- `tasting rate` writes through the canonical Parchment tasting endpoint.
 
 ### config
 
@@ -874,16 +876,15 @@ Use the right ID for the right command.
 
 - `catalog_id`: `coffee_catalog` rows; used by `catalog get`, `catalog similar`, `inventory add --catalog-id`, `tasting get`, `roast list --catalog-id`
 - `inventory id`: `green_coffee_inv` rows; used by `inventory get/update/delete`, `roast --coffee-id`, `tasting rate`, `roast list --coffee-id`
-- `roast_id`: `roast_data` rows; used by `roast get/delete`, `sales --roast-id`, `roast list --roast-id`
-- `sales record` also supports resolving a roast from `inventory id` plus `--batch-name`; if that selector is ambiguous, use exact `roast_id`
+- `roast_id`: `roast_data` rows; used by `roast get/delete`, `sales record --roast-id`, `roast list --roast-id`
+- `sales record` also supports resolving a roast from `inventory id` plus `--batch-name`; because sales retain inventory + batch rather than roast ID, duplicate batch names on one inventory item are rejected
 - `sale id`: `coffee_sales` rows; used by `sales update/delete`
 
 ## Environment variables
 
-- `PURVEYORS_SUPABASE_URL`: override the Supabase project URL
-- `PURVEYORS_SUPABASE_ANON_KEY`: override the Supabase anon key
+- `PURVEYORS_SUPABASE_URL`: override the Supabase Auth issuer used only for OAuth bootstrap
 - `PURVEYORS_BASE_URL`: override the Purveyors web base URL
-- `PURVEYORS_API_KEY`: API-key token used by API-backed catalog proof reads, paid-tier similarity reads, and SDK-backed Parchment commands when you want to call canonical API contracts without relying on the local OAuth session
+- `PURVEYORS_API_KEY`: explicit API-key override for canonical Parchment commands
 - `PARCHMENT_API_KEY`: preferred API-key variable for SDK-backed Parchment commands; also accepted for API-backed proof and paid-tier similarity paths
 - `PARCHMENT_API_BASE_URL`: override the SDK-backed Parchment API base URL for `market`, `price-index`, and `procurement` commands
 - `PURVEY_DEBUG`: enable verbose error output
@@ -918,7 +919,7 @@ Agent integration rules of thumb:
 
 - Discover first with `purvey manifest`, then call the narrowest command or package subpath that fits the job.
 - Use `purvey context` when a human-readable operator summary is useful before tool selection.
-- Prefer OAuth session tokens for normal user workflows; use `PURVEYORS_API_KEY` or `PARCHMENT_API_KEY` only when you intentionally need an API-key-backed Parchment path such as catalog proof, paid-tier similarity, market intelligence, price-index, or procurement reads.
+- Use `purvey auth login` for normal user workflows. OAuth is used only to bootstrap a machine-scoped Parchment API key; the CLI does not retain Supabase session or refresh tokens. Environment `PURVEYORS_API_KEY` or `PARCHMENT_API_KEY` values remain available for explicit automation overrides.
 - Treat `--include-proof` as API output, not a local scoring feature. If a filter cannot round-trip through `/v1/catalog?include=proof`, the CLI rejects that invocation instead of returning misleading proof data.
 - Treat `catalog similar` as the canonical `/v1/catalog/{id}/similar` contract. Preserve the distinction between `canonical_candidates` and `similar_recommendations`; do not flatten or re-sort grouped results unless you have a specific downstream reason.
 - Treat `market`, `price-index`, and `procurement` as SDK-backed canonical API reads. Do not add procurement create/write behavior to this command group until the Phase 2 write contract ships.
@@ -935,7 +936,7 @@ purvey auth login --headless
 
 **Catalog commands fail after logging in**
 
-Run `purvey auth status` to confirm you have a `viewer` or `member` role. If the session is stale, run `purvey auth logout` and log in again.
+Run `purvey auth status` to confirm the stored CLI key is active and has a `viewer` or `member` role. If it is stale or revoked, run `purvey auth logout` and log in again.
 
 **Wrong ID type passed to a command**
 
@@ -954,7 +955,9 @@ purvey inventory list --limit 20 --offset 40
 **`inventory delete` fails with dependency conflict**
 
 ```bash
-purvey inventory delete 7 --force --yes
+purvey roast delete <roast-id> --yes
+purvey sales delete <sale-id> --yes
+purvey inventory delete 7 --yes
 ```
 
 **Enable verbose error output**
@@ -985,7 +988,7 @@ Key files:
 - `src/index.ts`: executable entrypoint
 - `src/program.ts`: top-level CLI registration and global options
 - `src/commands/`: command definitions and help text
-- `src/lib/`: business logic and Supabase integration
+- `src/lib/`: business logic and Parchment SDK integration
 - `src/commands/context.ts`: dense human-readable agent reference
 - `src/commands/manifest.ts`: machine-readable CLI manifest command
 - `src/lib/manifest.ts`: shared manifest contract, package export list, command metadata, ID guidance, and context renderer

package/dist/commands/auth.d.ts

@@ -1,4 +1,6 @@
 import { Command } from 'commander';
+import type { StoredCredentials } from '../types/index.js';
+import { type ParchmentClient } from '@purveyors/sdk';
 interface CallbackResult {
     accessToken: string;
     refreshToken: string;
@@ -9,12 +11,14 @@ interface ManualCallbackReader {
     close: () => void;
 }
 type ManualCallbackQuestion = (query: string, callback: (answer: string) => void) => void;
+export declare function createOAuthUrl(redirectTo: string): string;
+export declare function exchangeOAuthSessionForApiKey(accessToken: string, clientOverride?: ParchmentClient): Promise<StoredCredentials>;
 /**
  * Extract Supabase OAuth tokens from a full callback URL, URL fragment, or
  * query string. Exported for auth-flow contract tests.
  */
-export declare function parseOAuthCallbackUrl(callbackUrl: string): CallbackResult;
-export declare function createManualCallbackReaderForQuestion(question: ManualCallbackQuestion, closeQuestion: () => void, canRead: boolean): ManualCallbackReader | null;
+export declare function parseOAuthCallbackUrl(callbackUrl: string, expectedState?: string): CallbackResult;
+export declare function createManualCallbackReaderForQuestion(question: ManualCallbackQuestion, closeQuestion: () => void, canRead: boolean, expectedState?: string): ManualCallbackReader | null;
 /**
  * Build and return the `auth` command subtree.
  */

package/dist/commands/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,UAAU,cAAc;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAQD,UAAU,oBAAoB;IAC5B,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACjC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,KAAK,sBAAsB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,KAAK,IAAI,CAAC;AA6G1F;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAoCzE;AAED,wBAAgB,qCAAqC,CACnD,QAAQ,EAAE,sBAAsB,EAChC,aAAa,EAAE,MAAM,IAAI,EACzB,OAAO,EAAE,OAAO,GACf,oBAAoB,GAAG,IAAI,CAwC7B;AAoOD;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAkF1C"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,OAAO,KAAK,EAAiB,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI1E,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAwB7E,UAAU,cAAc;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AASD,UAAU,oBAAoB;IAC5B,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACjC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,KAAK,sBAAsB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,KAAK,IAAI,CAAC;AAE1F,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAKzD;AAiBD,wBAAsB,6BAA6B,CACjD,WAAW,EAAE,MAAM,EACnB,cAAc,CAAC,EAAE,eAAe,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAwC5B;AAsHD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,cAAc,CA2CjG;AAED,wBAAgB,qCAAqC,CACnD,QAAQ,EAAE,sBAAsB,EAChC,aAAa,EAAE,MAAM,IAAI,EACzB,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,oBAAoB,GAAG,IAAI,CAwC7B;AAsLD;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAmF1C"}

package/dist/commands/auth.js

@@ -1,14 +1,90 @@
 import { Command } from 'commander';
 import { createServer } from 'http';
-import { createAnonClient, validateSession } from '../lib/supabase.js';
+import { validateSession } from '../lib/auth-client.js';
 import { writeCredentials, deleteCredentials } from '../lib/config.js';
 import { outputData, shouldUseInteractiveOutput, success, info, warn } from '../lib/output.js';
 import { withErrorHandling, AuthError, exitCodeForError } from '../lib/errors.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import { createInterface } from 'readline';
+import { createParchmentClient } from '@purveyors/sdk';
+import { getParchmentBaseUrl } from '../lib/parchment-base.js';
+import { hostname } from 'os';
+import { randomUUID } from 'crypto';
 const DEFAULT_CALLBACK_HOST = 'localhost';
 const CALLBACK_PATH = '/auth/callback';
+const SUPABASE_AUTH_URL = process.env.PURVEYORS_SUPABASE_URL || 'https://bjblfzfdtfvuitqdbodn.supabase.co';
+const CLI_API_KEY_SCOPES = [
+    // The canonical API uses catalog:read for catalog, Market Index,
+    // Price Index, and procurement reads; those data planes do not define
+    // separate key scopes.
+    'catalog:read',
+    'inventory:read',
+    'inventory:write',
+    'roast:read',
+    'roast:write',
+    'sales:read',
+    'sales:write',
+    'tasting:read',
+    'tasting:write',
+];
+export function createOAuthUrl(redirectTo) {
+    const url = new URL('/auth/v1/authorize', SUPABASE_AUTH_URL);
+    url.searchParams.set('provider', 'google');
+    url.searchParams.set('redirect_to', redirectTo);
+    return url.toString();
+}
+function decodeSessionIdentity(accessToken) {
+    try {
+        const payload = JSON.parse(Buffer.from(accessToken.split('.')[1] ?? '', 'base64url').toString('utf8'));
+        return {
+            id: typeof payload.sub === 'string' ? payload.sub : 'unknown',
+            email: typeof payload.email === 'string' ? payload.email : 'unknown',
+            role: typeof payload.role === 'string' ? payload.role : undefined,
+        };
+    }
+    catch {
+        return { id: 'unknown', email: 'unknown' };
+    }
+}
+export async function exchangeOAuthSessionForApiKey(accessToken, clientOverride) {
+    const client = clientOverride ?? createParchmentClient({ baseUrl: getParchmentBaseUrl(), token: accessToken });
+    const me = await client.me();
+    if (!me.response.ok || me.error || !me.data?.authenticated || !me.data.userId) {
+        throw new AuthError('OAuth session could not be verified by Parchment.');
+    }
+    const keyName = `purvey-cli-${hostname()}`;
+    const existing = await client.apiKeys.list();
+    if (!existing.response.ok || existing.error) {
+        throw new AuthError('Failed to inspect existing CLI API keys.', existing.error);
+    }
+    const supersededKeys = (existing.data?.data ?? []).filter((key) => key.name === keyName && key.isActive);
+    const result = await client.apiKeys.create({
+        name: keyName,
+        scopes: [...CLI_API_KEY_SCOPES],
+    });
+    if (!result.response.ok || result.error || !result.data?.apiKey) {
+        throw new AuthError('Failed to create a scoped Parchment API key.', result.error);
+    }
+    for (const key of supersededKeys) {
+        const revoked = await client.apiKeys.revoke(key.id);
+        if (!revoked.response.ok || revoked.error) {
+            await client.apiKeys.revoke(result.data.key.id).catch(() => undefined);
+            throw new AuthError('Failed to replace the existing CLI API key.', revoked.error);
+        }
+    }
+    const identity = decodeSessionIdentity(accessToken);
+    return {
+        apiKey: result.data.apiKey,
+        keyId: result.data.key.id,
+        createdAt: result.data.key.createdAt ?? new Date().toISOString(),
+        user: {
+            ...identity,
+            id: me.data.userId,
+            role: me.data.primaryAppRole ?? identity.role,
+        },
+    };
+}
 /**
  * Start a one-shot local HTTP server to receive the Supabase OAuth callback.
  *
@@ -18,6 +94,7 @@ const CALLBACK_PATH = '/auth/callback';
  */
 function startCallbackServer() {
     return new Promise((resolve, reject) => {
+        const state = randomUUID();
         let tokenResolve;
         let tokenReject;
         const tokenPromise = new Promise((res, rej) => {
@@ -26,7 +103,7 @@ function startCallbackServer() {
         });
         const server = createServer((req, res) => {
             const url = new URL(req.url ?? '/', `http://${DEFAULT_CALLBACK_HOST}`);
-            if (url.pathname === CALLBACK_PATH) {
+            if (url.pathname === CALLBACK_PATH && url.searchParams.get('state') === state) {
                 res.writeHead(200, { 'Content-Type': 'text/html' });
                 res.end(`<!DOCTYPE html>
 <html>
@@ -43,6 +120,7 @@ function startCallbackServer() {
       access_token: params.get('access_token'),
       refresh_token: params.get('refresh_token'),
       expires_in: params.get('expires_in'),
+      state: new URLSearchParams(window.location.search).get('state'),
     })
   }).then(() => {
     document.body.innerHTML =
@@ -61,8 +139,8 @@ function startCallbackServer() {
                     res.end('ok');
                     server.close();
                     try {
-                        const { access_token, refresh_token, expires_in } = JSON.parse(body);
-                        if (!access_token || !refresh_token) {
+                        const { access_token, refresh_token, expires_in, state: callbackState, } = JSON.parse(body);
+                        if (!access_token || !refresh_token || callbackState !== state) {
                             tokenReject(new AuthError('OAuth callback did not include tokens. Try again.'));
                             return;
                         }
@@ -89,6 +167,7 @@ function startCallbackServer() {
             }
             resolve({
                 port: addr.port,
+                state,
                 tokenPromise,
                 close: () => {
                     try {
@@ -107,7 +186,7 @@ function startCallbackServer() {
  * Extract Supabase OAuth tokens from a full callback URL, URL fragment, or
  * query string. Exported for auth-flow contract tests.
  */
-export function parseOAuthCallbackUrl(callbackUrl) {
+export function parseOAuthCallbackUrl(callbackUrl, expectedState) {
     const trimmed = callbackUrl.trim();
     if (!trimmed) {
         throw new AuthError('No URL provided.');
@@ -129,6 +208,12 @@ export function parseOAuthCallbackUrl(callbackUrl) {
     const accessToken = params.get('access_token');
     const refreshToken = params.get('refresh_token');
     const expiresIn = params.get('expires_in');
+    if (expectedState) {
+        const parsedUrl = new URL(trimmed, 'http://localhost');
+        if (parsedUrl.searchParams.get('state') !== expectedState) {
+            throw new AuthError('OAuth callback state did not match this login attempt.');
+        }
+    }
     if (!accessToken || !refreshToken) {
         throw new AuthError('Could not extract tokens from the URL.\n' +
             '  Make sure you copied the full callback URL including the #access_token=... part.');
@@ -139,7 +224,7 @@ export function parseOAuthCallbackUrl(callbackUrl) {
         expiresIn: parseInt(expiresIn ?? '3600', 10),
     };
 }
-export function createManualCallbackReaderForQuestion(question, closeQuestion, canRead) {
+export function createManualCallbackReaderForQuestion(question, closeQuestion, canRead, expectedState) {
     if (!canRead)
         return null;
     let closed = false;
@@ -152,7 +237,7 @@ export function createManualCallbackReaderForQuestion(question, closeQuestion, c
                 if (closed)
                     return;
                 try {
-                    const callbackResult = parseOAuthCallbackUrl(answer);
+                    const callbackResult = parseOAuthCallbackUrl(answer, expectedState);
                     closed = true;
                     closeQuestion();
                     resolve(callbackResult);
@@ -177,14 +262,14 @@ export function createManualCallbackReaderForQuestion(question, closeQuestion, c
         },
     };
 }
-function createManualCallbackReader() {
+function createManualCallbackReader(expectedState) {
     if (!process.stdin.isTTY)
         return null;
     const rl = createInterface({
         input: process.stdin,
         output: process.stdout,
     });
-    return createManualCallbackReaderForQuestion(rl.question.bind(rl), () => rl.close(), process.stdin.isTTY);
+    return createManualCallbackReaderForQuestion(rl.question.bind(rl), () => rl.close(), process.stdin.isTTY, expectedState);
 }
 /**
  * `purvey auth login`
@@ -192,19 +277,12 @@ function createManualCallbackReader() {
  */
 const loginAction = withErrorHandling(async () => {
     const callbackServer = await startCallbackServer();
-    const { port, tokenPromise } = callbackServer;
-    const redirectTo = `http://${DEFAULT_CALLBACK_HOST}:${port}${CALLBACK_PATH}`;
+    const { port, state, tokenPromise } = callbackServer;
+    const redirectTo = `http://${DEFAULT_CALLBACK_HOST}:${port}${CALLBACK_PATH}?state=${encodeURIComponent(state)}`;
     try {
-        const supabase = createAnonClient();
-        const { data, error } = await supabase.auth.signInWithOAuth({
-            provider: 'google',
-            options: { redirectTo },
-        });
-        if (error || !data.url) {
-            throw new AuthError('Failed to generate OAuth URL.', error);
-        }
+        const oauthUrl = createOAuthUrl(redirectTo);
         console.log(chalk.bold('\n  Opening browser for authentication...'));
-        console.log(chalk.dim(`  If the browser does not open, visit:\n  ${data.url}\n`));
+        console.log(chalk.dim(`  If the browser does not open, visit:\n  ${oauthUrl}\n`));
         console.log(chalk.dim('  Waiting for the browser callback. If the browser lands on a localhost URL but\n' +
             '  the CLI does not finish, copy that full URL and paste it below.\n'));
         // Open browser cross-platform (graceful fallback for headless)
@@ -215,7 +293,7 @@ const loginAction = withErrorHandling(async () => {
                 : process.platform === 'win32'
                     ? 'start'
                     : 'xdg-open';
-            const child = spawn(openCmd, [data.url], { detached: true, stdio: 'ignore' });
+            const child = spawn(openCmd, [oauthUrl], { detached: true, stdio: 'ignore' });
             child.on('error', () => {
                 // Browser open failed (headless environment) — user can visit URL manually
             });
@@ -224,7 +302,7 @@ const loginAction = withErrorHandling(async () => {
         catch {
             // Gracefully ignore — URL is already printed above
         }
-        const manualReader = createManualCallbackReader();
+        const manualReader = createManualCallbackReader(state);
         const spinner = ora({ text: 'Waiting for authentication...', stream: process.stderr }).start();
         let callbackResult;
         try {
@@ -236,22 +314,9 @@ const loginAction = withErrorHandling(async () => {
         finally {
             manualReader?.close();
         }
-        const { accessToken, refreshToken, expiresIn } = callbackResult;
+        const { accessToken } = callbackResult;
         spinner.succeed('Authentication received');
-        // Fetch user info to confirm identity
-        const client = createAnonClient();
-        await client.auth.setSession({ access_token: accessToken, refresh_token: refreshToken });
-        const { data: { user }, } = await client.auth.getUser();
-        const creds = {
-            accessToken,
-            refreshToken,
-            expiresAt: Date.now() + expiresIn * 1000,
-            user: {
-                id: user?.id ?? 'unknown',
-                email: user?.email ?? 'unknown',
-                role: user?.role,
-            },
-        };
+        const creds = await exchangeOAuthSessionForApiKey(accessToken);
         await writeCredentials(creds);
         success(`Logged in as ${chalk.bold(creds.user.email)}`);
     }
@@ -289,12 +354,14 @@ const statusAction = withErrorHandling(async (_, cmd) => {
         authenticated: true,
         email: session.email,
         role: session.role ?? 'authenticated',
-        tokenExpires: new Date(session.expiresAt).toISOString(),
+        keyId: session.keyId,
+        keyCreated: session.createdAt,
     };
     if (isInteractive) {
         success(`Logged in as ${chalk.bold(session.email)}`);
         info(`Role: ${result.role}`);
-        info(`Token expires: ${result.tokenExpires}`);
+        info(`API key: ${result.keyId}`);
+        info(`Created: ${result.keyCreated}`);
         return;
     }
     outputData(result, opts);
@@ -305,18 +372,13 @@ const statusAction = withErrorHandling(async (_, cmd) => {
  */
 const headlessLoginAction = withErrorHandling(async () => {
     // Generate OAuth URL with purveyors.io callback page as redirect
-    const redirectTo = 'https://purveyors.io/auth/cli-callback';
-    const supabase = createAnonClient();
-    const { data, error } = await supabase.auth.signInWithOAuth({
-        provider: 'google',
-        options: { redirectTo, skipBrowserRedirect: true },
-    });
-    if (error || !data.url) {
-        throw new AuthError('Failed to generate OAuth URL.');
-    }
+    const state = randomUUID();
+    const redirectTo = new URL('https://purveyors.io/auth/cli-callback');
+    redirectTo.searchParams.set('state', state);
+    const oauthUrl = createOAuthUrl(redirectTo.toString());
     console.log(chalk.bold('\n  Headless Login\n'));
     console.log('  1. Open this URL in a browser and sign in:\n');
-    console.log(`     ${chalk.cyan(data.url)}\n`);
+    console.log(`     ${chalk.cyan(oauthUrl)}\n`);
     console.log("  2. After login, you'll see a page with a callback URL.");
     console.log('  3. Copy the full callback URL and paste it below.\n');
     // Read the callback URL from stdin
@@ -331,24 +393,9 @@ const headlessLoginAction = withErrorHandling(async () => {
     if (!callbackUrl) {
         throw new AuthError('No URL provided.');
     }
-    const { accessToken, refreshToken, expiresIn } = parseOAuthCallbackUrl(callbackUrl);
+    const { accessToken } = parseOAuthCallbackUrl(callbackUrl, state);
     const spinner = ora({ text: 'Validating session...', stream: process.stderr }).start();
-    const client = createAnonClient();
-    const { data: { user }, error: userError, } = await client.auth.getUser(accessToken);
-    if (userError || !user) {
-        spinner.fail('Token validation failed');
-        throw new AuthError('Invalid or expired token. Try the login flow again.');
-    }
-    const creds = {
-        accessToken,
-        refreshToken,
-        expiresAt: Date.now() + expiresIn * 1000,
-        user: {
-            id: user.id,
-            email: user.email ?? 'unknown',
-            role: user.role,
-        },
-    };
+    const creds = await exchangeOAuthSessionForApiKey(accessToken);
     await writeCredentials(creds);
     spinner.succeed(`Logged in as ${chalk.bold(creds.user.email)}`);
 });
@@ -358,7 +405,7 @@ const headlessLoginAction = withErrorHandling(async () => {
  */
 const logoutAction = withErrorHandling(async () => {
     await deleteCredentials();
-    success('Logged out successfully.');
+    warn('Local credentials cleared. The server API key remains active; revoke it from the Purveyors account key dashboard if this machine is lost or compromised.');
 });
 /**
  * Build and return the `auth` command subtree.
@@ -390,8 +437,8 @@ Examples:
 
 Notes:
   Credentials are stored at ~/.config/purvey/credentials.json (mode 0600).
-  Tokens auto-refresh; no need to re-login between sessions.
-  Uses Google OAuth via Supabase — same account as purveyors.io web app.
+  OAuth is used once to mint a scoped Parchment API key; session tokens are not retained.
+  Re-login replaces the prior CLI key for this machine.
 `);
     auth
         .command('status')
@@ -407,10 +454,11 @@ Examples:
   purvey auth status --json 2>/dev/null | jq .
 
 Output fields:
-  authenticated  boolean — true if a valid session exists
+  authenticated  boolean — true if the stored API key is valid
   email          your Google account email
   role           your purveyors.io role (viewer or member)
-  tokenExpires   ISO timestamp when the access token expires
+  keyId          identifier of the stored Parchment API key
+  keyCreated     ISO timestamp when the key was created
 
 Notes:
   When stdout is a TTY (interactive terminal), output is human-readable unless