@moda-ai/cli 1.12.6 → 1.13.1

package/dist/init/tenant.js

@@ -1,36 +1,144 @@
 // src/init/tenant.ts — Tenant selection and API key provisioning
 import { select } from '@inquirer/prompts';
-import { authFetch } from '../auth.js';
-import { resolveIngestUrl, saveCliConfig } from '../config.js';
-import { CliInputError, CliInputRequiredError } from '../errors.js';
+import { authFetch, getCachedLoginContext } from '../auth.js';
+import { loadCliConfig, resolveIngestUrl, resolveModaBaseUrl, saveCliConfig, } from '../config.js';
+import { resolveApiKeyFromActiveProfile, resolveTenantIdFromActiveProfile, } from '../profiles.js';
+import { CliAccessError, CliInputError, CliInputRequiredError } from '../errors.js';
+// Mirrors the backend's checkAdminAccess: only the viewer role is denied.
+const ADMIN_ACCESS_MESSAGE = 'You need admin or owner access to create API keys.';
+const ADMIN_ACCESS_GUIDANCE = 'Ask your organization owner to upgrade your role.';
+const API_KEY_PREFIX = 'moda_sk_';
+const SIGNED_KEY_VERSION = 'v1';
+// Bound the pre-bootstrap liveness probe tightly: a slow or unreachable
+// endpoint must never block init — we just mint a fresh key instead.
+const VALIDATE_TIMEOUT_MS = 3_000;
+/**
+ * Signed CLI keys embed their tenant: the format is
+ * moda_sk_<base64url("v1:keyId:tenantId:timestamp:signature")> — see
+ * createApiKey/parseAndVerifySignedKey in
+ * apps/moda-backend/src/api-keys/api-keys.service.ts. Decoding locally lets
+ * dedup reject a cross-tenant or malformed key structurally, with no network
+ * call. The HMAC signature can only be verified server-side; liveness (not
+ * revoked) is probed separately by isStoredKeyLive().
+ */
+function embeddedTenantId(key) {
+    if (!key.startsWith(API_KEY_PREFIX))
+        return undefined;
+    try {
+        const decoded = Buffer.from(key.slice(API_KEY_PREFIX.length), 'base64url').toString('utf8');
+        // Expected format: version:keyId:tenantId:timestamp:signature
+        const parts = decoded.split(':');
+        if (parts.length !== 5 || parts[0] !== SIGNED_KEY_VERSION)
+            return undefined;
+        return parts[2] || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Liveness probe for a stored key. Deliberately NOT the backend's public
+ * POST /api/api-keys/validate: the CLI's resolved base URL is the FRONTEND
+ * origin (moda.dev in prod, localhost:3000 in dev), which has no
+ * /api/api-keys/validate route and no rewrite for it — only /api/v1/data/* is
+ * proxied to the backend. Probing the Data API is the only path that reaches
+ * key validation from here; revisit when a validate proxy is added. Only a
+ * 200 with a JSON body counts as live; 401/403 (revoked/invalid), any other
+ * status, a non-JSON 200 (e.g. a frontend error page), a network error, or a
+ * timeout all return false so init falls through to minting — never block.
+ * The key value must never appear in logs, errors, or telemetry.
+ */
+async function isStoredKeyLive(key, options = {}) {
+    try {
+        // Resolve the base URL with the same profile/env context as the stored-key
+        // lookup, or a valid key for a non-active profile (e.g. `init --profile
+        // staging` while prod is active) is probed against the wrong origin, read
+        // as dead, and re-minted on every run.
+        const response = await fetch(`${resolveModaBaseUrl(options)}/api/v1/data/overview`, {
+            method: 'GET',
+            headers: { 'x-api-key': key },
+            signal: AbortSignal.timeout(VALIDATE_TIMEOUT_MS),
+        });
+        if (response.status !== 200)
+            return false;
+        await response.json();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A CLI key previously stored for this tenant, if any: the legacy
+ * ~/.moda/config.json first, then the active profile's key reference. Only a
+ * key whose stored tenant_id matches the selected tenant is a candidate.
+ */
+function findStoredKeyForTenant(tenantId, options = {}) {
+    const legacy = loadCliConfig(options);
+    if (legacy.api_key && legacy.tenant_id === tenantId) {
+        return legacy.api_key;
+    }
+    // Honors options.profile when init was run with --profile; otherwise the
+    // active profile / MODA_PROFILE resolution applies.
+    if (resolveTenantIdFromActiveProfile(options) === tenantId) {
+        const profileKey = resolveApiKeyFromActiveProfile(options);
+        if (profileKey)
+            return profileKey;
+    }
+    return undefined;
+}
 export async function selectTenantAndCreateKey(options = {}) {
-    // 1. Fetch CLI context
-    const contextRes = await authFetch('/api/cli/context');
-    if (!contextRes.ok) {
-        const body = await contextRes.text();
-        throw new Error(`Failed to fetch context (${contextRes.status}): ${body}`);
-    }
-    const ctx = (await contextRes.json());
-    if (!options.silent)
-        console.log(`  Authenticated as ${ctx.user.email}`);
+    const log = (message) => {
+        if (!options.silent)
+            console.log(message);
+    };
+    // Auth-session reads and stored-key lookups must honor init's --profile, or
+    // a profile-scoped login (secrets/auth/<profile>.json) is invisible here and
+    // init fails with "Not authenticated" despite a fresh token.
+    const authOptions = {
+        profile: options.profile,
+        env: options.env,
+    };
+    // 1. Fetch CLI context. A PKCE login that just ran in this process already
+    // returned the user + tenants in the exchange response; reuse it and skip
+    // one /api/cli/context round-trip. The cache is profile-keyed (a login for
+    // a different profile returns null here), and the fetch stays as the
+    // fallback for cached-token runs (no login happened) and legacy logins.
+    let ctx;
+    const cachedContext = getCachedLoginContext(authOptions);
+    if (cachedContext) {
+        ctx = cachedContext;
+    }
+    else {
+        const contextRes = await authFetch('/api/cli/context', {}, authOptions);
+        if (!contextRes.ok) {
+            const body = await contextRes.text();
+            throw new Error(`Failed to fetch context (${contextRes.status}): ${body}`);
+        }
+        ctx = (await contextRes.json());
+    }
+    log(`  Authenticated as ${ctx.user.email}`);
     // 2. Select tenant
     if (ctx.tenants.length === 0) {
-        throw new CliInputError('No organizations found. Create one at https://moda.dev', 'Create an organization in Moda, then rerun `moda init`.');
+        throw new CliAccessError('No organizations found. Create one at https://moda.dev');
     }
-    let tenantId;
-    if (options.tenantId) {
-        const selected = ctx.tenants.find((tenant) => tenant.id === options.tenantId);
-        if (!selected) {
-            throw new CliInputError(`Tenant '${options.tenantId}' is not available for the authenticated user.`, 'Run `moda init` without --tenant-id in a human terminal, or choose a tenant from the needs_input event.');
+    let selected;
+    if (options.tenantId !== undefined) {
+        // Exact id match only (case-sensitive; never slug/name, never a silent
+        // fallback to another tenant).
+        const match = ctx.tenants.find((tenant) => tenant.id === options.tenantId);
+        if (!match) {
+            const valid = ctx.tenants
+                .map((tenant) => `  ${tenant.id}  ${tenant.name} (${tenant.role})`)
+                .join('\n');
+            throw new CliInputError(`No organization with id '${options.tenantId}'. Valid organizations:\n${valid}`, 'Re-run with --tenant-id=<id> using one of the ids listed above.');
         }
-        tenantId = selected.id;
-        if (!options.silent)
-            console.log(`  Organization: ${selected.name}`);
+        selected = match;
+        log(`  Organization: ${selected.name}`);
     }
     else if (ctx.tenants.length === 1) {
-        tenantId = ctx.tenants[0].id;
-        if (!options.silent)
-            console.log(`  Organization: ${ctx.tenants[0].name}`);
+        selected = ctx.tenants[0];
+        log(`  Organization: ${selected.name}`);
     }
     else if (options.nonInteractive) {
         throw new CliInputRequiredError('Multiple Moda organizations are available; choose one and re-run with --tenant-id.', {
@@ -46,28 +154,52 @@ export async function selectTenantAndCreateKey(options = {}) {
         }, 'Re-run `moda init --tenant-id <tenant_id>`.');
     }
     else {
-        tenantId = await select({
+        selected = await select({
             message: 'Select organization',
-            choices: ctx.tenants.map((t) => ({
-                name: `${t.name} (${t.role})`,
-                value: t.id,
+            choices: ctx.tenants.map((tenant) => ({
+                name: `${tenant.name} (${tenant.role})`,
+                value: tenant,
             })),
         });
     }
-    // 3. Create API key via bootstrap endpoint
-    const bootstrapRes = await authFetch('/api/cli/bootstrap', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ tenantId }),
-    });
-    if (bootstrapRes.status === 403) {
-        throw new CliInputError('You need admin or owner access to create API keys.', 'Ask your organization owner to upgrade your role.');
+    // Role pre-check: the backend's bootstrap endpoint 403s viewers, so fail
+    // before creating anything. The 403 handler below stays as a backstop.
+    if (selected.role.toLowerCase() === 'viewer') {
+        throw new CliAccessError(ADMIN_ACCESS_MESSAGE, { guidance: ADMIN_ACCESS_GUIDANCE });
+    }
+    // 3. Reuse a previously minted key for this tenant when it structurally
+    // belongs to it (embedded tenant id) AND still works against the Data API,
+    // so re-running init does not accumulate one CLI key per run. A failed
+    // decode, tenant mismatch, or probe failure falls through to minting.
+    let result;
+    const storedKey = findStoredKeyForTenant(selected.id, authOptions);
+    if (storedKey &&
+        embeddedTenantId(storedKey) === selected.id &&
+        (await isStoredKeyLive(storedKey, authOptions))) {
+        log(`  Using existing CLI key for ${selected.name} (created earlier)`);
+        result = {
+            apiKey: storedKey,
+            tenantId: selected.id,
+            tenantName: selected.name,
+            tenantSlug: selected.slug,
+        };
     }
-    if (!bootstrapRes.ok) {
-        const body = await bootstrapRes.text();
-        throw new Error(`Failed to create API key (${bootstrapRes.status}): ${body}`);
+    // 4. Create API key via bootstrap endpoint
+    if (!result) {
+        const bootstrapRes = await authFetch('/api/cli/bootstrap', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ tenantId: selected.id }),
+        }, authOptions);
+        if (bootstrapRes.status === 403) {
+            throw new CliAccessError(ADMIN_ACCESS_MESSAGE, { guidance: ADMIN_ACCESS_GUIDANCE });
+        }
+        if (!bootstrapRes.ok) {
+            const body = await bootstrapRes.text();
+            throw new Error(`Failed to create API key (${bootstrapRes.status}): ${body}`);
+        }
+        result = (await bootstrapRes.json());
     }
-    const result = (await bootstrapRes.json());
     // Persist to ~/.moda/config.json (mode 0600) so the snapshot/session-end
     // hook can authenticate (api_key) and the local dev orchestrator can scope
     // ClickHouse (tenant_id) without the user exporting env vars into the shell
@@ -75,12 +207,17 @@ export async function selectTenantAndCreateKey(options = {}) {
     saveCliConfig({
         api_key: result.apiKey,
         tenant_id: result.tenantId,
-        ingest_url: resolveIngestUrl(),
-    });
-    if (!options.silent) {
-        console.log('  API key + tenant saved to ~/.moda/config.json\n');
-        console.log('  (Set MODA_API_KEY / MODA_TENANT_ID to override for scripts/CI.)\n');
+        ingest_url: resolveIngestUrl(authOptions),
+    }, authOptions);
+    // resolveTenantId() prefers MODA_TENANT_ID over the config file, so a stale
+    // env var silently shadows the selection we just saved. Warn unless the env
+    // var was itself the source of the selection.
+    const envTenantId = (options.env ?? process.env).MODA_TENANT_ID;
+    if (envTenantId && options.tenantIdSource !== 'env' && envTenantId !== result.tenantId) {
+        console.error(`  Warning: MODA_TENANT_ID is set to a different organization id and will shadow the saved selection (${result.tenantId}) for later commands. Unset it or set it to the selected organization id.`);
     }
+    log('  API key + tenant saved to ~/.moda/config.json\n');
+    log('  (Set MODA_API_KEY / MODA_TENANT_ID to override for scripts/CI.)\n');
     return result;
 }
 //# sourceMappingURL=tenant.js.map

package/dist/output.d.ts

@@ -19,7 +19,7 @@ export declare const EXIT_DEGRADED = 3;
 export declare const EXIT_AUTH_REQUIRED = 4;
 export declare const EXIT_INPUT_REQUIRED = 5;
 export declare const EXIT_CANCELLED = 130;
-export declare const AGENT_ERROR_CODES: readonly ["input_error", "api_error", "network_error", "auth_required", "input_required", "cancelled", "command_error", "unknown_error", "cloud_unavailable"];
+export declare const AGENT_ERROR_CODES: readonly ["input_error", "api_error", "network_error", "auth_required", "input_required", "cancelled", "command_error", "access_denied", "unknown_error", "cloud_unavailable"];
 export type AgentErrorCode = typeof AGENT_ERROR_CODES[number];
 export type AgentStatus = 'ok' | 'degraded' | 'error';
 export type AgentConfidence = 'high' | 'medium' | 'low' | 'unknown';

package/dist/output.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { CliAuthError, CliCancellationError, CliInputError, CliInputRequiredError, isApiLikeError, isNetworkLikeError, } from './errors.js';
+import { CliAccessError, CliAuthError, CliCancellationError, CliInputError, CliInputRequiredError, isApiLikeError, isNetworkLikeError, } from './errors.js';
 import { redactDeep } from './redact.js';
 export const AGENT_SCHEMA_VERSION = 'moda.agent.v1';
 export const AGENT_EVENT_SCHEMA_VERSION = 'moda.agent_event.v1';
@@ -28,6 +28,7 @@ export const AGENT_ERROR_CODES = [
     'input_required',
     'cancelled',
     'command_error',
+    'access_denied',
     'unknown_error',
     'cloud_unavailable',
 ];
@@ -416,6 +417,16 @@ export function errorToAgentError(error) {
             blocking: true,
         };
     }
+    if (error instanceof CliAccessError) {
+        // Access problem (missing organization or insufficient role), not
+        // auth-missing: exit stays EXIT_ERROR and no login command is suggested.
+        return {
+            code: 'access_denied',
+            message: error.message,
+            cause: error.guidance,
+            blocking: true,
+        };
+    }
     if (error instanceof Error) {
         if (error instanceof CliInputError || error.name === 'ZodError') {
             return {

package/dist/profile-commands.js

@@ -1,7 +1,11 @@
-import { authFetch, clearAuthSession, loadAuthSession, login } from './auth.js';
+import { authFetch, clearAuthSession, isAuthSessionValid, loadAuthSession, login, revokeCliSessionToken, } from './auth.js';
+import { EXIT_AUTH_REQUIRED, EXIT_OK } from './output.js';
 import { KEY_LIFECYCLE_ENDPOINT_REQUIREMENTS, createLocalKeyDescriptor, loadLocalKeyDescriptors, upsertLocalKeyDescriptor, writeLocalApiKeySecret, } from './keys.js';
 import { DEFAULT_INGEST_URL, PROD_BASE_URL, ensureSecretFilePermissions, getActiveProfile, getModaPaths, loadProfileConfig, resolveApiKeyFromActiveProfile, resolveSecretReference, secretFilePathFromRef, setActiveProfile, upsertProfile, } from './profiles.js';
 import { CliInputError } from './errors.js';
+// Bound the `auth status --online` probe: without a signal, undici's defaults
+// can stall a status check for minutes on a black-holed connection.
+const ONLINE_PROBE_TIMEOUT_MS = 5_000;
 function subcommand(context) {
     return context.positionals[0];
 }
@@ -60,7 +64,7 @@ export async function runAuthCommand(context) {
     switch (subcommand(context)) {
         case 'login': {
             const screen = flag(context, 'screen') === 'signup' ? 'signup' : 'login';
-            await login(screen);
+            await login(screen, { profile: context.profile, env: context.env });
             context.output.writeData({
                 status: 'authenticated',
                 profile: context.profile ?? process.env.MODA_PROFILE ?? null,
@@ -68,6 +72,10 @@ export async function runAuthCommand(context) {
             return { exitCode: 0 };
         }
         case 'logout': {
+            // moda_ct session tokens are server-side revocable: best-effort revoke
+            // (bounded, catch-all inside) before the local deletion. Legacy
+            // auth0-kind sessions have nothing to revoke.
+            await revokeCliSessionToken({ profile: context.profile, env: context.env });
             clearAuthSession({ profile: context.profile, env: context.env });
             context.output.writeData({
                 status: 'logged_out',
@@ -96,8 +104,78 @@ export async function runAuthCommand(context) {
             });
             return { exitCode: 0 };
         }
+        case 'status': {
+            // Being logged out is an expected state for `auth status`, not a
+            // failure: it must never throw CliAuthError (no error block, no error
+            // telemetry classification) and must never trigger a browser open. It
+            // reports clean data in every mode and signals session validity purely
+            // through the exit code (0 valid, 4 auth required).
+            const authOptions = { profile: context.profile, env: context.env };
+            const session = loadAuthSession({ ...authOptions, includeExpired: true });
+            const loggedIn = isAuthSessionValid(session);
+            const data = {
+                loggedIn,
+                profile: context.profile ??
+                    context.env.MODA_PROFILE ??
+                    session?.profile ??
+                    null,
+                expiresAt: session
+                    ? new Date(session.expires_at * 1000).toISOString()
+                    : null,
+            };
+            // `user` is emitted only when the stored session carries an email —
+            // the PKCE exchange path persists user_email; legacy sessions lack it.
+            if (session?.user_email) {
+                data.user = { email: session.user_email };
+            }
+            if (boolFlag(context, 'online')) {
+                let online = { reachable: false };
+                try {
+                    const response = await authFetch('/api/cli/context', { signal: AbortSignal.timeout(ONLINE_PROBE_TIMEOUT_MS) }, authOptions);
+                    // Any HTTP response means the server was reached; `ok` separates a
+                    // healthy 2xx from e.g. a 401/500.
+                    online = { reachable: true, ok: response.ok };
+                    if (response.ok) {
+                        const body = await response.json();
+                        if (Array.isArray(body.tenants)) {
+                            online.tenantCount = body.tenants.length;
+                        }
+                    }
+                }
+                catch {
+                    // Network failure, probe timeout, or no stored token to send: report
+                    // reachable: false; the exit code still follows local session
+                    // validity, never the online probe.
+                }
+                data.online = online;
+            }
+            context.output.writeData(data);
+            return { exitCode: loggedIn ? EXIT_OK : EXIT_AUTH_REQUIRED };
+        }
+        case 'token': {
+            const session = loadAuthSession({ profile: context.profile, env: context.env });
+            if (!session) {
+                if (context.flags.json === 'true') {
+                    // An explicit --json caller gets a parseable failure on stdout.
+                    process.stdout.write(`${JSON.stringify({ error: 'not_authenticated' })}\n`);
+                }
+                else {
+                    console.error('Not authenticated. Run "moda auth login".');
+                }
+                return { exitCode: EXIT_AUTH_REQUIRED };
+            }
+            // `auth token` exists to compose as $(moda auth token) and in pipes.
+            // Command substitution IS a pipe, so stdout is a non-TTY and this CLI
+            // would auto-select agent mode and wrap the token in a JSON envelope,
+            // breaking every composition. This command therefore deliberately
+            // bypasses the CliOutput envelope machinery in EVERY output mode
+            // (human/json/agent/agent-stream) and writes exactly the bare token plus
+            // a trailing newline to stdout — nothing else.
+            process.stdout.write(`${session.access_token}\n`);
+            return { exitCode: EXIT_OK };
+        }
         default:
-            throw new CliInputError('Unknown auth command.', 'Usage: moda auth <login|logout|whoami>');
+            throw new CliInputError('Unknown auth command.', 'Usage: moda auth <login|logout|status|token|whoami>');
     }
 }
 export async function runProfilesCommand(context) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.12.6",
+  "version": "1.13.1",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-07-06T09:38:49.718Z",
-  "cli_version": "1.12.6",
+  "bundled_at": "2026-07-06T10:28:52.049Z",
+  "cli_version": "1.13.1",
   "skills": [
     {
       "id": "integration-node-anthropic",

package/skills/moda-cli/SKILL.md

@@ -78,6 +78,53 @@ npx -p @moda-ai/cli moda <command>
 export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
 ```
 
+### Auth session inspection and token composition
+
+```bash
+moda auth login                  # browser PKCE sign-in; stores a moda_ct_ session token
+moda auth logout                 # revoke the session server-side, then delete it locally
+moda auth status                 # local session state; exit 0 logged in, exit 4 logged out
+moda auth status --online        # additionally probe GET /api/cli/context
+moda auth token                  # print the raw bearer token + newline, nothing else
+curl -H "Authorization: Bearer $(moda auth token)" https://moda.dev/api/cli/context
+```
+
+- `moda auth login` opens the browser consent flow at `{MODA_BASE_URL}/auth/cli`
+  with a localhost callback (ports 8432-8435, first free). Approving in the
+  browser hands the CLI a one-time code that it exchanges for a `moda_ct_...`
+  session token (sliding 30-day expiry, renewed automatically in the
+  background while you keep using the CLI). If the browser cannot reach the
+  machine, paste the callback URL or the code shown on the consent page into
+  the terminal.
+- `moda auth logout` revokes the stored `moda_ct_` session server-side
+  (best-effort) and deletes the local credential; legacy sessions are just
+  deleted locally.
+- `moda auth status` reports
+  `{ "loggedIn": <bool>, "profile": <string|null>, "expiresAt": <ISO|null> }`
+  plus `"user": { "email": <string> }` when the stored session carries an
+  email (PKCE `moda_ct_` sessions do; legacy sessions omit it), and exits `4`
+  when logged out. That exit is an **expected state signal, not
+  an error**: the payload is clean data (no error block, no stderr noise), and
+  no browser is ever opened. With `--online` the payload adds
+  `{ "online": { "reachable": <bool>, "ok": <bool>, "tenantCount": <n> } }`:
+  `reachable: true` means any HTTP response arrived (even a 401/500), `ok`
+  reflects HTTP success, and `tenantCount` is present only when the response
+  was ok and carried a tenants array. A network failure or probe timeout
+  (5 s) yields `reachable: false`; the exit code always follows local session
+  validity only, never the probe.
+- `moda auth token` writes exactly the bare token plus a trailing newline to
+  stdout in **every** output mode — including piped/json/agent, because
+  command substitution is a pipe — so `$(moda auth token)` composes safely
+  with no envelope to strip. When logged out it prints a stderr message and
+  exits `4`; with an explicit `--json` flag it instead prints
+  `{"error":"not_authenticated"}` to stdout (still exit `4`).
+- `moda auth token` prints whichever credential kind is stored. Newer logins
+  store a `moda_ct_...` CLI session token, which authenticates **`/api/cli/*`
+  endpoints only** — it is not accepted by the Data API (`/api/v1/data/*`
+  wants a `moda_sk_...` API key) or other dashboard endpoints. Legacy
+  sessions print the Auth0 bearer token as before.
+- Both respect `--profile=NAME` and `MODA_PROFILE`.
+
 ## Agent protocol
 
 Run `moda manifest --json` first when integrating with the CLI. It returns the
@@ -117,10 +164,73 @@ Branch on the exit code; it is stable and cheaper than parsing the payload:
 | `0` | ok — answer is grounded in Moda Cloud intelligence | Trust it. |
 | `1` | error — bad input, API/network failure, or unexpected failure | Read `errors[]`; retry only when the code is retryable. |
 | `3` | degraded — Moda Cloud was unavailable; answer synthesized from local Data API evidence | Answer is present but lower-trust; verify before acting. |
-| `4` | auth required | Run `auth.login_command`, then re-run `auth.resume_command` if present. |
-| `5` | input required | Pick a choice, append its `resume_flags`, and re-run. |
+| `4` | auth required — credentials are missing or expired | Run the `login_command` from the `auth` payload (`moda auth login`), then re-run `resume_command`. |
+| `5` | input required — a choice is needed that the non-interactive run could not answer | Pick a choice from the `input_request` payload and re-invoke the same command with that choice's `resume_flags` appended. |
 | `130` | cancelled | Treat as interrupted or closed pipe; do not retry blindly. |
 
+Exit codes `4` and `5` are recoverable-by-caller failures: the envelope's
+`errors[]` entry carries the exact commands/flags to recover with, as argv
+arrays (execute element-wise; join with spaces only for display).
+
+#### `auth_required` payload (exit `4`)
+
+The envelope's `errors[]` entry carries the recovery data on its `auth` field
+(in `--agent --stream` mode the same error arrives as an NDJSON event with
+`"event": "auth_required"`):
+
+```json
+{
+  "code": "auth_required",
+  "message": "Browser authentication is required before non-interactive init can continue.",
+  "suggested_commands": ["moda auth login", "moda init --yes"],
+  "blocking": true,
+  "auth": {
+    "reason": "no_stored_credentials",
+    "login_command": ["moda", "auth", "login"],
+    "resume_command": ["moda", "init", "--yes"]
+  }
+}
+```
+
+`reason` is one of:
+
+- `no_stored_credentials` — no session stored. Run `login_command`, then
+  `resume_command` (when present).
+- `token_expired` — the stored session expired. Run `login_command`, then
+  `resume_command`.
+- `token_revoked` — the stored `moda_ct_` CLI session token was revoked
+  server-side (e.g. from the dashboard). Run `login_command`, then
+  `resume_command`.
+- `renew_failed` — the API rejected an **unexpired** `moda_ct_` token but the
+  renewal check could not reach the server, so this is likely transient:
+  **retry the command; do not re-login.**
+
+#### `needs_input` payload (exit `5`)
+
+The envelope's `errors[]` entry carries the recovery data on its
+`input_request` field (in `--agent --stream` mode the event type is
+`"needs_input"`):
+
+```json
+{
+  "code": "needs_input",
+  "message": "An organization must be selected to continue.",
+  "blocking": true,
+  "input_request": {
+    "id": "init_tenant_selection",
+    "question": "Select organization",
+    "kind": "select",
+    "choices": [
+      { "value": "tnt_a", "label": "Acme (owner)", "resume_flags": ["--tenant-id", "tnt_a"] },
+      { "value": "tnt_b", "label": "Beta (viewer)", "resume_flags": ["--tenant-id", "tnt_b"] }
+    ]
+  }
+}
+```
+
+Re-invoke the original command with the chosen `resume_flags` appended (here:
+`moda init --tenant-id tnt_a`).
+
 ### The `moda.agent.v1` envelope
 
 Fields an agent should read:
@@ -140,7 +250,10 @@ Fields an agent should read:
 
 `errors[].code` is one of `input_error`, `api_error`, `network_error`,
 `auth_required`, `input_required`, `cancelled`, `command_error`,
-`unknown_error`, or a documented domain code such as `cloud_unavailable`.
+`access_denied`, `unknown_error`, or a documented domain code such as
+`cloud_unavailable`. `access_denied` (exit 1) is an access problem — no
+organizations or an insufficient (viewer) role — distinct from `auth_required`
+(exit 4, missing/expired credentials).
 
 ### The `moda.agent_event.v1` stream
 
@@ -581,6 +694,10 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | Command | Purpose |
 |---|---|
 | `moda init` | Browser auth + provision API key + install agent rules |
+| `moda auth login` | Browser PKCE sign-in; stores a revocable `moda_ct_` session token |
+| `moda auth logout` | Revoke the CLI session server-side, then delete it locally |
+| `moda auth status` | Local auth session state (exit `4` = logged out — expected, not an error) |
+| `moda auth token` | Print the raw bearer token for `$(moda auth token)` composition |
 | `moda search "<query>"` | **Message-grain semantic/keyword/hybrid search (incl. tool calls); primary content-discovery path** |
 | `moda overview` | Dashboard KPIs, top clusters, recent activity |
 | `moda ask "<question>"` | Natural-language production/harness answer with evidence (exit `3` = degraded local fallback) |