@moda-ai/cli 1.12.6 → 1.13.0

package/dist/auth.d.ts

@@ -13,10 +13,17 @@ export declare function loadToken(options?: AuthSessionOptions): string | null;
 export declare function loadAuthSession(options?: AuthSessionOptions): StoredAuth | null;
 export declare function saveAuthSession(accessToken: string, expiresIn: number, options?: ProfileIOOptions): StoredAuth;
 export declare function clearAuthSession(options?: ProfileIOOptions): void;
-export interface LoginOptions {
+export interface LoginOptions extends ProfileIOOptions {
+    /** Use this exact port for the localhost callback (no fallback ladder). */
     callbackPort?: number;
     timeoutMs?: number;
     openUrl?: (url: string) => Promise<void>;
+    /**
+     * Test hook: readable stream used for the manual-paste fallback instead of
+     * process.stdin. A truthy `isTTY` property on the stream enables the
+     * interactive bare-token confirmation path.
+     */
+    promptStream?: NodeJS.ReadableStream;
 }
 export declare function login(screen?: 'login' | 'signup', options?: LoginOptions): Promise<string>;
 export declare function authFetch(path: string, options?: RequestInit, authOptions?: AuthSessionOptions): Promise<Response>;

package/dist/auth.js

@@ -2,11 +2,17 @@
 import { createServer } from 'node:http';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createInterface } from 'node:readline';
 import { resolveModaBaseUrl } from './config.js';
 import { CliAuthError } from './errors.js';
 import { getModaPaths, loadProfileConfig, saveProfileConfig, secretFilePathFromRef, writeSecretJsonFile, } from './profiles.js';
 const CALLBACK_PORT = 8432;
+// Fallback ports tried in order when CALLBACK_PORT is taken. The frontend
+// callback redirect is port-parameterized, so any of these works as long as
+// the auth URL carries the port that actually got bound.
+const CALLBACK_PORT_LADDER = [CALLBACK_PORT, 8433, 8434, 8435];
 const AUTH_TIMEOUT_MS = 120_000;
+const DEFAULT_EXPIRES_IN_SECONDS = 86_400;
 function escapeHtml(value) {
     return value
         .replace(/&/g, '&')
@@ -154,8 +160,8 @@ export function clearAuthSession(options = {}) {
     }
     rmSync(tokenPath(options), { force: true });
 }
