fluxmail 0.7.0 → 0.8.1

package/dist/cli.js

@@ -16,7 +16,7 @@ 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 { prepareHostedGmailConnection, prepareHostedOutlookConnection, selectGmailConnectionMode, validateAccountConnectionFlags, } from './accounts/gmailConnection.js';
+import { assertHostedConnectionReady, prepareHostedGmailConnection, prepareHostedOutlookConnection, selectGmailConnectionMode, validateAccountConnectionFlags, } from './accounts/gmailConnection.js';
 import { listApiKeys } from './storage/apiKeys.js';
 import { findMember } from './storage/members.js';
 import { LICENSE_KEY_PATTERN } from './licensing/client.js';
@@ -25,12 +25,13 @@ 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, telemetryDisabledInAnyEnvironment, } from './telemetry.js';
-import { clearSessionToken, instanceClient, loadInstanceConfig, removeInstance, resolveInstance, saveLocalInstance, saveRemoteInstance, saveSessionToken, useInstance, } from './cliInstances.js';
-import { authenticateBearer, normalizeAndValidatePassword, recoverAdminPassword, setupInitialAdmin } from './auth.js';
+import { apiErrorCode, clearSessionToken, instanceClient, loadInstanceConfig, removeInstance, resolveInstance, saveLocalInstance, saveRemoteInstance, saveSessionToken, useInstance, } from './cliInstances.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 } from './accounts/telemetry.js';
 import { flushLogging, escapeLogTextForConsole, getLogger, logCodedFailure, logFailure, readLocalLogs, shutdownLogging, } from './logging.js';
 function collectOption(value, previous) {
     return [...previous, value];
@@ -177,6 +178,8 @@ function readSecretFile(file) {
 async function secretInput(file, label) {
     return file === undefined ? hiddenPrompt(label) : readSecretFile(file);
 }
+/** Offered when a configured public URL, not an explicit --hosted, chose the hosted flow. */
+const LOOPBACK_FLOW_REMEDY = 'Pass --local to use the loopback flow on this computer instead.';
 function planLine(ent) {
     const members = `${ent.maxMembers} member${ent.maxMembers === 1 ? '' : 's'}`;
     return `${ent.plan} (up to ${ent.maxAccounts} mailboxes, ${members})`;
@@ -189,12 +192,45 @@ function warnLicense(db, log = console.error) {
 }
 const activeCliOperations = new WeakMap();
 const activeUpdateNotifiers = new WeakMap();
+/** Attach safe, aggregate properties to the telemetry event for the running command. */
+function recordCliOperationProperties(program, properties) {
+    const active = activeCliOperations.get(program);
+    if (active)
+        active.properties = { ...active.properties, ...properties };
+}
+/** Read local mailbox state without letting telemetry affect the command. */
+async function inspectLocalRegistry(inspect) {
+    let context;
+    try {
+        context = createContext();
+        return inspect(context.registry);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (context) {
+            try {
+                await context.registry.close();
+            }
+            catch {
+                // Telemetry cleanup must not affect the command.
+            }
+            try {
+                context.db.$client.close();
+            }
+            catch {
+                // Telemetry cleanup must not affect the command.
+            }
+        }
+    }
+}
 function finishCliOperation(program, outcome, errorCode, error) {
     const active = activeCliOperations.get(program);
     if (!active)
         return;
     activeCliOperations.delete(program);
-    if (outcome === 'error' && !active.errorLogged) {
+    if (outcome === 'error') {
         const context = { productSurface: 'cli', operation: active.operation, skipConsole: true };
         if (error !== undefined)
             logFailure(active.logger, 'cli.operation_failed', error, context);
@@ -207,18 +243,14 @@ function finishCliOperation(program, outcome, errorCode, error) {
         outcome,
         durationMs: performance.now() - active.startedAt,
         errorCode,
+        ...(active.properties ? { properties: active.properties } : {}),
     });
 }
-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,
-    });
+/** End a failed command with the error's own telemetry code instead of a generic one. */
+function failCliOperation(program, error, prefix = 'Error: ') {
+    finishCliOperation(program, 'error', apiErrorCode(error), error);
+    console.error(`${prefix}${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
 }
 export function waitForServerListening(server) {
     return new Promise((resolve, reject) => {
@@ -390,9 +422,13 @@ export function createCliProgram(options = {}) {
         .option('--existing-admin <member>', 'Existing administrator id or email for a migrated instance')
         .action(async (opts) => {
         try {
+            const earlyContext = createContext();
+            if (isBootstrapComplete(earlyContext.db)) {
+                throw new EmailError('invalid_request', 'This instance has already been set up. Run "fluxmail --instance local login" to log in to the existing instance.');
+            }
             const name = opts.name ?? (opts.existingAdmin ? undefined : await textPrompt('Administrator name'));
             const email = opts.email ?? (await textPrompt('Administrator email'));
-            const context = createContext();
+            const context = earlyContext;
             const passwordMember = opts.existingAdmin
                 ? { ...findMember(context.db, opts.existingAdmin), email }
                 : { name: name ?? '', email };
@@ -415,9 +451,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;
+            failCliOperation(program, err);
         }
     });
     program
@@ -433,7 +467,10 @@ export function createCliProgram(options = {}) {
                 throw new EmailError('invalid_request', '--enroll and --reset cannot be used together.');
             }
             const requestedInstance = selectedInstance();
-            if (!opts.server && requestedInstance === 'local' && !loadInstanceConfig().instances.local) {
+            const instanceConfig = loadInstanceConfig();
+            if (!opts.server &&
+                !instanceConfig.instances.local &&
+                (requestedInstance === 'local' || (!requestedInstance && Object.keys(instanceConfig.instances).length === 0))) {
                 saveLocalInstance('local');
             }
             const instanceName = requestedInstance ?? (opts.server ? 'remote' : resolveInstance().name);
@@ -465,9 +502,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;
+            failCliOperation(program, err);
         }
     });
     program
@@ -484,9 +519,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;
+            failCliOperation(program, err);
         }
     });
     const instances = program.command('instances').description('Manage local and remote CLI instances');
@@ -495,8 +528,18 @@ export function createCliProgram(options = {}) {
         .description('List configured instances')
         .action(() => {
         const config = loadInstanceConfig();
-        for (const [name, profile] of Object.entries(config.instances)) {
-            console.log(`${name}${config.active === name ? ' *' : ''}  ${profile.kind}${profile.kind === 'remote' ? `  ${profile.serverUrl}` : ''}`);
+        const rows = Object.entries(config.instances).map(([name, profile]) => ({
+            name,
+            active: config.active === name ? '*' : '',
+            kind: profile.kind,
+            url: profile.kind === 'remote' ? profile.serverUrl : '',
+        }));
+        const width = (values) => Math.max(...values.map((value) => value.length));
+        const nameWidth = width(['NAME', ...rows.map((row) => row.name)]);
+        const kindWidth = width(['KIND', ...rows.map((row) => row.kind)]);
+        console.log(`${'NAME'.padEnd(nameWidth)}  ACTIVE  ${'KIND'.padEnd(kindWidth)}  URL`.trimEnd());
+        for (const row of rows) {
+            console.log(`${row.name.padEnd(nameWidth)}  ${(row.active ? '*' : ' ').padEnd('ACTIVE'.length)}  ${row.kind.padEnd(kindWidth)}  ${row.url}`.trimEnd());
         }
     });
     instances
@@ -509,9 +552,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;
+            failCliOperation(program, err);
         }
     });
     instances
@@ -524,9 +565,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;
+            failCliOperation(program, err);
         }
     });
     const authCommand = program.command('auth').description('Manage interactive authentication');
@@ -554,9 +593,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;
+            failCliOperation(program, err);
         }
     });
     authCommand
@@ -570,9 +607,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
-            logActiveCliError(program, err);
-            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err);
         }
     });
     authCommand
@@ -587,9 +622,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;
+            failCliOperation(program, err);
         }
     });
     program
@@ -708,33 +741,54 @@ export function createCliProgram(options = {}) {
             return;
         }
         const selected = resolveInstance(selectedInstance());
+        // A remote instance reconnects an IMAP mailbox that matches the address,
+        // so without --reauthorize only the server knows which one this is.
+        const reauthorize = opts.reauthorize !== undefined
+            ? true
+            : selected.profile.kind === 'remote' && provider === 'imap'
+                ? undefined
+                : false;
+        recordCliOperationProperties(program, connectionProperties({ provider, reauthorize }));
         if (!selected.token) {
-            console.error(`Error: Log in to instance "${selected.name}" before connecting a mailbox.`);
-            process.exitCode = 1;
+            failCliOperation(program, new EmailError('permission_denied', `Log in to instance "${selected.name}" before connecting a mailbox.`));
             return;
         }
         try {
             validateAccountConnectionFlags(provider, opts);
         }
         catch (err) {
-            logActiveCliError(program, err);
-            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err);
             return;
         }
         let useControlPlane = selected.profile.kind === 'remote' || provider === 'imap';
+        if (selected.profile.kind === 'remote' && provider !== 'imap') {
+            // A remote instance always completes OAuth through its own public URL.
+            recordCliOperationProperties(program, connectionProperties({ provider, reauthorize, flow: 'hosted' }));
+        }
         if (selected.profile.kind === 'local' && provider !== 'imap') {
             try {
-                useControlPlane = selectGmailConnectionMode(createContext().config, opts) === 'hosted';
+                const { config } = createContext();
+                const mode = selectGmailConnectionMode(config, opts);
+                recordCliOperationProperties(program, connectionProperties({
+                    provider,
+                    reauthorize,
+                    flow: mode === 'hosted' ? 'hosted' : 'loopback',
+                    oauthApp: configuredOAuthAppKind(config, provider),
+                }));
+                // A configured public URL selects the hosted flow on its own, so report a
+                // missing OAuth app here instead of after a connection grant is minted.
+                if (mode === 'hosted') {
+                    assertHostedConnectionReady(config, provider, opts.hosted ? undefined : LOOPBACK_FLOW_REMEDY);
+                }
+                useControlPlane = mode === 'hosted';
             }
             catch (err) {
-                logActiveCliError(program, err);
-                console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-                process.exitCode = 1;
+                failCliOperation(program, err);
                 return;
             }
         }
         if (useControlPlane) {
+            let localImapReauthorize = reauthorize ?? false;
             try {
                 if (selected.profile.kind === 'remote' && opts.local) {
                     throw new EmailError('invalid_request', '--local is only available for the local instance.');
@@ -751,6 +805,10 @@ export function createCliProgram(options = {}) {
                         throw new EmailError('invalid_request', '--imap-host is required for IMAP accounts.');
                     if (!opts.smtpHost)
                         throw new EmailError('invalid_request', '--smtp-host is required for IMAP accounts.');
+                    if (selected.profile.kind === 'local' && !localImapReauthorize) {
+                        localImapReauthorize =
+                            (await inspectLocalRegistry((registry) => registry.listAccounts().some((account) => account.email.toLowerCase() === email.toLowerCase()))) ?? false;
+                    }
                     const imapPassword = await accountSecret(opts.imapPasswordEnv, 'IMAP password');
                     const smtpPassword = opts.smtpPasswordEnv
                         ? await accountSecret(opts.smtpPasswordEnv, 'SMTP password')
@@ -792,15 +850,20 @@ export function createCliProgram(options = {}) {
                 if (result.connectionUrl)
                     console.log(`Open this URL in your browser:\n\n  ${result.connectionUrl}\n`);
                 if (result.account) {
+                    if (selected.profile.kind === 'local' && provider === 'imap') {
+                        const inventory = await inspectLocalRegistry((registry) => accountInventoryProperties(registry));
+                        recordCliOperationProperties(program, {
+                            reauthorize: localImapReauthorize,
+                            ...inventory,
+                        });
+                    }
                     console.log(`Connected ${result.account.email} (account id: ${result.account.id})`);
                     for (const warning of result.warnings ?? [])
                         console.log(`Warning: ${warning.message}.`);
                 }
             }
             catch (err) {
-                logActiveCliError(program, err);
-                console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-                process.exitCode = 1;
+                failCliOperation(program, err);
             }
             return;
         }
@@ -822,6 +885,7 @@ export function createCliProgram(options = {}) {
             if (!existing)
                 ctx.registry.assertCanAddAccount();
             const access = { sharedWithAll: false, grantedMemberIds: [] };
+            const accountIdsBeforeConnection = new Set(ctx.registry.listAccounts().map((account) => account.id));
             const auditConnection = (operation, accountId) => {
                 try {
                     recordAdminAuditEvent(ctx.db, {
@@ -868,6 +932,10 @@ export function createCliProgram(options = {}) {
                     return ctx.registry.addOutlookAccount(result.email, result.credentials, result.displayName, owner.id, existing?.id, access);
                 });
                 auditConnection('account.connection.complete', account.id);
+                recordCliOperationProperties(program, {
+                    reauthorize: accountIdsBeforeConnection.has(account.id),
+                    ...accountInventoryProperties(ctx.registry),
+                });
                 console.log(`\nConnected ${account.email} (account id: ${account.id})` +
                     (account.ownerMemberId === owner.id ? ` for member ${owner.name}` : ''));
                 return;
@@ -903,6 +971,10 @@ export function createCliProgram(options = {}) {
                 return ctx.registry.addGmailAccount(result.email, result.tokens, result.displayName, owner.id, access, result.oauthClient);
             });
             auditConnection('account.connection.complete', account.id);
+            recordCliOperationProperties(program, {
+                reauthorize: accountIdsBeforeConnection.has(account.id),
+                ...accountInventoryProperties(ctx.registry),
+            });
             console.log(`\nConnected ${account.email} (account id: ${account.id})` +
                 (account.ownerMemberId === owner.id ? ` for member ${owner.name}` : ''));
             if (account.ownerMemberId !== owner.id) {
@@ -912,9 +984,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
-            finishCliOperation(program, 'error', isEmailError(err) ? err.code : 'internal', err);
-            console.error(`\nError: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err, '\nError: ');
         }
     });
     accounts
