@profullstack/coinpay 0.6.11 → 0.9.0

package/bin/coinpay.js

@@ -15,16 +15,43 @@ import {
   DEFAULT_CHAINS,
 } from '../src/wallet.js';
 import { SwapClient, SwapCoins } from '../src/swap.js';
-import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'fs';
-import { execSync } from 'child_process';
+import {
+  createInvoice,
+  deleteInvoice,
+  getInvoice,
+  listInvoices,
+  publishInvoice,
+  sendInvoice,
+  updateInvoice,
+  InvoiceStatus,
+} from '../src/invoices.js';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, chmodSync } from 'fs';
+import { execSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
-import { homedir } from 'os';
+import { homedir, hostname } from 'os';
 import { join } from 'path';
 import { tmpdir } from 'os';
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-const CONFIG_FILE = join(homedir(), '.coinpay.json');
-const DEFAULT_WALLET_FILE = join(homedir(), '.coinpay-wallet.gpg');
+const HOME_DIRECTORY = process.env.COINPAY_HOME || process.env.HOME || homedir();
+const CONFIG_FILE = join(HOME_DIRECTORY, '.coinpay.json');
+const DEFAULT_WALLET_FILE = join(HOME_DIRECTORY, '.coinpay-wallet.gpg');
+// Where `coinpay update|upgrade|remove|uninstall` re-invoke the installer.
+const INSTALL_URL = process.env.COINPAY_INSTALL_URL || 'https://coinpayportal.com/install.sh';
+
+// Self-manage the CLI by delegating to the installer, which owns the
+// fetch-from-GitHub / uninstall logic. Works whether the user hit the
+// shell wrapper (which also intercepts these) or the raw binary directly.
+function handleSelfManage(action) {
+  const label = action === 'remove' ? 'Removing' : 'Updating';
+  print.info(`${label} the coinpay CLI via ${INSTALL_URL}`);
+  try {
+    execSync(`curl -fsSL "${INSTALL_URL}" | sh -s -- ${action}`, { stdio: 'inherit' });
+  } catch {
+    print.error(`coinpay ${action} failed — run it manually:\n  curl -fsSL ${INSTALL_URL} | sh -s -- ${action}`);
+    process.exit(1);
+  }
+}
 
 // ANSI colors
 const colors = {
@@ -74,11 +101,11 @@ function saveConfig(config) {
  */
 function getWalletFilePath(flags = {}) {
   if (flags['wallet-file']) {
-    return flags['wallet-file'].replace(/^~/, homedir());
+    return flags['wallet-file'].replace(/^~/, HOME_DIRECTORY);
   }
   const config = loadConfig();
   if (config.walletFile) {
-    return config.walletFile.replace(/^~/, homedir());
+    return config.walletFile.replace(/^~/, HOME_DIRECTORY);
   }
   return DEFAULT_WALLET_FILE;
 }
@@ -107,13 +134,19 @@ function getBaseUrl() {
   return process.env.COINPAY_BASE_URL || config.baseUrl || 'https://coinpayportal.com/api';
 }
 
+function getInvoiceShareUrl(invoiceId) {
+  return new URL(`/now/${encodeURIComponent(invoiceId)}`, getBaseUrl()).toString();
+}
+
 /**
  * Create client instance
  */
 function createClient() {
-  const apiKey = getApiKey();
+  // An API key, or the session token from `coinpay login` (the merchant JWT is
+  // accepted by the API the same way — via its userId claim).
+  const apiKey = getApiKey() || loadConfig().jwtToken;
   if (!apiKey) {
-    print.error('API key not configured. Run: coinpay config set-key <api-key>');
+    print.error('Not authenticated. Run: coinpay login  (or coinpay config set-key <api-key>)');
     process.exit(1);
   }
   return new CoinPayClient({ apiKey, baseUrl: getBaseUrl() });
@@ -126,6 +159,26 @@ function createUnauthenticatedClient() {
   return new CoinPayClient({ baseUrl: getBaseUrl() });
 }
 
+const BOOLEAN_FLAGS = new Set([
+  'active',
+  'plain',
+  'no-stream',
+  'hidden',
+  'active-only',
+  'debug',
+  'escrow',
+  'escrow-mode',
+  'h',
+  'help',
+  'json',
+  'no-open',
+  'no-save',
+  'show',
+  'v',
+  'version',
+  'yes',
+]);
+
 /**
  * Parse command line arguments
  */
@@ -140,16 +193,20 @@ function parseArgs(args) {
       if (eqIdx !== -1) {
         result.flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
       } else {
+        const name = arg.slice(2);
         const next = args[i + 1];
-        if (next && !next.startsWith('-')) {
-          result.flags[arg.slice(2)] = next;
+        if (BOOLEAN_FLAGS.has(name)) {
+          result.flags[name] = true;
+        } else if (next && !next.startsWith('-')) {
+          result.flags[name] = next;
           i++;
         } else {
-          result.flags[arg.slice(2)] = true;
+          result.flags[name] = true;
         }
       }
     } else if (arg.startsWith('-')) {
-      result.flags[arg.slice(1)] = args[++i] ?? true;
+      const name = arg.slice(1);
+      result.flags[name] = BOOLEAN_FLAGS.has(name) ? true : args[++i] ?? true;
     } else if (!result.command) {
       result.command = arg;
     } else if (!result.subcommand) {
@@ -162,6 +219,134 @@ function parseArgs(args) {
   return result;
 }
 
+function validateBooleanFlags(flags) {
+  for (const name of BOOLEAN_FLAGS) {
+    if (flags[name] !== undefined && flags[name] !== true) {
+      print.error('--' + name + ' does not take a value');
+      process.exit(1);
+    }
+  }
+}
+
+function parsePositiveInteger(value) {
+  if (typeof value !== 'string' || !/^\d+$/.test(value.trim())) {
+    return null;
+  }
+
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function parsePositiveAmount(value) {
+  if (typeof value !== 'string') return null;
+
+  const normalized = value.trim();
+  const match = /^(\d+)(?:\.(\d{1,2}))?$/.exec(normalized);
+  if (!match) return null;
+
+  const cents = BigInt(match[1]) * 100n + BigInt((match[2] || '').padEnd(2, '0'));
+  if (cents <= 0n || cents > BigInt(Number.MAX_SAFE_INTEGER)) return null;
+
+  return Number(cents) / 100;
+}
+
+function isValidDate(value) {
+  if (typeof value !== 'string') return false;
+
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+
+  const [, year, month, day] = match.map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return (
+    date.getUTCFullYear() === year &&
+    date.getUTCMonth() === month - 1 &&
+    date.getUTCDate() === day
+  );
+}
+
+function requireFlagValues(flags, names) {
+  for (const name of names) {
+    if (flags[name] === true) {
+      print.error('--' + name + ' requires a value');
+      process.exit(1);
+    }
+  }
+}
+
+function requireSingleInvoiceId(args, subcommand) {
+  if (args.length !== 1) {
+    print.error('Usage: coinpay invoice ' + subcommand + ' <id>');
+    process.exit(1);
+  }
+  return args[0];
+}
+
+function rejectUnsupportedFlags(flags, allowed) {
+  const allowedFlags = new Set([...allowed, 'debug', 'json']);
+  const unsupported = Object.keys(flags).filter((name) => !allowedFlags.has(name));
+  if (unsupported.length > 0) {
+    print.error('Unsupported option' + (unsupported.length > 1 ? 's' : '') + ': ' +
+      unsupported.map((name) => '--' + name).join(', '));
+    process.exit(1);
+  }
+}
+
+function invoiceForOutput(data, fallbackId) {
+  const invoice = data?.invoice ?? data ?? {};
+  const output = {
+    id: invoice.id ?? fallbackId,
+    invoiceNumber: invoice.invoiceNumber ?? invoice.invoice_number,
+    businessId: invoice.businessId ?? invoice.business_id,
+    clientId: invoice.clientId ?? invoice.client_id,
+    currency: invoice.currency,
+    amount: invoice.amount,
+    cryptoCurrency: invoice.cryptoCurrency ?? invoice.crypto_currency,
+    cryptoAmount: invoice.cryptoAmount ?? invoice.crypto_amount,
+    status: invoice.status,
+    dueDate: invoice.dueDate ?? invoice.due_date,
+    notes: invoice.notes,
+    walletId: invoice.walletId ?? invoice.wallet_id,
+    merchantWalletAddress:
+      invoice.merchantWalletAddress ?? invoice.merchant_wallet_address,
+    paymentAddress: invoice.paymentAddress ?? invoice.payment_address,
+    stripeCheckoutUrl: invoice.stripeCheckoutUrl ?? invoice.stripe_checkout_url,
+    paidAt: invoice.paidAt ?? invoice.paid_at,
+    sentAt: invoice.sentAt ?? invoice.sent_at,
+    createdAt: invoice.createdAt ?? invoice.created_at,
+    updatedAt: invoice.updatedAt ?? invoice.updated_at,
+  };
+
+  return Object.fromEntries(
+    Object.entries(output).filter(([, value]) => value !== undefined)
+  );
+}
+
+function assertInvoiceUpdatesApplied(invoice, updates) {
+  if (invoice.status !== InvoiceStatus.DRAFT) {
+    throw new Error('Invoice changed state before the update completed; no draft update was confirmed');
+  }
+
+  const mismatches = Object.entries(updates).filter(([field, expected]) => {
+    const actual = invoice[field];
+    if (field === 'amount') return Number(actual) !== Number(expected);
+    if (field === 'dueDate') return String(actual || '').slice(0, 10) !== expected;
+    return actual !== expected;
+  });
+
+  if (mismatches.length > 0) {
+    throw new Error(
+      'Invoice update was not confirmed for: ' + mismatches.map(([field]) => field).join(', ')
+    );
+  }
+}
+
+function describeInvoiceRouting(invoice) {
+  const crypto = invoice.cryptoCurrency || 'unset crypto';
+  const destination = invoice.merchantWalletAddress || 'resolved payee';
+  return crypto + ' -> ' + destination;
+}
+
 /**
  * Show help
  */
@@ -189,8 +374,30 @@ ${colors.cyan}Commands:${colors.reset}
     list                  List payments
     qr <id>               Get payment QR code
 
+  ${colors.bright}invoice${colors.reset}
+    create                Create a draft invoice (--amount required)
+      --wallet-id <id>    Route settlement through a saved wallet
+      --merchant-wallet-address <address>
+                            Route settlement to a direct address
+    get <id>              Get invoice details
+    list                  List invoices with optional filters
+    update <id>           Update editable fields on a draft invoice
+    publish <id>          Create payment details without emailing the client
+    send <id>             Create payment details and email the client
+    delete <id>           Permanently delete a draft invoice
+      --yes               Skip confirmation for publish/send/delete
+
+  ${colors.bright}tokens${colors.reset}
+    list                  List checkout tokens (--business-id, --active-only)
+
   ${colors.bright}business${colors.reset}
     create                Create a new business
+      --name <name>       Required
+      --category <slug>   Required; see: coinpay business categories
+      --description <s>   Optional
+      --webhook-url <url> Optional; enables webhooks and a generated secret
+      --webhook-secret <s>  Optional; supply your own instead
+    categories            List the valid business category slugs
     get <id>              Get business details
     list                  List businesses
     update <id>           Update business
@@ -229,11 +436,25 @@ ${colors.cyan}Commands:${colors.reset}
     create                Create a card payment via Stripe
     get <id>              Get card payment status
     list                  List card payments
-    connect onboard <id>  Create Stripe onboarding link
+    connect onboard <id>  Create Stripe onboarding link (--country required first time)
     connect status <id>   Check Stripe account status
     escrow release <id>   Release card escrow funds
     escrow refund <id>    Refund card escrow
 
+  ${colors.bright}finances${colors.reset}       (also: coinpay money)
+    [tui]                 Live dashboard: earnings, commission, refunds,
+                            bank & credit-card feeds, ledger, invoices, escrow
+      --days <n>          Window for earnings/cashflow (7, 30, 90, 365; default 30)
+      --interval <s>      Refresh every s seconds (default 30)
+      --business-id <id>  Narrow payments to one business
+    summary               Plain-text headline numbers (--json for machines)
+    position              Debt vs income, credits vs debits, recurring bills
+                            (also: coinpay finances debt)
+    accounts              Linked bank and card accounts with balances
+    ledger                Bank/card transactions (--limit, --search, --category, --account)
+    connections           Linked institutions and their last sync
+    sync                  Pull fresh balances from the bank bridge (--days)
+
   ${colors.bright}escrow${colors.reset}
     create                Create a new escrow
     get <id>              Get escrow status
@@ -259,6 +480,7 @@ ${colors.cyan}Commands:${colors.reset}
     badge [did]           Get embeddable reputation badge URL
     verify <id>           Verify a credential
     revocations           List revoked credentials
+    did setup             Use existing DID or create one automatically
     did claim             Claim (auto-generate) a new DID
     did me                Show your current DID
     issuer register       Register platform issuer (--name, --domain)
@@ -270,6 +492,12 @@ ${colors.cyan}Commands:${colors.reset}
     logs <business-id>    Get webhook logs
     test <business-id>    Send test webhook
 
+  ${colors.bright}self${colors.reset}
+    update                Update the coinpay CLI to the latest version
+    upgrade               Alias for update
+    remove                Uninstall the coinpay CLI
+    uninstall             Alias for remove
+
 ${colors.cyan}Wallet Options:${colors.reset}
   --words <12|24>         Number of mnemonic words (default: 12)
   --chains <BTC,ETH,...>  Chains to derive (default: BTC,ETH,SOL,POL,BCH)
@@ -326,6 +554,12 @@ ${colors.cyan}Examples:${colors.reset}
   coinpay swap quote --from BTC --to ETH --amount 0.1
   coinpay swap create --from BTC --to ETH --amount 0.1 --settle 0x...
 
+  # Connect Stripe to a business (country is locked at Stripe account creation)
+  coinpay card connect onboard <business-id> --country CA --email merchant@example.com
+
+  # List payment tokens for a business
+  coinpay tokens list --business-id <business-id> --active-only
+
 ${colors.cyan}Environment Variables:${colors.reset}
   COINPAY_API_KEY         API key (overrides config)
   COINPAY_BASE_URL        Custom API URL
@@ -388,6 +622,73 @@ async function promptYesNo(question, defaultYes = true) {
   return answer.toLowerCase().startsWith('y');
 }
 
+async function promptYesNoOnStderr(question) {
+  const answer = await new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question + ' [y/N] ', (value) => {
+      rl.close();
+      resolve(value.trim());
+    });
+  });
+  return answer.toLowerCase().startsWith('y');
+}
+
+async function confirmInvoiceMutation(flags, question) {
+  if (flags.yes === true) return true;
+  if (flags.json) {
+    throw new Error('--json requires --yes for invoice publish/send/delete');
+  }
+  if (!process.stdin.isTTY) {
+    throw new Error('Confirmation requires an interactive terminal; rerun with --yes');
+  }
+  return promptYesNoOnStderr(question);
+}
+
+/**
+ * Run gpg with the passphrase on a dedicated file descriptor and the plaintext
+ * on stdin, so neither ever touches the filesystem.
+ *
+ * This replaces a pair of temporary files in the system temp directory that
+ * held the wallet MNEMONIC and the password in plaintext for the duration of
+ * the gpg call. Three things made that dangerous:
+ *
+ *   1. The names were predictable — built from Date.now() — so another process
+ *      could poll the temp directory for `coinpay-wallet-*`.
+ *   2. Mode 0600 keeps out other OS users. It does not keep out anything
+ *      running AS the same user, which is the realistic threat on a developer
+ *      machine: a malicious npm postinstall, a compromised editor extension.
+ *   3. Overwrite-then-unlink does not reliably erase data on journalling or
+ *      copy-on-write filesystems, or on SSDs that remap blocks.
+ *
+ * The mnemonic derives every private key on every chain, so this window was
+ * worth removing rather than narrowing. Using fd 3 also keeps the passphrase
+ * off the command line, where it would be visible in `ps`.
+ */
+function runGpg(args, { stdinData, passphrase }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('gpg', args, { stdio: ['pipe', 'pipe', 'pipe', 'pipe'] });
+
+    const stdout = [];
+    let stderr = '';
+
+    child.stdout.on('data', (d) => stdout.push(d));
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve(Buffer.concat(stdout));
+      else reject(new Error(stderr.trim() || `gpg exited with code ${code}`));
+    });
+
+    const passFd = child.stdio[3];
+    passFd.on('error', () => {});
+    passFd.end(passphrase);
+
+    child.stdin.on('error', () => {});
+    if (stdinData !== undefined) child.stdin.end(stdinData);
+    else child.stdin.end();
+  });
+}
+
 /**
  * Check if gpg is available
  */