-function saveToken(accessToken, expiresIn) {
-    saveAuthSession(accessToken, expiresIn);
+function saveToken(accessToken, expiresIn, options = {}) {
+    saveAuthSession(accessToken, expiresIn, options);
 }
 // --- Login Flow ---
 const SUCCESS_HTML = `<!DOCTYPE html>
@@ -196,9 +202,20 @@ function closeAuthServer(server) {
 export async function login(screen = 'login', options = {}) {
     return new Promise((resolve, reject) => {
         let settled = false;
-        let localPort = options.callbackPort ?? CALLBACK_PORT;
-        let timeout;
         const state = randomBytes(16).toString('hex');
+        // An explicit callbackPort is used as-is (tests bind port 0 for an
+        // ephemeral port); only the default flow walks the fallback ladder.
+        const portsToTry = options.callbackPort !== undefined
+            ? [options.callbackPort]
+            : [...CALLBACK_PORT_LADDER];
+        let portIndex = 0;
+        let localPort = portsToTry[0];
+        let timeout;
+        // Manual-paste fallback state (used when the browser can't reach this box).
+        let promptInput;
+        let promptStreamIsTTY = false;
+        // Holds a bare token awaiting the interactive [y/N] confirmation.
+        let pendingBareToken = null;
         const server = createServer(async (req, res) => {
             if (settled)
                 return;
@@ -244,7 +261,10 @@ export async function login(screen = 'login', options = {}) {
                 });
                 return;
             }
-            saveToken(token, parseInt(expiresIn || '86400', 10));
+            saveToken(token, parseInt(expiresIn || '86400', 10), {
+                profile: options.profile,
+                env: options.env,
+            });
             res.writeHead(200, { 'Content-Type': 'text/html', Connection: 'close' });
             res.end(SUCCESS_HTML, () => {
                 succeed(token);
@@ -254,6 +274,13 @@ export async function login(screen = 'login', options = {}) {
             process.off('SIGINT', handleSigint);
             process.off('SIGTERM', handleSigterm);
         }
+        function closePromptInput() {
+            if (!promptInput)
+                return;
+            promptInput.removeListener('line', handlePastedLine);
+            promptInput.close();
+            promptInput = undefined;
+        }
         function finish(callback) {
             if (settled)
                 return;
@@ -261,6 +288,7 @@ export async function login(screen = 'login', options = {}) {
             if (timeout)
                 clearTimeout(timeout);
             removeSignalHandlers();
+            closePromptInput();
             // Always attempt to close the server: if SIGINT arrives between
             // server.listen() and its listening callback, the socket may already be
             // bound by the OS. closeAuthServer ignores ERR_SERVER_NOT_RUNNING.
@@ -273,35 +301,138 @@ export async function login(screen = 'login', options = {}) {
         function fail(error) {
             finish(() => reject(error));
         }
+        function completeWithToken(token, expiresIn) {
+            saveToken(token, expiresIn, { profile: options.profile, env: options.env });
+            succeed(token);
+        }
         function handleSigint() {
             fail(new Error('Authentication cancelled.'));
         }
         function handleSigterm() {
             fail(new Error('Authentication terminated.'));
         }
+        // Accepts a line pasted by the user when the browser cannot reach this
+        // machine: a full /callback-token?token=... URL, a /callback#token=...
+        // fragment URL, or a bare token string.
+        function handlePastedLine(line) {
+            if (settled)
+                return;
+            const trimmed = line.trim();
+            if (pendingBareToken !== null) {
+                const token = pendingBareToken;
+                pendingBareToken = null;
+                if (/^y(es)?$/i.test(trimmed)) {
+                    completeWithToken(token, DEFAULT_EXPIRES_IN_SECONDS);
+                }
+                else {
+                    // A bare Enter is the conventional No for a [y/N] prompt.
+                    fail(new Error('Bare token rejected: state cannot be verified.'));
+                }
+                return;
+            }
+            if (!trimmed)
+                return;
+            if (/^https?:\/\//i.test(trimmed)) {
+                let pastedUrl;
+                try {
+                    pastedUrl = new URL(trimmed);
+                }
+                catch {
+                    // A malformed paste intentionally aborts the login so a fresh state
+                    // is minted on the next attempt.
+                    fail(new Error('Could not parse the pasted URL. Paste the full callback URL from the browser.'));
+                    return;
+                }
+                // Fragment URLs (/callback#token=...) carry the same key/value pairs as
+                // the /callback-token query string; parse whichever is present.
+                const params = pastedUrl.hash.length > 1
+                    ? new URLSearchParams(pastedUrl.hash.slice(1))
+                    : pastedUrl.searchParams;
+                const token = params.get('token');
+                const expiresIn = params.get('expires_in');
+                const pastedState = params.get('state');
+                if (!pastedState || !safeEqual(pastedState, state)) {
+                    fail(new Error('Invalid authentication state.'));
+                    return;
+                }
+                if (!token) {
+                    fail(new Error('No token received'));
+                    return;
+                }
+                completeWithToken(token, parseInt(expiresIn || String(DEFAULT_EXPIRES_IN_SECONDS), 10));
+                return;
+            }
+            // Bare token: there is no state to verify, so require an explicit,
+            // interactive confirmation before trusting it.
+            if (promptStreamIsTTY) {
+                pendingBareToken = trimmed;
+                console.error('  State cannot be verified for a bare token. Continue? [y/N]');
+                return;
+            }
+            fail(new Error('State cannot be verified for a bare token in non-interactive mode. Paste the full callback URL instead.'));
+        }
+        function attachPromptInput() {
+            if (settled || promptInput)
+                return;
+            const stream = options.promptStream ??
+                (process.stdin && (process.stdin.isTTY || !process.stdin.destroyed)
+                    ? process.stdin
+                    : undefined);
+            if (!stream)
+                return;
+            promptStreamIsTTY = Boolean(stream.isTTY);
+            promptInput = createInterface({ input: stream, terminal: false });
+            promptInput.on('line', handlePastedLine);
+            // Waiting for a paste must not keep the process alive on its own; the
+            // callback server and the auth timeout already do that.
+            stream.unref?.();
+        }
         timeout = setTimeout(() => {
             fail(new Error('Authentication timed out. Please try again.'));
         }, options.timeoutMs ?? AUTH_TIMEOUT_MS);
         server.on('error', (err) => {
+            if (settled)
+                return;
             if (err.code === 'EADDRINUSE') {
-                fail(new Error(`Port ${localPort} is in use. Close the process using it and try again.`));
+                portIndex += 1;
+                if (portIndex < portsToTry.length) {
+                    localPort = portsToTry[portIndex];
+                    server.listen(localPort, '127.0.0.1');
+                    return;
+                }
+                if (options.callbackPort !== undefined) {
+                    fail(new Error(`Port ${options.callbackPort} is in use. Close the process using it and try again.`));
+                }
+                else {
+                    fail(new Error(`Ports ${CALLBACK_PORT_LADDER.join(', ')} are all in use. ` +
+                        'Close a process using one of them and try again.'));
+                }
             }
             else {
                 fail(err);
             }
         });
         server.listen(localPort, '127.0.0.1', async () => {
+            if (settled)
+                return;
             const address = server.address();
             if (address && typeof address === 'object') {
                 localPort = address.port;
             }
-            const authUrl = `${resolveModaBaseUrl()}/auth/cli?port=${localPort}&screen=${screen}&state=${state}`;
+            // Resolve the auth URL with the same profile/env context so `--profile
+            // staging` opens the staging flow (not whatever the active profile is)
+            // and the minted session matches where it will be stored.
+            const authUrl = `${resolveModaBaseUrl({ profile: options.profile, env: options.env })}/auth/cli?port=${localPort}&screen=${screen}&state=${state}`;
+            attachPromptInput();
             try {
                 await (options.openUrl ?? openAuthUrl)(authUrl);
             }
             catch {
-                console.error(`  Open this URL in your browser:\n  ${authUrl}`);
+                // The URL is printed below regardless of whether the browser opened.
             }
+            console.error(`  Open this URL in your browser if it did not open automatically:\n  ${authUrl}`);
+            console.error("  Paste the callback URL or code here if the browser can't reach this machine\n" +
+                "(if the browser page failed to redirect, copy the URL from the browser's address bar):");
         });
         process.once('SIGINT', handleSigint);
         process.once('SIGTERM', handleSigterm);
