fluxmail 0.5.0 → 0.6.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { emitKeypressEvents } from 'node:readline';
 import { createInterface } from 'node:readline/promises';
 import { hostname } from 'node:os';
@@ -10,7 +10,8 @@ import { serve } from '@hono/node-server';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { EmailError, isEmailError } from '@fluxmail/core';
 import { createContext } from './context.js';
-import { configFilePath, maskStoredConfigValue, readStoredConfig, resolveDataDir, setStoredConfig, unsetStoredConfig, } from './config.js';
+import { configTomlPath, createConfigurationService, deploymentToml, readLoggingSettings, resolveDataDir, resolveStoreLocation, writeDeploymentConfig, } from './config.js';
+import { migrateConfigurationFile, parseEnvContent, recognizedMigrationSettings } from './configMigration.js';
 import { createApp } from './http/app.js';
 import { buildMcpServer } from './mcp/buildServer.js';
 import { runLoopbackFlow } from './accounts/googleAuth.js';
@@ -21,12 +22,16 @@ import { findMember } from './storage/members.js';
 import { LICENSE_KEY_PATTERN } from './licensing/client.js';
 import { checkLicenseState, getEntitlements } from './licensing/entitlements.js';
 import { VERSION } from './version.js';
+import { inspectStoreCompatibility, MIN_SUPPORTED_STORE_FORMAT, openDb, openReadonlyDb, } from './storage/db.js';
 import { customPermissionPolicy, ADMIN_CAPABILITIES, FULL_PERMISSION_POLICY, isNamedPermissionProfile, MCP_CAPABILITIES, NAMED_PERMISSION_PROFILES, permissionPolicyForProfile, } from './permissions.js';
-import { captureOperation, getTelemetry, installTelemetryStreamEndHandler, isTelemetryEnabled, setTelemetryEnabled, shutdownTelemetry, } from './telemetry.js';
+import { captureOperation, getTelemetry, installTelemetryStreamEndHandler, isTelemetryEnabled, setTelemetryEnabled, shutdownTelemetry, telemetryDisabledInAnyEnvironment, } from './telemetry.js';
 import { clearSessionToken, instanceClient, loadInstanceConfig, removeInstance, resolveInstance, saveLocalInstance, saveRemoteInstance, saveSessionToken, useInstance, } from './cliInstances.js';
-import { authenticateBearer, recoverAdminPassword, setupInitialAdmin } from './auth.js';
+import { authenticateBearer, normalizeAndValidatePassword, recoverAdminPassword, setupInitialAdmin } from './auth.js';
 import { recordAdminAuditEvent } from './storage/adminAudit.js';
 import { canManageOwnedAccount } from './authorization.js';
+import { createCliUpdateNotifier } from './updateNotifier.js';
+import { registerMailCommands } from './cliMail.js';
+import { flushLogging, escapeLogTextForConsole, getLogger, logCodedFailure, logFailure, readLocalLogs, shutdownLogging, } from './logging.js';
 function collectOption(value, previous) {
     return [...previous, value];
 }