@@ -403,7 +704,39 @@ function hasGpg() {
 /**
  * Encrypt mnemonic with GPG and save to file
  */
+
+/**
+ * Minimum strength for a passphrase that protects an exported wallet.
+ *
+ * F5-L1-07 / L6B-05: there was no minimum at all here, while the sibling
+ * `generate-hd-wallets` backup asks for eight characters and the web wallet's
+ * create/import flow requires length >= 8 AND a strength score. A one-character
+ * passphrase was accepted on the path that produces a file an attacker can walk
+ * away with — and GPG's default KDF is far cheaper to attack on a GPU than the
+ * scrypt used by the other backup, so the passphrase is doing most of the work.
+ */
+function assertStrongPassphrase(password) {
+  const problems = [];
+  if (!password || password.length < 12) {
+    problems.push('at least 12 characters');
+  }
+  if (!/[a-z]/.test(password ?? '') || !/[A-Z]/.test(password ?? '')) {
+    problems.push('both upper and lower case');
+  }
+  if (!/\d/.test(password ?? '') && !/[^A-Za-z0-9]/.test(password ?? '')) {
+    problems.push('a digit or a symbol');
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      'Passphrase too weak — this is the only thing protecting your wallet file. ' +
+      'It needs ' + problems.join(', ') + '.'
+    );
+  }
+}
+
 async function saveEncryptedWallet(mnemonic, walletId, password, walletFile) {
+  assertStrongPassphrase(password);
+
   if (!hasGpg()) {
     throw new Error('GPG is required for wallet encryption. Install: apt install gnupg');
   }
@@ -415,24 +748,38 @@ async function saveEncryptedWallet(mnemonic, walletId, password, walletFile) {
     createdAt: new Date().toISOString(),
   });
   