@@ -321,8 +452,12 @@ export async function authFetch(path, options = {}, authOptions = {}) {
     if (!headers.has('Content-Type') && options.body) {
         headers.set('Content-Type', 'application/json');
     }
-    const origin = new URL(resolveModaBaseUrl()).origin;
-    let url = `${resolveModaBaseUrl()}${path}`;
+    // Resolve the origin from the same profile/env context used to load the
+    // token, or a profile-scoped session (e.g. `--profile staging`) is sent to
+    // the active/default origin — provisioning against the wrong environment.
+    const baseUrl = resolveModaBaseUrl(authOptions);
+    const origin = new URL(baseUrl).origin;
+    let url = `${baseUrl}${path}`;
     // Follow redirects manually so EVERY hop is origin-checked, not just the
     // first. Native `redirect: 'follow'` would silently strip the Authorization
     // header on a cross-host hop (per the Fetch spec) — the exact failure that

package/dist/cli.js

@@ -12,7 +12,7 @@ import { runSkillsCommand } from './skills.js';
 import { runHarnessCommand } from './harness.js';
 import { runSyncCommand } from './sync.js';
 import { runDoctorCommand, runStatusCommand } from './doctor.js';
-import { CliAuthError, CliCancellationError, CliInputError, CliInputRequiredError, isApiLikeError, isNetworkLikeError } from './errors.js';
+import { CliAccessError, CliAuthError, CliCancellationError, CliInputError, CliInputRequiredError, isApiLikeError, isNetworkLikeError } from './errors.js';
 import { buildSearchAdoptionTelemetry, isTelemetryDisabled, SEARCH_MODES, sendCliUsageTelemetry, stripTelemetryFlag, } from './telemetry.js';
 import { isUpdateCheckDisabled, printUpdateNotice, startUpdateCheck, stripUpdateCheckFlag, } from './update-check.js';
 import { createCommandContext } from './command-context.js';
@@ -111,6 +111,8 @@ Commands:
   manifest                         Describe the CLI machine protocol and commands
   doctor                           Diagnose local Moda setup and data flow
   auth login                       Authenticate with Moda
+  auth status                      Show local auth session state (exit 4 when logged out); --online probes the API
+  auth token                       Print the raw bearer token for $(moda auth token)
   auth logout                      Clear cached Moda auth
   auth whoami                      Show the authenticated Moda user
   profiles list                    List local Moda profiles
@@ -759,7 +761,14 @@ export const commandRegistry = createCommandRegistry([
     {
         name: 'auth',
         description: 'Authenticate and inspect browser auth sessions',
-        examples: ['moda auth login', 'moda auth whoami', 'moda auth logout'],
+        examples: [
+            'moda auth login',
+            'moda auth status',
+            'moda auth status --online',
+            'moda auth token',
+            'moda auth whoami',
+            'moda auth logout',
+        ],
         auth: 'none',
         outputModes: ['human', 'json', 'agent'],
         mutability: 'write',
@@ -1075,10 +1084,12 @@ export function classifyCliError(error) {
     if (error instanceof z.ZodError ||
         error instanceof CliInputError ||
         error instanceof CliInputRequiredError ||
-        error instanceof CliAuthError) {
-        // Auth/input-required are caller-actionable states (missing credentials,
-        // needs a choice), not unknown failures. Bucket them with validation so
-        // the missing-API-key case keeps its pre-hardening telemetry type.
+        error instanceof CliAuthError ||
+        error instanceof CliAccessError) {
+        // Auth/input-required/access are caller-actionable states (missing
+        // credentials, needs a choice, insufficient role), not unknown failures.
+        // Bucket them with validation so the missing-API-key case keeps its
+        // pre-hardening telemetry type.
         return 'validation_error';
     }
     if (error instanceof ApiError || isApiLikeError(error)) {
@@ -1095,6 +1106,11 @@ export function printCliError(error) {
         if (error.usage)
             safeWriteStderr(`${error.usage}\n`);
     }
+    else if (error instanceof CliAccessError) {
+        safeWriteStderr(`Error: ${error.message}\n`);
+        if (error.guidance)
+            safeWriteStderr(`${error.guidance}\n`);
+    }
     else if (error instanceof z.ZodError) {
         const issues = error.errors.map((e) => {
             const field = e.path.length ? e.path.join('.') : 'input';

package/dist/config.d.ts

@@ -17,8 +17,11 @@ export declare function loadCliConfig(options?: ProfileIOOptions): CliConfig;
 /**
  * Merge-and-write the persisted config. Always chmod 0600 since it holds the
  * API key. Best-effort: never throws on chmod failure (some filesystems).
+ * `options.profile` scopes the best-effort profile sync (e.g. `moda init
+ * --profile staging`), so the key is synced to the requested profile rather
+ * than whatever profile happens to be active.
  */
-export declare function saveCliConfig(update: CliConfig): void;
+export declare function saveCliConfig(update: CliConfig, options?: ProfileIOOptions): void;
 /**
  * Resolve the API key: prefer the environment (so CI / explicit exports win),
  * then fall back to the persisted `~/.moda/config.json`. Read lazily so a

package/dist/config.js

@@ -14,11 +14,14 @@ export function loadCliConfig(options = {}) {
 /**
  * Merge-and-write the persisted config. Always chmod 0600 since it holds the
  * API key. Best-effort: never throws on chmod failure (some filesystems).
+ * `options.profile` scopes the best-effort profile sync (e.g. `moda init
+ * --profile staging`), so the key is synced to the requested profile rather
+ * than whatever profile happens to be active.
  */
-export function saveCliConfig(update) {
-    const merged = writeLegacyCliConfig(update);
+export function saveCliConfig(update, options = {}) {
+    const merged = writeLegacyCliConfig(update, options);
     try {
-        syncLegacyConfigToProfile(merged);
+        syncLegacyConfigToProfile(merged, options);
     }
     catch {
         // The legacy config write is the compatibility contract; profile sync is a

package/dist/errors.d.ts

@@ -2,6 +2,19 @@ export declare class CliInputError extends Error {
     readonly usage?: string | undefined;
     constructor(message: string, usage?: string | undefined);
 }
+/**
+ * The authenticated user cannot perform the requested action with their
+ * current access (no organizations, or insufficient role). This is an access
+ * problem, not missing auth — the dispatcher maps it to EXIT_ERROR (1),
+ * never EXIT_AUTH_REQUIRED.
+ */
+export declare class CliAccessError extends Error {
+    /** Optional follow-up line telling the user how to obtain access. */
+    readonly guidance?: string;
+    constructor(message: string, options?: {
+        guidance?: string;
+    });
+}
 export interface AgentInputChoice {
     value: string;
     label: string;

package/dist/errors.js

@@ -6,6 +6,21 @@ export class CliInputError extends Error {
         this.name = 'CliInputError';
     }
 }
+/**
+ * The authenticated user cannot perform the requested action with their
+ * current access (no organizations, or insufficient role). This is an access
+ * problem, not missing auth — the dispatcher maps it to EXIT_ERROR (1),
+ * never EXIT_AUTH_REQUIRED.
+ */
+export class CliAccessError extends Error {
+    /** Optional follow-up line telling the user how to obtain access. */
+    guidance;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = 'CliAccessError';
+        this.guidance = options.guidance;
+    }
+}
 export class CliInputRequiredError extends Error {
     input_request;
     constructor(message, input_request, usage) {

package/dist/exit-funnel.js

@@ -1,4 +1,4 @@
-import { CliAuthError, CliCancellationError, CliInputRequiredError, } from './errors.js';
+import { CliAccessError, CliAuthError, CliCancellationError, CliInputRequiredError, } from './errors.js';
 import { EXIT_AUTH_REQUIRED, EXIT_CANCELLED, EXIT_ERROR, EXIT_INPUT_REQUIRED, EXIT_OK, wasOutputCancelled, } from './output.js';
 const finishedContexts = new WeakSet();
 export async function finishRun(context, outcome) {
@@ -37,6 +37,10 @@ export function exitCodeForError(error) {
         return EXIT_INPUT_REQUIRED;
     if (error instanceof CliCancellationError)
         return EXIT_CANCELLED;
+    // An access problem (missing org / insufficient role) is a hard failure,
+    // never auth-required — it stays EXIT_ERROR (the default), made explicit here.
+    if (error instanceof CliAccessError)
+        return EXIT_ERROR;
     return EXIT_ERROR;
 }
 function exitCodeForOutcome(outcome) {

package/dist/init/index.js

@@ -77,11 +77,17 @@ export async function runInit(flags, options = {}) {
     // Step 3: Tenant + API Key
     log(renderInitStep(3, 7, 'Workspace & Profile'));
     emit('workspace', 'Selecting workspace and creating API key.');
+    // --tenant-id flag wins over MODA_TENANT_ID; the source drives the
+    // env-shadow warning so we don't warn when the env var was the selection.
+    const tenantIdFlag = stringFlag(flagValue(flags, 'tenant-id', 'tenant_id'));
+    const tenantIdEnv = process.env.MODA_TENANT_ID;
     const { apiKey, tenantName } = await selectTenantAndCreateKey({
-        tenantId: stringFlag(flagValue(flags, 'tenant-id', 'tenant_id')),
+        tenantId: tenantIdFlag ?? tenantIdEnv,
+        tenantIdSource: tenantIdFlag ? 'flag' : tenantIdEnv ? 'env' : undefined,
         nonInteractive: json || agent,
         silent: !human,
         resumeCommand: ['moda', 'init', ...resumeFlagsForInit(flags)],
+        profile: stringFlag(flags.profile),
     });
     log(renderInitNote(`Active workspace: ${tenantName}`));
     emit('workspace', `Active workspace: ${tenantName}`, 'completed');

package/dist/init/tenant.d.ts

@@ -4,11 +4,25 @@ interface BootstrapResult {
     tenantName: string;
     tenantSlug: string;
 }
-export declare function selectTenantAndCreateKey(options?: {
+export interface SelectTenantAndCreateKeyOptions {
+    /** Tenant id preselected via --tenant-id (flag) or MODA_TENANT_ID (env). */
     tenantId?: string;
+    /** Where the preselected tenant id came from; drives the env-shadow warning. */
+    tenantIdSource?: 'flag' | 'env';
+    /** Non-interactive runs must never open the selection prompt. */
     nonInteractive?: boolean;
+    /** Suppress human prose so it never interleaves with JSON envelopes on stdout. */
     silent?: boolean;
+    /** Resume command echoed into the needs_input event for multi-tenant runs. */
     resumeCommand?: string[];
-}): Promise<BootstrapResult>;
+    /**
+     * Profile context (--profile) threaded from init: scopes the auth-session
+     * reads and request origin behind authFetch, the stored-key candidate
+     * lookup, and the liveness-probe base URL to the given profile.
+     */
+    profile?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function selectTenantAndCreateKey(options?: SelectTenantAndCreateKeyOptions): Promise<BootstrapResult>;
 export {};
 //# sourceMappingURL=tenant.d.ts.map

package/dist/init/tenant.js

@@ -1,36 +1,133 @@
 // 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 { 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 = {}) {
+    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
-    const contextRes = await authFetch('/api/cli/context');
+    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}`);
     }
     const ctx = (await contextRes.json());
-    if (!options.silent)
-        console.log(`  Authenticated as ${ctx.user.email}`);
+    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 +143,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 +196,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 } 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,
@@ -96,8 +100,73 @@ 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,
+            };
+            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.0",
   "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-06T09:53:55.227Z",
+  "cli_version": "1.13.0",
   "skills": [
     {
       "id": "integration-node-anthropic",

package/skills/moda-cli/SKILL.md

@@ -140,7 +140,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