fluxmail 0.12.0 → 0.14.0

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { emitKeypressEvents } from 'node:readline';
 import { createInterface } from 'node:readline/promises';
 import { hostname } from 'node:os';
@@ -10,12 +11,14 @@ 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 { RuntimeLifecycle } from './lifecycle.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';
 import { runMicrosoftLoopbackFlow } from './accounts/microsoftAuth.js';
+import { IMAP_CONNECTION_TEST_TIMEOUT_MS } from './accounts/registry.js';
 import { assertHostedConnectionReady, prepareHostedGmailConnection, prepareHostedOutlookConnection, selectGmailConnectionMode, validateAccountConnectionFlags, } from './accounts/gmailConnection.js';
 import { listApiKeys } from './storage/apiKeys.js';
 import { findMember } from './storage/members.js';
@@ -23,16 +26,17 @@ 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 { customPermissionPolicy, ADMIN_CAPABILITIES, DEFAULT_PERMISSION_POLICY, DEFAULT_PERMISSION_PROFILE, isNamedPermissionProfile, MCP_CAPABILITIES, NAMED_PERMISSION_PROFILES, permissionPolicyForProfile, } from './permissions.js';
 import { captureOperation, getTelemetry, installTelemetryStreamEndHandler, isTelemetryEnabled, setTelemetryEnabled, shutdownTelemetry, telemetryDisabledInAnyEnvironment, } from './telemetry.js';
 import { apiErrorCode, apiRequestId, clearSessionToken, instanceClient, loadInstanceConfig, removeInstance, resolveInstance, resolveStdioInstance, saveLocalInstance, saveRemoteInstance, saveSessionToken, setRequestDeadlineMs, useInstance, } from './cliInstances.js';
 import { cliExitCode, parseOutputFormat, printOutput } from './cliOutput.js';