@@ -953,9 +1023,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;
+            failCliOperation(program, err);
         }
     });
     accounts
@@ -978,9 +1046,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
-            logActiveCliError(program, err);
-            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err);
         }
     });
     accounts
@@ -989,15 +1055,24 @@ export function createCliProgram(options = {}) {
         .description('Disconnect an account and delete its stored tokens')
         .action(async (accountId) => {
         try {
-            await instanceClient(selectedInstance()).json(`/api/v1/accounts/${encodeURIComponent(accountId)}/connection`, {
+            const selected = resolveInstance(selectedInstance());
+            const provider = selected.profile.kind === 'local'
+                ? await inspectLocalRegistry((registry) => registry.getAccount(accountId).provider)
+                : undefined;
+            await instanceClient(selected.name).json(`/api/v1/accounts/${encodeURIComponent(accountId)}/connection`, {
                 method: 'DELETE',
             });
+            if (selected.profile.kind === 'local') {
+                const inventory = await inspectLocalRegistry((registry) => accountInventoryProperties(registry));
+                recordCliOperationProperties(program, {
+                    ...(provider ? { provider } : {}),
+                    ...inventory,
+                });
+            }
             console.log(`Removed ${accountId}`);
         }
         catch (err) {
-            logActiveCliError(program, err);
-            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err);
         }
     });
     accounts
@@ -1015,9 +1090,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;
+            failCliOperation(program, err);
         }
     });
     accounts
