@pitcher/cli-scripts 2.20.1 → 3.0.0

package/README.md

@@ -2,6 +2,16 @@
 
 > Pitcher CLI Tools provide a suite of command-line utilities to streamline your workflow. For the best experience, we recommend installing the tools globally using `npm install -g @pitcher/cli-scripts`.
 
+Releases are published to npm automatically: a merge to `main` that bumps `version` in `package.json` publishes that version, and a merge without a bump publishes nothing (`.github/workflows/cli-scripts-publish.yml`; release flow in `CLAUDE.md`).
+
+> ⚠️ **Breaking changes in 3.0.0**
+>
+> 1. **Local `p mcp` now serves ONLY 3 tools** (`pitcher_dev_sync`, `pitcher_dev_sync_revert`, `pitcher_publish_app`), down from 124. Everything else is the hosted server `https://pitcher-mcp.fly.dev/mcp`. `p mcp` no longer reads `NG_API_KEY`/`NG_ORG`/`NG_URL`/`NG_ENV`; run `p login` once (`--domain` or `PITCHER_DOMAIN` when logged in to several orgs).
+> 2. **Every other command uses your `p login` session.** `--api-key` (automation) still wins when passed; `NG_API_KEY` is used only when you have NO `p login` session, and is otherwise ignored with a notice. `--org` no longer defaults to `dev` on the session path: the session's org is the target. `--domain` cannot be combined with `--api-key` or `--org`.
+> 3. **The Claude Desktop `.mcpb` extension is retired.** Claude Desktop adds the remote URL natively.
+> 4. **`p analytics kpi` requires `--type`** (one of the 12 KPI types listed in `p analytics kpi --help`). The old default `all` always returned a 500.
+> 5. **Node ≥ 22.12** (`engines`).
+
 ## Help
 
 ```bash
@@ -10,62 +20,55 @@ p --help
 p command --help
 ```
 
-## MCP server
+## Sign in (`p login`)
 
-Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps one tool per CLI `run*` function: every command below (including `dsr create`/`get`/`update`/`delete`/`bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
+People sign in with their own Pitcher account; API keys are for automation (CI, deploy scripts).
 
 ```bash
-p mcp
-# or without a global install
-npx @pitcher/cli-scripts mcp
+p login --domain acme.my.pitcher.com      # opens the browser; --no-browser prints the URL instead
+p whoami                                  # every session: domain, environment, email, token expiry, status
+p logout acme.my.pitcher.com              # or: p logout --all
 ```
 
-### Environment variables
-
-Auth and org scope are resolved once at boot from environment variables. They are never tool inputs, so the model cannot change org or credentials mid-session.
+- **`p logout` is local only:** it deletes the session file and makes no Auth0 call. The refresh token is not revoked; it expires on its own. Your hosted MCP connectors (ChatGPT, Claude) are unaffected. A new `p login` over an existing session likewise just replaces the file. (Revoking is avoided on purpose: the CLI and the hosted server share one Auth0 client, and a revoke can delete the whole grant, signing every connector out.)
 
-- `NG_API_KEY` (required, secret): the API key the server authenticates as.
-- `NG_ORG` (default `dev`): organization subdomain, or set `NG_URL` directly for a full origin.
-- `NG_ENV` (`prod` or `test`): controls the destructive-hint guard on write tools (see below). When unset, anything other than the `dev` org (or, if `NG_URL` is set, anything other than `https://dev.my.pitcher.com`) is treated as production.
+- **One session per org domain.** Commands pick it with `--domain`, else `PITCHER_DOMAIN`, else the only session. Logged in to several orgs and nothing explicit → an error naming them (never a silent pick).
+- Sessions live in `${XDG_CONFIG_HOME:-~/.config}/pitcher/sessions/<domain>.json` (mode `0600`, directories `0700`). The access token refreshes itself; an expired session asks you to `p login` again.
+- The sign-in listener uses `http://127.0.0.1:53682/callback` only. Over SSH, forward port 53682 and use `--no-browser`.
+- **Precedence:** `--api-key` → your `p login` session → `NG_API_KEY`. With a session, `--org acme` (or `--url https://acme.my.pitcher.com`) selects the `acme` session; a `--url`/`--publish-url` on another host is refused rather than sent your token.
+- CI is unaffected: it passes `--api-key` and has no session.
 
-One config entry = one org, because the API key is org-specific. To work against multiple orgs, add multiple entries (e.g. `pitcher-dev`, `pitcher-prod`) with different env blocks; do not try to pass org per tool call.
-
-### Host config example (Claude Desktop / `.mcp.json`)
-
-```jsonc
-"pitcher": {
-  "command": "npx",
-  "args": ["-y", "@pitcher/cli-scripts", "mcp"],
-  "env": { "NG_API_KEY": "<key>", "NG_ORG": "dev" }
-}
-```
-
-### Tool annotations
+## MCP server
 
-- Read commands are marked `readOnlyHint`. `dev-sync` counts as a write (it mutates remote dev-override state).
-- `publish-app` is always marked `destructiveHint` (it creates a live, org-visible release). Other write tools get `destructiveHint` only when the resolved environment is production (`NG_ENV=prod`, or — with `NG_ENV` unset — a target other than `dev` / `dev.my.pitcher.com`). This steers hosts toward requiring extra confirmation before mutating a production org.
+Pitcher's MCP tools come from two places:
 
-### Desktop Extension (`.mcpb`)
+| Server | Tools | Add it with |
+|---|---|---|
+| **Hosted** (OAuth; Claude Code, Claude Desktop, claude.ai, ChatGPT) | everything: content, canvases, DSRs, analytics, L&D, users, … (121 tools, prompts, resources) | `claude mcp add --transport http pitcher https://pitcher-mcp.fly.dev/mcp` — Claude Desktop: Settings → Connectors → Add custom connector, same URL |
+| **Local** `p mcp` (stdio) | only `pitcher_dev_sync`, `pitcher_dev_sync_revert`, `pitcher_publish_app` (they zip a folder on YOUR machine) | `claude mcp add pitcher-local -- p mcp` |
 
-For one-click install in Claude Desktop (name + icon, an install-time API-key/org form, no hand-edited config, no Node prerequisite), build a `.mcpb` bundle:
+Claude Code users add both. The local server runs on your `p login` session (no API key, no env block); the domain is fixed when it starts. Signed in to several orgs? Add one entry per org:
 
-```bash
-yarn mcpb:pack        # → pitcher.mcpb (validated + packed)
+```jsonc
+"pitcher-local-acme": { "command": "p", "args": ["mcp", "--domain", "acme.my.pitcher.com"] }
 ```
 
-Install by double-clicking `pitcher.mcpb` (or Settings → Extensions → Install Extension). Claude Desktop prompts for the API key (stored in the OS keychain) and organization; both are editable afterward, so switching orgs needs no reinstall.
-
-The bundle reuses the same server as `p mcp` but registers a **content-tool subset (121)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
+- Auth and org are pinned when the server starts and are never tool inputs. The session token is refreshed before each tool call; after `p logout` the tools answer AUTH until you `p login` and restart the server.
+- `pitcher_publish_app` is always marked `destructiveHint`. `pitcher_dev_sync`/`_revert` get it unless the session's org is a test org (an unknown environment counts as production).
+- `dev-sync` is a one-shot sync as a tool; the continuous `watch` mode is CLI-only.
 
 This section is a reference only. For app-development conventions (modules, settings, mount points, SFDC), see the `pitcher-apps` skill, not this README.
 
 ## To run the `publish-app` command:
 
 ```bash
-# Basic usage
+# Signed in with p login: publishes to your session's org
+p publish-app <folder>
+
+# Automation (CI): an API key; --org picks the org
 p publish-app <folder> --org pitcher --api-key myapikey
 
-# Publish to current folder and default org (dev)
+# With an API key and no --org, the org is dev
 p publish-app --api-key myapikey
 
 # Publish to a specific organization subdomain (e.g., pitcher.my.pitcher.com)
@@ -103,11 +106,11 @@ p publish-app --org pitcher --increment-version --install-to-env-name Production
 Sync a marketplace app directly to S3 for live development testing without publishing. This is useful for testing app changes in a pre-production environment.
 
 ```bash
-# One-time sync from dist folder
-p dev-sync sync --file-id <pitcher_file_id> --api-key myapikey
+# One-time sync from dist folder (on your p login session)
+p dev-sync sync --file-id <pitcher_file_id>
 
-# Sync to a specific organization (default: dev)
-p dev-sync sync --file-id <pitcher_file_id> --org pitcher
+# Signed in to several orgs: pick one
+p dev-sync sync --file-id <pitcher_file_id> --domain pitcher.my.pitcher.com
 
 # Watch mode - auto-sync on file changes (reverts on Ctrl+C)
 p dev-sync watch --file-id <pitcher_file_id> --api-key myapikey
@@ -223,15 +226,12 @@ p canvases get 01CANVASID... --api-key myapikey
 
 ## To run the `shared-links` command:
 
-Create and read share links for canvases or files (returns the `short_url`).
+Create and read share links for canvases (returns the `short_url`).
 
 ```bash
 # Create a share link for a canvas
 p shared-links create --canvas-id 01CANVASID... --api-key myapikey
 
-# Create a share link for a file
-p shared-links create --file-id 01FILEID... --api-key myapikey
-
 # Fetch the existing share link for a canvas
 p shared-links get --canvas-id 01CANVASID... --api-key myapikey
 ```
@@ -352,7 +352,7 @@ p org get --api-key myapikey
 
 ## To run the `analytics` command:
 
-Read rollup analytics totals (`org`/`instance`), KPI metrics, and content/user engagement analytics. `org`/`instance` are Django rollups; `kpi` and the 7 verbs below hit the **clickhouse-api** service (`clickhouse.pitcher.com`) via the same env resolution as everything else — `--org`/`--url` pick the environment (routed via `x-original-domain`). Access **follows the key user's real role**: `popularity`, `users`, `files`, and `canvases` need an **org-admin** key; `engagement`, `viewers`, and `sessions` work with a member key. `kpi` and `sessions` return the raw payload; the other row-heavy verbs return a shaped envelope (`summary`, `rows`, `total_count`, `returned`, `has_more`, and sometimes `truncated`/`warnings`) capped by `--limit` (default 20, max 100). Date-range verbs default to a **30-day window** when `--start-date`/`--end-date` are omitted. `viewers` and `sessions` require `--canvas-id`; `sessions` also requires `--user`.
+Read rollup analytics totals (`org`/`instance`), KPI metrics, and content/user engagement analytics. `org`/`instance` are Django rollups; `kpi` and the 7 verbs below hit the **clickhouse-api** service (`clickhouse.pitcher.com`) via the same env resolution as everything else — `--org`/`--url` pick the environment (routed via `x-original-domain`). Access **follows the signed-in user's own role** (or the key user's, with an API key): `popularity`, `users`, `files`, and `canvases` need an **org-admin** key; `engagement`, `viewers`, and `sessions` work with a member key. `kpi` and `sessions` return the raw payload; the other row-heavy verbs return a shaped envelope (`summary`, `rows`, `total_count`, `returned`, `has_more`, and sometimes `truncated`/`warnings`) capped by `--limit` (default 20, max 100). Date-range verbs default to a **30-day window** when `--start-date`/`--end-date` are omitted. `viewers` and `sessions` require `--canvas-id`; `sessions` also requires `--user`.
 
 ```bash
 # Organization-wide rollups (org-admin key required)
@@ -362,7 +362,7 @@ p analytics org --api-key myapikey
 p analytics instance --instance-id 01... --api-key myapikey
 
 # KPI metrics from the clickhouse analytics service (PIT-7647).
-# Access follows the key user's real role on the instance; --org/--url pick the
+# Access follows the signed-in user's own role on the instance; --org/--url pick the
 # env exactly as for other commands (they route via x-original-domain).
 # Activity metrics need a date window; inventory counts (total-members, ...) do not.
 p analytics kpi --instance-id 01... --type total-members --api-key myapikey

package/dist/index.js

@@ -27,6 +27,7 @@ import { createMetadataTemplateCommand } from './src/commands/metadataTemplate.j
 import { createDsrCommand } from './src/commands/dsr.js';
 import { createLdCommand } from './src/commands/ld.js';
 import { createMcpCommand } from './src/commands/mcp.js';
+import { createLoginCommand, createLogoutCommand, createWhoamiCommand } from './src/commands/login.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -61,4 +62,7 @@ program.addCommand(createLdCommand());
 program.addCommand(createOrgCommand());
 program.addCommand(createAnalyticsCommand());
 program.addCommand(createMcpCommand());
+program.addCommand(createLoginCommand());
+program.addCommand(createLogoutCommand());
+program.addCommand(createWhoamiCommand());
 program.parseAsync(process.argv);

package/dist/src/commands/analytics.d.ts

@@ -22,9 +22,9 @@ export interface AnalyticsKpiOpts extends CommonOpts {
  * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
  * org api-key; the caller inherits the key user's real role. Dates are required
  * by the server for activity-metric types (inventory counts like
- * `total-members` need none) — that validation stays server-side, as does the
- * set of valid `type` values (a bad one comes back as a 400 listing them). There
- * is no aggregate `all` type, so `--type` is required.
+ * `total-members` need none) — that validation stays server-side. `--type` is
+ * required and checked against `KPI_TYPES` before any request (there is no
+ * aggregate `all` type; clickhouse-api also 400s a missing or unknown one).
  */
 export declare function runAnalyticsKpi(opts: AnalyticsKpiOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
 export interface AnalyticsEngagementOpts extends CommonOpts {

package/dist/src/commands/analytics.js

@@ -4,6 +4,7 @@ import { ok, fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
 import { withAuthFlags } from './withAuth.js';
+import { isKpiType, KPI_TYPES } from '../core/kpiTypes.js';
 import { shapeAnalytics, pageSizeFor, withDefaultWindow, todayIso } from '../core/analytics-shape.js';
 export async function runAnalyticsOrg(opts, deps = {}) {
     try {
@@ -32,16 +33,17 @@ export async function runAnalyticsInstance(opts, deps = {}) {
  * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
  * org api-key; the caller inherits the key user's real role. Dates are required
  * by the server for activity-metric types (inventory counts like
- * `total-members` need none) — that validation stays server-side, as does the
- * set of valid `type` values (a bad one comes back as a 400 listing them). There
- * is no aggregate `all` type, so `--type` is required.
+ * `total-members` need none) — that validation stays server-side. `--type` is
+ * required and checked against `KPI_TYPES` before any request (there is no
+ * aggregate `all` type; clickhouse-api also 400s a missing or unknown one).
  */
 export async function runAnalyticsKpi(opts, deps = {}) {
     try {
         if (!opts.instanceId)
             throw createCliError('VALIDATION', '--instance-id is required for analytics kpi');
-        if (!opts.type)
-            throw createCliError('VALIDATION', '--type is required for analytics kpi');
+        if (!opts.type || !isKpiType(opts.type)) {
+            throw createCliError('VALIDATION', `--type is required for analytics kpi, one of: ${KPI_TYPES.join(', ')}`);
+        }
         const client = clickhouseClientFor(opts, deps);
         const params = {
             instance_id: opts.instanceId,
@@ -380,7 +382,7 @@ export function createAnalyticsCommand() {
     });
     withAuthFlags(cmd.command('kpi'))
         .option('--instance-id <id>', 'Instance ID (required)')
-        .option('--type <type>', 'KPI type, e.g. total-members, total-active-users (required)')
+        .option('--type <type>', `KPI type (required), one of: ${KPI_TYPES.join(', ')}`)
         .option('--start-date <iso>', 'Window start (ISO date; required by the server for activity metrics)')
         .option('--end-date <iso>', 'Window end (ISO date; required by the server for activity metrics)')
         .option('--group-ids <csv>', 'Comma-separated distribution-group IDs to scope by')

package/dist/src/commands/announcements.js

@@ -70,9 +70,30 @@ export async function runAnnouncementsCreate(opts, deps = {}) {
             throw createCliError('VALIDATION', 'announcement requires non-empty string title and body (via --from-file or --title/--body)');
         }
         const client = clientFor(opts, deps);
-        // Deliberately omit `user_id`/`no_user_id`: omitting user_id yields the
-        // desired instance-shared row (see design §4.3); there is no --owned flag.
-        const res = await client.post(APPSDB_ENDPOINT, { type: ANNOUNCEMENT_TYPE, instance_id: opts.instanceId, data }, { params: { instance_id: opts.instanceId }, headers: { 'x-instance-id': opts.instanceId } });
+        const scope = { params: { instance_id: opts.instanceId }, headers: { 'x-instance-id': opts.instanceId } };
+        // An announcement must be an instance-SHARED row (user_id null), or reps cannot read it. An API key gets
+        // that by omitting user_id, but a user's JWT stamps the author unless an instance admin sends
+        // `no_user_id: true` (next-core appsdb/ownership.ts). The flag is harmless on the key path.
+        const res = await client.post(APPSDB_ENDPOINT, { type: ANNOUNCEMENT_TYPE, instance_id: opts.instanceId, data, no_user_id: true }, scope);
+        // A non-admin caller still gets the row created, user-owned (the server only logs a warning): remove it
+        // best-effort and fail, because it would be visible only to its author.
+        // The route always RETURNs user_id (appsdb/route.ts), so anything but null is a user-owned row.
+        const row = (res.data ?? {});
+        if (row.user_id !== null) {
+            const id = String(row.id);
+            let removed = false;
+            try {
+                await client.delete(`${APPSDB_ENDPOINT}/${encodeURIComponent(id)}`, scope);
+                removed = true;
+            }
+            catch {
+                removed = false;
+            }
+            throw createCliError('AUTH', 'Only instance admins can publish announcements (the row would have been visible only to you).' +
+                (removed
+                    ? ''
+                    : ` An unshared announcement row ${id} was created and could not be removed; delete it in appsDB by hand.`));
+        }
         return ok(res.data);
     }
     catch (e) {

package/dist/src/commands/devSync.d.ts

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import type { AxiosInstance } from 'axios';
-import { type Credential } from '../core/credential.js';
+import type { Credential } from '../core/credential.js';
 import { type Envelope } from '../core/envelope.js';
 interface AppJson {
     name: string;
@@ -19,7 +19,9 @@ interface DevSyncOptions {
     fileId: string;
     apiKey?: string;
     credential?: Credential;
+    domain?: string;
     org?: string;
+    url?: string;
     quiet?: boolean;
     output?: string;
 }

package/dist/src/commands/devSync.js

@@ -3,8 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import FormData from 'form-data';
 import chokidar from 'chokidar';
-import { credentialOf } from '../core/credential.js';
-import { resolveBaseUrl } from '../core/baseUrl.js';
+import { resolveRequestTarget } from '../core/target.js';
 import { makeClient, toCliError } from '../core/http.js';
 import { zipDirectoryToBuffer } from '../core/archive.js';
 import { ok, fail } from '../core/envelope.js';
@@ -32,11 +31,10 @@ export function readAppJson(distPath) {
 }
 export async function runDevSync(opts, deps = {}) {
     try {
-        const cred = credentialOf(opts);
-        const baseUrl = resolveBaseUrl(opts);
+        const target = resolveRequestTarget(opts);
         const distPath = findDistPath(deps.cwd);
         const appJson = readAppJson(distPath);
-        const client = deps.client ?? makeClient(baseUrl, cred);
+        const client = deps.client ?? makeClient(target.baseUrl, target.source);
         log(`Syncing ${appJson.name} from ${distPath}...`, { quiet: opts.quiet });
         const zip = await zipDirectoryToBuffer(distPath);
         log(`Zip created: ${(zip.length / 1024).toFixed(2)} KB`, { quiet: opts.quiet });
@@ -57,9 +55,8 @@ export async function runDevSync(opts, deps = {}) {
 }
 export async function runRevert(opts, deps = {}) {
     try {
-        const cred = credentialOf(opts);
-        const baseUrl = resolveBaseUrl(opts);
-        const client = deps.client ?? makeClient(baseUrl, cred);
+        const target = resolveRequestTarget(opts);
+        const client = deps.client ?? makeClient(target.baseUrl, target.source);
         const res = await client.delete(SYNC_ENDPOINT, {
             headers: { 'Content-Type': 'application/json' },
             data: { file_id: opts.fileId },
@@ -142,13 +139,15 @@ export function createDevSyncCommand() {
         .command('sync')
         .description('One-time sync of the app to S3')
         .requiredOption('--file-id <id>', 'File ID of the installed app (pitcher_file.id)')
-        .option('--api-key <apiKey>', 'API Key for authentication')
-        .option('--org <organization>', 'Organization subdomain', 'dev')
+        .option('--api-key <apiKey>', 'API key (CI/automation only; people use `p login`)')
+        .option('--domain <domain>', 'p login session to use, e.g. acme.my.pitcher.com (see p whoami)')
+        .option('--org <organization>', 'Organization subdomain (with --api-key: default dev; with a session: picks it)')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         const env = await runDevSync({
             fileId: options.fileId,
             apiKey: options.apiKey,
+            domain: options.domain,
             org: options.org,
             quiet: globals.quiet,
         });
@@ -158,14 +157,16 @@ export function createDevSyncCommand() {
         .command('watch')
         .description('Watch the dist folder and sync on changes')
         .requiredOption('--file-id <id>', 'File ID of the installed app (pitcher_file.id)')
-        .option('--api-key <apiKey>', 'API Key for authentication')
-        .option('--org <organization>', 'Organization subdomain', 'dev')
+        .option('--api-key <apiKey>', 'API key (CI/automation only; people use `p login`)')
+        .option('--domain <domain>', 'p login session to use, e.g. acme.my.pitcher.com (see p whoami)')
+        .option('--org <organization>', 'Organization subdomain (with --api-key: default dev; with a session: picks it)')
         .option('--debounce <ms>', 'Debounce time in milliseconds', '2500')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         await watchDevSync({
             fileId: options.fileId,
             apiKey: options.apiKey,
+            domain: options.domain,
             org: options.org,
             quiet: globals.quiet,
             output: globals.output,
@@ -175,13 +176,15 @@ export function createDevSyncCommand() {
         .command('revert')
         .description('Revert the dev override and restore the original version')
         .requiredOption('--file-id <id>', 'File ID of the installed app (pitcher_file.id)')
-        .option('--api-key <apiKey>', 'API Key for authentication')
-        .option('--org <organization>', 'Organization subdomain', 'dev')
+        .option('--api-key <apiKey>', 'API key (CI/automation only; people use `p login`)')
+        .option('--domain <domain>', 'p login session to use, e.g. acme.my.pitcher.com (see p whoami)')
+        .option('--org <organization>', 'Organization subdomain (with --api-key: default dev; with a session: picks it)')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         const env = await runRevert({
             fileId: options.fileId,
             apiKey: options.apiKey,
+            domain: options.domain,
             org: options.org,
             quiet: globals.quiet,
         });

package/dist/src/commands/login.d.ts

@@ -0,0 +1,83 @@
+import type { AddressInfo } from 'node:net';
+import { Command } from 'commander';
+import type { Credential } from '../core/credential.js';
+import { type Envelope } from '../core/envelope.js';
+import { type FetchFn } from '../core/pitcherAuth.js';
+import { type SessionCredentialOpts } from '../core/session.js';
+/** The loopback redirect registered on both Auth0 Native apps (`http://127.0.0.1:53682/callback`). */
+export declare const LOGIN_PORT = 53682;
+export interface LoginDeps {
+    fetch?: FetchFn;
+    /** Open the authorize URL. Default: `browserCommand` (`open` / `xdg-open` / `rundll32 url.dll`). */
+    openBrowser?: (url: string) => void;
+    /** Ask for the domain on a TTY. Default: readline on stderr. */
+    prompt?: (question: string) => Promise<string>;
+    isTty?: boolean;
+    /** Test seam: 0 = an ephemeral port (the redirect URI follows the bound port). */
+    port?: number;
+    timeoutMs?: number;
+    now?: () => number;
+    env?: NodeJS.ProcessEnv;
+    /** Test seam: observe the bound address. */
+    onListen?: (address: AddressInfo) => void;
+    quiet?: boolean;
+}
+export interface LoginResult {
+    domain: string;
+    environment?: string;
+    email?: string;
+    sub: string;
+    expiresAt: number;
+}
+/**
+ * The URL-opening command per platform. Windows uses the URL handler directly: through `cmd /c start`,
+ * cmd.exe would split the unquoted URL at its first `&` and drop client_id, state and the PKCE challenge.
+ */
+export declare function browserCommand(url: string, platform: NodeJS.Platform): [string, string[]];
+/** `GET /api/v1/users/me/` with the bearer: proves the token works on Django and yields the email. */
+export declare function fetchMe(domain: string, cred: Credential, doFetch: FetchFn): Promise<{
+    email?: string;
+}>;
+export declare function runLogin(opts: {
+    domain?: string;
+    browser?: boolean;
+}, deps?: LoginDeps): Promise<Envelope<LoginResult>>;
+export interface LogoutDeps {
+    fetch?: FetchFn;
+    env?: NodeJS.ProcessEnv;
+    quiet?: boolean;
+}
+export declare function runLogout(opts: {
+    domain?: string;
+    all?: boolean;
+}, deps?: LogoutDeps): Promise<Envelope<{
+    loggedOut: string[];
+}>>;
+export interface WhoamiRow {
+    domain: string;
+    environment?: string;
+    email?: string;
+    /** access-token expiry, epoch seconds */
+    expiresAt?: number;
+    status: string;
+}
+export interface WhoamiDeps {
+    fetch?: FetchFn;
+    env?: NodeJS.ProcessEnv;
+    session?: Omit<SessionCredentialOpts, 'env'>;
+}
+/**
+ * One whoami row's status, matched on the specific failure (never "any AUTH"): only a session Auth0 or Django
+ * no longer accepts is `expired`; a held lock is `busy`; a file we refuse to read is `invalid session file`;
+ * anything else (network, 5xx) is `unreachable`.
+ */
+export declare function whoamiStatus(domain: string, e: unknown): string;
+/** Never reads `--api-key`/`NG_API_KEY`; never returns a token. One bad session never fails the listing. */
+export declare function runWhoami(opts: {
+    domain?: string;
+}, deps?: WhoamiDeps): Promise<Envelope<{
+    sessions: WhoamiRow[];
+}>>;
+export declare function createLoginCommand(): Command;
+export declare function createLogoutCommand(): Command;
+export declare function createWhoamiCommand(): Command;