@@ -81,11 +86,11 @@ function connectionSecurity(value, option) {
 }
 async function hiddenPrompt(label) {
     if (!process.stdin.isTTY || !process.stdin.setRawMode) {
-        throw new EmailError('invalid_request', `${label} must be supplied through a password environment variable.`);
+        throw new EmailError('invalid_request', `${label} requires an interactive terminal or an explicit non-interactive input.`);
     }
+    const wasFlowing = process.stdin.readableFlowing === true;
     emitKeypressEvents(process.stdin);
     const wasRaw = process.stdin.isRaw;
-    const wasPaused = process.stdin.isPaused();
     process.stdout.write(`${label}: `);
     process.stdin.setRawMode(true);
     process.stdin.resume();
@@ -94,7 +99,7 @@ async function hiddenPrompt(label) {
         const finish = (error) => {
             process.stdin.off('keypress', onKeypress);
             process.stdin.setRawMode(wasRaw);
-            if (wasPaused)
+            if (!wasFlowing)
                 process.stdin.pause();
             process.stdout.write('\n');
             if (error)
@@ -136,6 +141,25 @@ async function textPrompt(label) {
 async function loginPassword(label = 'Password') {
     return process.env.FLUXMAIL_PASSWORD ?? hiddenPrompt(label);
 }
+async function newPassword(label, member, prompt) {
+    return withNewPassword(label, member, prompt, async (password) => password);
+}
+async function withNewPassword(label, member, prompt, submit) {
+    const configured = process.env.FLUXMAIL_PASSWORD;
+    if (configured !== undefined)
+        return submit(normalizeAndValidatePassword(configured, member));
+    for (;;) {
+        const password = await prompt(label);
+        try {
+            return await submit(normalizeAndValidatePassword(password, member));
+        }
+        catch (error) {
+            if (!(error instanceof EmailError) || error.code !== 'invalid_request')
+                throw error;
+            console.error(`Error: ${error.message}`);
+        }
+    }
+}
 async function accountSecret(envName, label) {
     if (!envName)
         return hiddenPrompt(label);
@@ -144,6 +168,15 @@ async function accountSecret(envName, label) {
         throw new EmailError('invalid_request', `${envName} is not set or is empty.`);
     return value;
 }
+function readSecretFile(file) {
+    const value = readFileSync(file === '-' ? 0 : file, 'utf8').replace(/\r?\n$/, '');
+    if (!value)
+        throw new EmailError('invalid_request', 'The secret input is empty.');
+    return value;
+}
+async function secretInput(file, label) {
+    return file === undefined ? hiddenPrompt(label) : readSecretFile(file);
+}
 function planLine(ent) {
     const members = `${ent.maxMembers} member${ent.maxMembers === 1 ? '' : 's'}`;
     return `${ent.plan} (up to ${ent.maxAccounts} mailboxes, ${members})`;
@@ -155,11 +188,19 @@ function warnLicense(db, log = console.error) {
         log(`Warning: ${warning}`);
 }
 const activeCliOperations = new WeakMap();
-function finishCliOperation(program, outcome, errorCode) {
+const activeUpdateNotifiers = new WeakMap();
+function finishCliOperation(program, outcome, errorCode, error) {
     const active = activeCliOperations.get(program);
     if (!active)
         return;
     activeCliOperations.delete(program);
+    if (outcome === 'error' && !active.errorLogged) {
+        const context = { productSurface: 'cli', operation: active.operation, skipConsole: true };
+        if (error !== undefined)
+            logFailure(active.logger, 'cli.operation_failed', error, context);
+        else
+            logCodedFailure(active.logger, 'cli.operation_failed', errorCode ?? 'command_failed', 'CLI command failed', context);
+    }
     captureOperation(active.telemetry, {
         productSurface: 'cli',
         operation: active.operation,
@@ -168,6 +209,17 @@ function finishCliOperation(program, outcome, errorCode) {
         errorCode,
     });
 }
+function logActiveCliError(program, error) {
+    const active = activeCliOperations.get(program);
+    if (!active || active.errorLogged)
+        return;
+    active.errorLogged = true;
+    logFailure(active.logger, 'cli.operation_failed', error, {
+        productSurface: 'cli',
+        operation: active.operation,
+        skipConsole: true,
+    });
+}
 export function waitForServerListening(server) {
     return new Promise((resolve, reject) => {
         const onError = (error) => {
@@ -182,15 +234,39 @@ export function waitForServerListening(server) {
         server.once('listening', onListening);
     });
 }
+async function shutdownTelemetryThenLogging() {
+    try {
+        await shutdownTelemetry();
+    }
+    finally {
+        await shutdownLogging();
+    }
+}
+export async function shutdownTelemetryAndLogging() {
+    const initialLogFlush = flushLogging().catch(() => { });
+    try {
+        await shutdownTelemetry();
+    }
+    finally {
+        await initialLogFlush;
+        await shutdownLogging();
+    }
+}
+export function installStdioShutdownHandler(stream) {
+    installTelemetryStreamEndHandler(stream, shutdownTelemetryThenLogging);
+}
 /** Build the command tree without parsing arguments or running command actions. */
 export function createCliProgram(options = {}) {
     const program = new Command();
     program
         .name('fluxmail')
-        .description('Fluxmail, a self-hosted MCP server for your email')
+        .description('Fluxmail, a self-hosted email API with MCP, REST, and CLI access')
         .option('--instance <name>', 'Use a named local or remote instance')
+        .option('-a, --mail-account <id-or-email>', 'Use an email account by ID or address')
+        .option('--no-update-notifier', 'Skip the automatic update check for this command')
         .version(VERSION, '-v, --version');
     const selectedInstance = () => program.opts().instance;
+    const selectedAccount = () => program.opts().mailAccount;
     function commandPath(command) {
         const names = [];
         for (let current = command; current?.parent; current = current.parent)
@@ -199,7 +275,7 @@ export function createCliProgram(options = {}) {
     }
     let telemetrySignalHandlersInstalled = false;
     const TELEMETRY_SIGNAL_SHUTDOWN_TIMEOUT_MS = 1_000;
-    /** Flush queued telemetry before restoring Node's default signal behavior. */
+    /** Flush queued telemetry and local logs before restoring Node's default signal behavior. */
     function installTelemetrySignalHandlers() {
         if (telemetrySignalHandlersInstalled)
             return;
@@ -216,7 +292,7 @@ export function createCliProgram(options = {}) {
                 process.kill(process.pid, signal);
             };
             const timeout = setTimeout(resignal, TELEMETRY_SIGNAL_SHUTDOWN_TIMEOUT_MS);
-            void shutdownTelemetry().finally(() => {
+            void shutdownTelemetryAndLogging().finally(() => {
                 clearTimeout(timeout);
                 resignal();
             });
@@ -230,14 +306,57 @@ export function createCliProgram(options = {}) {
     }
     program.hook('preAction', (_command, actionCommand) => {
         const command = commandPath(actionCommand);
+        const updateNotifierEnabled = program.opts().updateNotifier;
+        if (updateNotifierEnabled && actionCommand.name() !== 'stdio') {
+            try {
+                const notifier = options.updateNotifierFactory?.();
+                if (notifier)
+                    activeUpdateNotifiers.set(program, notifier);
+            }
+            catch {
+                // Update checks must not affect command execution.
+            }
+        }
         // Respect the opt-out before creating a telemetry client or recording this command.
         if (command === 'telemetry disable')
             return;
+        let telemetryEnvironment;
+        let telemetryDataDir;
+        if (command === 'config migrate') {
+            const migration = actionCommand.opts();
+            if (migration.from) {
+                try {
+                    const values = parseEnvContent(readFileSync(path.resolve(migration.from), 'utf8'));
+                    if (values.FLUXMAIL_DATA_DIR !== undefined) {
+                        telemetryDataDir = resolveDataDir({
+                            env: { ...process.env, FLUXMAIL_DATA_DIR: values.FLUXMAIL_DATA_DIR },
+                        });
+                    }
+                    if (telemetryDisabledInAnyEnvironment(process.env, values)) {
+                        telemetryEnvironment = { ...process.env, FLUXMAIL_TELEMETRY: '0' };
+                    }
+                }
+                catch {
+                    // The command action reports file and parsing errors.
+                }
+            }
+        }
+        const dataDir = telemetryDataDir ?? resolveDataDir();
+        let logging;
+        try {
+            logging = readLoggingSettings(dataDir);
+        }
+        catch {
+            // Keep recovery and remote commands available when logging configuration is invalid.
+            logging = { level: 'info', destination: 'both' };
+        }
+        const mode = actionCommand.name() === 'serve' ? 'serve' : actionCommand.name() === 'stdio' ? 'stdio' : 'cli';
         activeCliOperations.set(program, {
-            telemetry: options.telemetry ?? getTelemetry(resolveDataDir()),
+            telemetry: options.telemetry ?? getTelemetry(dataDir, telemetryEnvironment),
             operation: command,
             startedAt: performance.now(),
             initialExitCode: process.exitCode,
+            logger: getLogger(dataDir, mode, logging),
         });
     });
     program.hook('postAction', async (_command, actionCommand) => {
@@ -247,8 +366,20 @@ export function createCliProgram(options = {}) {
             process.exitCode !== undefined &&
             process.exitCode !== 0;
         finishCliOperation(program, failed ? 'error' : 'success', failed ? 'command_failed' : undefined);
-        if (!options.telemetry && actionCommand.name() !== 'serve' && actionCommand.name() !== 'stdio') {
-            await shutdownTelemetry();
+        try {
+            if (actionCommand.name() !== 'serve' && actionCommand.name() !== 'stdio') {
+                await Promise.all([options.telemetry ? Promise.resolve() : shutdownTelemetry(), shutdownLogging()]);
+            }
+        }
+        finally {
+            const notifier = activeUpdateNotifiers.get(program);
+            activeUpdateNotifiers.delete(program);
+            try {
+                notifier?.notify();
+            }
+            catch {
+                // Update notices must not affect the command outcome.
+            }
         }
     });
     program
@@ -261,8 +392,11 @@ export function createCliProgram(options = {}) {
         try {
             const name = opts.name ?? (opts.existingAdmin ? undefined : await textPrompt('Administrator name'));
             const email = opts.email ?? (await textPrompt('Administrator email'));
-            const password = await loginPassword('New password');
             const context = createContext();
+            const passwordMember = opts.existingAdmin
+                ? { ...findMember(context.db, opts.existingAdmin), email }
+                : { name: name ?? '', email };
+            const password = await newPassword('New password', passwordMember, options.passwordPrompt ?? hiddenPrompt);
             const result = await setupInitialAdmin(context.db, {
                 ...(name ? { name } : {}),
                 email,
@@ -281,6 +415,7 @@ export function createCliProgram(options = {}) {
             console.log(`Fluxmail is ready. Logged in to local as ${result.member.name}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -307,16 +442,15 @@ export function createCliProgram(options = {}) {
             const client = instanceClient(instanceName, false);
             const deviceName = `CLI on ${hostname()}`;
             const result = opts.enroll || opts.reset
-                ? await client.json(opts.reset ? '/api/v1/auth/password-reset' : '/api/v1/auth/enroll', {
-                    method: 'POST',
-                    headers: { 'content-type': 'application/json' },
-                    body: JSON.stringify({
-                        token: (opts.reset ? process.env.FLUXMAIL_RESET_CODE : process.env.FLUXMAIL_INVITE_CODE) ??
-                            (await hiddenPrompt(opts.reset ? 'Password reset code' : 'Enrollment code')),
-                        password: await loginPassword('New password'),
-                        deviceName,
-                    }),
-                }, false)
+                ? await (async () => {
+                    const token = (opts.reset ? process.env.FLUXMAIL_RESET_CODE : process.env.FLUXMAIL_INVITE_CODE) ??
+                        (await hiddenPrompt(opts.reset ? 'Password reset code' : 'Enrollment code'));
+                    return withNewPassword('New password', undefined, options.passwordPrompt ?? hiddenPrompt, (password) => client.json(opts.reset ? '/api/v1/auth/password-reset' : '/api/v1/auth/enroll', {
+                        method: 'POST',
+                        headers: { 'content-type': 'application/json' },
+                        body: JSON.stringify({ token, password, deviceName }),
+                    }, false));
+                })()
                 : await client.json('/api/v1/auth/login', {
                     method: 'POST',
                     headers: { 'content-type': 'application/json' },
@@ -331,6 +465,7 @@ export function createCliProgram(options = {}) {
             console.log(`Logged in to ${instanceName} as ${result.member.name}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -349,6 +484,7 @@ export function createCliProgram(options = {}) {
             console.log(`Logged out of ${selected.name}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -373,6 +509,7 @@ export function createCliProgram(options = {}) {
             console.log(`Using ${name}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -387,6 +524,7 @@ export function createCliProgram(options = {}) {
             console.log(`Removed CLI instance ${name}. Server data was not changed.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -402,8 +540,9 @@ export function createCliProgram(options = {}) {
             if (selected.profile.kind !== 'local') {
                 throw new EmailError('invalid_request', 'Administrator recovery is only available on the local instance host.');
             }
-            const password = await loginPassword('New password');
             const context = createContext();
+            const target = findMember(context.db, memberRef);
+            const password = await newPassword('New password', target, options.passwordPrompt ?? hiddenPrompt);
             const member = await recoverAdminPassword(context.db, memberRef, password);
             recordAdminAuditEvent(context.db, {
                 operation: 'auth.recover_admin',
@@ -415,6 +554,7 @@ export function createCliProgram(options = {}) {
             console.log(`Reset ${member.name}'s password and revoked existing sessions.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -430,6 +570,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -446,6 +587,7 @@ export function createCliProgram(options = {}) {
             console.log(`Revoked ${sessionId}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -459,6 +601,10 @@ export function createCliProgram(options = {}) {
         const app = createApp(ctx);
         ctx.scheduler.start();
         const server = serve({ fetch: app.fetch, port: ctx.config.port }, () => {
+            ctx.logger.info('server.started', 'Fluxmail HTTP server started', {
+                details: { port: ctx.config.port },
+                skipConsole: true,
+            });
             ctx.telemetry.capture('mcp server started', { product_surface: 'mcp', transport: 'http' });
             console.log(`Fluxmail listening on ${ctx.config.publicUrl}`);
             console.log(`  MCP endpoint:   ${ctx.config.publicUrl}/mcp`);
@@ -478,7 +624,7 @@ export function createCliProgram(options = {}) {
             }
             console.log(`  Plan:           ${planLine(getEntitlements(ctx.db))}`);
             warnLicense(ctx.db, console.log);
-            ctx.licenseController.start(console.log);
+            ctx.licenseController.start();
         });
         await waitForServerListening(server);
     });
@@ -490,7 +636,7 @@ export function createCliProgram(options = {}) {
         .option('--allow <capability>', 'Allow one MCP capability; repeat as needed', collectOption, [])
         .action(async (opts) => {
         installTelemetrySignalHandlers();
-        installTelemetryStreamEndHandler(process.stdin);
+        installStdioShutdownHandler(process.stdin);
         const ctx = createContext();
         const permissions = permissionPolicyFromOptions(opts);
         const selected = resolveInstance(selectedInstance());
@@ -509,12 +655,18 @@ export function createCliProgram(options = {}) {
             maxAttachmentBytes: ctx.config.maxAttachmentBytes,
             telemetry: ctx.telemetry,
             transport: 'stdio',
+            logger: ctx.logger,
         });
         ctx.scheduler.start();
         await server.connect(new StdioServerTransport());
         ctx.telemetry.capture('mcp server started', { product_surface: 'mcp', transport: 'stdio' });
+        ctx.logger.info('server.started', 'Fluxmail stdio MCP server started', {
+            productSurface: 'mcp',
+            details: { transport: 'stdio' },
+            skipConsole: true,
+        });
         // stdout belongs to the MCP protocol; log to stderr only.
-        ctx.licenseController.start(console.error);
+        ctx.licenseController.start();
         console.error('Fluxmail MCP server running on stdio');
         warnLicense(ctx.db);
         const pending = scopedService.listScheduled().filter((send) => send.status === 'pending').length;
@@ -565,6 +717,7 @@ export function createCliProgram(options = {}) {
             validateAccountConnectionFlags(provider, opts);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
             return;
@@ -575,6 +728,7 @@ export function createCliProgram(options = {}) {
                 useControlPlane = selectGmailConnectionMode(createContext().config, opts) === 'hosted';
             }
             catch (err) {
+                logActiveCliError(program, err);
                 console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
                 process.exitCode = 1;
                 return;
@@ -644,6 +798,7 @@ export function createCliProgram(options = {}) {
                 }
             }
             catch (err) {
+                logActiveCliError(program, err);
                 console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
                 process.exitCode = 1;
             }
@@ -745,7 +900,7 @@ export function createCliProgram(options = {}) {
                     throw new EmailError('invalid_request', `Google authorized ${result.email}, but account ${existing.id} belongs to ${existing.email}. ` +
                         'Try again and choose the matching Google account.');
                 }
-                return ctx.registry.addGmailAccount(result.email, result.tokens, result.displayName, owner.id, access);
+                return ctx.registry.addGmailAccount(result.email, result.tokens, result.displayName, owner.id, access, result.oauthClient);
             });
             auditConnection('account.connection.complete', account.id);
             console.log(`\nConnected ${account.email} (account id: ${account.id})` +
@@ -757,7 +912,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
-            finishCliOperation(program, 'error', isEmailError(err) ? err.code : 'internal');
+            finishCliOperation(program, 'error', isEmailError(err) ? err.code : 'internal', err);
             console.error(`\nError: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -798,6 +953,7 @@ export function createCliProgram(options = {}) {
                 console.log(`Warning: ${warning.message}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -822,6 +978,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -838,6 +995,7 @@ export function createCliProgram(options = {}) {
             console.log(`Removed ${accountId}`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -857,6 +1015,7 @@ export function createCliProgram(options = {}) {
             console.log(`${account.email} is now owned by ${account.ownerMemberId}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -882,6 +1041,7 @@ export function createCliProgram(options = {}) {
             console.log(`Updated access for ${account.email}: ${account.sharedWithAll ? 'all members' : `${account.grantedMemberIds.length} explicit grant(s)`}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -908,6 +1068,7 @@ export function createCliProgram(options = {}) {
             console.log(`Expires: ${new Date(member.invitation.expiresAt).toISOString()}`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -927,6 +1088,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -943,6 +1105,7 @@ export function createCliProgram(options = {}) {
             console.log(`Removed ${memberId}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -965,6 +1128,7 @@ export function createCliProgram(options = {}) {
             console.log(`${member.name} now has the ${member.role} role.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -987,6 +1151,7 @@ export function createCliProgram(options = {}) {
             console.log(`${member.name} is now ${member.status}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1006,6 +1171,7 @@ export function createCliProgram(options = {}) {
                 console.log(`Expires: ${new Date(token.expiresAt).toISOString()}`);
             }
             catch (err) {
+                logActiveCliError(program, err);
                 console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
                 process.exitCode = 1;
             }
@@ -1023,6 +1189,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1038,6 +1205,7 @@ export function createCliProgram(options = {}) {
             console.log(`Revoked ${sessionId}.`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1094,6 +1262,7 @@ export function createCliProgram(options = {}) {
             console.log('Store it now; it cannot be shown again.');
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1120,6 +1289,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1146,6 +1316,7 @@ export function createCliProgram(options = {}) {
                 : `Updated ${keyId} to ${accountIds.length} mailbox(es).`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1180,6 +1351,7 @@ export function createCliProgram(options = {}) {
             console.log(`Updated ${keyId} to profile ${permissions.profile}`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1199,6 +1371,7 @@ export function createCliProgram(options = {}) {
             console.log(`Revoked ${keyId}`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1206,9 +1379,19 @@ export function createCliProgram(options = {}) {
     const license = program.command('license').description('Manage the paid-tier license');
     license
         .command('activate')
-        .argument('<key>', 'License key (fluxmail_lic_…), shown once at purchase')
+        .argument('[key]', 'Deprecated: license key shown once at purchase')
+        .option('--key-file <path>', 'Read the license key from a file, or use - for stdin')
         .description('Store a license key and validate it with the license server')
-        .action(async (key) => {
+        .action(async (deprecatedKey, options) => {
+        if (deprecatedKey && options.keyFile) {
+            console.error('Error: The deprecated positional key cannot be combined with --key-file.');
+            process.exitCode = 1;
+            return;
+        }
+        if (deprecatedKey) {
+            console.error('Warning: Passing a license key as an argument is deprecated. Use --key-file or hidden input.');
+        }
+        const key = deprecatedKey ?? (await secretInput(options.keyFile, 'License key'));
         if (!LICENSE_KEY_PATTERN.test(key)) {
             console.error('That does not look like a Fluxmail license key (expected "fluxmail_lic_" followed by 40 hex characters).');
             process.exitCode = 1;
@@ -1230,6 +1413,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1242,7 +1426,7 @@ export function createCliProgram(options = {}) {
             const status = await instanceClient(selectedInstance()).json('/api/v1/admin/license');
             console.log(status.configured
                 ? `License configured from ${status.source}.`
-                : 'No license key configured. Run "fluxmail license activate <key>" after purchasing one.');
+                : 'No license key configured. Run "fluxmail license activate" after purchasing one.');
             console.log(`Current plan: ${planLine(status.entitlements)}`);
             console.log(`Usage: ${status.usage.accounts} mailbox(es), ${status.usage.members} member(s)` +
                 (status.usage.overQuota ? ' (over plan limits)' : ''));
@@ -1252,6 +1436,7 @@ export function createCliProgram(options = {}) {
                 console.log(`Warning: ${status.warning}`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1268,51 +1453,174 @@ export function createCliProgram(options = {}) {
             console.log('This instance is back to Personal plan limits.');
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
     });
-    const configCmd = program
-        .command('config')
-        .description('Persistent settings stored in the data dir, usable from any directory');
+    const configCmd = program.command('config').description('Inspect and initialize deployment configuration');
     configCmd
-        .command('set')
-        .argument('<key>', 'Setting name, e.g. GOOGLE_CLIENT_ID')
-        .argument('<value>')
-        .description('Store a setting (shell env vars and local .env files still take precedence)')
-        .action((key, value) => {
+        .command('init')
+        .description('Create config.toml in the Fluxmail data directory')
+        .action(() => {
         try {
             const dataDir = resolveDataDir();
-            setStoredConfig(dataDir, key, value);
-            console.log(`Set ${key} in ${configFilePath(dataDir)}`);
+            const file = configTomlPath(dataDir);
+            writeDeploymentConfig(file, deploymentToml(), { exclusive: true });
+            console.log(`Created ${file}`);
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
     });
     configCmd
-        .command('unset')
-        .argument('<key>')
-        .description('Remove a stored setting')
-        .action((key) => {
-        const dataDir = resolveDataDir();
-        console.log(unsetStoredConfig(dataDir, key) ? `Removed ${key}` : `${key} is not set`);
+        .command('show')
+        .description('Show effective configuration, sources, paths, and restart requirements')
+        .action(() => {
+        const deployment = resolveStoreLocation().deployment;
+        const compatibility = inspectStoreCompatibility(deployment.dbPath, deployment.dataDir);
+        const canReadInstanceSettings = compatibility.storeFormat >= MIN_SUPPORTED_STORE_FORMAT &&
+            compatibility.storeFormat <= compatibility.maximumSupportedFormat;
+        const db = canReadInstanceSettings && deployment.dbPath !== ':memory:'
+            ? openReadonlyDb(deployment.dbPath)
+            : openDb(':memory:', { backupBeforeMigration: false });
+        try {
+            const configuration = createConfigurationService(deployment, db);
+            const config = configuration.config;
+            console.log(`Data directory: ${deployment.dataDir} [${deployment.sources.dataDir}]`);
+            console.log(`Configuration file: ${deployment.configFile}${existsSync(deployment.configFile) ? '' : ' (not created)'}`);
+            console.log(`Database: ${deployment.dbPath} [${deployment.sources.dbPath}] restart required`);
+            console.log(`Server port: ${deployment.port} [${deployment.sources.port}] restart required`);
+            console.log(`Public URL: ${deployment.publicUrl} [${deployment.sources.publicUrl}] restart required`);
+            console.log(`Trust proxy: ${deployment.trustProxy} [${deployment.sources.trustProxy}] restart required`);
+            console.log(`Local OAuth host: ${deployment.oauthHost} [${deployment.sources.oauthHost}] restart required`);
+            console.log(`Local OAuth port: ${deployment.oauthPort} [${deployment.sources.oauthPort}] restart required`);
+            console.log(`Maximum attachment: ${deployment.maxAttachmentBytes / (1024 * 1024)} MB [${deployment.sources.maxAttachmentBytes}] restart required`);
+            console.log(`Encryption key: ${deployment.encryptionKey.length === 32 ? 'configured' : 'not configured'} [${deployment.sources.encryptionKey}]`);
+            const oauth = configuration.oauthStatus();
+            console.log(`Google OAuth: configured [${oauth.google.source}]`);
+            console.log(`Outlook OAuth: ${oauth.outlook.clientId ? 'configured' : 'not configured'} [${oauth.outlook.source ?? 'none'}]`);
+            console.log(`License: ${config.licenseKey ? 'configured' : 'not configured'} [${configuration.licenseSource() ?? 'none'}]`);
+        }
+        finally {
+            db.$client.close();
+        }
     });
     configCmd
-        .command('list')
-        .description('Show stored settings (secret values are masked)')
-        .action(() => {
-        const dataDir = resolveDataDir();
-        const stored = readStoredConfig(dataDir);
-        const keys = Object.keys(stored);
-        if (!keys.length) {
-            console.log(`No stored settings. Run "fluxmail config set <KEY> <value>" (file: ${configFilePath(dataDir)}).`);
+        .command('migrate')
+        .requiredOption('--from <env-file>', 'Read recognized settings from this env file')
+        .option('--dry-run', 'Show recognized setting names without changing Fluxmail')
+        .description('Import settings from an env file without deleting it')
+        .action((options) => {
+        const source = path.resolve(options.from);
+        if (options.dryRun) {
+            const recognized = recognizedMigrationSettings(parseEnvContent(readFileSync(source, 'utf8')));
+            console.log(recognized.length ? recognized.join('\n') : 'No recognized settings found.');
             return;
         }
-        for (const key of keys) {
-            const value = stored[key] ?? '';
-            console.log(`${key}=${maskStoredConfigValue(key, value)}`);
+        const result = migrateConfigurationFile(source);
+        console.log(`Imported ${result.recognized.length} recognized setting${result.recognized.length === 1 ? '' : 's'} from ${result.source}.`);
+        console.log('Restart Fluxmail to apply deployment configuration changes.');
+    });
+    const oauth = program.command('oauth').description('Manage OAuth applications');
+    oauth
+        .command('status')
+        .description('Show OAuth application status without secrets')
+        .action(async () => {
+        const status = await instanceClient(selectedInstance()).json('/api/v1/admin/oauth-apps');
+        console.log(JSON.stringify(status, null, 2));
+    });
+    const oauthConfigure = oauth.command('configure').description('Configure an OAuth application');
+    oauthConfigure
+        .command('google')
+        .requiredOption('--client-id <id>', 'Google OAuth client ID')
+        .option('--client-secret-file <path>', 'Read the client secret from a file, or use - for stdin')
+        .description('Configure a custom Google OAuth application')
+        .action(async (options) => {
+        const clientSecret = await secretInput(options.clientSecretFile, 'Google client secret');
+        await instanceClient(selectedInstance()).json('/api/v1/admin/oauth-apps/google', {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ clientId: options.clientId, clientSecret }),
+        });
+        console.log('Google OAuth application configured.');
+    });
+    oauthConfigure
+        .command('outlook')
+        .requiredOption('--client-id <id>', 'Microsoft OAuth client ID')
+        .option('--tenant-id <tenant>', 'Microsoft tenant ID', 'common')
+        .option('--public-client', 'Configure a public client without a secret')
+        .option('--client-secret-file <path>', 'Read the client secret from a file, or use - for stdin')
+        .description('Configure a custom Microsoft OAuth application')
+        .action(async (options) => {
+        if (options.publicClient && options.clientSecretFile) {
+            throw new EmailError('invalid_request', '--public-client cannot be combined with --client-secret-file.');
+        }
+        const clientSecret = options.publicClient
+            ? undefined
+            : await secretInput(options.clientSecretFile, 'Microsoft client secret');
+        await instanceClient(selectedInstance()).json('/api/v1/admin/oauth-apps/outlook', {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                clientId: options.clientId,
+                tenantId: options.tenantId,
+                publicClient: Boolean(options.publicClient),
+                ...(clientSecret ? { clientSecret } : {}),
+            }),
+        });
+        console.log('Microsoft OAuth application configured.');
+    });
+    oauth
+        .command('reset')
+        .argument('<provider>', 'google or outlook')
+        .description('Remove a stored OAuth application')
+        .action(async (provider) => {
+        if (provider !== 'google' && provider !== 'outlook') {
+            throw new EmailError('invalid_request', 'Provider must be google or outlook.');
+        }
+        await instanceClient(selectedInstance()).json(`/api/v1/admin/oauth-apps/${provider}`, { method: 'DELETE' });
+        console.log(`${provider === 'google' ? 'Google' : 'Microsoft'} OAuth application reset.`);
+    });
+    program
+        .command('logs')
+        .description('Show recent local log entries')
+        .option('--tail <count>', 'Number of entries to show, from 1 through 1000', '100')
+        .option('--level <level>', 'Minimum level: info, warn, or error', 'info')
+        .option('--json', 'Print each entry as JSON')
+        .action((opts) => {
+        try {
+            const tail = Number(opts.tail);
+            if (!Number.isInteger(tail) || tail < 1 || tail > 1000) {
+                throw new EmailError('invalid_request', '--tail must be an integer from 1 through 1000.');
+            }
+            if (!['info', 'warn', 'error'].includes(opts.level)) {
+                throw new EmailError('invalid_request', '--level must be info, warn, or error.');
+            }
+            const result = readLocalLogs(resolveDataDir(), {
+                tail,
+                minimumLevel: opts.level,
+            });
+            for (const entry of result.entries) {
+                if (opts.json) {
+                    console.log(entry.raw);
+                    continue;
+                }
+                const singleLine = escapeLogTextForConsole;
+                const code = entry.record.error?.code ? ` [${singleLine(entry.record.error.code)}]` : '';
+                console.log(`${singleLine(entry.record.timestamp)} ${entry.record.level.toUpperCase()} ${singleLine(entry.record.event)}${code}: ${singleLine(entry.record.message)}`);
+            }
+            if (result.malformedLines > 0) {
+                console.error(`Warning: skipped ${result.malformedLines} malformed local log line${result.malformedLines === 1 ? '' : 's'}.`);
+            }
+        }
+        catch (error) {
+            const code = isEmailError(error) ? error.code : 'internal';
+            finishCliOperation(program, 'error', code, error);
+            console.error(`Error [${code}]: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
         }
     });
     const telemetryCmd = program.command('telemetry').description('Manage anonymous usage telemetry');
@@ -1330,7 +1638,6 @@ export function createCliProgram(options = {}) {
         .action(() => {
         const dataDir = resolveDataDir();
         setTelemetryEnabled(dataDir, true);
-        unsetStoredConfig(dataDir, 'FLUXMAIL_TELEMETRY');
         console.log('Telemetry enabled. FLUXMAIL_TELEMETRY=0 or DO_NOT_TRACK=1 can still turn it off.');
     });
     telemetryCmd
@@ -1340,6 +1647,15 @@ export function createCliProgram(options = {}) {
         const dataDir = resolveDataDir();
         console.log(`Telemetry is ${isTelemetryEnabled(dataDir) ? 'enabled' : 'disabled'}.`);
     });
+    registerMailCommands(program, {
+        selectedInstance,
+        selectedAccount,
+        reportError: (error, code) => {
+            finishCliOperation(program, 'error', code, error);
+            console.error(`Error [${code}]: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+        },
+    });
     program
         .command('status')
         .description('Show mailbox and provider status for the selected instance')
@@ -1349,6 +1665,7 @@ export function createCliProgram(options = {}) {
             console.log(JSON.stringify(status, null, 2));
         }
         catch (err) {
+            logActiveCliError(program, err);
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
             process.exitCode = 1;
         }
@@ -1356,15 +1673,15 @@ export function createCliProgram(options = {}) {
     return program;
 }
 export async function runCli(argv = process.argv) {
-    const program = createCliProgram();
+    const program = createCliProgram({ updateNotifierFactory: createCliUpdateNotifier });
     try {
         await program.parseAsync([...argv]);
     }
     catch (err) {
-        finishCliOperation(program, 'error', isEmailError(err) ? err.code : 'internal');
+        finishCliOperation(program, 'error', isEmailError(err) ? err.code : 'internal', err);
         console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
         process.exitCode = 1;
-        await shutdownTelemetry();
+        await Promise.all([shutdownTelemetry(), shutdownLogging()]);
     }
 }
 function isEntrypoint() {