@@ -1041,9 +1114,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;
+            failCliOperation(program, err);
         }
     });
     const membersCmd = program.command('members').description('Manage members (people using this instance)');
@@ -1068,9 +1139,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;
+            failCliOperation(program, err);
         }
     });
     membersCmd
@@ -1088,9 +1157,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
-            logActiveCliError(program, err);
-            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err);
         }
     });
     membersCmd
@@ -1105,9 +1172,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;
+            failCliOperation(program, err);
         }
     });
     membersCmd
@@ -1128,9 +1193,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;
+            failCliOperation(program, err);
         }
     });
     membersCmd
@@ -1151,9 +1214,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;
+            failCliOperation(program, err);
         }
     });
     for (const [commandName, endpoint, label] of [
@@ -1171,9 +1232,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;
+                failCliOperation(program, err);
             }
         });
     }
@@ -1189,9 +1248,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
-            logActiveCliError(program, err);
-            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err);
         }
     });
     membersCmd
@@ -1205,9 +1262,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;
+            failCliOperation(program, err);
         }
     });
     const apikey = program.command('apikey').description('Manage API keys for the HTTP MCP and REST APIs');
@@ -1262,9 +1317,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;
+            failCliOperation(program, err);
         }
     });
     apikey
@@ -1289,9 +1342,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
-            logActiveCliError(program, err);
-            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err);
         }
     });
     apikey