-  const tmpFile = join(tmpdir(), `coinpay-wallet-${Date.now()}.json`);
-  const passFile = join(tmpdir(), `coinpay-pass-${Date.now()}`);
-  
+  // The mnemonic goes to gpg on stdin and the passphrase on fd 3. Neither is
+  // written to disk, and neither appears in the process arguments.
+  await runGpg(
+    [
+      '--batch',
+      '--yes',
+      '--passphrase-fd', '3',
+      '--pinentry-mode', 'loopback',
+      '--symmetric',
+      '--cipher-algo', 'AES256',
+      '--output', walletFile,
+    ],
+    { stdinData: content, passphrase: password }
+  );
+
+  // Restrict the file gpg just created (F-L7-01 / F5-L1-02).
+  //
+  // `--output` means GPG creates the file itself, at the process umask — so it
+  // typically lands world-readable, and every other local user can copy an
+  // encrypted wallet at their leisure and attack the passphrase offline.
+  // Sibling writes in this same CLI pass `{ mode: 0o600 }`, but that option
+  // only applies when Node does the writing.
   try {
-    writeFileSync(tmpFile, content, { mode: 0o600 });
-    writeFileSync(passFile, password, { mode: 0o600 });
-    
-    execSync(
-      `gpg --batch --yes --passphrase-file "${passFile}" --pinentry-mode loopback --symmetric --cipher-algo AES256 --output "${walletFile}" "${tmpFile}"`,
-      { stdio: ['pipe', 'pipe', 'pipe'] }
+    chmodSync(walletFile, 0o600);
+  } catch (err) {
+    console.warn(
+      `Warning: could not restrict permissions on ${walletFile} — ` +
+      'other local users may be able to read it. ' + (err?.message ?? err)
     );
-    
-    return true;
-  } finally {
-    // Secure cleanup
-    try { writeFileSync(tmpFile, Buffer.alloc(content.length, 0)); unlinkSync(tmpFile); } catch {}
-    try { writeFileSync(passFile, Buffer.alloc(password.length, 0)); unlinkSync(passFile); } catch {}
   }
+
+  return true;
 }
 
 /**
@@ -447,21 +794,18 @@ async function loadEncryptedWallet(password, walletFile) {
     throw new Error(`Wallet file not found: ${walletFile}`);
   }
   
-  const passFile = join(tmpdir(), `coinpay-pass-${Date.now()}`);
-  
-  try {
-    writeFileSync(passFile, password, { mode: 0o600 });
-    
-    const result = execSync(
-      `gpg --batch --yes --passphrase-file "${passFile}" --pinentry-mode loopback --decrypt "${walletFile}"`,
-      { stdio: ['pipe', 'pipe', 'pipe'] }
-    );
-    
-    const data = JSON.parse(result.toString());
-    return data;
-  } finally {
-    try { writeFileSync(passFile, Buffer.alloc(password.length, 0)); unlinkSync(passFile); } catch {}
-  }
+  const result = await runGpg(
+    [
+      '--batch',
+      '--yes',
+      '--passphrase-fd', '3',
+      '--pinentry-mode', 'loopback',
+      '--decrypt', walletFile,
+    ],
+    { passphrase: password }
+  );
+
+  return JSON.parse(result.toString());
 }
 
 /**
@@ -607,33 +951,521 @@ async function handlePayment(subcommand, args, flags) {
         print.error('Required: --business-id');
         return;
       }
-      
-      const payments = await client.listPayments({
-        businessId,
-        status,
-        limit: limit ? parseInt(limit, 10) : undefined,
-      });
-      
-      print.json(payments);
-      break;
-    }
-    
-    case 'qr': {
-      const paymentId = args[0];
-      
-      if (!paymentId) {
-        print.error('Payment ID required');
-        return;
+      
+      const payments = await client.listPayments({
+        businessId,
+        status,
+        limit: limit ? parseInt(limit, 10) : undefined,
+      });
+      
+      print.json(payments);
+      break;
+    }
+    
+    case 'qr': {
+      const paymentId = args[0];
+      
+      if (!paymentId) {
+        print.error('Payment ID required');
+        return;
+      }
+      
+      const url = client.getPaymentQRUrl(paymentId);
+      print.info(`QR Code URL: ${url}`);
+      break;
+    }
+    
+    default:
+      print.error(`Unknown payment command: ${subcommand}`);
+      showHelp();
+  }
+}
+
+function printInvoiceDetails(invoice, { shareUrl } = {}) {
+  const label = invoice.invoiceNumber || invoice.id;
+  console.log('\n' + colors.bright + label + colors.reset);
+  print.info('ID: ' + invoice.id);
+  print.info('Status: ' + (invoice.status || 'unknown'));
+  print.info('Amount: ' + invoice.amount + ' ' + (invoice.currency || ''));
+  if (invoice.businessId) print.info('Business: ' + invoice.businessId);
+  if (invoice.clientId) print.info('Client: ' + invoice.clientId);
+  if (invoice.cryptoCurrency) print.info('Crypto: ' + invoice.cryptoCurrency);
+  if (invoice.walletId) print.info('Wallet reference: ' + invoice.walletId);
+  if (invoice.merchantWalletAddress) {
+    print.info('Settlement address: ' + invoice.merchantWalletAddress);
+  }
+  if (invoice.paymentAddress) print.info('Payment address: ' + invoice.paymentAddress);
+  if (invoice.dueDate) print.info('Due: ' + invoice.dueDate);
+  if (invoice.notes) print.info('Notes: ' + invoice.notes);
+  if (shareUrl) {
+    print.info('Share link: ' + shareUrl);
+  }
+  console.log();
+}
+
+/**
+ * Invoice commands
+ */
+async function handleInvoice(subcommand, args, flags) {
+  const client = createClient();
+
+  switch (subcommand) {
+    case 'create': {
+      requireFlagValues(flags, [
+        'amount',
+        'business-id',
+        'client-id',
+        'currency',
+        'crypto-currency',
+        'due-date',
+        'notes',
+        'wallet-id',
+        'merchant-wallet-address',
+      ]);
+
+      const amount = parsePositiveAmount(flags.amount);
+      if (amount === null) {
+        print.error('--amount must be a positive decimal with at most two decimal places');
+        print.info('Example: coinpay invoice create --amount 125 --currency USD --notes "Consulting"');
+        process.exit(1);
+      }
+
+      const currency = flags.currency || 'USD';
+      if (!/^[A-Za-z]{3}$/.test(currency)) {
+        print.error('--currency must be a three-letter currency code');
+        process.exit(1);
+      }
+
+      const dueDate = flags['due-date'];
+      if (dueDate !== undefined && !isValidDate(dueDate)) {
+        print.error('--due-date must be a valid date in YYYY-MM-DD format');
+        process.exit(1);
+      }
+
+      const cryptoCurrency = flags['crypto-currency'];
+      const invoice = await createInvoice(client, {
+        businessId: flags['business-id'],
+        clientId: flags['client-id'],
+        currency: currency.toUpperCase(),
+        amount,
+        cryptoCurrency: cryptoCurrency?.toUpperCase(),
+        dueDate,
+        notes: flags.notes,
+        walletId: flags['wallet-id'],
+        merchantWalletAddress: flags['merchant-wallet-address'],
+      });
+      if (flags.json) {
+        print.json(invoice);
+        break;
+      }
+
+      print.success('Draft invoice created');
+      printInvoiceDetails(invoice);
+      break;
+    }
+
+    case 'list': {
+      requireFlagValues(flags, ['business-id', 'status', 'client-id', 'date-from', 'date-to']);
+
+      const status = flags.status?.toLowerCase();
+      const validStatuses = new Set(Object.values(InvoiceStatus));
+      if (status !== undefined && !validStatuses.has(status)) {
+        print.error('--status must be one of: ' + [...validStatuses].join(', '));
+        process.exit(1);
+      }
+
+      const dateFrom = flags['date-from'];
+      const dateTo = flags['date-to'];
+      if (dateFrom !== undefined && !isValidDate(dateFrom)) {
+        print.error('--date-from must be a valid date in YYYY-MM-DD format');
+        process.exit(1);
+      }
+      if (dateTo !== undefined && !isValidDate(dateTo)) {
+        print.error('--date-to must be a valid date in YYYY-MM-DD format');
+        process.exit(1);
+      }
+      if (dateFrom && dateTo && dateFrom > dateTo) {
+        print.error('--date-from must not be later than --date-to');
+        process.exit(1);
+      }
+
+      const result = await listInvoices(client, {
+        businessId: flags['business-id'],
+        status,
+        clientId: flags['client-id'],
+        dateFrom,
+        dateTo,
+      });
+
+      if (flags.json) {
+        print.json(result);
+        break;
+      }
+
+      if (result.invoices.length === 0) {
+        print.info('No invoices found');
+        break;
+      }
+
+      console.log('\n' + colors.bright + 'Invoices' + colors.reset + ' (' + (result.total ?? result.invoices.length) + ')\n');
+      for (const invoice of result.invoices) {
+        const label = invoice.invoiceNumber || invoice.id;
+        const created = invoice.createdAt ? invoice.createdAt.slice(0, 10) : '-';
+        console.log(
+          '  ' + colors.bright + label + colors.reset +
+          '  ' + (invoice.status || 'unknown') +
+          '  ' + invoice.amount + ' ' + (invoice.currency || '') +
+          '  ' + created
+        );
+        if (invoice.invoiceNumber && invoice.id) console.log('    ' + invoice.id);
+      }
+      console.log();
+      break;
+    }
+
+    case 'get': {
+      rejectUnsupportedFlags(flags, []);
+      const id = requireSingleInvoiceId(args, 'get');
+
+      const invoice = await getInvoice(client, id);
+      if (flags.json) {
+        print.json(invoice);
+        break;
+      }
+
+      printInvoiceDetails(invoice);
+      break;
+    }
+
+    case 'update': {
+      const updateFlags = [
+        'amount',
+        'currency',
+        'crypto-currency',
+        'due-date',
+        'notes',
+        'client-id',
+        'wallet-id',
+        'merchant-wallet-address',
+      ];
+      rejectUnsupportedFlags(flags, updateFlags);
+      if (flags.notes === true) {
+        print.error('--notes requires a value; use --notes= to clear existing notes');
+        process.exit(1);
+      }
+      requireFlagValues(flags, updateFlags);
+      const id = requireSingleInvoiceId(args, 'update');
+      const updates = {};
+
+      if (flags.amount !== undefined) {
+        const amount = parsePositiveAmount(flags.amount);
+        if (amount === null) {
+          print.error('--amount must be a positive decimal with at most two decimal places');
+          process.exit(1);
+        }
+        updates.amount = amount;
+      }
+
+      if (flags.currency !== undefined) {
+        if (!/^[A-Za-z]{3}$/.test(flags.currency)) {
+          print.error('--currency must be a three-letter currency code');
+          process.exit(1);
+        }
+        updates.currency = flags.currency.toUpperCase();
+      }
+
+      if (flags['crypto-currency'] !== undefined) {
+        const cryptoCurrency = flags['crypto-currency'].trim();
+        if (!cryptoCurrency) {
+          print.error('--crypto-currency must not be empty');
+          process.exit(1);
+        }
+        updates.cryptoCurrency = cryptoCurrency.toUpperCase();
+      }
+
+      if (flags['due-date'] !== undefined) {
+        if (!isValidDate(flags['due-date'])) {
+          print.error('--due-date must be a valid date in YYYY-MM-DD format');
+          process.exit(1);
+        }
+        updates.dueDate = flags['due-date'];
+      }
+
+      if (flags.notes !== undefined) updates.notes = flags.notes;
+
+      const stringUpdates = [
+        ['client-id', 'clientId'],
+        ['wallet-id', 'walletId'],
+        ['merchant-wallet-address', 'merchantWalletAddress'],
+      ];
+      for (const [flag, field] of stringUpdates) {
+        if (flags[flag] === undefined) continue;
+        const value = flags[flag].trim();
+        if (!value) {
+          print.error('--' + flag + ' must not be empty');
+          process.exit(1);
+        }
+        updates[field] = value;
+      }
+
+      if (Object.keys(updates).length === 0) {
+        print.error('Provide at least one editable field for invoice update');
+        print.info('Example: coinpay invoice update <id> --amount 125 --notes "Updated scope"');
+        process.exit(1);
+      }
+
+      const current = await getInvoice(client, id);
+      if (current.status !== InvoiceStatus.DRAFT) {
+        throw new Error('Only draft invoices can be updated (current: ' +
+          (current.status || 'unknown') + ')');
+      }
+
+      const updated = await updateInvoice(client, id, updates);
+      assertInvoiceUpdatesApplied(updated, updates);
+
+      if (flags.json) {
+        print.json(updated);
+        break;
+      }
+
+      print.success('Draft invoice updated');
+      const routingFields = ['cryptoCurrency', 'merchantWalletAddress'];
+      if (routingFields.some((field) => updates[field] !== undefined)) {
+        print.info('Payment routing: ' + describeInvoiceRouting(current) +
+          ' => ' + describeInvoiceRouting(updated));
+      }
+      if (updates.walletId !== undefined) {
+        print.info('Wallet reference: ' + (current.walletId || 'unset') +
+          ' => ' + updated.walletId);
+      }
+      printInvoiceDetails(updated);
+      break;
+    }
+
+    case 'publish': {
+      rejectUnsupportedFlags(flags, ['yes']);
+      const id = requireSingleInvoiceId(args, 'publish');
+      const current = await getInvoice(client, id);
+      const existingShareUrl = getInvoiceShareUrl(id);
+
+      if (current.status === InvoiceStatus.SENT) {
+        if (!current.paymentAddress) {
+          throw new Error(
+            'Published invoice has no active payment address; refresh it in the web app'
+          );
+        }
+        if (flags.json) {
+          print.json({
+            ...current,
+            shareUrl: existingShareUrl,
+            emailAttempted: false,
+            idempotentReplay: true,
+          });
+          break;
+        }
+        print.success('Invoice is already published; no email sent');
+        printInvoiceDetails(current, { shareUrl: existingShareUrl });
+        break;
+      }
+
+      if (current.status !== InvoiceStatus.DRAFT) {
+        throw new Error(
+          'Only draft invoices can be published (current: ' + (current.status || 'unknown') + ')'
+        );
+      }
+      if (!current.cryptoCurrency) {
+        throw new Error('Set --crypto-currency before publishing this invoice');
+      }
+
+      const label = current.invoiceNumber || current.id;
+      const confirmed = await confirmInvoiceMutation(
+        flags,
+        'Publish ' +
+          label +
+          ' for ' +
+          current.amount +
+          ' ' +
+          (current.currency || '') +
+          ' using ' +
+          current.cryptoCurrency +
+          '? This creates live payment details but does not email the client.'
+      );
+      if (!confirmed) {
+        print.info('Aborted');
+        break;
+      }
+
+      const result = await publishInvoice(client, id);
+      const published = invoiceForOutput(result, id);
+      if (
+        result?.success === false ||
+        published.status !== InvoiceStatus.SENT ||
+        !published.paymentAddress
+      ) {
+        throw new Error('Invoice publish was not confirmed by the server');
+      }
+      const shareUrl =
+        typeof result?.paymentLink === 'string'
+          ? result.paymentLink
+          : getInvoiceShareUrl(published.id);
+
+      if (flags.json) {
+        print.json({
+          ...published,
+          shareUrl,
+          emailAttempted: false,
+          idempotentReplay: result?.idempotentReplay === true,
+        });
+        break;
+      }
+
+      print.success('Invoice published; no email sent');
+      printInvoiceDetails(published, { shareUrl });
+      break;
+    }
+
+    case 'send': {
+      rejectUnsupportedFlags(flags, ['yes']);
+      const id = requireSingleInvoiceId(args, 'send');
+      const current = await getInvoice(client, id);
+      const sendable = new Set([InvoiceStatus.DRAFT, InvoiceStatus.OVERDUE]);
+      if (!sendable.has(current.status)) {
+        throw new Error('Only draft or overdue invoices can be sent (current: ' +
+          (current.status || 'unknown') + ')');
+      }
+      if (!current.cryptoCurrency) {
+        throw new Error('Set --crypto-currency before sending this invoice');
+      }
+
+      const label = current.invoiceNumber || current.id;
+      const recipient = current.clientId ? 'client ' + current.clientId : 'the configured client';
+      const amount = current.amount + ' ' + (current.currency || '');
+      const resendWarning = current.status === InvoiceStatus.OVERDUE
+        ? ' This will issue new payment details and email the client again.'
+        : ' This will create payment details and email the client.';
+      const confirmed = await confirmInvoiceMutation(
+        flags,
+        'Send ' + label + ' to ' + recipient + ' for ' + amount +
+          ' using ' + current.cryptoCurrency + '?' + resendWarning
+      );
+      if (!confirmed) {
+        print.info('Aborted');
+        break;
+      }
+
+      const result = await sendInvoice(client, id);
+      let sent = invoiceForOutput(result, id);
+      const legacySuccess = result?.success === true &&
+        !Object.prototype.hasOwnProperty.call(result, 'invoice') &&
+        sent.status === undefined;
+
+      if (legacySuccess) {
+        sent = invoiceForOutput({
+          ...current,
+          ...result,
+          status: InvoiceStatus.SENT,
+        }, id);
+      } else if (result?.success === false || sent.status !== InvoiceStatus.SENT) {
+        throw new Error('Invoice send was not confirmed by the server');
+      }
+      const shareUrl = getInvoiceShareUrl(sent.id);
+
+      if (flags.json) {
+        const delivery = {};
+        for (const field of ['emailAccepted', 'emailTrackingSaved', 'warning', 'emailError']) {
+          if (Object.prototype.hasOwnProperty.call(result ?? {}, field)) {
+            delivery[field] = result[field];
+          }
+        }
+        print.json({ ...sent, shareUrl, ...delivery });
+        break;
+      }
+
+      if (result?.emailAccepted === false) {
+        print.warn('Invoice payment link created, but the email provider did not accept the message');
+      } else if (result?.emailAccepted === true) {
+        print.success('Invoice sent; email accepted by provider');
+      } else {
+        print.success('Invoice sent; email status was not reported by the server');
+      }
+      if (legacySuccess) {
+        print.warn('The server returned limited invoice details; run coinpay invoice get ' +
+          id + ' to refresh them.');
+      }
+      printInvoiceDetails(sent, { shareUrl });
+      break;
+    }
+
+    case 'delete': {
+      rejectUnsupportedFlags(flags, ['yes']);
+      const id = requireSingleInvoiceId(args, 'delete');
+      const current = await getInvoice(client, id);
+      if (current.status !== InvoiceStatus.DRAFT) {
+        throw new Error('Only draft invoices can be deleted (current: ' +
+          (current.status || 'unknown') + ')');
+      }
+
+      const label = current.invoiceNumber || current.id;
+      const confirmed = await confirmInvoiceMutation(
+        flags,
+        'Permanently delete draft invoice ' + label + ' for ' + current.amount +
+          ' ' + (current.currency || '') + '?'
+      );
+      if (!confirmed) {
+        print.info('Aborted');
+        break;
+      }
+
+      const result = await deleteInvoice(client, id);
+      if (result?.success === false) {
+        throw new Error('Invoice deletion was not confirmed by the server');
+      }
+
+      if (flags.json) {
+        print.json({ id, deleted: true });
+        break;
+      }
+      print.success('Draft invoice deleted: ' + id);
+      break;
+    }
+
+    default:
+      print.error('Unknown invoice command: ' + subcommand);
+      print.info('Available: create, list, get, update, publish, send, delete');
+      process.exit(1);
+  }
+}
+
+/**
+ * Token discovery commands
+ */
+async function handleTokens(subcommand, args, flags) {
+  const client = createClient();
+
+  switch (subcommand) {
+    case 'list': {
+      const businessId = flags['business-id'];
+      const activeOnly = flags['active-only'] === true || flags.active === true;
+      const result = await client.getTokens({ businessId, activeOnly });
+
+      if (flags.json) {
+        print.json(result);
+        break;
+      }
+
+      const tokens = result.tokens || [];
+      print.info(`Payment tokens (${tokens.length})`);
+      for (const token of tokens) {
+        const chain = token.chain ? ` on ${token.chain}` : '';
+        const source = token.wallet_source ? ` (${token.wallet_source})` : '';
+        console.log(`  ${colors.bright}${token.code}${colors.reset} ${token.ticker || token.symbol}${chain}${source}`);
       }
-      
-      const url = client.getPaymentQRUrl(paymentId);
-      print.info(`QR Code URL: ${url}`);
       break;
     }
-    
+
     default:
-      print.error(`Unknown payment command: ${subcommand}`);
-      showHelp();
+      print.error(`Unknown tokens command: ${subcommand}`);
+      print.info('Available: list');
   }
 }
 
