circleinbox 0.1.0

package/circleinbox-cli.cjs

@@ -0,0 +1,1626 @@
+#!/usr/bin/env node
+// CircleInbox CLI — Email infrastructure for agents and developers
+// https://circleinbox.com
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const CLI_VERSION = '0.1.0';
+const HOME_DIR = os.homedir();
+const CONFIG_DIR = path.join(HOME_DIR, '.circleinbox');
+const DEFAULT_API_URL = 'https://circleinbox.com/api/v1';
+
+// ============================================================================
+// Color helpers
+// ============================================================================
+
+const c = {
+  red: (text) => '\x1b[0;31m' + text + '\x1b[0m',
+  green: (text) => '\x1b[0;32m' + text + '\x1b[0m',
+  yellow: (text) => '\x1b[1;33m' + text + '\x1b[0m',
+  blue: (text) => '\x1b[0;34m' + text + '\x1b[0m',
+  purple: (text) => '\x1b[0;35m' + text + '\x1b[0m',
+  cyan: (text) => '\x1b[0;36m' + text + '\x1b[0m',
+  bold: (text) => '\x1b[1m' + text + '\x1b[0m',
+  dim: (text) => '\x1b[2m' + text + '\x1b[0m',
+};
+
+// ============================================================================
+// Flag parser
+// ============================================================================
+
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      // Check if next arg exists and is not a flag
+      if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+        flags[key] = args[i + 1];
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (arg.startsWith('-') && arg.length === 2) {
+      const key = arg.slice(1);
+      if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        flags[key] = args[i + 1];
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { flags, positional };
+}
+
+// ============================================================================
+// Output helpers
+// ============================================================================
+
+let globalFlags = {};
+
+function output(data) {
+  if (globalFlags.json) {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+
+function log(...args) {
+  if (!globalFlags.quiet) {
+    console.log(...args);
+  }
+}
+
+function info(msg) { log(c.blue('i'), msg); }
+function success(msg) { log(c.green('✓'), msg); }
+function warn(msg) { log(c.yellow('!'), msg); }
+function error(msg) { console.error(c.red('✗'), msg); }
+
+// ============================================================================
+// Table formatter
+// ============================================================================
+
+function table(headers, rows) {
+  if (globalFlags.json) return;
+  if (rows.length === 0) {
+    log(c.dim('  (no results)'));
+    return;
+  }
+
+  // Calculate column widths
+  const widths = headers.map((h, i) => {
+    const maxData = rows.reduce((max, row) => Math.max(max, String(row[i] || '').length), 0);
+    return Math.max(h.length, maxData);
+  });
+
+  // Header
+  const headerLine = headers.map((h, i) => h.padEnd(widths[i])).join('  ');
+  log(c.bold(headerLine));
+  log(c.dim(widths.map(w => '─'.repeat(w)).join('──')));
+
+  // Rows
+  for (const row of rows) {
+    const line = row.map((cell, i) => String(cell || '').padEnd(widths[i])).join('  ');
+    log(line);
+  }
+}
+
+// ============================================================================
+// Config manager
+// ============================================================================
+
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+function loadConfig() {
+  const configPath = path.join(CONFIG_DIR, 'config.json');
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    return { apiUrl: DEFAULT_API_URL, outputFormat: 'pretty' };
+  }
+}
+
+function saveConfig(config) {
+  ensureConfigDir();
+  const configPath = path.join(CONFIG_DIR, 'config.json');
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+// ============================================================================
+// Credential management (AES-256-GCM)
+// ============================================================================
+
+const CREDENTIALS_PATH = path.join(CONFIG_DIR, 'credentials');
+const KEY_PATH = path.join(CONFIG_DIR, '.key');
+const KEY_LENGTH = 32;
+const IV_LENGTH = 12;
+
+function getEncryptionKey() {
+  // Try macOS keychain first
+  if (process.platform === 'darwin') {
+    try {
+      const { execSync } = require('child_process');
+      const key = execSync(
+        'security find-generic-password -a circleinbox -s encryption-key -w 2>/dev/null',
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+      ).trim();
+      if (key && key.length >= 64) {
+        return Buffer.from(key.slice(0, 64), 'hex');
+      }
+    } catch {
+      // Keychain entry doesn't exist, fall through
+    }
+  }
+
+  // Fallback: file-based key
+  try {
+    const keyData = JSON.parse(fs.readFileSync(KEY_PATH, 'utf8'));
+    if (keyData.derivedKey) {
+      return Buffer.from(keyData.derivedKey, 'hex');
+    }
+  } catch {
+    // Key doesn't exist, create one
+  }
+
+  // Generate new key
+  ensureConfigDir();
+  const key = crypto.randomBytes(KEY_LENGTH);
+  fs.writeFileSync(KEY_PATH, JSON.stringify({ derivedKey: key.toString('hex') }), { mode: 0o600 });
+
+  // Try to store in macOS keychain
+  if (process.platform === 'darwin') {
+    try {
+      const { execSync } = require('child_process');
+      execSync(
+        `security add-generic-password -a circleinbox -s encryption-key -w "${key.toString('hex')}" -U 2>/dev/null`,
+        { stdio: 'ignore' }
+      );
+    } catch {
+      // Keychain unavailable, file fallback is fine
+    }
+  }
+
+  return key;
+}
+
+function encryptCredentials(data) {
+  const key = getEncryptionKey();
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+
+  const plaintext = JSON.stringify(data);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  return JSON.stringify({
+    iv: iv.toString('hex'),
+    tag: tag.toString('hex'),
+    data: encrypted.toString('hex'),
+  });
+}
+
+function decryptCredentials() {
+  try {
+    const raw = fs.readFileSync(CREDENTIALS_PATH, 'utf8');
+    const { iv, tag, data } = JSON.parse(raw);
+
+    const key = getEncryptionKey();
+    const decipher = crypto.createDecipheriv(
+      'aes-256-gcm',
+      key,
+      Buffer.from(iv, 'hex')
+    );
+    decipher.setAuthTag(Buffer.from(tag, 'hex'));
+
+    const decrypted = Buffer.concat([
+      decipher.update(Buffer.from(data, 'hex')),
+      decipher.final(),
+    ]);
+
+    return JSON.parse(decrypted.toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveCredentials(apiKey) {
+  ensureConfigDir();
+  const encrypted = encryptCredentials({ apiKey });
+  fs.writeFileSync(CREDENTIALS_PATH, encrypted, { mode: 0o600 });
+}
+
+function loadApiKey() {
+  const creds = decryptCredentials();
+  return creds?.apiKey || process.env.CIRCLEINBOX_API_KEY || null;
+}
+
+// ============================================================================
+// API client
+// ============================================================================
+
+class ApiClient {
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+
+  async request(method, path, body, extraHeaders) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      'Authorization': `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json',
+      ...extraHeaders,
+    };
+
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30000);
+        let response;
+        try {
+          response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+          });
+        } finally {
+          clearTimeout(timeoutId);
+        }
+
+        const text = await response.text();
+        let data;
+        try {
+          data = JSON.parse(text);
+        } catch {
+          if (!response.ok) {
+            const err = new Error(`Request failed: ${response.status} ${response.statusText}`);
+            err.status = response.status;
+            err.code = 'INVALID_RESPONSE';
+            throw err;
+          }
+          // For successful responses with no/invalid JSON (e.g. 204), return empty object
+          data = {};
+        }
+
+        if (!response.ok) {
+          // Retry on 429 or 5xx
+          if ((response.status === 429 || response.status >= 500) && attempt < 2) {
+            const delay = Math.pow(2, attempt) * 1000 * (0.5 + Math.random());
+            await new Promise(r => setTimeout(r, delay));
+            continue;
+          }
+
+          const errMsg = data.error?.message || `Request failed: ${response.status}`;
+          const err = new Error(errMsg);
+          err.code = data.error?.code || 'UNKNOWN';
+          err.status = response.status;
+          throw err;
+        }
+
+        return data;
+      } catch (err) {
+        lastError = err;
+        if (err.status && err.status < 500 && err.status !== 429) throw err;
+        if (attempt < 2) {
+          const delay = Math.pow(2, attempt) * 1000 * (0.5 + Math.random());
+          await new Promise(r => setTimeout(r, delay));
+        }
+      }
+    }
+    throw lastError;
+  }
+
+  get(path) { return this.request('GET', path); }
+  post(path, body, headers) { return this.request('POST', path, body, headers); }
+  put(path, body) { return this.request('PUT', path, body); }
+  patch(path, body) { return this.request('PATCH', path, body); }
+  del(path) { return this.request('DELETE', path); }
+}
+
+function getClient() {
+  const apiKey = loadApiKey();
+  if (!apiKey) {
+    error('Not logged in. Run: circleinbox login');
+    process.exit(1);
+  }
+  const baseUrl = globalFlags.apiUrlOverride || loadConfig().apiUrl || DEFAULT_API_URL;
+  return new ApiClient(baseUrl, apiKey);
+}
+
+// ============================================================================
+// Mailbox resolution helper
+// ============================================================================
+
+async function resolveMailbox(client, mailboxRef) {
+  // If it looks like a UUID, use directly
+  if (mailboxRef.includes('-') && !mailboxRef.includes('@')) {
+    return mailboxRef;
+  }
+
+  // Otherwise, look up by email address
+  const result = await client.get('/inboxes');
+  const matches = (result.data || []).filter(m =>
+    m.email === mailboxRef || m.email.startsWith(mailboxRef + '@')
+  );
+
+  if (matches.length === 0) {
+    throw new Error(`Mailbox not found: ${mailboxRef}`);
+  }
+  if (matches.length > 1) {
+    const emails = matches.map(m => m.email).join(', ');
+    throw new Error(`Ambiguous mailbox "${mailboxRef}" matches multiple: ${emails}. Use full email address.`);
+  }
+
+  return matches[0].id;
+}
+
+// ============================================================================
+// Domain resolution helper
+// ============================================================================
+
+async function resolveDomain(client, domainRef) {
+  const result = await client.get('/domains');
+  const domain = result.data?.find(d =>
+    d.id === domainRef || d.domain === domainRef
+  );
+
+  if (!domain) {
+    throw new Error(`Domain not found: ${domainRef}`);
+  }
+
+  return domain;
+}
+
+// ============================================================================
+// Commands: General
+// ============================================================================
+
+function commandVersion() {
+  console.log(`circleinbox v${CLI_VERSION}`);
+}
+
+function commandHelp() {
+  log(`
+${c.bold('CircleInbox CLI')} v${CLI_VERSION}
+Email infrastructure for agents and developers
+
+${c.bold('USAGE')}
+  circleinbox <command> [options]
+
+${c.bold('GENERAL')}
+  login [--key <api-key>]     Store API key (encrypted)
+  logout                      Remove stored credentials
+  status                      Show connection status and org info
+  version                     Show CLI version
+  help                        Show this help
+
+${c.bold('DOMAINS')}
+  domains list                List all domains with DNS status
+  dns check <domain>          Check DNS records for a domain
+
+${c.bold('INBOXES')}
+  inbox list                  List all mailboxes
+  inbox create <email>        Create a new mailbox
+  inbox check <mailbox> [-l N]  List emails in mailbox
+  inbox read <mailbox> <uid>  Read a specific email
+  inbox delete <mailbox>      Delete a mailbox
+
+${c.bold('SEND')}
+  send --from <email> --to <email> --subject "..." --text "..."
+
+${c.bold('ALIASES')}
+  alias list [--domain <d>]   List aliases
+  alias create <addr> <dest>  Create alias forwarding
+  alias update <id> <dest>    Update alias destinations
+  alias delete <id>           Delete an alias
+
+${c.bold('VAULT (Credentials)')}
+  vault list <mailbox>        List stored credentials
+  vault store <mailbox>       Store a new credential
+  vault get <mbx> <hash>      Get credential with password
+  vault update <mbx> <hash>   Update a credential
+  vault delete <mbx> <hash>   Delete a credential
+
+${c.bold('PASSWORD RESET')}
+  reset <mailbox> <hash>      Orchestrated password reset flow
+  reset <mbx> <hash> --clearauth  ClearAuth direct API reset
+
+${c.bold('PROVISION')}
+  provision <domain>          Full domain-to-mailbox setup
+
+${c.bold('GLOBAL FLAGS')}
+  --json                      Output raw JSON
+  --quiet                     Suppress decorative output
+  --api-url <url>             Override API base URL
+`);
+}
+
+// ============================================================================
+// Commands: Login / Logout / Status
+// ============================================================================
+
+async function commandLogin(args) {
+  const { flags, positional } = parseFlags(args);
+  let apiKey = flags.key || positional[0];
+
+  if (!apiKey) {
+    // Read from stdin if available
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    apiKey = await new Promise((resolve) => {
+      rl.question('API Key (ci_live_...): ', (answer) => {
+        rl.close();
+        resolve(answer.replace(/[\x00-\x1F\x7F]/g, '').trim());
+      });
+    });
+  }
+
+  if (!apiKey) {
+    error('No API key provided');
+    process.exit(1);
+  }
+
+  if (!apiKey.startsWith('ci_live_')) {
+    error('Invalid API key format. Must start with ci_live_');
+    process.exit(1);
+  }
+
+  // Test the key
+  info('Verifying API key...');
+  const config = loadConfig();
+  const client = new ApiClient(config.apiUrl || DEFAULT_API_URL, apiKey);
+
+  try {
+    const result = await client.get('/domains');
+    saveCredentials(apiKey);
+    success(`Logged in. ${result.data?.length || 0} domain(s) accessible.`);
+  } catch (err) {
+    error(`API key verification failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+async function commandLogout() {
+  try {
+    if (fs.existsSync(CREDENTIALS_PATH)) {
+      fs.unlinkSync(CREDENTIALS_PATH);
+    }
+    if (fs.existsSync(KEY_PATH)) {
+      fs.unlinkSync(KEY_PATH);
+    }
+
+    // Remove from macOS keychain
+    if (process.platform === 'darwin') {
+      try {
+        const { execSync } = require('child_process');
+        execSync('security delete-generic-password -a circleinbox -s encryption-key 2>/dev/null', { stdio: 'ignore' });
+      } catch {
+        // Not in keychain, that's fine
+      }
+    }
+
+    success('Logged out. Credentials removed.');
+  } catch (err) {
+    error(`Logout failed: ${err.message}`);
+  }
+}
+
+async function commandStatus() {
+  const apiKey = loadApiKey();
+  const config = loadConfig();
+
+  log(c.bold('CircleInbox Status'));
+  log('');
+  log(`  API URL:    ${config.apiUrl || DEFAULT_API_URL}`);
+  log(`  Logged in:  ${apiKey ? c.green('yes') : c.red('no')}`);
+
+  if (!apiKey) {
+    log('');
+    log(`  Run ${c.cyan('circleinbox login')} to get started.`);
+    return;
+  }
+
+  try {
+    const client = new ApiClient(config.apiUrl || DEFAULT_API_URL, apiKey);
+    const [domains, inboxes] = await Promise.all([
+      client.get('/domains'),
+      client.get('/inboxes'),
+    ]);
+
+    log(`  Domains:    ${domains.data?.length || 0}`);
+    log(`  Mailboxes:  ${inboxes.data?.length || 0}`);
+
+    if (globalFlags.json) {
+      output({
+        apiUrl: config.apiUrl || DEFAULT_API_URL,
+        loggedIn: true,
+        domains: domains.data?.length || 0,
+        mailboxes: inboxes.data?.length || 0,
+      });
+    }
+  } catch (err) {
+    warn(`Could not reach API: ${err.message}`);
+  }
+}
+
+// ============================================================================
+// Commands: Domains & DNS
+// ============================================================================
+
+async function commandDomains(args) {
+  const client = getClient();
+  const result = await client.get('/domains');
+  const domains = result.data || [];
+
+  if (globalFlags.json) { output(result); return; }
+
+  log(c.bold(`\nDomains (${domains.length})\n`));
+
+  const check = (v) => v ? c.green('✓') : c.red('✗');
+  table(
+    ['Domain', 'Status', 'MX', 'SPF', 'DKIM', 'Mailcow'],
+    domains.map(d => [
+      d.domain,
+      d.status,
+      check(d.mxVerified),
+      check(d.spfVerified),
+      check(d.dkimVerified),
+      check(d.mailcowProvisioned),
+    ])
+  );
+  log('');
+}
+
+async function commandDns(args) {
+  const { positional } = parseFlags(args);
+  const sub = positional[0];
+
+  if (sub !== 'check' || !positional[1]) {
+    error('Usage: circleinbox dns check <domain>');
+    process.exit(1);
+  }
+
+  const domainName = positional[1];
+  const client = getClient();
+  const domain = await resolveDomain(client, domainName);
+
+  if (globalFlags.json) { output(domain); return; }
+
+  const check = (v) => v ? c.green('✓ verified') : c.red('✗ missing');
+
+  log(c.bold(`\nDNS Status: ${domain.domain}\n`));
+  log(`  MX Record:     ${check(domain.mxVerified)}`);
+  log(`  SPF Record:    ${check(domain.spfVerified)}`);
+  log(`  DKIM Record:   ${check(domain.dkimVerified)}`);
+  log(`  DMARC Record:  ${check(domain.dmarcVerified)}`);
+  log(`  Mailcow:       ${domain.mailcowProvisioned ? c.green('provisioned') : c.yellow('not provisioned')}`);
+
+  if (!domain.mxVerified || !domain.spfVerified || !domain.dkimVerified) {
+    log(c.bold('\nRequired DNS Records:'));
+    if (!domain.mxVerified) {
+      log(`  MX    ${domain.domain}  →  mail.circleinbox.com  (priority 10)`);
+    }
+    if (!domain.spfVerified) {
+      log(`  TXT   ${domain.domain}  →  "v=spf1 include:mail.circleinbox.com ~all"`);
+    }
+    if (!domain.dkimVerified) {
+      log(`  CNAME dkim._domainkey.${domain.domain}  →  dkim._domainkey.mail.circleinbox.com`);
+    }
+    if (!domain.dmarcVerified) {
+      log(`  TXT   _dmarc.${domain.domain}  →  "v=DMARC1; p=quarantine; rua=mailto:dmarc@${domain.domain}"`);
+    }
+  }
+  log('');
+}
+
+// ============================================================================
+// Commands: Inbox
+// ============================================================================
+
+async function commandInbox(args) {
+  const { flags, positional } = parseFlags(args);
+  const sub = positional[0];
+
+  switch (sub) {
+    case 'list':
+      return inboxList();
+    case 'create':
+      return inboxCreate(positional.slice(1), flags);
+    case 'check':
+      return inboxCheck(positional.slice(1), flags);
+    case 'read':
+      return inboxRead(positional.slice(1), flags);
+    case 'delete':
+      return inboxDelete(positional.slice(1));
+    default:
+      error('Usage: circleinbox inbox <list|create|check|read|delete>');
+      process.exit(1);
+  }
+}
+
+async function inboxList() {
+  const client = getClient();
+  const result = await client.get('/inboxes');
+  const inboxes = result.data || [];
+
+  if (globalFlags.json) { output(result); return; }
+
+  log(c.bold(`\nMailboxes (${inboxes.length})\n`));
+  table(
+    ['Email', 'Display Name', 'Type'],
+    inboxes.map(m => [m.email, m.displayName || '', m.type || 'regular'])
+  );
+  log('');
+}
+
+async function inboxCreate(positional, flags) {
+  if (!positional[0]) {
+    error('Usage: circleinbox inbox create <local>@<domain> [--display "Name"]');
+    process.exit(1);
+  }
+
+  const email = positional[0];
+  const atIndex = email.indexOf('@');
+  if (atIndex === -1) {
+    error('Invalid email format. Use: local@domain.com');
+    process.exit(1);
+  }
+
+  const localPart = email.slice(0, atIndex);
+  const domainName = email.slice(atIndex + 1);
+
+  const client = getClient();
+  const domain = await resolveDomain(client, domainName);
+
+  const body = {
+    domainId: domain.id,
+    localPart,
+    displayName: flags.display || flags.name || localPart,
+  };
+
+  if (flags.password) {
+    body.password = flags.password;
+  }
+
+  const result = await client.post('/inboxes', body);
+
+  if (globalFlags.json) { output(result); return; }
+
+  success(`Mailbox created: ${result.data.email}`);
+  log('');
+
+  if (result.data.password) {
+    log(c.yellow('  ⚠ SAVE THIS PASSWORD — it will not be shown again'));
+    log(`  Password: ${c.bold(result.data.password)}`);
+    log('');
+  }
+
+  if (result.data.smtp) {
+    log(c.bold('  SMTP Connection:'));
+    log(`    Host:     ${result.data.smtp.host}`);
+    log(`    Port:     ${result.data.smtp.port}`);
+    log(`    Security: ${result.data.smtp.security}`);
+    log(`    Username: ${result.data.smtp.username}`);
+  }
+
+  if (result.data.imap) {
+    log(c.bold('  IMAP Connection:'));
+    log(`    Host:     ${result.data.imap.host}`);
+    log(`    Port:     ${result.data.imap.port}`);
+    log(`    Security: ${result.data.imap.security}`);
+    log(`    Username: ${result.data.imap.username}`);
+  }
+  log('');
+}
+
+async function inboxCheck(positional, flags) {
+  if (!positional[0]) {
+    error('Usage: circleinbox inbox check <mailbox> [--limit N]');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const mailboxId = await resolveMailbox(client, positional[0]);
+  const limit = flags.limit || flags.l || 20;
+
+  const result = await client.get(`/inboxes/${mailboxId}/emails?limit=${limit}`);
+
+  if (globalFlags.json) { output(result); return; }
+
+  const emails = result.data?.emails || [];
+  log(c.bold(`\nInbox: ${result.data?.inbox?.email || mailboxId} (${emails.length} emails)\n`));
+
+  table(
+    ['UID', 'From', 'Subject', 'Date', 'Read'],
+    emails.map(e => [
+      e.uid,
+      (e.from || '').slice(0, 30),
+      (e.subject || '').slice(0, 40),
+      e.date ? new Date(e.date).toLocaleDateString() : '',
+      e.isRead ? c.dim('read') : c.bold('NEW'),
+    ])
+  );
+  log('');
+}
+
+async function inboxRead(positional) {
+  if (!positional[0] || !positional[1]) {
+    error('Usage: circleinbox inbox read <mailbox> <uid>');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const mailboxId = await resolveMailbox(client, positional[0]);
+  const uid = positional[1];
+
+  const result = await client.get(`/inboxes/${mailboxId}/emails/${uid}`);
+
+  if (globalFlags.json) { output(result); return; }
+
+  const email = result.data;
+  log('');
+  log(c.bold(`Subject: ${email.subject || '(no subject)'}`));
+  log(`From:    ${email.from}`);
+  log(`To:      ${(email.to || []).join(', ')}`);
+  if (email.cc?.length) log(`CC:      ${email.cc.join(', ')}`);
+  log(`Date:    ${email.date}`);
+  log(c.dim('─'.repeat(60)));
+
+  // Prefer text body, strip basic HTML if only HTML available
+  const body = email.body?.text || (email.body?.html || '').replace(/<[^>]+>/g, '');
+  log(body);
+
+  if (email.attachments?.length) {
+    log('');
+    log(c.bold(`Attachments (${email.attachments.length}):`));
+    for (const att of email.attachments) {
+      log(`  ${att.filename} (${att.contentType}, ${formatBytes(att.size)})`);
+    }
+  }
+  log('');
+}
+
+async function inboxDelete(positional) {
+  if (!positional[0]) {
+    error('Usage: circleinbox inbox delete <mailbox>');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const mailboxId = await resolveMailbox(client, positional[0]);
+
+  // Confirmation
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve) => {
+    rl.question(c.yellow(`Delete mailbox ${positional[0]}? This cannot be undone. (y/N) `), (answer) => {
+      rl.close();
+      resolve(answer.replace(/[\x00-\x1F\x7F]/g, '').trim());
+    });
+  });
+
+  if (answer.toLowerCase() !== 'y') {
+    info('Cancelled.');
+    return;
+  }
+
+  await client.del(`/inboxes/${mailboxId}`);
+  success(`Mailbox deleted: ${positional[0]}`);
+}
+
+// ============================================================================
+// Commands: Send
+// ============================================================================
+
+async function commandSend(args) {
+  const { flags } = parseFlags(args);
+
+  if (!flags.from || !flags.to || !flags.subject) {
+    error('Usage: circleinbox send --from <email> --to <email> --subject "..." --text "..."');
+    process.exit(1);
+  }
+
+  let text = flags.text;
+  let html = flags.html;
+
+  // Support reading from stdin
+  if (text === '-' || html === '-') {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    const stdinContent = Buffer.concat(chunks).toString('utf8');
+    if (text === '-') text = stdinContent;
+    if (html === '-') html = stdinContent;
+  }
+
+  if (!text && !html) {
+    error('Provide --text or --html body (use - to read from stdin)');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const body = {
+    from: { email: flags.from, name: flags['from-name'] },
+    to: flags.to,
+    subject: flags.subject,
+  };
+  if (text) body.text = text;
+  if (html) body.html = html;
+  if (flags.tags) body.tags = flags.tags.split(',');
+
+  const extraHeaders = {};
+  if (flags['idempotency-key']) {
+    extraHeaders['Idempotency-Key'] = flags['idempotency-key'];
+  }
+
+  const result = await client.post('/send', body, extraHeaders);
+
+  if (globalFlags.json) { output(result); return; }
+
+  success(`Email sent. Message ID: ${result.messageId}`);
+  if (result.rateLimit) {
+    log(c.dim(`  Rate limit: ${result.rateLimit.remaining}/${result.rateLimit.limit} remaining`));
+  }
+}
+
+// ============================================================================
+// Commands: Aliases
+// ============================================================================
+
+async function commandAlias(args) {
+  const { flags, positional } = parseFlags(args);
+  const sub = positional[0];
+
+  switch (sub) {
+    case 'list':
+      return aliasList(flags);
+    case 'create':
+      return aliasCreate(positional.slice(1), flags);
+    case 'update':
+      return aliasUpdate(positional.slice(1));
+    case 'delete':
+      return aliasDelete(positional.slice(1));
+    default:
+      error('Usage: circleinbox alias <list|create|update|delete>');
+      process.exit(1);
+  }
+}
+
+async function aliasList(flags) {
+  const client = getClient();
+  let path = '/aliases';
+
+  if (flags.domain) {
+    const domain = await resolveDomain(client, flags.domain);
+    path += `?domainId=${domain.id}`;
+  }
+
+  const result = await client.get(path);
+  const aliases = result.data || [];
+
+  if (globalFlags.json) { output(result); return; }
+
+  log(c.bold(`\nAliases (${aliases.length})\n`));
+  table(
+    ['Address', 'Destinations', 'Created'],
+    aliases.map(a => [
+      a.address,
+      (a.destinations || []).join(', '),
+      a.createdAt ? new Date(a.createdAt).toLocaleDateString() : '',
+    ])
+  );
+  log('');
+}
+
+async function aliasCreate(positional) {
+  if (!positional[0] || !positional[1]) {
+    error('Usage: circleinbox alias create <alias>@<domain> <dest1> [dest2...]');
+    process.exit(1);
+  }
+
+  const address = positional[0];
+  const destinations = positional.slice(1);
+  const atIndex = address.indexOf('@');
+  if (atIndex === -1) {
+    error('Invalid alias format. Use: local@domain.com');
+    process.exit(1);
+  }
+
+  const localPart = address.slice(0, atIndex);
+  const domainName = address.slice(atIndex + 1);
+
+  const client = getClient();
+  const domain = await resolveDomain(client, domainName);
+
+  const result = await client.post('/aliases', {
+    domainId: domain.id,
+    localPart,
+    destinations,
+  });
+
+  if (globalFlags.json) { output(result); return; }
+
+  success(`Alias created: ${address} → ${destinations.join(', ')}`);
+}
+
+async function aliasUpdate(positional) {
+  if (!positional[0] || !positional[1]) {
+    error('Usage: circleinbox alias update <aliasId> <dest1> [dest2...]');
+    process.exit(1);
+  }
+
+  const aliasId = positional[0];
+  const destinations = positional.slice(1);
+
+  const client = getClient();
+  const result = await client.patch(`/aliases/${aliasId}`, { destinations });
+
+  if (globalFlags.json) { output(result); return; }
+
+  success(`Alias updated: destinations → ${destinations.join(', ')}`);
+}
+
+async function aliasDelete(positional) {
+  if (!positional[0]) {
+    error('Usage: circleinbox alias delete <aliasId>');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  await client.del(`/aliases/${positional[0]}`);
+  success(`Alias deleted: ${positional[0]}`);
+}
+
+// ============================================================================
+// Commands: Vault (Credentials)
+// ============================================================================
+
+async function commandVault(args) {
+  const { flags, positional } = parseFlags(args);
+  const sub = positional[0];
+
+  switch (sub) {
+    case 'list':
+      return vaultList(positional.slice(1), flags);
+    case 'store':
+      return vaultStore(positional.slice(1), flags);
+    case 'get':
+      return vaultGet(positional.slice(1));
+    case 'update':
+      return vaultUpdate(positional.slice(1), flags);
+    case 'delete':
+      return vaultDelete(positional.slice(1));
+    default:
+      error('Usage: circleinbox vault <list|store|get|update|delete>');
+      process.exit(1);
+  }
+}
+
+async function vaultList(positional) {
+  if (!positional[0]) {
+    error('Usage: circleinbox vault list <mailbox>');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const mailboxId = await resolveMailbox(client, positional[0]);
+  const result = await client.get(`/credentials?mailboxId=${mailboxId}`);
+  const creds = result.data || [];
+
+  if (globalFlags.json) { output(result); return; }
+
+  log(c.bold(`\nCredentials for ${positional[0]} (${creds.length})\n`));
+  table(
+    ['Service', 'URL', 'Username', 'Created'],
+    creds.map(cr => [
+      cr.serviceName || '',
+      cr.serviceUrl || '',
+      cr.email || cr.username || '',
+      cr.createdAt ? new Date(cr.createdAt).toLocaleDateString() : '',
+    ])
+  );
+  log('');
+}
+
+async function vaultStore(positional, flags) {
+  if (!positional[0]) {
+    error('Usage: circleinbox vault store <mailbox> --service <url> --username <user> [--password <pass>] [--notes "..."]');
+    process.exit(1);
+  }
+
+  if (!flags.service || !flags.username) {
+    error('Required: --service <url> --username <user>');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const mailboxId = await resolveMailbox(client, positional[0]);
+
+  const body = {
+    mailboxId,
+    serviceUrl: flags.service,
+    username: flags.username,
+  };
+  if (flags.password) body.password = flags.password;
+  if (flags.name) body.serviceName = flags.name;
+  if (flags.notes) body.notes = flags.notes;
+
+  const result = await client.post('/credentials', body);
+
+  if (globalFlags.json) { output(result); return; }
+
+  success(`Credential stored: ${result.data?.serviceName || flags.service}`);
+  if (result.passwordGenerated) {
+    warn('Password was auto-generated. Save it now:');
+  }
+  log(`  Username: ${result.data?.username || result.data?.email}`);
+  log(`  Password: ${c.bold(result.data?.password || '(hidden)')}`);
+  if (result.data?.notes) log(`  Notes:    ${result.data.notes}`);
+  log('');
+}
+
+async function vaultGet(positional) {
+  if (!positional[0] || !positional[1]) {
+    error('Usage: circleinbox vault get <mailbox> <serviceHash>');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const mailboxId = await resolveMailbox(client, positional[0]);
+  const result = await client.get(`/credentials/${positional[1]}?mailboxId=${mailboxId}`);
+
+  if (globalFlags.json) { output(result); return; }
+
+  const cred = result.data;
+  log('');
+  log(c.bold(cred.serviceName || 'Credential'));
+  log(`  URL:       ${cred.serviceUrl}`);
+  log(`  Username:  ${cred.username || cred.email}`);
+  log(`  Password:  ${c.bold(cred.password)}`);
+  if (cred.notes) log(`  Notes:     ${cred.notes}`);
+  log(`  Created:   ${cred.createdAt}`);
+  log(`  Updated:   ${cred.updatedAt}`);
+  log('');
+}
+
+async function vaultUpdate(positional, flags) {
+  if (!positional[0] || !positional[1]) {
+    error('Usage: circleinbox vault update <mailbox> <serviceHash> [--username <user>] [--password <pass>] [--notes "..."]');
+    process.exit(1);
+  }
+
+  const body = {};
+  if (flags.username) body.username = flags.username;
+  if (flags.password) body.password = flags.password;
+  if (flags.notes !== undefined) body.notes = flags.notes;
+
+  if (Object.keys(body).length === 0) {
+    error('Provide at least one of: --username, --password, --notes');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const mailboxId = await resolveMailbox(client, positional[0]);
+  const result = await client.put(`/credentials/${positional[1]}?mailboxId=${mailboxId}`, body);
+
+  if (globalFlags.json) { output(result); return; }
+
+  success(`Credential updated: ${result.data?.serviceName || positional[1]}`);
+}
+
+async function vaultDelete(positional) {
+  if (!positional[0] || !positional[1]) {
+    error('Usage: circleinbox vault delete <mailbox> <serviceHash>');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const mailboxId = await resolveMailbox(client, positional[0]);
+  await client.del(`/credentials/${positional[1]}?mailboxId=${mailboxId}`);
+  success(`Credential deleted: ${positional[1]}`);
+}
+
+// ============================================================================
+// Commands: Password Reset
+// ============================================================================
+
+async function commandReset(args) {
+  const { flags, positional } = parseFlags(args);
+
+  if (!positional[0] || !positional[1]) {
+    error('Usage: circleinbox reset <mailbox> <serviceHash> [--clearauth] [--password <new>]');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  const mailboxId = await resolveMailbox(client, positional[0]);
+  const serviceHash = positional[1];
+
+  // Step 1: Look up credential
+  info('Looking up credential...');
+  const credResult = await client.get(`/credentials/${serviceHash}?mailboxId=${mailboxId}`);
+  const cred = credResult.data;
+
+  log(`  Service:  ${cred.serviceName || cred.serviceUrl}`);
+  log(`  URL:      ${cred.serviceUrl}`);
+  log(`  Username: ${cred.username || cred.email}`);
+  log('');
+
+  if (flags.clearauth) {
+    // ClearAuth direct API flow
+    return resetClearAuth(client, mailboxId, serviceHash, cred, flags);
+  }
+
+  // Refuse to send credentials over non-HTTPS connections
+  const serviceUrl = cred.serviceUrl.replace(/\/$/, '');
+  if (!serviceUrl.startsWith('https://')) {
+    error('Refusing to send credentials over insecure HTTP. Service URL must use HTTPS.');
+    process.exit(1);
+  }
+
+  // Generic flow: instruct user to trigger reset manually
+  log(c.bold('Step 1: Trigger password reset'));
+  log(`  Go to ${c.cyan(cred.serviceUrl)} and click "Forgot Password"`);
+  log(`  Enter: ${c.bold(cred.username || cred.email)}`);
+  log('');
+  log(c.bold('Step 2: Waiting for reset email...'));
+
+  // Poll inbox
+  const resetEmail = await pollForResetEmail(client, mailboxId, cred.serviceUrl);
+
+  if (!resetEmail) {
+    error('No reset email found after 5 minutes. Check manually.');
+    process.exit(1);
+  }
+
+  // Extract links
+  log('');
+  log(c.bold('Step 3: Reset links found:'));
+  const links = extractResetLinks(resetEmail);
+  links.forEach((link, i) => {
+    log(`  [${i + 1}] ${link}`);
+  });
+
+  if (links.length === 0) {
+    warn('No reset links found in email. Check manually.');
+    log(c.dim('  Email body:'));
+    const body = resetEmail.body?.text || (resetEmail.body?.html || '').replace(/<[^>]+>/g, '').slice(0, 500);
+    log(c.dim('  ' + body));
+  }
+
+  // Update vault
+  log('');
+  log(c.bold('Step 4: Update credential'));
+  let newPassword = flags.password;
+  if (!newPassword) {
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    newPassword = await new Promise((resolve) => {
+      rl.question('New password (or press enter to skip): ', (answer) => {
+        rl.close();
+        resolve(answer.replace(/[\x00-\x1F\x7F]/g, '').trim());
+      });
+    });
+  }
+
+  if (newPassword) {
+    const now = new Date().toISOString().slice(0, 10);
+    await client.put(`/credentials/${serviceHash}?mailboxId=${mailboxId}`, {
+      password: newPassword,
+      notes: `Password reset ${now}. ${cred.notes || ''}`.trim(),
+    });
+    success('Credential updated with new password.');
+  } else {
+    info('Skipped credential update.');
+  }
+}
+
+async function resetClearAuth(client, mailboxId, serviceHash, cred, flags) {
+  const serviceUrl = cred.serviceUrl.replace(/\/$/, '');
+  const username = cred.username || cred.email;
+
+  // Refuse to send credentials over non-HTTPS connections
+  if (!serviceUrl.startsWith('https://')) {
+    error('Refusing to send credentials over insecure HTTP. Service URL must use HTTPS.');
+    process.exit(1);
+  }
+
+  // Step 1: Request reset via ClearAuth API
+  info(`Requesting reset from ${serviceUrl}/auth/request-reset ...`);
+  try {
+    const controller1 = new AbortController();
+    const timeoutId1 = setTimeout(() => controller1.abort(), 30000);
+    try {
+      await fetch(`${serviceUrl}/auth/request-reset`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email: username }),
+        signal: controller1.signal,
+      });
+    } finally {
+      clearTimeout(timeoutId1);
+    }
+    success('Reset requested.');
+  } catch (err) {
+    error(`Failed to request reset: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Step 2: Poll for email
+  log(c.bold('Waiting for reset email...'));
+  const resetEmail = await pollForResetEmail(client, mailboxId, serviceUrl);
+
+  if (!resetEmail) {
+    error('No reset email found after 5 minutes.');
+    process.exit(1);
+  }
+
+  // Step 3: Extract token
+  const body = resetEmail.body?.text || resetEmail.body?.html || '';
+  const tokenMatch = body.match(/[?&]token=([a-zA-Z0-9._-]+)/);
+  if (!tokenMatch) {
+    error('Could not extract reset token from email.');
+    const links = extractResetLinks(resetEmail);
+    if (links.length) {
+      log('Found links:');
+      links.forEach(l => log(`  ${l}`));
+    }
+    process.exit(1);
+  }
+
+  const token = tokenMatch[1];
+  info(`Token extracted: ${token.slice(0, 12)}...`);
+
+  // Step 4: Generate or use provided password
+  const newPassword = flags.password || generatePassword();
+  if (!flags.password) {
+    info(`Generated password: ${c.bold(newPassword)}`);
+  }
+
+  // Step 5: Complete reset via ClearAuth API
+  info(`Completing reset at ${serviceUrl}/auth/reset-password ...`);
+  const controller2 = new AbortController();
+  const timeoutId2 = setTimeout(() => controller2.abort(), 30000);
+  let resetResponse;
+  try {
+    resetResponse = await fetch(`${serviceUrl}/auth/reset-password`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token, password: newPassword }),
+      signal: controller2.signal,
+    });
+  } finally {
+    clearTimeout(timeoutId2);
+  }
+
+  if (!resetResponse.ok) {
+    error(`Reset failed: ${resetResponse.status}`);
+    process.exit(1);
+  }
+
+  success('Password reset complete.');
+
+  // Step 6: Update vault
+  const now = new Date().toISOString().slice(0, 10);
+  await client.put(`/credentials/${serviceHash}?mailboxId=${mailboxId}`, {
+    password: newPassword,
+    notes: `ClearAuth reset ${now}. ${cred.notes || ''}`.trim(),
+  });
+  success('Credential updated in vault.');
+}
+
+async function pollForResetEmail(client, mailboxId, serviceUrl) {
+  let serviceDomain = '';
+  try { serviceDomain = new URL(serviceUrl).hostname; } catch {}
+
+  const maxAttempts = 30; // 5 minutes at 10s intervals
+  let consecutiveErrors = 0;
+  for (let i = 0; i < maxAttempts; i++) {
+    if (i > 0) {
+      await new Promise(r => setTimeout(r, 10000));
+    }
+    process.stdout.write('.');
+
+    try {
+      const result = await client.get(`/inboxes/${mailboxId}/emails?limit=5`);
+      consecutiveErrors = 0; // Reset on success
+      const emails = result.data?.emails || [];
+
+      for (const email of emails) {
+        const subject = (email.subject || '').toLowerCase();
+        const from = (email.from || '').toLowerCase();
+
+        const isResetEmail =
+          /reset|password|verify|confirm/i.test(subject) ||
+          (serviceDomain && from.includes(serviceDomain));
+
+        if (isResetEmail) {
+          // Fetch full email
+          const full = await client.get(`/inboxes/${mailboxId}/emails/${email.uid}`);
+          process.stdout.write('\n');
+          success(`Found reset email: "${email.subject}"`);
+          return full.data;
+        }
+      }
+    } catch (err) {
+      consecutiveErrors++;
+      // Abort on auth errors — no point continuing
+      if (err.code === 'AUTH_ERROR' || err.status === 401 || err.status === 403) {
+        process.stdout.write('\n');
+        error(`Authentication error while polling: ${err.message}`);
+        return null;
+      }
+      // Abort after 5 consecutive errors (server likely down)
+      if (consecutiveErrors >= 5) {
+        process.stdout.write('\n');
+        error(`Polling aborted after ${consecutiveErrors} consecutive errors: ${err.message}`);
+        return null;
+      }
+    }
+  }
+
+  process.stdout.write('\n');
+  return null;
+}
+
+function extractResetLinks(email) {
+  const body = (email.body?.text || '') + ' ' + (email.body?.html || '');
+  const urlPattern = /https?:\/\/[^\s"'<>]+(?:reset|token|confirm|password|verify)[^\s"'<>]*/gi;
+  const matches = body.match(urlPattern) || [];
+  return [...new Set(matches)];
+}
+
+function generatePassword(length = 20) {
+  const upper = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+  const lower = 'abcdefghijklmnopqrstuvwxyz';
+  const nums = '0123456789';
+  const special = '!@#$%^&*_+-=';
+  const all = upper + lower + nums + special;
+
+  const required = [
+    upper[crypto.randomInt(upper.length)],
+    lower[crypto.randomInt(lower.length)],
+    nums[crypto.randomInt(nums.length)],
+    special[crypto.randomInt(special.length)],
+  ];
+
+  const rest = [];
+  for (let i = 0; i < length - required.length; i++) {
+    rest.push(all[crypto.randomInt(all.length)]);
+  }
+
+  const chars = [...required, ...rest];
+  for (let i = chars.length - 1; i > 0; i--) {
+    const j = crypto.randomInt(i + 1);
+    [chars[i], chars[j]] = [chars[j], chars[i]];
+  }
+
+  return chars.join('');
+}
+
+// ============================================================================
+// Commands: Provision
+// ============================================================================
+
+async function commandProvision(args) {
+  const { flags, positional } = parseFlags(args);
+
+  if (!positional[0]) {
+    error('Usage: circleinbox provision <domain> [--local hello] [--display "Name"]');
+    process.exit(1);
+  }
+
+  const domainName = positional[0];
+  const localPart = flags.local || 'hello';
+  const displayName = flags.display || flags.name || localPart;
+  const dryRun = flags['dry-run'] === true;
+
+  const client = getClient();
+
+  // Step 1: Check domain exists
+  info(`Checking domain: ${domainName}...`);
+  const domain = await resolveDomain(client, domainName);
+
+  log(`  Status:   ${domain.status}`);
+  log(`  Mailcow:  ${domain.mailcowProvisioned ? c.green('provisioned') : c.yellow('not provisioned')}`);
+
+  if (!domain.mailcowProvisioned) {
+    if (dryRun) {
+      log(c.yellow('\n  [dry-run] Would provision domain in Mailcow'));
+      return;
+    }
+    info('Provisioning domain in Mailcow...');
+    await client.post(`/domains/${domain.id}/setup-user-inboxes`);
+    success('Domain provisioned.');
+  }
+
+  // Step 2: Create mailbox
+  const email = `${localPart}@${domainName}`;
+  if (dryRun) {
+    log(c.yellow(`\n  [dry-run] Would create mailbox: ${email}`));
+    return;
+  }
+
+  info(`Creating mailbox: ${email}...`);
+  const result = await client.post('/inboxes', {
+    domainId: domain.id,
+    localPart,
+    displayName,
+  });
+
+  success(`Mailbox created: ${result.data.email}`);
+  log('');
+
+  if (result.data.password) {
+    log(c.yellow('  ⚠ SAVE THIS PASSWORD — it will not be shown again'));
+    log(`  Password: ${c.bold(result.data.password)}`);
+  }
+
+  if (result.data.smtp) {
+    log('');
+    log(c.bold('  SMTP:') + ` ${result.data.smtp.host}:${result.data.smtp.port} (${result.data.smtp.security})`);
+    log(c.bold('  IMAP:') + ` ${result.data.imap.host}:${result.data.imap.port} (${result.data.imap.security})`);
+  }
+
+  // Step 3: DNS check
+  if (!domain.mxVerified || !domain.spfVerified || !domain.dkimVerified) {
+    log('');
+    warn('DNS records incomplete. Required:');
+    if (!domain.mxVerified) log(`  MX  ${domainName} → mail.circleinbox.com (priority 10)`);
+    if (!domain.spfVerified) log(`  TXT ${domainName} → "v=spf1 include:mail.circleinbox.com ~all"`);
+    if (!domain.dkimVerified) log(`  CNAME dkim._domainkey.${domainName} → dkim._domainkey.mail.circleinbox.com`);
+  }
+
+  log('');
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+function formatBytes(bytes) {
+  if (!bytes) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let i = 0;
+  let size = bytes;
+  while (size >= 1024 && i < units.length - 1) {
+    size /= 1024;
+    i++;
+  }
+  return `${size.toFixed(i > 0 ? 1 : 0)} ${units[i]}`;
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+try {
+  const allArgs = process.argv.slice(2);
+  const { flags: gf, positional: topArgs } = parseFlags(allArgs);
+
+  // Extract global flags before routing
+  globalFlags = {
+    json: gf.json === true,
+    quiet: gf.quiet === true,
+  };
+
+  // Override API URL if provided (in-memory only, never persisted)
+  if (gf['api-url']) {
+    globalFlags.apiUrlOverride = gf['api-url'];
+  }
+
+  const command = topArgs[0];
+  const args = topArgs.slice(1);
+
+  // Find the command's actual index in allArgs by skipping global flags
+  const GLOBAL_FLAGS_WITH_VALUE = new Set(['--api-url']);
+  const GLOBAL_FLAGS_BOOLEAN = new Set(['--json', '--quiet']);
+  let commandIndex = -1;
+  for (let i = 0; i < allArgs.length; i++) {
+    if (GLOBAL_FLAGS_WITH_VALUE.has(allArgs[i])) {
+      i++; // skip the flag's value
+      continue;
+    }
+    if (GLOBAL_FLAGS_BOOLEAN.has(allArgs[i])) {
+      continue;
+    }
+    // First non-global-flag arg is the command
+    commandIndex = i;
+    break;
+  }
+
+  // Slice from after the command and strip global flags
+  const rawSubArgs = commandIndex >= 0 ? allArgs.slice(commandIndex + 1) : [];
+  const subArgs = [];
+  for (let i = 0; i < rawSubArgs.length; i++) {
+    if (GLOBAL_FLAGS_BOOLEAN.has(rawSubArgs[i])) continue;
+    if (GLOBAL_FLAGS_WITH_VALUE.has(rawSubArgs[i])) {
+      i++; // skip the flag's value
+      continue;
+    }
+    subArgs.push(rawSubArgs[i]);
+  }
+
+  switch (command) {
+    case 'version':
+    case '--version':
+    case '-v':
+      commandVersion();
+      break;
+
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      commandHelp();
+      break;
+
+    case 'login':
+      commandLogin(subArgs).catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'logout':
+      commandLogout().catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'status':
+      commandStatus().catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'domains':
+      commandDomains(subArgs).catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'dns':
+      commandDns(subArgs).catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'inbox':
+      commandInbox(subArgs).catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'send':
+      commandSend(subArgs).catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'alias':
+      commandAlias(subArgs).catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'vault':
+      commandVault(subArgs).catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'reset':
+      commandReset(subArgs).catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    case 'provision':
+      commandProvision(subArgs).catch(err => { error(err.message); process.exit(1); });
+      break;
+
+    default:
+      error(`Unknown command: ${command}`);
+      log(`Run ${c.cyan('circleinbox help')} for usage.`);
+      process.exit(1);
+  }
+} catch (err) {
+  console.error(c.red('✗'), err.message);
+  process.exit(1);
+}