@moda-ai/cli 1.13.1 → 1.13.2

package/dist/auth.js

@@ -52,7 +52,17 @@ function safeEqual(a, b) {
 function looksLikeOneTimeCode(value) {
     return /^[A-Za-z0-9_-]{32,96}$/.test(value);
 }
-// --- PKCE (RFC 7636, S256) ---
+class CodeExchangeError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = 'CodeExchangeError';
+    }
+}
+function exchangeFailureReason(error) {
+    return error instanceof CodeExchangeError ? error.reason : 'exchange_failed';
+}
 /** base64url(sha256(verifier)) — the S256 code challenge for a verifier. */
 export function computePkceChallenge(codeVerifier) {
     return createHash('sha256').update(codeVerifier).digest('base64url');
@@ -186,6 +196,10 @@ export async function login(screen = 'login', options = {}) {
                     }
                     exchangeInFlight = true;
                     void (async () => {
+                        // A PKCE grant implies a frontend deployment new enough to host
+                        // /auth/cli/done, so the browser is bounced to the branded page
+                        // instead of inline HTML. Only fixed, token-free params ride the
+                        // Location header — never the code, verifier, token, or state.
                         try {
                             const cliToken = await exchangeCodeForSession(code);
                             // Leave exchangeInFlight true on success: succeed() only runs
@@ -194,16 +208,23 @@ export async function login(screen = 'login', options = {}) {
                             // callback could start a concurrent exchange before `settled`
                             // flips. The flag only needs to clear on failure, where a
                             // retry paste is still legitimate.
-                            res.writeHead(200, { 'Content-Type': 'text/html', Connection: 'close' });
-                            res.end(SUCCESS_HTML, () => {
+                            res.writeHead(302, {
+                                Location: `${resolveModaBaseUrl()}/auth/cli/done?status=success`,
+                                Connection: 'close',
+                            });
+                            res.end(() => {
                                 succeed(cliToken);
                             });
                         }
                         catch (err) {
                             exchangeInFlight = false;
                             const error = err instanceof Error ? err : new Error(String(err));
-                            res.writeHead(400, { 'Content-Type': 'text/html', Connection: 'close' });
-                            res.end(`<html><body><h2>Error</h2><p>${escapeHtml(error.message)}</p></body></html>`, () => {
+                            res.writeHead(302, {
+                                Location: `${resolveModaBaseUrl()}/auth/cli/done` +
+                                    `?status=error&reason=${exchangeFailureReason(err)}`,
+                                Connection: 'close',
+                            });
+                            res.end(() => {
                                 fail(error);
                             });
                         }
@@ -349,30 +370,30 @@ export async function login(screen = 'login', options = {}) {
                 });
             }
             catch {
-                throw new Error('Could not reach the Moda API to exchange the login code. Check your network and try again.');
+                throw new CodeExchangeError('Could not reach the Moda API to exchange the login code. Check your network and try again.', 'unreachable');
             }
             if (response.status >= 300 && response.status < 400) {
-                throw new Error(`The Moda API redirected the login code exchange (HTTP ${response.status}). ` +
+                throw new CodeExchangeError(`The Moda API redirected the login code exchange (HTTP ${response.status}). ` +
                     'Refusing to re-send the login code across a redirect. ' +
-                    'Check MODA_BASE_URL (use https://moda.dev, not www.moda.dev) and try again.');
+                    'Check MODA_BASE_URL (use https://moda.dev, not www.moda.dev) and try again.', 'exchange_failed');
             }
             if (response.status === 401) {
-                throw new Error('The login code was rejected (invalid, expired, or already used). Run the login command again.');
+                throw new CodeExchangeError('The login code was rejected (invalid, expired, or already used). Run the login command again.', 'code_rejected');
             }
             if (!response.ok) {
-                throw new Error(`Login code exchange failed (HTTP ${response.status}). Try again.`);
+                throw new CodeExchangeError(`Login code exchange failed (HTTP ${response.status}). Try again.`, 'exchange_failed');
             }
             let payload;
             try {
                 payload = (await response.json());
             }
             catch {
-                throw new Error('The login code exchange returned an unreadable response. Try again.');
+                throw new CodeExchangeError('The login code exchange returned an unreadable response. Try again.', 'exchange_failed');
             }
             const cliToken = typeof payload.cli_token === 'string' ? payload.cli_token : undefined;
             const expiresAtMs = typeof payload.expires_at === 'string' ? Date.parse(payload.expires_at) : NaN;
             if (!cliToken || !Number.isFinite(expiresAtMs)) {
-                throw new Error('The login code exchange returned an incomplete response. Try again.');
+                throw new CodeExchangeError('The login code exchange returned an incomplete response. Try again.', 'exchange_failed');
             }
             const userEmail = typeof payload.user?.email === 'string' ? payload.user.email : undefined;
             persistAuthSession({

package/dist/cli.d.ts

@@ -11,6 +11,16 @@ export interface ParsedArgs {
 }
 export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function flagsToArgs(flags: Record<string, string>, positionalKey?: string, positionalValue?: string): Record<string, unknown>;
+/**
+ * Build the argv the caller should re-run to resume an interrupted command,
+ * echoing back the raw flags exactly as parsed (so per-invocation opt-outs
+ * like --no-telemetry survive). Treats `--flag` and `--flag=true` identically.
+ *
+ * Limitation: positional arguments are not included — the current callers
+ * (`moda init`, `moda provision`) take none. Extend the signature before
+ * reusing this for a command with positionals.
+ */
+export declare function buildResumeCommand(command: string, flags: Record<string, string>): string[];
 export declare function runCommand(command: string, positional: string | undefined, flags: Record<string, string>, positionals?: string[], context?: CommandContext): Promise<number>;
 interface CommandDispatchResult {
     exitCode: number;

package/dist/cli.js

@@ -101,12 +101,29 @@ export function flagsToArgs(flags, positionalKey, positionalValue) {
     }
     return result;
 }
+/**
+ * Build the argv the caller should re-run to resume an interrupted command,
+ * echoing back the raw flags exactly as parsed (so per-invocation opt-outs
+ * like --no-telemetry survive). Treats `--flag` and `--flag=true` identically.
+ *
+ * Limitation: positional arguments are not included — the current callers
+ * (`moda init`, `moda provision`) take none. Extend the signature before
+ * reusing this for a command with positionals.
+ */
+export function buildResumeCommand(command, flags) {
+    return [
+        'moda',
+        command,
+        ...Object.entries(flags).map(([key, value]) => value === 'true' ? `--${key}` : `--${key}=${value}`),
+    ];
+}
 // --- Help ---
 function printHelp() {
     console.error(`Usage: moda <command> [options]
 
 Commands:
   init                             Set up Moda in your project
+  provision                        Headless tenant + API key provisioning (JSON credentials on stdout)
   status                           Show concise local Moda setup status
   manifest                         Describe the CLI machine protocol and commands
   doctor                           Diagnose local Moda setup and data flow
@@ -234,8 +251,17 @@ Init flags:
   --no-autosync                    Skip autosync workflow creation
   --offline                        Run final validation offline (skip the online telemetry check)
 
+Provision flags (headless; requires an existing "moda auth login" session):
+  --tenant-id=ID                   Organization to provision (required with multiple
+                                   organizations; MODA_TENANT_ID env is also honored,
+                                   flag wins). Never prompts, even on a TTY.
+  --label=TEXT                     API key label (default: machine hostname)
+  --save                           Also persist the key to ~/.moda/config.json
+                                   (default: print only; headless callers own storage)
+
 Examples:
   moda init
+  moda provision --tenant-id=<org-id>
   moda status
   moda manifest --json
   moda doctor --json
@@ -734,6 +760,32 @@ export const commandRegistry = createCommandRegistry([
             return { exitCode: 0, apiKey: result.apiKey };
         },
     },
+    {
+        name: 'provision',
+        description: 'Headless tenant + API key provisioning for CI and agents (JSON credentials on stdout)',
+        examples: [
+            'moda provision',
+            'moda provision --tenant-id=<org-id>',
+            'moda provision --tenant-id=<org-id> --label=ci-runner --save',
+            'KEY=$(moda provision --tenant-id <org-id> | jq -r .apiKey)',
+        ],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: true,
+        // result-and-error like init: recoverable failures (auth_required /
+        // input_required / access_error) are recorded, not just successes.
+        telemetry: 'result-and-error',
+        handler: async (context) => {
+            const { runProvision } = await import('./provision.js');
+            return runProvision(context, {
+                // rawFlags (not context.flags) so per-invocation opt-outs like
+                // --no-telemetry survive into the resume command.
+                resumeCommand: buildResumeCommand('provision', context.rawFlags),
+            });
+        },
+    },
     {
         name: 'manifest',
         description: 'Describe the CLI machine protocol, commands, events, and exit codes',

package/dist/command-context.d.ts

@@ -38,6 +38,13 @@ export interface CommandContext {
     /** Snapshot of telemetry recorded so far by the handler. */
     getTelemetryMeta(): CommandTelemetryMeta;
 }
+/**
+ * Normalize a raw flag/env value to a trimmed non-empty string. Accepts
+ * non-string values because flagsToArgs number-coerces numeric-looking flag
+ * values (which must never happen to tenant ids, profile names, or labels);
+ * empty values (`--label=`) become undefined so defaults apply.
+ */
+export declare function stringOption(value: unknown): string | undefined;
 export declare function createCommandContext(input: CommandContextInput, options?: {
     commandName?: string;
     commandFlags?: Record<string, string>;

package/dist/command-context.js

@@ -2,6 +2,18 @@ import { createCliOutput, outputModeFromFlags } from './output.js';
 function flagEnabled(flags, key) {
     return flags[key] === 'true';
 }
+/**
+ * Normalize a raw flag/env value to a trimmed non-empty string. Accepts
+ * non-string values because flagsToArgs number-coerces numeric-looking flag
+ * values (which must never happen to tenant ids, profile names, or labels);
+ * empty values (`--label=`) become undefined so defaults apply.
+ */
+export function stringOption(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    return text.length > 0 ? text : undefined;
+}
 export function createCommandContext(input, options = {}) {
     const flags = options.commandFlags ?? input.flags;
     const rawFlags = options.rawFlags ?? input.flags;

package/dist/init/tenant.d.ts

@@ -4,17 +4,39 @@ interface BootstrapResult {
     tenantName: string;
     tenantSlug: string;
 }
+export interface TenantKeyResult extends BootstrapResult {
+    /**
+     * True when a previously stored key for the selected tenant passed the
+     * liveness probe and was reused instead of minting a new one.
+     */
+    reused: boolean;
+}
 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. */
+    /**
+     * Non-interactive runs must never open the selection prompt. Headless-by-
+     * contract callers (`moda provision`) pass true unconditionally — regardless
+     * of terminal state.
+     */
     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[];
+    /**
+     * Bootstrap key label sent to the backend (clipped to its 60-char cap).
+     * Defaults to the machine hostname.
+     */
+    label?: string;
+    /**
+     * When false, skip the ~/.moda/config.json persistence entirely —
+     * headless callers (`moda provision`) own their credential storage.
+     * Defaults to true (init behavior).
+     */
+    persistConfig?: boolean;
     /**
      * Profile context (--profile) threaded from init: scopes the auth-session
      * reads and request origin behind authFetch, the stored-key candidate
@@ -22,7 +44,17 @@ export interface SelectTenantAndCreateKeyOptions {
      */
     profile?: string;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Test seam for the post-bootstrap validate-retry: override the retry
+     * delays and/or the sleep implementation so tests never wait on real
+     * timers. Production callers leave this unset (defaults:
+     * POST_BOOTSTRAP_VALIDATE_DELAYS_MS via setTimeout).
+     */
+    validateRetry?: {
+        delaysMs?: readonly number[];
+        sleep?: (ms: number) => Promise<void>;
+    };
 }
-export declare function selectTenantAndCreateKey(options?: SelectTenantAndCreateKeyOptions): Promise<BootstrapResult>;
+export declare function selectTenantAndCreateKey(options?: SelectTenantAndCreateKeyOptions): Promise<TenantKeyResult>;
 export {};
 //# sourceMappingURL=tenant.d.ts.map

package/dist/init/tenant.js

@@ -1,8 +1,12 @@
 // src/init/tenant.ts — Tenant selection and API key provisioning
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
 import { select } from '@inquirer/prompts';
 import { authFetch, getCachedLoginContext } from '../auth.js';
 import { loadCliConfig, resolveIngestUrl, resolveModaBaseUrl, saveCliConfig, } from '../config.js';
-import { resolveApiKeyFromActiveProfile, resolveTenantIdFromActiveProfile, } from '../profiles.js';
+import { getModaDir, resolveApiKeyFromActiveProfile, resolveTenantIdFromActiveProfile, writeSecretJsonFile, } 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.';
@@ -12,6 +16,118 @@ 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;
+/**
+ * Post-bootstrap validate-retry schedule (WP-2.3): key provisioning spans
+ * Postgres + Cloudflare KV, so a freshly minted key can lag a moment before
+ * it validates. Retry the liveness probe at these delays (3 attempts after
+ * the initial call, ~3.5s of retry sleeps plus up to VALIDATE_TIMEOUT_MS per
+ * probe against a hanging endpoint) before warning and moving on.
+ */
+const POST_BOOTSTRAP_VALIDATE_DELAYS_MS = [
+    500, 1_000, 2_000,
+];
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// The backend truncates the bootstrap label to 60 printable chars; clip the
+// hostname client-side too so what we send is what lands on the key name.
+const MAX_LABEL_LENGTH = 60;
+// Backend contract for the Idempotency-Key header (UUIDs match this too).
+const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+/**
+ * State file backing bootstrap idempotency across process restarts:
+ * ~/.moda/pending-bootstrap.json maps tenant id -> the Idempotency-Key of an
+ * in-flight (or failed) bootstrap POST. Written BEFORE the POST and cleared
+ * on success, so a retry after a network failure reuses the same key and the
+ * backend replays the original response instead of minting another ApiKey.
+ *
+ * Deliberately global (~/.moda, like config.json) and shared across
+ * profiles: the server scopes keys to the authenticated user, so the worst
+ * case of cross-profile sharing is one extra key minted — not worth
+ * profile-scoping the file.
+ */
+function pendingBootstrapPath(options = {}) {
+    return join(getModaDir(options), 'pending-bootstrap.json');
+}
+function loadPendingBootstrapState(options = {}) {
+    try {
+        const path = pendingBootstrapPath(options);
+        if (!existsSync(path))
+            return {};
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {};
+        }
+        const state = {};
+        for (const [tenantId, entry] of Object.entries(parsed)) {
+            if (entry &&
+                typeof entry === 'object' &&
+                typeof entry.idempotency_key === 'string') {
+                state[tenantId] = entry;
+            }
+        }
+        return state;
+    }
+    catch {
+        // A corrupt state file must never block init; fresh keys are always safe.
+        return {};
+    }
+}
+/**
+ * Return the Idempotency-Key to use for this tenant's bootstrap POST,
+ * persisting it before the network call. A key left over from a previous
+ * failed attempt is reused so the retry replays instead of double-minting.
+ * File-system failures degrade to an in-memory key (init must never block).
+ */
+function reserveBootstrapIdempotencyKey(tenantId, options = {}) {
+    const state = loadPendingBootstrapState(options);
+    const existing = state[tenantId]?.idempotency_key;
+    if (existing && IDEMPOTENCY_KEY_PATTERN.test(existing)) {
+        return existing;
+    }
+    const key = randomUUID();
+    state[tenantId] = {
+        idempotency_key: key,
+        created_at: new Date().toISOString(),
+    };
+    try {
+        writeSecretJsonFile(pendingBootstrapPath(options), state);
+    }
+    catch {
+        // Best-effort persistence: without it a retry mints a fresh key, which
+        // is the pre-idempotency behavior, not a failure.
+    }
+    return key;
+}
+/** Clear the tenant's pending key after a successful bootstrap. */
+function clearBootstrapIdempotencyKey(tenantId, options = {}) {
+    try {
+        const state = loadPendingBootstrapState(options);
+        if (!(tenantId in state))
+            return;
+        delete state[tenantId];
+        const path = pendingBootstrapPath(options);
+        if (Object.keys(state).length === 0) {
+            rmSync(path, { force: true });
+        }
+        else {
+            writeSecretJsonFile(path, state);
+        }
+    }
+    catch {
+        // Leftover state is harmless: the key replays the stored response.
+    }
+}
+/** Label sent in the bootstrap body; the backend sanitizes it further. */
+function bootstrapLabel(custom) {
+    const clipped = custom?.trim().slice(0, MAX_LABEL_LENGTH);
+    if (clipped)
+        return clipped;
+    try {
+        return hostname().slice(0, MAX_LABEL_LENGTH) || 'moda init';
+    }
+    catch {
+        return 'moda init';
+    }
+}
 /**
  * Signed CLI keys embed their tenant: the format is
  * moda_sk_<base64url("v1:keyId:tenantId:timestamp:signature")> — see
@@ -87,6 +203,27 @@ function findStoredKeyForTenant(tenantId, options = {}) {
     }
     return undefined;
 }
+/**
+ * Post-bootstrap verification (WP-2.3): confirm a freshly minted key is live
+ * before declaring success, reusing the same Data API probe as dedup.
+ * Provisioning spans Postgres + Cloudflare KV (eventual consistency), so
+ * failures are retried at the POST_BOOTSTRAP_VALIDATE_DELAYS_MS schedule.
+ * Exhaustion is a stderr warning, never an init failure: init's final doctor
+ * step surfaces persistent problems, and blocking here past the retry
+ * schedule would punish every user for a transient propagation delay.
+ */
+async function verifyFreshKeyLive(key, probeOptions, overrides) {
+    const delays = overrides?.delaysMs ?? POST_BOOTSTRAP_VALIDATE_DELAYS_MS;
+    const sleep = overrides?.sleep ?? defaultSleep;
+    if (await isStoredKeyLive(key, probeOptions))
+        return;
+    for (const delayMs of delays) {
+        await sleep(delayMs);
+        if (await isStoredKeyLive(key, probeOptions))
+            return;
+    }
+    console.error('  Warning: API key created but not yet active; propagation can take a few seconds. moda doctor --online will confirm.');
+}
 export async function selectTenantAndCreateKey(options = {}) {
     const log = (message) => {
         if (!options.silent)
@@ -172,11 +309,16 @@ export async function selectTenantAndCreateKey(options = {}) {
     // 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;
+    let reused = false;
     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)`);
+        // A pending idempotency key left by an earlier failed bootstrap is moot
+        // once the stored key is reused; clear it so it does not linger.
+        clearBootstrapIdempotencyKey(selected.id, authOptions);
+        reused = true;
         result = {
             apiKey: storedKey,
             tenantId: selected.id,
@@ -184,40 +326,79 @@ export async function selectTenantAndCreateKey(options = {}) {
             tenantSlug: selected.slug,
         };
     }
-    // 4. Create API key via bootstrap endpoint
+    // 4. Create API key via bootstrap endpoint. The Idempotency-Key is
+    // persisted to ~/.moda/pending-bootstrap.json BEFORE the POST, so a retry
+    // after a network failure reuses the same key and the backend replays the
+    // original response instead of minting a second ApiKey.
     if (!result) {
+        const idempotencyKey = reserveBootstrapIdempotencyKey(selected.id, authOptions);
         const bootstrapRes = await authFetch('/api/cli/bootstrap', {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ tenantId: selected.id }),
+            headers: {
+                'Content-Type': 'application/json',
+                'Idempotency-Key': idempotencyKey,
+            },
+            body: JSON.stringify({
+                tenantId: selected.id,
+                label: bootstrapLabel(options.label),
+            }),
         }, authOptions);
         if (bootstrapRes.status === 403) {
             throw new CliAccessError(ADMIN_ACCESS_MESSAGE, { guidance: ADMIN_ACCESS_GUIDANCE });
         }
+        if (bootstrapRes.status === 409) {
+            const body = await bootstrapRes.text();
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                // Fall through to the generic error below.
+            }
+            if (parsed?.error === 'cli_key_cap_reached') {
+                throw new CliAccessError(parsed.message ||
+                    'This organization has reached its CLI API key limit.', {
+                    // Command-agnostic: this path is shared by `moda init` and
+                    // `moda provision`.
+                    guidance: 'Revoke old CLI keys in the dashboard (Settings -> API Keys), then retry.',
+                });
+            }
+            throw new Error(`Failed to create API key (409): ${body}`);
+        }
         if (!bootstrapRes.ok) {
             const body = await bootstrapRes.text();
             throw new Error(`Failed to create API key (${bootstrapRes.status}): ${body}`);
         }
         result = (await bootstrapRes.json());
+        clearBootstrapIdempotencyKey(selected.id, authOptions);
+        // Fresh mints only: the reused-key path above already proved liveness
+        // via the dedup probe, so re-validating there would be a wasted call.
+        await verifyFreshKeyLive(result.apiKey, authOptions, options.validateRetry);
     }
     // 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
     // that launches Claude. Env still wins over the file at read time.
-    saveCliConfig({
-        api_key: result.apiKey,
-        tenant_id: result.tenantId,
-        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;
+    //
+    // Headless callers (persistConfig: false) skip this block entirely: they
+    // own their credential storage, and the env-shadow warning below only
+    // makes sense when a selection was actually saved.
+    if (options.persistConfig !== false) {
+        saveCliConfig({
+            api_key: result.apiKey,
+            tenant_id: result.tenantId,
+            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, reused };
 }
 //# sourceMappingURL=tenant.js.map

package/dist/provision.d.ts

@@ -0,0 +1,28 @@
+import { type CommandContext } from './command-context.js';
+export interface ProvisionRunOptions {
+    /**
+     * Original invocation as an argv array (e.g. ['moda', 'provision',
+     * '--save']), threaded into recoverable failures so the caller knows
+     * exactly how to resume after logging in.
+     */
+    resumeCommand?: string[];
+}
+export interface ProvisionResult {
+    exitCode: number;
+    apiKey?: string;
+}
+/**
+ * The credentials document printed to stdout. Field names are a public
+ * contract (`moda provision | jq -r .apiKey`); do not rename.
+ */
+export interface ProvisionPayload {
+    apiKey: string;
+    tenantId: string;
+    tenantName: string;
+    tenantSlug: string;
+    ingestUrl: string;
+    baseUrl: string;
+    reused: boolean;
+}
+export declare function runProvision(context: CommandContext, options?: ProvisionRunOptions): Promise<ProvisionResult>;
+//# sourceMappingURL=provision.d.ts.map

package/dist/provision.js

@@ -0,0 +1,104 @@
+// src/provision.ts — moda provision: headless tenant + API key provisioning
+// for CI jobs and agents. Requires an existing CLI session (moda auth login
+// run previously); browserless signup is explicitly out of scope (decision
+// D3), so a missing session fails fast with CliAuthError instead of opening
+// a browser.
+import { loadAuthSession } from './auth.js';
+import { stringOption } from './command-context.js';
+import { resolveIngestUrl, resolveModaBaseUrl } from './config.js';
+import { CliAuthError } from './errors.js';
+import { selectTenantAndCreateKey } from './init/tenant.js';
+export async function runProvision(context, options = {}) {
+    const resumeCommand = options.resumeCommand ?? ['moda', 'provision'];
+    // Pre-coercion raw values (like init's tenantIdFlag/profileFlag): the
+    // dispatcher's flagsToArgs number-coerces numeric-looking values, which
+    // must never happen to tenant ids, profile names, or labels.
+    const profileFlag = stringOption(context.rawFlags.profile);
+    const authOptions = { profile: profileFlag, env: context.env };
+    // Provision never opens a browser (headless by contract), so the session
+    // check happens up front: no stored session is a recoverable exit-4
+    // failure with explicit instructions, not a login prompt.
+    const session = loadAuthSession(authOptions);
+    if (!session) {
+        const expiredSession = loadAuthSession({ ...authOptions, includeExpired: true });
+        throw new CliAuthError('moda provision requires an existing CLI session and never opens a browser. ' +
+            'Run "moda auth login" on a machine with a browser first, then re-run provision here ' +
+            '(or skip provisioning and set MODA_API_KEY directly).', {
+            reason: expiredSession ? 'token_expired' : 'no_stored_credentials',
+            login_command: ['moda', 'auth', 'login'],
+            resume_command: resumeCommand,
+        });
+    }
+    const flagTenantId = stringOption(context.rawFlags['tenant-id'] ?? context.rawFlags.tenant_id);
+    const envTenantId = stringOption(context.env.MODA_TENANT_ID);
+    const label = stringOption(context.rawFlags.label);
+    const save = context.flags.save === 'true';
+    // Reuses init's dedup + bootstrap machinery (stored-key liveness probe,
+    // Idempotency-Key persistence, label, cap/viewer errors). Multi-tenant
+    // accounts without --tenant-id/MODA_TENANT_ID throw CliInputRequiredError
+    // (exit 5) with per-tenant resume flags — even on a TTY, provision is
+    // headless by contract and never prompts.
+    let result;
+    try {
+        result = await selectTenantAndCreateKey({
+            tenantId: flagTenantId ?? envTenantId,
+            tenantIdSource: flagTenantId !== undefined ? 'flag' : envTenantId !== undefined ? 'env' : undefined,
+            // Unconditional (init derives this from flags/TTY): provision is
+            // headless by contract even on an interactive terminal.
+            nonInteractive: true,
+            // stdout must stay exactly one JSON credentials document; all provision
+            // prose goes to stderr, so suppress the tenant-selection prose entirely.
+            silent: true,
+            // Multi-tenant runs surface CliInputRequiredError (exit 5); echo this
+            // invocation's resume command so the caller knows how to continue.
+            resumeCommand,
+            label,
+            // Headless callers own their credential storage; --save opts into the
+            // init-style ~/.moda/config.json persistence.
+            persistConfig: save,
+            profile: profileFlag,
+            env: context.env,
+        });
+    }
+    catch (error) {
+        // A mid-flight 401 classified by authFetch (token_expired /
+        // token_revoked / renew_failed during the context or bootstrap call)
+        // throws a CliAuthError that carries only the login command. Re-throw
+        // with this invocation's resume command attached so the caller knows how
+        // to continue after recovering, matching the upfront session gate above.
+        if (error instanceof CliAuthError && !error.auth.resume_command) {
+            throw new CliAuthError(error.message, {
+                reason: error.auth.reason,
+                login_command: error.auth.login_command,
+                resume_command: resumeCommand,
+            });
+        }
+        throw error;
+    }
+    const payload = {
+        apiKey: result.apiKey,
+        tenantId: result.tenantId,
+        tenantName: result.tenantName,
+        tenantSlug: result.tenantSlug,
+        ingestUrl: resolveIngestUrl(authOptions),
+        baseUrl: resolveModaBaseUrl(authOptions),
+        reused: result.reused,
+    };
+    // Security note on stderr, never stdout: stdout carries a live credential
+    // and must stay exactly one parseable JSON document.
+    console.error('Output contains a live API key. Avoid piping to logs.');
+    if (save) {
+        console.error('Saved API key + tenant to ~/.moda/config.json (--save).');
+    }
+    // `moda provision` exists to be composed: `KEY=$(moda provision | jq -r
+    // .apiKey)`. Command substitution IS a pipe, so stdout is a non-TTY and
+    // the CLI would auto-select agent mode and wrap the payload in a
+    // moda.agent.v1 envelope, burying apiKey under `.data`. Like `moda auth
+    // token`, this command therefore deliberately bypasses the CliOutput
+    // envelope machinery in EVERY output mode (human/json/agent) and writes
+    // exactly one JSON document to stdout — nothing else. Human TTY runs get
+    // the same machine-parseable JSON: credentials output is the whole point.
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return { exitCode: 0, apiKey: result.apiKey };
+}
+//# sourceMappingURL=provision.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.13.1",
+  "version": "1.13.2",
   "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-06T10:28:52.049Z",
-  "cli_version": "1.13.1",
+  "bundled_at": "2026-07-06T10:32:52.250Z",
+  "cli_version": "1.13.2",
   "skills": [
     {
       "id": "integration-node-anthropic",

package/skills/moda-cli/SKILL.md

@@ -44,10 +44,12 @@ the user specifically asked for `moda prompts sync` or `moda prompts promote`.
 
 ## Required inputs
 
-Before running any command except `moda init`:
+Before running any command except `moda init`, `moda provision`, and the
+`moda auth ...` session commands (which use the browser/CLI session instead):
 
 - `MODA_API_KEY` env var must be set (`moda_sk_...`). If missing, run
-  `moda init` to provision one, or have the user export it.
+  `moda init` (interactive) or `moda provision` (headless, needs an existing
+  session) to provision one, or have the user export it.
 
 Optional:
 
@@ -78,6 +80,56 @@ npx -p @moda-ai/cli moda <command>
 export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
 ```
 
+### Headless provisioning (CI / agents): `moda provision`
+
+`moda provision` mints (or reuses) a tenant API key with zero prompts and
+prints a single JSON credentials document to stdout — in every output mode,
+even on an interactive terminal, so it composes directly:
+
+```bash
+KEY=$(moda provision --tenant-id t1 | jq -r .apiKey)
+```
+
+Output shape:
+
+```json
+{
+  "apiKey": "moda_sk_...",
+  "tenantId": "t1",
+  "tenantName": "Acme",
+  "tenantSlug": "acme",
+  "ingestUrl": "https://moda-ingest.modas.workers.dev",
+  "baseUrl": "https://moda.dev",
+  "reused": false
+}
+```
+
+Rules and limitations:
+
+- **Requires an existing CLI session.** There is no browserless signup or
+  login: with no stored session it exits `4` (`auth_required`) telling you to
+  run `moda auth login` on a machine with a browser first, or to skip
+  provisioning and export `MODA_API_KEY` directly.
+- **Never prompts, even on a TTY.** A single-tenant account auto-selects;
+  with multiple tenants you must pass `--tenant-id=<id>` (or set
+  `MODA_TENANT_ID`), otherwise it exits `5` (`needs_input`) with per-tenant
+  `resume_flags`.
+- `reused: true` means a previously stored key for that tenant passed a
+  liveness probe and was reused instead of minting a new one (same dedup +
+  idempotent bootstrap machinery as `moda init`).
+- **Does not write `~/.moda/config.json` by default** — headless callers own
+  their credential storage. Pass `--save` to opt into the init-style
+  persistence.
+- `--label=<text>` names the created key (default: machine hostname);
+  `--profile=NAME` scopes the session lookup.
+- stdout carries a live credential — a warning is printed to stderr; never
+  pipe provision stdout into logs.
+
+**When to use which:** `moda init` is the interactive first-time onboarding
+wizard for a repo (harness discovery, skills, prompts, validation);
+`moda provision` is for CI jobs and agents that already have a session and
+just need credentials.
+
 ### Auth session inspection and token composition
 
 ```bash
@@ -694,6 +746,7 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | Command | Purpose |
 |---|---|
 | `moda init` | Browser auth + provision API key + install agent rules |
+| `moda provision` | Headless tenant + API key provisioning; single JSON credentials doc on stdout (exit `4` without a session, `5` when `--tenant-id` is needed) |
 | `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) |