+import { CliStartupError, cliStartupDiagnostics } from './cliStartupDiagnostics.js';
 import { authenticateBearer, isBootstrapComplete, 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 { accountInventoryProperties, configuredOAuthAppKind, connectionProperties, instanceUsageProperties, } from './accounts/telemetry.js';
+import { accountInventoryProperties, connectionFailureKind, configuredOAuthAppKind, connectionProperties, instanceUsageProperties, } from './accounts/telemetry.js';
 import { flushLogging, escapeLogTextForConsole, getLogger, logCodedFailure, logFailure, readLocalLogs, shutdownLogging, } from './logging.js';
 function collectOption(value, previous) {
     return [...previous, value];
@@ -43,25 +47,24 @@ function accountIdsFromRefs(ctx, refs) {
 export function permissionPolicyFromOptions(opts, requireSelection = false) {
     try {
         const supplemental = opts.admin ?? [];
-        if (opts.profile && opts.allow.length) {
-            throw new Error('--profile cannot be combined with --allow.');
-        }
-        if (opts.allow.length && supplemental.length) {
+        if (!opts.profile && opts.allow.length && supplemental.length) {
             throw new Error('--admin can only be combined with a named --profile. Put admin capabilities in --allow for a custom policy.');
         }
         if (opts.profile) {
             if (!isNamedPermissionProfile(opts.profile)) {
                 throw new Error(`Unknown profile "${opts.profile}". Expected one of: ${NAMED_PERMISSION_PROFILES.join(', ')}.`);
             }
-            return permissionPolicyForProfile(opts.profile, supplemental);
+            const named = permissionPolicyForProfile(opts.profile, supplemental);
+            // --allow adds capabilities to the profile, which makes the result a custom policy.
+            return opts.allow.length ? customPermissionPolicy([...named.capabilities, ...opts.allow]) : named;
         }
         if (opts.allow.length)
             return customPermissionPolicy(opts.allow);
         if (supplemental.length)
-            return permissionPolicyForProfile('full', supplemental);
+            return permissionPolicyForProfile(DEFAULT_PERMISSION_PROFILE, supplemental);
         if (requireSelection)
             throw new Error('Choose --profile or at least one --allow capability.');
-        return FULL_PERMISSION_POLICY;
+        return DEFAULT_PERMISSION_POLICY;
     }
     catch (error) {
         throw new EmailError('invalid_request', error instanceof Error ? error.message : String(error));
@@ -85,7 +88,12 @@ function connectionPort(value, option) {
     }
     return port;
 }
-function connectionSecurity(value, option) {
+// Without an explicit mode, follow the port's standard: implicit TLS on 993 and
+// 465, STARTTLS elsewhere. A mismatched mode fails the TLS handshake or waits
+// for a greeting the server never sends.
+function connectionSecurity(value, port, option) {
+    if (value === undefined)
+        return port === 993 || port === 465 ? 'tls' : 'starttls';
     if (value !== 'tls' && value !== 'starttls') {
         throw new EmailError('invalid_request', `${option} must be "tls" or "starttls".`);
     }
@@ -263,8 +271,43 @@ function finishCliOperation(program, outcome, errorCode, error) {
     if (!active)
         return;
     activeCliOperations.delete(program);
+    if (active.operation === 'accounts add' && outcome === 'error') {
+        const status = apiHttpStatus(error);
+        const connectionStage = apiConnectionStage(error);
+        active.properties = {
+            ...active.properties,
+            failure_kind: connectionFailureKind(errorCode ?? 'internal', status, error instanceof TypeError),
+            ...(status === undefined ? {} : { http_status: status }),
+            ...(connectionStage ? { connection_stage: connectionStage } : {}),
+        };
+    }
+    const startupProperties = active.operation === 'stdio' && outcome === 'error'
+        ? {
+            startup_phase: active.properties?.startup_phase,
+            startup_data_dir_source: active.properties?.startup_data_dir_source,
+            startup_instance_selection: active.properties?.startup_instance_selection,
+            ...cliStartupDiagnostics(error),
+        }
+        : {};
     if (outcome === 'error') {
-        const context = { productSurface: 'cli', operation: active.operation, skipConsole: true };
+        const connectionDetails = active.operation === 'accounts add'
+            ? {
+                request_id: apiRequestId(error),
+                connection_stage: active.properties?.connection_stage,
+                failure_kind: active.properties?.failure_kind,
+                http_status: active.properties?.http_status,
+            }
+            : undefined;
+        const details = {
+            ...(active.operation === 'stdio' ? startupProperties : {}),
+            ...connectionDetails,
+        };
+        const context = {
+            productSurface: 'cli',
+            operation: active.operation,
+            skipConsole: true,
+            ...(Object.values(details).some((value) => value !== undefined) ? { details } : {}),
+        };
         if (error !== undefined)
             logFailure(active.logger, 'cli.operation_failed', error, context);
         else
@@ -276,9 +319,24 @@ function finishCliOperation(program, outcome, errorCode, error) {
         outcome,
         durationMs: performance.now() - active.startedAt,
         errorCode,
-        ...(active.properties ? { properties: active.properties } : {}),
+        properties: { ...active.properties, ...startupProperties },
     });
 }
+function apiHttpStatus(error) {
+    if (!error || typeof error !== 'object' || !('status' in error))
+        return undefined;
+    const status = error.status;
+    return typeof status === 'number' && Number.isInteger(status) && status >= 0 && status <= 599 ? status : undefined;
+}
+function apiConnectionStage(error) {
+    if (!error || typeof error !== 'object' || !('connectionStage' in error))
+        return undefined;
+    const stage = error.connectionStage;
+    return typeof stage === 'string' &&
+        ['server_validation', 'provider_check', 'account_persist', 'oauth_prepare', 'complete'].includes(stage)
+        ? stage
+        : undefined;
+}
 /** End a failed command with the error's own telemetry code instead of a generic one. */
 function failCliOperation(program, error, prefix = 'Error: ') {
     const code = apiErrorCode(error);
@@ -446,7 +504,7 @@ export function createCliProgram(options = {}) {
         const alreadyStructured = ['folders', 'labels', 'emails', 'threads', 'drafts', 'scheduled', 'attachments'].includes(group ?? '') ||
             command === 'accounts list' ||
             command === 'status';
-        const interactive = ['setup', 'login', 'serve', 'stdio'].includes(command) ||
+        const interactive = ['setup', 'login', 'serve', 'stdio', 'scheduled run'].includes(command) ||
             group === 'auth' ||
             command === 'accounts add' ||
             command === 'accounts configure' ||
@@ -487,7 +545,9 @@ export function createCliProgram(options = {}) {
             process.exitCode !== 0;
         finishCliOperation(program, failed ? 'error' : 'success', failed ? 'command_failed' : undefined);
         try {
-            if (actionCommand.name() !== 'serve' && actionCommand.name() !== 'stdio') {
+            if (actionCommand.name() !== 'serve' &&
+                actionCommand.name() !== 'stdio' &&
+                commandPath(actionCommand) !== 'scheduled run') {
                 await Promise.all([options.telemetry ? Promise.resolve() : shutdownTelemetry(), shutdownLogging()]);
             }
         }
@@ -717,11 +777,22 @@ export function createCliProgram(options = {}) {
         .command('serve')
         .description('Run the HTTP server (MCP at /mcp and REST at /api/v1)')
         .action(async () => {
-        installTelemetrySignalHandlers();
-        const ctx = createContext();
-        const app = createApp(ctx);
-        ctx.scheduler.start();
-        const server = serve({ fetch: app.fetch, port: ctx.config.port }, () => {
+        let lifecycle;
+        try {
+            const ctx = createContext();
+            lifecycle = new RuntimeLifecycle(ctx, shutdownTelemetryAndLogging);
+            const app = createApp(ctx);
+            const runtime = lifecycle;
+            const server = serve({
+                fetch: (request, env) => runtime.stopping
+                    ? new Response('Server is shutting down.', { status: 503 })
+                    : runtime.request(() => app.fetch(request, env)),
+                port: ctx.config.port,
+            });
+            lifecycle.attachServer(server);
+            await waitForServerListening(server);
+            if (lifecycle.stopping)
+                return;
             ctx.logger.info('server.started', 'Fluxmail HTTP server started', {
                 details: { port: ctx.config.port },
                 skipConsole: true,
@@ -750,33 +821,42 @@ export function createCliProgram(options = {}) {
             console.log(`  Plan:           ${planLine(getEntitlements(ctx.db))}`);
             warnLicense(ctx.db, console.log);
             ctx.licenseController.start();
-        });
-        await waitForServerListening(server);
+            ctx.scheduler.start();
+        }
+        catch (error) {
+            finishCliOperation(program, 'error', apiErrorCode(error), error);
+            await lifecycle?.close();
+            throw error;
+        }
     });
     program
         .command('stdio')
         .description('Run as a stdio MCP server (for Claude Desktop / Claude Code local config)')
         .option('--account <account>', 'Limit access to one mailbox; repeat as needed', collectOption, [])
         .option('--profile <profile>', `Tool profile: ${NAMED_PERMISSION_PROFILES.join(', ')}`)
-        .option('--allow <capability>', 'Allow one MCP capability; repeat as needed', collectOption, [])
+        .option('--allow <capability>', 'Allow one MCP capability, or add it to --profile; repeat as needed', collectOption, [])
         .action(async (opts) => {
         const startupPhase = (phase) => recordCliOperationProperties(program, { startup_phase: phase });
         let ctx;
         let server;
         try {
+            recordCliOperationProperties(program, {
+                startup_data_dir_source: process.env.FLUXMAIL_DATA_DIR ? 'environment' : 'default',
+                startup_instance_selection: selectedInstance() === undefined ? 'automatic' : 'explicit',
+            });
             startupPhase('permissions');
             const permissions = permissionPolicyFromOptions(opts);
             startupPhase('instance');
             const selected = resolveStdioInstance(selectedInstance());
             startupPhase('authentication');
             if (!selected.token)
-                throw new EmailError('permission_denied', `Log in to the local instance before starting stdio MCP. Run "fluxmail --instance ${selected.name} login".`);
+                throw new CliStartupError('permission_denied', `Log in to the local instance before starting stdio MCP. Run "fluxmail --instance ${selected.name} login".`, 'session_missing');
             startupPhase('context');
             ctx = createContext();
             startupPhase('authentication');
             const principal = authenticateBearer(ctx.db, selected.token);
             if (!principal || principal.kind !== 'session')
-                throw new EmailError('permission_denied', `The local CLI session has expired. Run "fluxmail --instance ${selected.name} login".`);
+                throw new CliStartupError('permission_denied', `The local CLI session has expired. Run "fluxmail --instance ${selected.name} login".`, 'session_invalid');
             startupPhase('account_scope');
             const accountIds = accountIdsFromRefs(ctx, opts.account);
             const scopedService = ctx.service.withPrincipal({ ...principal, accountIds });
@@ -791,7 +871,6 @@ export function createCliProgram(options = {}) {
             installTelemetrySignalHandlers();
             installStdioShutdownHandler(process.stdin);
             await server.connect(new StdioServerTransport());
-            ctx.scheduler.start();
             ctx.telemetry.capture('mcp server started', {
                 ...instanceUsageProperties(ctx.db),
                 product_surface: 'mcp',
@@ -805,10 +884,16 @@ export function createCliProgram(options = {}) {
             // stdout belongs to the MCP protocol; log to stderr only.
             ctx.licenseController.start();
             console.error('Fluxmail MCP server running on stdio');
+            if (!opts.profile && !opts.allow.length) {
+                console.error('No permission profile selected, so this connection is read-only. ' +
+                    'Add --profile or --allow to enable drafts, organizing, or sending: https://fluxmail.ai/docs/permissions');
+            }
             warnLicense(ctx.db);
-            const pending = scopedService.listScheduled().filter((send) => send.status === 'pending').length;
+            const pending = permissions.capabilities.includes('mail.read')
+                ? scopedService.listScheduled().filter((send) => send.status === 'pending').length
+                : 0;
             if (pending > 0)
-                console.error(`Scheduled sends pending: ${pending}`);
+                console.error(`Scheduled sends pending: ${pending}. Delivery requires "fluxmail serve" or "fluxmail scheduled run" using the same data directory.`);
             startupPhase('ready');
         }
         catch (error) {
@@ -905,12 +990,12 @@ export function createCliProgram(options = {}) {
         .option('--display-name <name>', 'Sender name for IMAP messages')
         .option('--imap-host <host>', 'IMAP server hostname')
         .option('--imap-port <port>', 'IMAP server port', '993')
-        .option('--imap-security <mode>', 'IMAP security: tls or starttls', 'tls')
+        .option('--imap-security <mode>', 'IMAP security: tls or starttls; defaults to tls on port 993, otherwise starttls')
         .option('--imap-user <user>', 'IMAP username; defaults to the mailbox address')
         .option('--imap-password-env <name>', 'Read the IMAP password from this environment variable')
         .option('--smtp-host <host>', 'SMTP server hostname')
         .option('--smtp-port <port>', 'SMTP server port', '587')
-        .option('--smtp-security <mode>', 'SMTP security: tls or starttls', 'starttls')
+        .option('--smtp-security <mode>', 'SMTP security: tls or starttls; defaults to tls on port 465, otherwise starttls')
         .option('--smtp-user <user>', 'SMTP username; defaults to the IMAP username')
         .option('--smtp-password-env <name>', 'Read a separate SMTP password from this environment variable')
         .option('--sent-folder <path>', 'Sent mailbox path')
@@ -936,7 +1021,12 @@ export function createCliProgram(options = {}) {
             : selected.profile.kind === 'remote' && provider === 'imap'
                 ? undefined
                 : false;
-        recordCliOperationProperties(program, connectionProperties({ provider, reauthorize }));
+        recordCliOperationProperties(program, connectionProperties({
+            provider,
+            reauthorize,
+            stage: 'cli_validation',
+            ...(provider === 'imap' ? { flow: 'imap_credentials' } : {}),
+        }));
         if (!selected.token) {
             failCliOperation(program, new EmailError('permission_denied', `Log in to instance "${selected.name}" before connecting a mailbox.`));
             return;
@@ -1002,21 +1092,23 @@ export function createCliProgram(options = {}) {
                         ? await accountSecret(opts.smtpPasswordEnv, 'SMTP password')
                         : imapPassword;
                     const imapUser = opts.imapUser ?? email;
+                    const imapPort = connectionPort(opts.imapPort, '--imap-port');
+                    const smtpPort = connectionPort(opts.smtpPort, '--smtp-port');
                     request = {
                         ...request,
                         email,
                         ...(opts.displayName ? { displayName: opts.displayName } : {}),
                         imap: {
                             host: opts.imapHost,
-                            port: connectionPort(opts.imapPort, '--imap-port'),
-                            security: connectionSecurity(opts.imapSecurity, '--imap-security'),
+                            port: imapPort,
+                            security: connectionSecurity(opts.imapSecurity, imapPort, '--imap-security'),
                             user: imapUser,
                             password: imapPassword,
                         },
                         smtp: {
                             host: opts.smtpHost,
-                            port: connectionPort(opts.smtpPort, '--smtp-port'),
-                            security: connectionSecurity(opts.smtpSecurity, '--smtp-security'),
+                            port: smtpPort,
+                            security: connectionSecurity(opts.smtpSecurity, smtpPort, '--smtp-security'),
                             user: opts.smtpUser ?? imapUser,
                             password: smtpPassword,
                         },
@@ -1030,10 +1122,45 @@ export function createCliProgram(options = {}) {
                         },
                     };
                 }
-                const result = await instanceClient(selected.name).json('/api/v1/accounts/connections', {
-                    method: 'POST',
-                    headers: { 'content-type': 'application/json' },
-                    body: JSON.stringify(request),
+                // The server's IMAP connection check has its own 30-second limit. Give
+                // its response a small margin so the CLI reports the server's result.
+                const requestTimeoutMs = provider === 'imap' && program.getOptionValueSource('timeout') === 'default'
+                    ? IMAP_CONNECTION_TEST_TIMEOUT_MS + 5_000
+                    : undefined;
+                const requestTimeoutClass = program.getOptionValueSource('timeout') !== 'default'
+                    ? 'custom'
+                    : requestTimeoutMs
+                        ? 'imap_margin'
+                        : 'default';
+                const requestId = randomUUID();
+                recordCliOperationProperties(program, {
+                    connection_stage: 'connection_request',
+                    request_timeout_class: requestTimeoutClass,
+                });
+                const requestStartedAt = performance.now();
+                let result;
+                try {
+                    result = await instanceClient(selected.name, true, requestTimeoutMs).json('/api/v1/accounts/connections', {
+                        method: 'POST',
+                        headers: { 'content-type': 'application/json', 'x-request-id': requestId },
+                        body: JSON.stringify(request),
+                    });
+                }
+                catch (error) {
+                    const status = apiHttpStatus(error);
+                    recordCliOperationProperties(program, {
+                        connection_request_duration_ms: performance.now() - requestStartedAt,
+                        ...(status === undefined ? { http_status: 0 } : { http_status: status }),
+                    });
+                    throw error;
+                }
+                recordCliOperationProperties(program, {
+                    connection_request_duration_ms: performance.now() - requestStartedAt,
+                    ...(result.connectionUrl
+                        ? { connection_stage: 'oauth_prepare' }
+                        : result.account
+                            ? { connection_stage: 'complete' }
+                            : {}),
                 });
                 if (result.connectionUrl)
                     console.log(`Open this URL in your browser:\n\n  ${result.connectionUrl}\n`);
@@ -1091,6 +1218,7 @@ export function createCliProgram(options = {}) {
             if (provider === 'outlook') {
                 const connectionMode = selectGmailConnectionMode(ctx.config, opts);
                 if (connectionMode === 'hosted') {
+                    recordCliOperationProperties(program, { connection_stage: 'oauth_prepare' });
                     const { connectionUrl } = prepareHostedOutlookConnection(ctx.db, ctx.config, {
                         ownerMemberId: owner.id,
                         ...(existing ? { reauthorizeAccountId: existing.id } : {}),
@@ -1102,6 +1230,7 @@ export function createCliProgram(options = {}) {
                     console.log('This link expires in 10 minutes and can only be used once.');
                     return;
                 }
+                recordCliOperationProperties(program, { connection_stage: 'oauth_prepare' });
                 const account = await runMicrosoftLoopbackFlow(ctx.config, (url, context) => printLoopbackInstructions('outlook', url, context, ctx.config.oauthPort), (result) => {
                     const duplicate = ctx.registry
                         .listAccounts()
@@ -1113,10 +1242,12 @@ export function createCliProgram(options = {}) {
                         throw new EmailError('invalid_request', `Microsoft authorized ${result.email}, but account ${existing.id} belongs to ${existing.email}. ` +
                             'Try again and choose the matching Microsoft account.');
                     }
+                    recordCliOperationProperties(program, { connection_stage: 'account_persist' });
                     return ctx.registry.addOutlookAccount(result.email, result.credentials, result.displayName, owner.id, existing?.id, access);
                 }, loopbackFlowOptions(program, 'outlook'));
                 auditConnection('account.connection.complete', account.id);
                 recordCliOperationProperties(program, {
+                    connection_stage: 'complete',
                     reauthorize: accountIdsBeforeConnection.has(account.id),
                     ...accountInventoryProperties(ctx.registry),
                 });
@@ -1126,6 +1257,7 @@ export function createCliProgram(options = {}) {
             }
             const gmailConnectionMode = selectGmailConnectionMode(ctx.config, opts);
             if (gmailConnectionMode === 'hosted') {
+                recordCliOperationProperties(program, { connection_stage: 'oauth_prepare' });
                 const { connectionUrl } = prepareHostedGmailConnection(ctx.db, ctx.config, {
                     ownerMemberId: owner.id,
                     ...(existing ? { reauthorizeAccountId: existing.id } : {}),
@@ -1137,6 +1269,7 @@ export function createCliProgram(options = {}) {
                 console.log('This link expires in 10 minutes and can only be used once.');
                 return;
             }
+            recordCliOperationProperties(program, { connection_stage: 'oauth_prepare' });
             const account = await runLoopbackFlow(ctx.config, (url, context) => printLoopbackInstructions('gmail', url, context, ctx.config.oauthPort), (result) => {
                 const duplicate = ctx.registry
                     .listAccounts()
@@ -1148,10 +1281,12 @@ 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.');
                 }
+                recordCliOperationProperties(program, { connection_stage: 'account_persist' });
                 return ctx.registry.addGmailAccount(result.email, result.tokens, result.displayName, owner.id, access, result.oauthClient);
             }, loopbackFlowOptions(program, 'gmail'));
             auditConnection('account.connection.complete', account.id);
             recordCliOperationProperties(program, {
+                connection_stage: 'complete',
                 reauthorize: accountIdsBeforeConnection.has(account.id),
                 ...accountInventoryProperties(ctx.registry),
             });
@@ -1448,7 +1583,7 @@ export function createCliProgram(options = {}) {
         .option('--member <member>', 'Admin only: issue the key to another member')
         .option('--account <account>', 'Limit the key to one mailbox; repeat as needed', collectOption, [])
         .option('--profile <profile>', `Tool profile: ${NAMED_PERMISSION_PROFILES.join(', ')}`)
-        .option('--allow <capability>', 'Allow one capability in a custom policy; repeat as needed', collectOption, [])
+        .option('--allow <capability>', 'Allow one capability in a custom policy, or add it to --profile; repeat as needed', collectOption, [])
         .option('--admin <capability>', 'Add one admin capability to a named profile; repeat as needed', collectOption, [])
         .description('Create an API key (shown once)')
         .action(async (opts) => {
@@ -1543,7 +1678,7 @@ export function createCliProgram(options = {}) {
         .command('permissions')
         .argument('<keyId>')
         .option('--profile <profile>', `Tool profile: ${NAMED_PERMISSION_PROFILES.join(', ')}`)
-        .option('--allow <capability>', 'Allow one capability in a custom policy; repeat as needed', collectOption, [])
+        .option('--allow <capability>', 'Allow one capability in a custom policy, or add it to --profile; repeat as needed', collectOption, [])
         .option('--admin <capability>', 'Add one admin capability to a named profile; repeat as needed', collectOption, [])
         .description('Change the permissions for an API key')
         .action(async (keyId, opts) => {
@@ -1872,6 +2007,37 @@ export function createCliProgram(options = {}) {
             process.exitCode = cliExitCode(code);
         },
     });
+    program.commands
+        .find((command) => command.name() === 'scheduled')
+        .command('run')
+        .description('Run scheduled delivery for this local instance without HTTP or MCP')
+        .action(async () => {
+        let lifecycle;
+        try {
+            if (selectedAccount() !== undefined) {
+                throw new EmailError('invalid_request', 'scheduled run processes the whole instance; omit --mail-account.');
+            }
+            const name = selectedInstance();
+            if (name !== undefined) {
+                const profile = loadInstanceConfig().instances[name];
+                if (!profile)
+                    throw new EmailError('not_found', `No CLI instance named "${name}".`);
+                if (profile.kind !== 'local') {
+                    throw new EmailError('invalid_request', 'scheduled run requires a local instance. Run it on the host that stores the schedules.');
+                }
+            }
+            const ctx = createContext();
+            lifecycle = new RuntimeLifecycle(ctx, shutdownTelemetryAndLogging);
+            ctx.licenseController.start();
+            ctx.scheduler.start();
+            console.log('Fluxmail scheduled delivery running. Press Ctrl-C to stop.');
+        }
+        catch (error) {
+            finishCliOperation(program, 'error', apiErrorCode(error), error);
+            await lifecycle?.close();
+            throw error;
+        }
+    });
     program
         .command('status')
         .description('Show mailbox and provider status for the selected instance')