@@ -1316,9 +1367,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;
+            failCliOperation(program, err);
         }
     });
     apikey
@@ -1351,9 +1400,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;
+            failCliOperation(program, err);
         }
     });
     apikey
@@ -1371,9 +1418,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;
+            failCliOperation(program, err);
         }
     });
     const license = program.command('license').description('Manage the paid-tier license');
@@ -1413,9 +1458,7 @@ export function createCliProgram(options = {}) {
             }
         }
         catch (err) {
-            logActiveCliError(program, err);
-            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err);
         }
     });
     license
@@ -1436,9 +1479,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;
+            failCliOperation(program, err);
         }
     });
     license
@@ -1453,9 +1494,7 @@ 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;
+            failCliOperation(program, err);
         }
     });
     const configCmd = program.command('config').description('Inspect and initialize deployment configuration');
@@ -1470,9 +1509,7 @@ export function createCliProgram(options = {}) {
             console.log(`Created ${file}`);
         }
         catch (err) {
-            logActiveCliError(program, err);
-            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-            process.exitCode = 1;
+            failCliOperation(program, err);
         }
     });
     configCmd
@@ -1665,9 +1702,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;
+            failCliOperation(program, err);
         }
     });
     return program;
@@ -1678,9 +1713,7 @@ export async function runCli(argv = process.argv) {
         await program.parseAsync([...argv]);
     }
     catch (err) {
-        finishCliOperation(program, 'error', isEmailError(err) ? err.code : 'internal', err);
-        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-        process.exitCode = 1;
+        failCliOperation(program, err);
         await Promise.all([shutdownTelemetry(), shutdownLogging()]);
     }
 }