@@ -645,18 +1477,43 @@ async function handleBusiness(subcommand, args, flags) {
   
   switch (subcommand) {
     case 'create': {
-      const { name, 'webhook-url': webhookUrl } = flags;
-      
-      if (!name) {
-        print.error('Required: --name');
+      const {
+        name,
+        category,
+        description,
+        'webhook-url': webhookUrl,
+        'webhook-secret': webhookSecret,
+      } = flags;
+
+      if (!name || !category) {
+        // The API has required a category since businesses started being
+        // classified on create, and this command had no way to send one -- so it
+        // failed with "Select a valid business category" and no route to fixing
+        // it. Naming the flag here is cheaper than reading the taxonomy.
+        print.error('Required: --name <name> --category <slug>');
+        print.info('Categories: coinpay business categories');
         return;
       }
-      
-      const business = await client.createBusiness({ name, webhookUrl });
+
+      const business = await client.createBusiness({
+        name,
+        category,
+        description,
+        webhookUrl,
+        webhookSecret,
+      });
       print.success('Business created');
       print.json(business);
       break;
     }
+
+    case 'categories': {
+      // Fetched rather than hardcoded: the taxonomy is server-side and a stale
+      // copy in the CLI is how "Select a valid business category" happens twice.
+      const result = await client.listBusinessCategories();
+      print.json(result);
+      break;
+    }
     
     case 'get': {
       const businessId = args[0];
@@ -1836,17 +2693,18 @@ async function handleAuth(subcommand, args, flags) {
         const client = new CoinPayClient({ apiKey: jwtToken, baseUrl: getBaseUrl() });
         const { getMe } = await import('../src/auth.js');
         const result = await getMe(client);
-        
+        const me = result?.merchant || result;
+
         print.success('Current merchant:');
-        print.info(`ID: ${result.id}`);
-        print.info(`Email: ${result.email}`);
-        if (result.name) {
-          print.info(`Name: ${result.name}`);
+        print.info(`ID: ${me.id}`);
+        print.info(`Email: ${me.email}`);
+        if (me.name) {
+          print.info(`Name: ${me.name}`);
         }
-        print.info(`Created: ${result.created_at}`);
-        
+        if (me.created_at) print.info(`Created: ${me.created_at}`);
+
         if (flags.json) {
-          print.json(result);
+          print.json(me);
         }
       } catch (error) {
         if (error.message.includes('401') || error.message.includes('403')) {
@@ -2013,15 +2871,28 @@ async function handleReputation(subcommand, args, flags) {
       const client = createClient();
 
       if (didSubcommand === 'claim') {
-        const { claimDid } = await import('../src/reputation.js');
-        const result = await claimDid(client);
+        const { claimDid, getMyDid } = await import('../src/reputation.js');
+
+        // Idempotent: a merchant can only hold one principal DID, so if one
+        // already exists just show it (exit 0) instead of erroring with
+        // "already has a principal DID". This lets automated setup (e.g.
+        // c0mpute worker onboarding) call `did claim` unconditionally.
+        let existing = null;
+        try {
+          existing = await getMyDid(client);
+        } catch {
+          existing = null; // no DID yet — fall through to claim
+        }
+
+        const result = existing?.did ? existing : await claimDid(client);
 
         if (result.did) {
-          print.success(`DID claimed: ${result.did}`);
+          print.success(`${existing?.did ? 'DID ready' : 'DID claimed'}: ${result.did}`);
           console.log(`  Public Key: ${result.public_key}`);
           console.log(`  Verified: ${result.verified}`);
         } else {
           print.error(result.error || 'Failed to claim DID');
+          process.exitCode = 1;
         }
 
         if (flags.json) print.json(result);
@@ -2061,6 +2932,31 @@ async function handleReputation(subcommand, args, flags) {
           print.info('No DID found. Run: coinpay reputation did claim');
         }
 
+        if (flags.json) print.json(result);
+      } else if (didSubcommand === 'setup') {
+        // Ensure the merchant has a payable DID, hands-free: use the existing
+        // one if there is one, otherwise create it automatically. No prompts —
+        // worker onboarding (c0mpute worker register) must never block.
+        const { getMyDid, claimDid } = await import('../src/reputation.js');
+
+        let existing = null;
+        try {
+          existing = await getMyDid(client);
+        } catch {
+          existing = null; // none yet — create below
+        }
+
+        const result = existing?.did ? existing : await claimDid(client);
+
+        if (result.did) {
+          print.success(`${existing?.did ? 'Using existing DID' : 'Created DID'}: ${result.did}`);
+          console.log(`  Public Key: ${result.public_key}`);
+          console.log(`  Verified: ${result.verified}`);
+        } else {
+          print.error(result.error || 'Failed to set up DID');
+          process.exitCode = 1;
+        }
+
         if (flags.json) print.json(result);
       } else {
         // Default: show current DID
@@ -2291,9 +3187,9 @@ async function handlePayout(subcommand, args, flags) {
 
   switch (subcommand) {
     case 'create': {
-      const amount = parseInt(flags.amount);
-      if (!amount || amount <= 0) {
-        print.error('--amount is required (in cents, e.g., 5000 for $50.00)');
+      const amount = parsePositiveInteger(flags.amount);
+      if (amount === null) {
+        print.error('--amount must be a positive integer in cents (e.g., 5000 for $50.00)');
         print.info('Example: coinpay payout create --amount 5000 --description "Weekly payout"');
         process.exit(1);
       }
@@ -2435,7 +3331,8 @@ async function handleCard(subcommand, args, flags) {
         case 'onboard': {
           if (!merchantId) {
             print.error('Merchant ID required');
-            print.info('Usage: coinpay card connect onboard <merchantId>');
+            print.info('Usage: coinpay card connect onboard <merchantId> --country <ISO-2> [--email <email>]');
+            print.info('Country is required on first onboarding (e.g. US, CA, GB, AU, DE) and is locked once the Stripe account is created.');
             return;
           }
 
@@ -2559,15 +3456,740 @@ async function handleCard(subcommand, args, flags) {
 /**
  * Main entry point
  */
+// Top-level commands offered by the interactive menu (shown when `coinpay` is
+// run with no arguments in a TTY). Self-manage commands are intentionally omitted.
+const MENU_COMMANDS = [
+  ['login', 'Log in headlessly — approve in a browser on any device'],
+  ['whoami', 'Show the signed-in merchant'],
+  ['logout', 'Sign out on this device'],
+  ['config', 'API key & endpoint (set-key, set-url, show)'],
+  ['auth', 'Merchant account (register, login, me)'],
+  ['finances', 'Live money dashboard (earnings, cards, bank feeds, ledger)'],
+  ['payment', 'Payments (create, get, list, qr)'],
+  ['invoice', 'Invoices (create, list, get, update, publish, send, delete)'],
+  ['tokens', 'List checkout tokens'],
+  ['business', 'Businesses (create, get, list, update)'],
+  ['rates', 'Exchange rates (get, list)'],
+  ['wallet', 'Local encrypted wallet (create, import, balance, send, history…)'],
+  ['swap', 'Cross-chain swaps'],
+  ['escrow', 'Escrow & series operations'],
+  ['ln', 'Lightning wallet'],
+  ['webhook', 'Webhook management'],
+  ['payout', 'Payouts'],
+  ['card', 'Card payments & issuing'],
+  ['reputation', 'DID, credentials, receipts, issuer'],
+  ['x402', 'x402 protocol operations'],
+  ['oauth', 'OAuth operations'],
+];
+
+// Subcommands per command group (name → [[subcommand, description], …]).
+const SUBCOMMANDS = {
+  config: [['set-key', 'Set your API key'], ['set-url', 'Set custom API URL'], ['show', 'Show current configuration']],
+  auth: [['register', 'Register new merchant account'], ['login', 'Login to merchant account'], ['me', 'Show current merchant info']],
+  finances: [['tui', 'Live dashboard (default)'], ['summary', 'Headline numbers as text'], ['position', 'Debt vs income, credits vs debits'], ['accounts', 'Bank & card accounts'], ['ledger', 'Bank/card transactions'], ['connections', 'Linked institutions'], ['sync', 'Pull fresh bank data']],
+  payment: [['create', 'Create a new payment'], ['get', 'Get payment details <id>'], ['list', 'List payments'], ['qr', 'Get payment QR code <id>']],
+  invoice: [['create', 'Create a draft invoice'], ['list', 'List invoices'], ['get', 'Get invoice details <id>'], ['update', 'Update a draft invoice <id>'], ['publish', 'Publish an invoice <id>'], ['send', 'Send an invoice <id>'], ['delete', 'Delete a draft invoice <id>']],
+  tokens: [['list', 'List checkout tokens']],
+  business: [['create', 'Create a new business'], ['get', 'Get business details <id>'], ['list', 'List businesses'], ['update', 'Update business <id>']],
+  rates: [['get', 'Get exchange rate <crypto>'], ['list', 'Get all exchange rates']],
+  wallet: [['create', 'Create a new wallet'], ['import', 'Import wallet <mnemonic>'], ['unlock', 'Decrypt wallet and show info'], ['info', 'Show wallet info'], ['addresses', 'List all addresses'], ['derive', 'Derive new address <chain>'], ['derive-missing', 'Derive missing chains'], ['balance', 'Get balance(s) [chain]'], ['send', 'Send a transaction'], ['history', 'Transaction history'], ['backup', 'Export encrypted backup'], ['delete', 'Delete local wallet file']],
+  swap: [['coins', 'List supported coins'], ['quote', 'Get swap quote'], ['create', 'Create swap transaction'], ['status', 'Check swap status <swap-id>'], ['history', 'Swap history']],
+  escrow: [['create', 'Create a new escrow'], ['get', 'Get escrow status <id>'], ['list', 'List escrows'], ['release', 'Release funds <id>'], ['refund', 'Refund funds <id>'], ['dispute', 'Open a dispute <id>'], ['events', 'Get escrow audit log <id>'], ['auth', 'Authenticate with escrow token <id>'], ['series', 'Series operations']],
+  ln: [['enable', 'Enable Lightning wallet'], ['address', 'Lightning address'], ['invoice', 'Create an invoice'], ['send', 'Send a payment'], ['balance', 'Lightning balance'], ['payments', 'List payments']],
+  webhook: [['logs', 'Get webhook logs <business-id>'], ['test', 'Send test webhook <business-id>']],
+  payout: [['create', 'Create a payout'], ['list', 'List payouts'], ['get', 'Get payout details <id>']],
+  card: [['create', 'Create a card payment'], ['get', 'Get card payment status <id>'], ['list', 'List card payments'], ['connect', 'Stripe onboarding / status'], ['escrow', 'Release / refund card escrow']],
+  reputation: [['submit', 'Submit a task receipt'], ['query', 'Query agent reputation <did>'], ['credential', 'Get credential details <id>'], ['credentials', 'List credentials [did]'], ['receipts', 'List task receipts [did]'], ['badge', 'Reputation badge URL [did]'], ['verify', 'Verify a credential <id>'], ['revocations', 'List revoked credentials'], ['did', 'DID claim / me'], ['issuer', 'Issuer register / list / rotate']],
+  x402: [
+    ['status', 'x402 status'],
+    ['test', 'x402 test'],
+    ['pay', 'pay for a URL, approving in your browser'],
+  ],
+  oauth: [['list', 'List OAuth clients'], ['create', 'Create an OAuth client'], ['get', 'Get client details <id>'], ['delete', 'Delete a client <id>']],
+};
+
+function askLine(prompt) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => { rl.close(); resolve(answer); });
+  });
+}
+
+// Re-invoke this CLI as a child so the real parser/handlers run unchanged.
+function runChild(argv) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [process.argv[1], ...argv], { stdio: 'inherit' });
+    child.on('exit', () => resolve());
+    child.on('error', () => resolve());
+  });
+}
+
+// An authenticated client (session token or API key) for the guided menu flows
+// that need to fetch your data. Returns null if not authenticated.
+function authedClientOrNull() {
+  const apiKey = getApiKey() || loadConfig().jwtToken;
+  return apiKey ? new CoinPayClient({ apiKey, baseUrl: getBaseUrl() }) : null;
+}
+
+function unwrapList(res) {
+  const list = res?.data ?? res?.businesses ?? res?.payments ?? res;
+  return Array.isArray(list) ? list : [];
+}
+
+// Fetch the merchant's businesses and let them pick one; returns a business id.
+async function pickBusiness(io) {
+  const client = authedClientOrNull();
+  if (!client) { print.error('Not signed in — run `coinpay login` first.'); return null; }
+  let list;
+  try { list = unwrapList(await client.listBusinesses()); }
+  catch (e) { print.error('Could not fetch businesses: ' + e.message); return null; }
+  if (!list.length) { print.info('No businesses yet — create one first (business → create).'); return null; }
+  if (list.length === 1) return list[0].id; // only one — no need to ask
+  return io.select({
+    message: 'Which business?',
+    choices: list.map((b) => ({ name: `${b.name || b.id}  ${colors.reset}(${b.id})`, value: b.id })),
+    pageSize: 15,
+  });
+}
+
+// Fetch payments for a business and let them pick one; returns a payment id.
+async function pickPayment(io, businessId) {
+  const client = authedClientOrNull();
+  if (!client) return null;
+  let list;
+  try { list = unwrapList(await client.listPayments({ businessId })); }
+  catch (e) { print.error('Could not fetch payments: ' + e.message); return null; }
+  if (!list.length) { print.info('No payments for that business yet.'); return null; }
+  return io.select({
+    message: 'Which payment?',
+    choices: list.map((p) => ({
+      name: `${p.id}  ${[p.amount, p.currency, p.status].filter(Boolean).join(' ')}`.trim(),
+      value: p.id,
+    })),
+    pageSize: 15,
+  });
+}
+
+// Guided interactive flows keyed by "command subcommand": fetch your data + ask
+// for inputs, then return the argv to run (or null to abort). Used by the menu.
+const GUIDED = {
+  'business get': async (io) => {
+    const id = await pickBusiness(io);
+    return id ? ['business', 'get', id] : null;
+  },
+  'business update': async (io) => {
+    const id = await pickBusiness(io);
+    if (!id) return null;
+    const name = (await io.input({ message: 'New name (blank to keep):' })).trim();
+    const url = (await io.input({ message: 'New webhook URL (blank to keep):' })).trim();
+    const argv = ['business', 'update', id];
+    if (name) argv.push('--name', name);
+    if (url) argv.push('--webhook-url', url);
+    if (argv.length === 3) { print.info('Nothing to update.'); return null; }
+    return argv;
+  },
+  'business create': async (io) => {
+    const name = (await io.input({ message: 'Business name:' })).trim();
+    if (!name) { print.error('Name is required.'); return null; }
+    const url = (await io.input({ message: 'Webhook URL (optional):' })).trim();
+    const argv = ['business', 'create', '--name', name];
+    if (url) argv.push('--webhook-url', url);
+    return argv;
+  },
+  'payment create': async (io) => {
+    const businessId = await pickBusiness(io);
+    if (!businessId) return null;
+    const amount = (await io.input({ message: 'Amount:' })).trim();
+    if (!amount) { print.error('Amount is required.'); return null; }
+    const currency = (await io.input({ message: 'Currency:', default: 'USD' })).trim() || 'USD';
+    const blockchain = await io.select({
+      message: 'Blockchain:',
+      choices: ['BTC', 'ETH', 'SOL', 'POL', 'BCH'].map((c) => ({ name: c, value: c })),
+    });
+    const description = (await io.input({ message: 'Description (optional):' })).trim();
+    const argv = ['payment', 'create', '--business-id', businessId, '--amount', amount, '--currency', currency, '--blockchain', blockchain];
+    if (description) argv.push('--description', description);
+    return argv;
+  },
+  'payment get': async (io) => {
+    const b = await pickBusiness(io);
+    if (!b) return null;
+    const p = await pickPayment(io, b);
+    return p ? ['payment', 'get', p] : null;
+  },
+  'payment qr': async (io) => {
+    const b = await pickBusiness(io);
+    if (!b) return null;
+    const p = await pickPayment(io, b);
+    return p ? ['payment', 'qr', p] : null;
+  },
+  'payment list': async (io) => {
+    const b = await pickBusiness(io);
+    return b ? ['payment', 'list', '--business-id', b] : null;
+  },
+};
+
+// Fallback menu (used only if @inquirer/prompts can't be loaded): a numbered
+// list, then a prompt for the subcommand + args.
+async function numberedMenu() {
+  console.log('');
+  console.log(`  ${colors.bright}${colors.cyan}coinpay${colors.reset}  ·  interactive menu (v${VERSION})`);
+  for (;;) {
+    console.log('');
+    MENU_COMMANDS.forEach(([name, desc], i) => {
+      const num = colors.yellow + String(i + 1).padStart(2) + colors.reset;
+      console.log(`  ${num}  ${colors.bright}${name.padEnd(11)}${colors.reset}${desc}`);
+    });
+    console.log('');
+    const answer = (await askLine('  pick a number, type a command (with args), or q to quit: ')).trim();
+    if (!answer || answer === 'q' || answer === 'quit' || answer === 'exit') break;
+
+    let argv;
+    if (/^\d+$/.test(answer)) {
+      const idx = parseInt(answer, 10) - 1;
+      if (idx < 0 || idx >= MENU_COMMANDS.length) { print.error('  invalid choice'); continue; }
+      const name = MENU_COMMANDS[idx][0];
+      const hint = (SUBCOMMANDS[name] || []).map((s) => s[0]).join(', ');
+      const rest = (await askLine(
+        `  coinpay ${colors.bright}${name}${colors.reset} ▸ subcommand + args${hint ? ` (${hint})` : ''} — Enter to list: `
+      )).trim();
+      argv = [name, ...(rest ? rest.split(/\s+/) : [])];
+    } else {
+      argv = answer.split(/\s+/);
+    }
+    console.log('');
+    await runChild(argv);
+  }
+}
+
+// Arrow-key drill-down menu (parity with the ugig CLI): pick a command, pick a
+// subcommand, fill in args, run — looping until you quit. Falls back to the
+// numbered menu if @inquirer/prompts isn't installed.
+async function runInteractiveMenu() {
+  let select, input;
+  try { ({ select, input } = await import('@inquirer/prompts')); }
+  catch { return numberedMenu(); }
+
+  const BACK = '\x00back';
+  const TYPE = '\x00type';
+  const splitArgs = (s) => (s ? s.trim().split(/\s+/).filter(Boolean) : []);
+
+  // Who's signed in (refreshed after login/logout). Shown in the menu header.
+  let me = await fetchMe();
+
+  for (;;) {
+    let cmd;
+    try {
+      cmd = await select({
+        message: `coinpay — ${me ? `signed in as ${me.email}` : 'not signed in (pick login)'} — pick a command:`,
+        choices: MENU_COMMANDS.map(([name, desc]) => ({ name: `${name.padEnd(11)} ${desc}`, value: name })),
+        pageSize: 20,
+      });
+    } catch { break; } // Ctrl-C / ESC quits
+
+    const subs = SUBCOMMANDS[cmd] || [];
+    let argv;
+    if (subs.length) {
+      let sub;
+      try {
+        sub = await select({
+          message: `coinpay ${cmd} — pick a subcommand:`,
+          choices: [
+            ...subs.map(([n, d]) => ({ name: `${n.padEnd(14)} ${d || ''}`.trimEnd(), value: n })),
+            { name: '✎ type subcommand + args…', value: TYPE },
+            { name: '↩ back', value: BACK },
+          ],
+          pageSize: 20,
+        });
+      } catch { continue; }
+      if (sub === BACK) continue;
+      if (sub === TYPE) {
+        let line; try { line = await input({ message: `coinpay ${cmd}` }); } catch { continue; }
+        argv = [cmd, ...splitArgs(line)];
+      } else if (GUIDED[`${cmd} ${sub}`]) {
+        // Guided flow: fetch your data + ask for the inputs, then run.
+        let g; try { g = await GUIDED[`${cmd} ${sub}`]({ select, input }); } catch { continue; }
+        if (!g) continue;
+        argv = g;
+      } else {
+        let extra; try { extra = await input({ message: `args/flags for 'coinpay ${cmd} ${sub}' (optional):` }); } catch { continue; }
+        argv = [cmd, sub, ...splitArgs(extra)];
+      }
+    } else {
+      let line; try { line = await input({ message: `coinpay ${cmd}` }); } catch { continue; }
+      argv = [cmd, ...splitArgs(line)];
+    }
+    console.log('');
+    await runChild(argv);
+    console.log('');
+    // login/logout change who's signed in — refresh the header.
+    if (argv[0] === 'login' || argv[0] === 'logout') me = await fetchMe();
+  }
+}
+
+// Headless login: ask the server for a device code, show a URL to approve on any
+// device, and poll until a merchant session token is minted and stored. No
+// password on this machine — works over SSH / on a server.
+async function handleLogin() {
+  const cfg = loadConfig();
+  const base = (cfg.baseUrl || 'https://coinpayportal.com/api').replace(/\/$/, '');
+
+  let start;
+  try {
+    const res = await fetch(`${base}/cli-auth/start`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ client_name: hostname() }),
+    });
+    if (!res.ok) throw new Error(`server returned ${res.status}`);
+    start = await res.json();
+  } catch (err) {
+    print.error(`Couldn't start login: ${err.message}`);
+    process.exit(1);
+  }
+
+  // G-1.2-10: there is no pre-filled approval link any more. A link that filled
+  // in the code turned a phishing message into one-click account takeover —
+  // anyone could start a device authorization and send the resulting link to a
+  // signed-in merchant. Entering the code by hand is what ties the approval to
+  // a terminal the person is actually sitting at.
+  print.info('');
+  console.log('  To log in, open this URL on any device (e.g. your desktop):');
+  console.log('');
+  console.log('    ' + colors.cyan + start.verification_uri + colors.reset);
+  console.log('');
+  console.log('  and enter this code: ' + colors.bright + start.user_code + colors.reset);
+  console.log('');
+  console.log(colors.yellow + '  Only enter a code your own terminal printed.' + colors.reset);
+  console.log('');
+  print.info('Waiting for approval… (Ctrl-C to cancel)');
+
+  const deadline = Date.now() + (start.expires_in || 600) * 1000;
+  const intervalMs = Math.max(1, start.interval || 5) * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, intervalMs));
+    let data = {};
+    try {
+      const res = await fetch(`${base}/cli-auth/poll`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ device_code: start.device_code }),
+      });
+      if (res.status === 202) continue; // authorization_pending
+      data = await res.json().catch(() => ({}));
+    } catch {
+      continue; // transient network error — keep polling
+    }
+    if (data.status === 'complete' && data.token) {
+      cfg.jwtToken = data.token;
+      saveConfig(cfg);
+      const me = await fetchMe();
+      print.success(me ? `Logged in as ${meLabel(me)}` : 'Logged in! Session saved to ' + CONFIG_FILE);
+      return;
+    }
+    if (data.status === 'denied') { print.error('Request denied.'); process.exit(1); }
+    if (data.status === 'expired') { print.error('Login request expired — run `coinpay login` again.'); process.exit(1); }
+  }
+  print.error('Timed out waiting for approval.');
+  process.exit(1);
+}
+
+function handleLogout() {
+  const cfg = loadConfig();
+  delete cfg.jwtToken;
+  saveConfig(cfg);
+  print.success('Logged out — session removed from ' + CONFIG_FILE);
+}
+
+// Fetch the signed-in merchant (via the stored session token), or null if not
+// logged in / the token is stale. Used to greet after login, for `whoami`, and
+// to show who you are in the interactive menu.
+async function fetchMe() {
+  const cfg = loadConfig();
+  if (!cfg.jwtToken) return null;
+  try {
+    const client = new CoinPayClient({ apiKey: cfg.jwtToken, baseUrl: getBaseUrl() });
+    const { getMe } = await import('../src/auth.js');
+    const result = await getMe(client);
+    return result?.merchant || result || null;
+  } catch {
+    return null;
+  }
+}
+
+function meLabel(me) {
+  if (!me) return null;
+  return me.name ? `${me.name} <${me.email}>` : me.email;
+}
+
+async function handleWhoami(flags) {
+  const me = await fetchMe();
+  if (!me) {
+    print.error('Not signed in. Run: coinpay login');
+    process.exitCode = 1;
+    return;
+  }
+  print.success(`Signed in as ${meLabel(me)}`);
+  if (me.id) print.info(`Merchant ID: ${me.id}`);
+  if (flags?.json) print.json(me);
+}
+
+
+/**
+ * Finances — the merchant's money in one place (bank feeds via SimpleFIN or
+ * Plaid, crypto and card earnings, commission paid, refunds, invoices, escrow).
+ *
+ * Needs the merchant session from `coinpay login`; the bank-data routes
+ * refuse business API keys on purpose.
+ */
+function financesClient() {
+  const cfg = loadConfig();
+  const token = process.env.COINPAY_SESSION_TOKEN || cfg.jwtToken;
+  if (!token) {
+    print.error('Finances need your merchant session, not an API key. Run: coinpay login');
+    process.exit(1);
+  }
+  return { client: new CoinPayClient({ apiKey: token, baseUrl: getBaseUrl(), timeout: 120000 }), token, baseUrl: getBaseUrl() };
+}
+
+function pad(value, width, align = 'left') {
+  const s = String(value ?? '');
+  if (s.length >= width) return s;
+  return align === 'right' ? s.padStart(width) : s.padEnd(width);
+}
+
+function printTable(rows, columns) {
+  if (!rows.length) return;
+  const widths = columns.map((c) => Math.max(c.title.length, ...rows.map((r) => String(c.render(r) ?? '').length)));
+  console.log(colors.bright + columns.map((c, i) => pad(c.title, widths[i], c.align)).join('  ') + colors.reset);
+  for (const r of rows) {
+    console.log(columns.map((c, i) => pad(c.render(r) ?? '', widths[i], c.align)).join('  '));
+  }
+}
+
+function printFinanceSummary(snapshot, fmt) {
+  const { money, ago } = fmt;
+  const e = snapshot.earnings;
+  const b = snapshot.bank;
+  const cur = b.currency || 'USD';
+  const win = `${snapshot.windowDays}d`;
+  const line = (label, value, color = '') => console.log(`  ${pad(label, 26)} ${color}${value}${colors.reset}`);
+
+  console.log(`\n${colors.bright}Earnings · ${win}${colors.reset}${snapshot.plan ? colors.cyan + '  (' + snapshot.plan.commission_percent + ' plan)' + colors.reset : ''}`);
+  line('Gross volume', money(e.grossVolumeUsd), colors.bright);
+  line('  crypto', money(e.cryptoVolumeUsd));
+  line('  cards', money(e.cardVolumeUsd));
+  line('Commission paid', `-${money(e.commissionUsd)}`, colors.yellow);
+  line('Card processor fees', `-${money(e.stripeFeesUsd)}`, colors.yellow);
+  line('Refunds', `-${money(e.refundsUsd)}`, e.refundsUsd > 0 ? colors.red : '');
+  line('Net earnings', money(e.netUsd), e.netUsd >= 0 ? colors.green : colors.red);
+  line('Paid transactions', `${e.transactions} (${e.failed} failed, ${e.failureRate}%)`);
+
+  console.log(`\n${colors.bright}Bank & cards${colors.reset}`);
+  if (!b.connections.length) {
+    console.log('  Nothing linked. Connect a bank at ' + new URL('/finances', getBaseUrl()).toString());
+  } else {
+    line('Cash & assets', money(b.assets, cur), colors.green);
+    line('Cards & loans owed', money(b.liabilities, cur), colors.red);
+    line('Net position', money(b.net, cur), b.net >= 0 ? colors.green : colors.red);
+    line(`Cash in · ${win}`, money(b.cashflow.moneyIn, cur), colors.green);
+    line(`Cash out · ${win}`, money(b.cashflow.moneyOut, cur), colors.red);
+    line('Cashflow net', money(b.cashflow.net, cur), b.cashflow.net >= 0 ? colors.green : colors.red);
+    line('Accounts', `${b.accountCount} (${b.creditCards.length} credit cards)`);
+    line('Last bank sync', `${ago(b.connections[0]?.last_synced_at)} · ${b.connections[0]?.last_sync_status || '—'}`);
+  }
+
+  console.log(`\n${colors.bright}Pipeline${colors.reset}`);
+  const inv = snapshot.invoices;
+  const esc = snapshot.escrow;
+  line('Invoices outstanding', `${money(inv.totals.outstanding)} (${inv.counts.outstanding})`, colors.yellow);
+  line('Invoices overdue', `${money(inv.totals.overdue)} (${inv.counts.overdue})`, inv.counts.overdue ? colors.red : '');
+  line(`Invoices paid · ${win}`, `${money(inv.totals.paid)} (${inv.counts.paid})`, colors.green);
+  line('Escrow held', `${money(esc.heldUsd)} (${esc.held})`, colors.cyan);
+  line(`Escrow released · ${win}`, `${money(esc.releasedUsd)} (${esc.released})`);
+  line(`Escrow refunded · ${win}`, `${money(esc.refundedUsd)} (${esc.refunded})`, esc.refunded ? colors.red : '');
+  line('Card payouts pending', money(snapshot.payout.pendingUsd));
+  line(`Card payouts paid · ${win}`, money(snapshot.payout.paidUsd), colors.green);
+
+  if (snapshot.position) printPosition(snapshot.position, fmt, { heading: true });
+
+  const failed = Object.keys(snapshot.errors);
+  if (failed.length) {
+    console.log('');
+    print.warn(`Unavailable: ${failed.map((k) => `${k} (${snapshot.errors[k]})`).join('; ')}`);
+  }
+  console.log('');
+}
+
+/**
+ * Debt against income as text.
+ *
+ * Shared by `finances summary` (as one more section) and `finances position`
+ * (on its own, with the account and recurring detail the summary omits).
+ */
+function printPosition(position, fmt, { heading = false, detail = false } = {}) {
+  const { money, pct } = fmt;
+  const cur = position.currency || 'USD';
+  const look = `${Math.round(position.observedDays ?? position.lookbackDays)}d`;
+  const line = (label, value, color = '') => console.log(`  ${pad(label, 26)} ${color}${value}${colors.reset}`);
+
+  if (heading) console.log(`\n${colors.bright}Debt & income · ${look}${colors.reset}${colors.cyan}  (${position.monthsObserved} months)${colors.reset}`);
+
+  const inc = position.income;
+  const spend = position.spending;
+  const debt = position.debt;
+  const r = position.ratios;
+
+  line('Income', `${money(inc.total, cur)}  (${money(inc.perMonth, cur)}/mo)`, colors.green);
+  line('Spending', `${money(spend.total, cur)}  (${money(spend.perMonth, cur)}/mo)`, colors.red);
+  line('Net', `${money(position.net.total, cur)}  (${money(position.net.perMonth, cur)}/mo)`, position.net.total >= 0 ? colors.green : colors.red);
+  line('Kept of income', pct(position.net.savingsRate, 1));
+  line('Gross credits / debits', `${money(inc.grossCredits, cur)} / ${money(spend.grossDebits, cur)}`);
+  line('Total owed', money(debt.total, cur), colors.red);
+  line('  revolving / instalment', `${money(debt.revolving, cur)} / ${money(debt.instalment, cur)}`);
+  line('Debt paid per month', money(debt.servicePerMonth, cur), colors.green);
+  line('Fixed bills per month', money(position.recurring.monthlyTotal, cur), colors.yellow);
+  line('Clear in', debt.payoffMonths === null ? 'never at this rate' : `${debt.payoffMonths} months (${debt.payoffDate ? debt.payoffDate.slice(0, 10) : '—'})`, debt.payoffMonths === null ? colors.red : '');
+  line('Debt to income', r.debtToIncome === null ? '—' : `${r.debtToIncome.toFixed(2)}x`, (r.debtToIncome ?? 0) > 1 ? colors.red : colors.green);
+  line('Debt service ratio', pct(r.debtServiceRatio, 1), (r.debtServiceRatio ?? 0) > 0.36 ? colors.red : colors.green);
+  line('Months of cover', r.monthsOfCover === null ? '—' : r.monthsOfCover.toFixed(1));
+  line('Card utilisation', pct(r.creditUtilisation, 0));
+
+  for (const sc of position.scopes) {
+    line(`${sc.scope} (${sc.accounts} acct)`, `${money(sc.income, cur)} in · ${money(sc.spending, cur)} out · owes ${money(sc.debt, cur)}`);
+  }
+
+  if (position.confidence.noLiabilityAccounts) {
+    console.log('');
+    print.warn('No card or loan account is linked, so the debt figures are blind.');
+  }
+  if (position.confidence.uncategorisedShare > 0.25) {
+    console.log('');
+    print.warn(`${pct(position.confidence.uncategorisedShare, 0)} of transactions are uncategorised — the income/spending split is rough.`);
+  }
+
+  if (!detail) return;
+
+  if (position.months.length) {
+    console.log(`\n${colors.bright}Month by month${colors.reset}`);
+    printTable(position.months, [
+      { title: 'Month', align: 'left', render: (m) => (m.partial ? `${m.month} *` : m.month) },
+      { title: 'Income', align: 'right', render: (m) => money(m.income, cur) },
+      { title: 'Spending', align: 'right', render: (m) => money(m.spending, cur) },
+      { title: 'Net', align: 'right', render: (m) => money(m.net, cur) },
+      { title: 'Debt paid', align: 'right', render: (m) => money(m.debtService, cur) },
+      { title: 'Rows', align: 'right', render: (m) => String(m.transactions) },
+    ]);
+    console.log(`  ${colors.cyan}* partial month${colors.reset}`);
+  }
+
+  if (debt.accounts.length) {
+    console.log(`\n${colors.bright}Owed by account${colors.reset}`);
+    printTable(debt.accounts, [
+      { title: 'Institution', align: 'left', render: (d) => d.org || '—' },
+      { title: 'Account', align: 'left', render: (d) => d.name },
+      { title: 'Kind', align: 'left', render: (d) => d.kind },
+      { title: 'Side', align: 'left', render: (d) => d.scope },
+      { title: 'Owed', align: 'right', render: (d) => money(d.owed, cur) },
+      { title: 'Share', align: 'right', render: (d) => pct(d.share, 0) },
+      { title: `Paid ${look}`, align: 'right', render: (d) => money(d.paid, cur) },
+      { title: 'Clear in', align: 'right', render: (d) => (d.payoffMonths === null ? 'never' : `${d.payoffMonths} mo`) },
+    ]);
+  }
+
+  if (position.recurring.charges.length) {
+    console.log(`\n${colors.bright}Recurring${colors.reset}  ${colors.cyan}${money(position.recurring.monthlyTotal, cur)}/mo, of which ${money(position.recurring.monthlyDebtService, cur)} is debt${colors.reset}`);
+    printTable(position.recurring.charges, [
+      { title: 'Payee', align: 'left', render: (c) => c.payee },
+      { title: 'Amount', align: 'right', render: (c) => money(c.amount, cur) },
+      { title: 'Every', align: 'left', render: (c) => c.cadence },
+      { title: 'Seen', align: 'right', render: (c) => String(c.occurrences) },
+      { title: 'Last', align: 'left', render: (c) => c.lastSeen.slice(0, 10) },
+      { title: 'Next', align: 'left', render: (c) => c.nextExpected.slice(0, 10) },
+      { title: 'Per month', align: 'right', render: (c) => money(c.monthlyEquivalent, cur) },
+      { title: 'Kind', align: 'left', render: (c) => (c.isDebtService ? 'debt' : 'bill') },
+    ]);
+  }
+  console.log('');
+}
+
+async function handleFinances(subcommand, args, flags) {
+  const parsedDays = Number.parseInt(String(flags.days ?? flags.window ?? ''), 10);
+  const days = Number.isFinite(parsedDays) && parsedDays > 0 ? parsedDays : 30;
+  const fin = await import('../src/finances.js');
+
+  switch (subcommand || 'tui') {
+    case 'tui':
+    case 'dashboard':
+    case 'watch': {
+      const { client, token, baseUrl } = financesClient();
+      const wantsText = flags.plain || flags.json || !process.stdout.isTTY || !process.stdin.isTTY;
+      if (wantsText) {
+        const snapshot = await fin.collectFinanceSnapshot(client, { days, businessId: flags['business-id'] });
+        if (flags.json) { print.json(snapshot); return; }
+        const fmt = await import('../src/finances-tui.js');
+        printFinanceSummary(snapshot, fmt);
+        return;
+      }
+      const parsedInterval = Number.parseInt(String(flags.interval ?? ''), 10);
+      const { runFinancesTui } = await import('../src/finances-tui.js');
+      await runFinancesTui({
+        client,
+        baseUrl,
+        token: flags['no-stream'] ? null : token,
+        days,
+        interval: Number.isFinite(parsedInterval) ? parsedInterval : 30,
+        businessId: flags['business-id'],
+        theme: flags.theme,
+      });
+      return;
+    }
+
+    case 'summary': {
+      const { client } = financesClient();
+      const snapshot = await fin.collectFinanceSnapshot(client, { days, businessId: flags['business-id'] });
+      if (flags.json) { print.json(snapshot); return; }
+      const fmt = await import('../src/finances-tui.js');
+      printFinanceSummary(snapshot, fmt);
+      return;
+    }
+
+    case 'position':
+    case 'debt':
+    case 'income': {
+      // Reads the summary route alone: everything on this screen comes from
+      // there, so there is no reason to fan out to eleven sources for it.
+      const { client } = financesClient();
+      const summary = await fin.getFinanceSummary(client, { days, includeHidden: Boolean(flags.hidden) });
+      const position = summary?.position;
+      if (!position) {
+        print.error('This CoinPay server does not report a debt-and-income position yet.');
+        process.exit(1);
+      }
+      if (flags.json) { print.json(position); return; }
+      const fmt = await import('../src/finances-tui.js');
+      console.log('');
+      printPosition(position, fmt, { heading: true, detail: true });
+      return;
+    }
+
+    case 'accounts': {
+      const { client } = financesClient();
+      const accounts = await fin.listFinanceAccounts(client, { includeHidden: Boolean(flags.hidden) });
+      if (flags.json) { print.json({ accounts }); return; }
+      if (!accounts.length) { print.info('No linked accounts. Connect a bank at ' + new URL('/finances', getBaseUrl()).toString()); return; }
+      const { money, shortDate } = await import('../src/finances-tui.js');
+      console.log('');
+      printTable(accounts, [
+        { title: 'Institution', render: (a) => a.org_name || '—' },
+        { title: 'Account', render: (a) => a.name },
+        { title: 'Kind', render: (a) => a.effective_kind || a.kind },
+        { title: 'Balance', align: 'right', render: (a) => money(a.display_balance ?? a.balance ?? 0, a.currency || 'USD') },
+        { title: 'Available', align: 'right', render: (a) => (a.available_balance == null ? '—' : money(a.available_balance, a.currency || 'USD')) },
+        { title: 'As of', render: (a) => shortDate(a.balance_date) },
+        { title: 'Id', render: (a) => a.id },
+      ]);
+      console.log('');
+      return;
+    }
+
+    case 'ledger':
+    case 'transactions': {
+      const { client } = financesClient();
+      const parsedLimit = Number.parseInt(String(flags.limit ?? ''), 10);
+      const page = await fin.listFinanceTransactions(client, {
+        limit: Number.isFinite(parsedLimit) ? parsedLimit : 50,
+        offset: Number.parseInt(String(flags.offset ?? '0'), 10) || 0,
+        search: flags.search,
+        category: flags.category,
+        accountId: flags.account,
+        startDate: flags.start || flags.since,
+        endDate: flags.end || flags.until,
+        includePending: !flags['no-pending'],
+      });
+      if (flags.json) { print.json(page); return; }
+      if (!page.rows?.length) { print.info('No transactions match.'); return; }
+      const { money, shortDate } = await import('../src/finances-tui.js');
+      console.log('');
+      printTable(page.rows, [
+        { title: 'Date', render: (r) => shortDate(r.transacted_at || r.posted) },
+        { title: 'Account', render: (r) => `${r.org_name ? r.org_name.split(' ')[0] + ' ' : ''}${r.account_name}` },
+        { title: 'Payee / description', render: (r) => (r.payee || r.description || r.memo || '—').slice(0, 40) },
+        { title: 'Category', render: (r) => r.category || '—' },
+        { title: 'Amount', align: 'right', render: (r) => money(r.amount, r.currency || 'USD') },
+        { title: '', render: (r) => (r.pending ? 'pending' : '') },
+      ]);
+      console.log(`\n${page.rows.length} of ${page.total}` + (page.total > page.offset + page.rows.length ? `  (--offset ${page.offset + page.rows.length} for more)` : ''));
+      console.log('');
+      return;
+    }
+
+    case 'connections': {
+      const { client } = financesClient();
+      const data = await fin.listFinanceConnections(client);
+      if (flags.json) { print.json(data); return; }
+      const list = data.connections || [];
+      if (!list.length) {
+        print.info('No bank connections. Link one at ' + new URL('/finances', getBaseUrl()).toString() + (data.plaidEnabled ? ' (Plaid or SimpleFIN)' : ' (SimpleFIN)'));
+        return;
+      }
+      const { ago } = await import('../src/finances-tui.js');
+      console.log('');
+      for (const c of list) {
+        console.log(`${colors.bright}${c.label || c.id}${colors.reset}  ${colors.cyan}${c.provider}${colors.reset}  ${c.is_active ? colors.green + 'active' : colors.yellow + 'inactive'}${colors.reset}`);
+        console.log(`  id          ${c.id}`);
+        console.log(`  last sync   ${ago(c.last_synced_at)} · ${c.last_sync_status || '—'} · ${c.last_sync_accounts ?? 0} accounts / ${c.last_sync_transactions ?? 0} transactions`);
+        if (c.last_sync_error) console.log(`  ${colors.yellow}note${colors.reset}        ${c.last_sync_error}`);
+      }
+      console.log('');
+      return;
+    }
+
+    case 'sync': {
+      const { client } = financesClient();
+      print.info('Pulling fresh balances and transactions from the bank bridge…');
+      const parsedSyncDays = Number.parseInt(String(flags.days ?? ''), 10);
+      const result = await fin.syncFinances(client, {
+        days: Number.isFinite(parsedSyncDays) ? parsedSyncDays : undefined,
+        connectionId: flags.connection || flags['connection-id'],
+      });
+      if (flags.json) { print.json(result); return; }
+      const t = result.totals || {};
+      print.success(`Synced ${t.accounts ?? 0} accounts: ${t.transactionsNew ?? 0} new of ${t.transactionsSeen ?? 0} transactions (${result.status}).`);
+      for (const r of result.results || []) {
+        if (r.status === 'partial' || r.error) print.warn(`${r.connectionId || r.id || 'connection'}: ${r.error || r.status}`);
+      }
+      return;
+    }
+
+    default:
+      print.error(`Unknown finances command: ${subcommand}`);
+      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync]');
+      process.exit(1);
+  }
+}
+
 async function main() {
   const { command, subcommand, args, flags } = parseArgs(process.argv.slice(2));
+  validateBooleanFlags(flags);
   
   if (flags.version || flags.v) {
     console.log(VERSION);
     return;
   }
   
-  if (flags.help || flags.h || !command) {
+  if (flags.help || flags.h) {
+    showHelp();
+    return;
+  }
+
+  if (!command) {
+    // No command in an interactive terminal → browse-and-run menu instead of a
+    // bare help dump. Piped/non-TTY invocations keep printing help.
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      await runInteractiveMenu();
+      return;
+    }
     showHelp();
     return;
   }
@@ -2584,10 +4206,12 @@ async function handleLightning(subcommand, args, flags) {
         console.error(colors.red + 'Error: --wallet-id required' + colors.reset);
         process.exit(1);
       }
-      const mnemonic = await getDecryptedMnemonic(flags);
+      // NEW-20: this used to decrypt the stored seed — prompting for the
+      // passphrase — purely to post it to the server, which validated it and
+      // threw it away. Provisioning is a custodial LNbits wallet, so nothing
+      // is derived or signed here. The seed never leaves the machine now.
       const result = await client.lightning.enableWallet({
         wallet_id: walletId,
-        mnemonic,
         business_id: flags['business-id'],
       });
       console.log(colors.green + '⚡ Lightning wallet enabled!' + colors.reset);
@@ -2715,6 +4339,18 @@ async function handleLightning(subcommand, args, flags) {
 }
 
     switch (command) {
+      case 'login':
+        await handleLogin();
+        break;
+
+      case 'logout':
+        handleLogout();
+        break;
+
+      case 'whoami':
+        await handleWhoami(flags);
+        break;
+
       case 'config':
         await handleConfig(subcommand, args);
         break;
@@ -2722,6 +4358,14 @@ async function handleLightning(subcommand, args, flags) {
       case 'payment':
         await handlePayment(subcommand, args, flags);
         break;
+
+      case 'invoice':
+        await handleInvoice(subcommand, args, flags);
+        break;
+
+      case 'tokens':
+        await handleTokens(subcommand, args, flags);
+        break;
         
       case 'business':
         await handleBusiness(subcommand, args, flags);
@@ -2775,14 +4419,37 @@ async function handleLightning(subcommand, args, flags) {
       case 'oauth':
         await handleOAuth(subcommand, args, flags);
         break;
-        
+
+      case 'finances':
+      case 'finance':
+      case 'money':
+        await handleFinances(subcommand, args, flags);
+        break;
+
+      case 'tui':
+      case 'dashboard':
+        await handleFinances('tui', [subcommand, ...args].filter(Boolean), flags);
+        break;
+
+      case 'update':
+      case 'upgrade':
+      case 'self-update':
+        handleSelfManage('update');
+        break;
+
+      case 'remove':
+      case 'uninstall':
+        handleSelfManage('remove');
+        break;
+
       default:
         print.error(`Unknown command: ${command}`);
         showHelp();
         process.exit(1);
     }
   } catch (error) {
-    print.error(error.message);
+    const code = error?.response?.code;
+    print.error(error.message + (code ? ' (' + code + ')' : ''));
     if (flags.debug) {
       console.error(error);
     }
@@ -2896,6 +4563,108 @@ async function handleOAuth(subcommand, args, flags) {
   }
 }
 
+/**
+ * Open the platform's browser at a URL.
+ *
+ * Failure is not fatal: the URL is printed either way, so a headless box or an
+ * unusual desktop just means the user opens it themselves.
+ */
+async function openInBrowser(url) {
+  const { spawn } = await import('node:child_process');
+  const command =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    spawn(command, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' })
+      .on('error', () => {})
+      .unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `coinpay x402 pay <url>` — fetch a paid resource, approving in the browser.
+ *
+ * The terminal cannot sign: browser wallets expose themselves to pages, not to
+ * processes. So this serves a one-shot approval page on loopback, opens it,
+ * and waits for the signed `X-PAYMENT` header to come back before retrying the
+ * original request.
+ */
+async function handleX402Pay(args, flags) {
+  const target = args[0] || flags.url;
+  if (!target) {
+    print.error('Usage: coinpay x402 pay <url>');
+    process.exit(1);
+  }
+
+  const { startPaymentServer } = await import('../src/x402-pay-server.js');
+
+  print.info(`Fetching ${target}`);
+  const first = await fetch(target);
+
+  if (first.status !== 402) {
+    // Nothing to pay for. Still the useful answer, so print it rather than
+    // treating "free" as an error.
+    print.success(`No payment required (HTTP ${first.status})`);
+    const body = await first.text();
+    if (flags.output) {
+      await (await import('node:fs/promises')).writeFile(flags.output, body);
+      print.info(`Wrote ${flags.output}`);
+    } else {
+      console.log(body);
+    }
+    return;
+  }
+
+  let paymentRequired;
+  try {
+    paymentRequired = await first.clone().json();
+  } catch {
+    print.error('Resource returned 402 but its body was not valid x402 JSON');
+    process.exit(1);
+  }
+
+  const server = await startPaymentServer({
+    paymentRequired,
+    resourceUrl: target,
+    port: flags.port ? Number(flags.port) : 0,
+  });
+
+  try {
+    if (flags['no-open']) {
+      print.info(`Open this to approve:\n  ${server.url}`);
+    } else {
+      await openInBrowser(server.url);
+      print.info(`Approve in your browser:\n  ${server.url}`);
+    }
+    print.info('Waiting for approval…');
+
+    const header = await server.waitForPayment();
+    print.success('Payment approved');
+
+    const paid = await fetch(target, { headers: { 'X-PAYMENT': header } });
+    if (paid.status === 402) {
+      // Never sign again automatically — a second 402 means the payment was
+      // refused rather than missing, and retrying spends the user's money on a
+      // resource that just said no.
+      print.error('Payment was rejected by the resource. Not retrying.');
+      process.exit(1);
+    }
+
+    const body = await paid.text();
+    if (flags.output) {
+      await (await import('node:fs/promises')).writeFile(flags.output, body);
+      print.success(`HTTP ${paid.status} — wrote ${flags.output}`);
+    } else {
+      print.success(`HTTP ${paid.status}`);
+      console.log(body);
+    }
+  } finally {
+    await server.close();
+  }
+}
+
 /**
  * Handle x402 commands
  */
@@ -2911,16 +4680,23 @@ Usage: coinpay x402 <command> [options]
 Commands:
   status          Check x402 facilitator status
   test            Test x402 flow against an endpoint
+  pay <url>       Fetch a paid URL, approving payment in your browser
 
 Options:
   --url <url>     Endpoint URL for testing
   --network <net> Network: base, ethereum, polygon (default: base)
   --amount <amt>  Amount in USDC smallest unit (default: 1000000 = 1 USDC)
+  --output <file> (pay) Write the paid response body to a file
+  --port <n>      (pay) Port for the local approval page (default: random)
+  --no-open       (pay) Print the URL instead of opening a browser
 `);
     return;
   }
 
   switch (subcommand) {
+    case 'pay':
+      return handleX402Pay(args, flags);
+
     case 'status': {
       const apiKey = flags['api-key'] || config.apiKey;
       const baseUrl = flags['base-url'] || config.baseUrl || 'https://coinpayportal.com';