simplefin-cli 0.1.0

package/PLAN.md

@@ -0,0 +1,104 @@
+# SimpleFIN CLI Plan
+
+## Overview
+CLI tool for accessing financial data via SimpleFIN Bridge (multi-bank support)
+
+## Author
+dilllxd
+
+## License
+MIT + Commons Clause
+
+## Module Path
+github.com/dilllxd/simplefin-cli
+
+## Dependencies
+- native Go `net/http`
+- charm.sh/gum for pretty output
+- viper for config (TOML)
+
+## Config Location
+~/.config/simplefin-cli/config.toml
+
+## Multi-Account Support
+No - single account, but links multiple banks internally
+
+## Commands
+
+### Connection
+```bash
+simplefin connect                    # Interactive setup token prompt
+simplefin connect --token "..."      # Non-interactive
+simplefin status                     # Check connection status
+simplefin disconnect                 # Remove all bank connections
+```
+
+### Accounts
+```bash
+simplefin accounts list              # List all linked accounts
+simplefin accounts get <account-id>  # Get account details
+simplefin accounts balances          # Get all current balances
+```
+
+### Transactions
+```bash
+simplefin transactions               # Recent transactions (default 30 days)
+simplefin transactions --days 7
+simplefin transactions --days 90
+simplefin transactions --account <account-id>
+simplefin transactions --format json
+simplefin transactions-by-date --start 2026-01-01 --end 2026-01-31
+```
+
+### Sync
+```bash
+simplefin sync                       # Force refresh from all banks
+simplefin sync --account <account-id>  # Refresh specific account
+```
+
+## Config File
+```toml
+[connection]
+setup_token = "${SIMPLEFIN_SETUP_TOKEN}"
+access_url = "${SIMPLEFIN_ACCESS_URL}"  # Optional, overrides token
+
+[output]
+format = "table"
+colors = true
+```
+
+## Environment Variables
+- SIMPLEFIN_SETUP_TOKEN
+- SIMPLEFIN_ACCESS_URL
+
+## Storage
+~/.config/simplefin-cli/connection.json:
+```json
+{
+  "access_url": "https://bridge.simplefin.org/simplefin/...",
+  "created_at": "2026-01-10T00:00:00Z",
+  "last_sync": "2026-01-10T12:00:00Z"
+}
+```
+
+## Auth Flow
+1. User visits https://bridge.simplefin.org/simplefin/create
+2. Gets a setup token
+3. Runs `simplefin connect --token "..."`
+4. CLI exchanges setup token for access URL
+5. Access URL stored for future use
+
+## Data Types
+- Account (name, type, balance, currency, institution)
+- Transaction (date, amount, description, category, account)
+
+## Implementation Phases
+1. Config + connection flow
+2. Account listing and balance retrieval
+3. Transaction retrieval (by days and date range)
+4. Sync/refresh functionality
+
+## Testing
+- Unit tests for API client
+- Integration tests with real SimpleFIN connection
+- Mock server for testing

package/README.md

@@ -0,0 +1,88 @@
+# SimpleFIN CLI
+
+CLI tool for accessing financial data via SimpleFIN Bridge.
+
+## Author
+dilllxd
+
+## License
+MIT
+
+## Installation
+
+```bash
+npm install -g simplefin-cli
+```
+
+## Usage
+
+### Connect to SimpleFIN Bridge
+
+```bash
+simplefin connect
+```
+
+You'll need a setup token from https://bridge.simplefin.org/simplefin/create
+
+### List Accounts
+
+```bash
+simplefin accounts
+```
+
+### View Transactions
+
+```bash
+simplefin transactions              # Last 30 days
+simplefin transactions --days 7     # Last 7 days
+simplefin transactions --json       # JSON output
+```
+
+### Disconnect
+
+```bash
+simplefin disconnect
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `simplefin connect` | Connect to SimpleFIN Bridge |
+| `simplefin disconnect` | Disconnect and remove credentials |
+| `simplefin status` | Check connection status |
+| `simplefin accounts` | List connected accounts |
+| `simplefin transactions` | List recent transactions |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON (for all commands) |
+| `-d, --days` | Number of days to look back (for transactions) |
+| `-t, --token` | Setup token (for connect) |
+
+## Environment Variables
+
+- `SIMPLEFIN_SETUP_TOKEN` - Setup token for connect command
+
+## Configuration
+
+Config stored in `~/.config/simplefin-cli/connection.json`
+
+## Publishing to npm
+
+```bash
+# Log in to npm
+npm login
+
+# Publish
+cd simplefin-cli
+npm publish
+```
+
+## Testing
+
+```bash
+node test.js
+```

package/bin/simplefin.js

@@ -0,0 +1,442 @@
+const { Command } = require('commander');
+const axios = require('axios');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const program = new Command();
+
+function getConfigDir() {
+  return path.join(os.homedir(), '.config', 'simplefin-cli');
+}
+
+function getConnectionPath() {
+  return path.join(getConfigDir(), 'connection.json');
+}
+
+function loadConnection() {
+  try {
+    const data = fs.readFileSync(getConnectionPath(), 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+function saveConnection(accessUrl, username, password) {
+  fs.mkdirSync(getConfigDir(), { recursive: true });
+  const connection = {
+    access_url: accessUrl,
+    username,
+    password,
+    created_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(getConnectionPath(), JSON.stringify(connection, null, 2));
+}
+
+function deleteConnection() {
+  try {
+    fs.unlinkSync(getConnectionPath());
+  } catch (e) {
+    // ignore
+  }
+}
+
+function parseAuthFromUrl(accessUrl) {
+  const match = accessUrl.match(/:\/\/([^:]+):([^@]+)@/);
+  if (match) {
+    return {
+      username: match[1],
+      password: match[2],
+      baseUrl: accessUrl.replace(/:\/\/[^:]+:[^@]+@/, '://'),
+    };
+  }
+  return null;
+}
+
+async function claimAccessUrl(setupToken) {
+  const claimUrl = Buffer.from(setupToken, 'base64').toString('utf-8');
+  
+  const response = await axios.post(claimUrl, '', {
+    headers: { 'Content-Length': '0' },
+    timeout: 10000,
+  });
+
+  if (response.status === 403) {
+    throw new Error('Token is invalid or has already been used');
+  }
+
+  if (response.status !== 200) {
+    throw new Error(`Unexpected response: ${response.status}`);
+  }
+
+  const accessUrl = response.data.trim();
+  if (!accessUrl) {
+    throw new Error('Empty response from server');
+  }
+
+  return accessUrl;
+}
+
+async function getInfo(baseUrl) {
+  const response = await axios.get(`${baseUrl}/info`);
+  return response.data;
+}
+
+async function getAccounts(options) {
+  const params = new URLSearchParams();
+  
+  if (options.startDate) params.append('start-date', options.startDate);
+  if (options.endDate) params.append('end-date', options.endDate);
+  if (options.pending) params.append('pending', '1');
+  if (options.account) params.append('account', options.account);
+  if (options.balancesOnly) params.append('balances-only', '1');
+  
+  const url = `${options.baseUrl}/accounts${params.toString() ? '?' + params.toString() : ''}`;
+  
+  const response = await axios.get(url, {
+    auth: { username: options.username, password: options.password },
+  });
+
+  if (response.status === 403) {
+    throw new Error('Authentication failed - access may be revoked');
+  }
+
+  if (response.status === 402) {
+    throw new Error('Payment required');
+  }
+
+  return response.data;
+}
+
+function formatDate(timestamp) {
+  if (!timestamp) return 'N/A';
+  const date = new Date(timestamp * 1000);
+  return date.toLocaleString('en-US', {
+    month: 'short', day: 'numeric', year: 'numeric',
+    hour: 'numeric', minute: '2-digit', hour12: true,
+  });
+}
+
+function formatDateFull(timestamp) {
+  if (!timestamp) return 'N/A';
+  const date = new Date(timestamp * 1000);
+  return date.toLocaleString('en-US', {
+    weekday: 'short', month: 'short', day: 'numeric', year: 'numeric',
+    hour: 'numeric', minute: '2-digit', hour12: true,
+  });
+}
+
+function formatDateShort(timestamp) {
+  if (!timestamp) return '';
+  const date = new Date(timestamp * 1000);
+  return date.toLocaleDateString('en-US', { month: '2-digit', day: '2-digit' });
+}
+
+function truncate(str, len) {
+  if (!str) return '';
+  return str.length > len ? str.slice(0, len - 3) + '...' : str;
+}
+
+program.name('simplefin').description('SimpleFIN CLI - Access your financial data');
+
+// ===== INFO COMMAND =====
+program.command('info')
+  .description('Get SimpleFIN server information')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    const conn = loadConnection();
+    if (!conn) {
+      console.log('Not connected');
+      console.log("Run 'simplefin connect' first");
+      process.exit(1);
+    }
+    
+    try {
+      const data = await getInfo(conn.access_url);
+      
+      if (options.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      
+      console.log('Server Info');
+      console.log('-----------');
+      console.log(`Supported versions: ${(data.versions || []).join(', ')}`);
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ===== CONNECT COMMAND =====
+program.command('connect')
+  .description('Connect to SimpleFIN Bridge')
+  .option('-t, --token <token>', 'Setup token (or use SIMPLEFIN_SETUP_TOKEN env var)')
+  .action(async (options) => {
+    let setupToken = options.token || process.env.SIMPLEFIN_SETUP_TOKEN;
+    
+    if (!setupToken) {
+      console.log('Error: Setup token required');
+      console.log('Provide via:');
+      console.log('  -t, --token option: simplefin connect --token <token>');
+      console.log('  Environment variable: export SIMPLEFIN_SETUP_TOKEN=<token>');
+      console.log('\nGet a token at: https://bridge.simplefin.org/simplefin/create');
+      process.exit(1);
+    }
+    
+    console.log('Connecting to SimpleFIN Bridge...');
+    
+    try {
+      const accessUrl = await claimAccessUrl(setupToken);
+      const auth = parseAuthFromUrl(accessUrl);
+      if (!auth) {
+        throw new Error('Could not parse credentials from Access URL');
+      }
+      saveConnection(auth.baseUrl, auth.username, auth.password);
+      console.log('Connected successfully!');
+      console.log('\nNext steps:');
+      console.log('  simplefin info         - Server info');
+      console.log('  simplefin accounts     - List your accounts');
+      console.log('  simplefin transactions - View transactions');
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ===== DISCONNECT COMMAND =====
+program.command('disconnect')
+  .description('Disconnect from SimpleFIN Bridge')
+  .action(() => {
+    deleteConnection();
+    console.log('Disconnected successfully');
+  });
+
+// ===== STATUS COMMAND =====
+program.command('status')
+  .description('Check connection status')
+  .option('--json', 'Output as JSON')
+  .action((options) => {
+    const conn = loadConnection();
+    if (!conn) {
+      console.log('Not connected');
+      console.log("Run 'simplefin connect' first");
+      process.exit(1);
+    }
+    
+    if (options.json) {
+      console.log(JSON.stringify({
+        connected: true,
+        server: conn.access_url,
+        created_at: conn.created_at,
+      }, null, 2));
+      return;
+    }
+    
+    console.log('Connection Status');
+    console.log('-----------------');
+    console.log('Connected');
+    console.log(`Server: ${conn.access_url}`);
+    console.log(`Connected since: ${formatDate(new Date(conn.created_at).getTime() / 1000)}`);
+  });
+
+// ===== ACCOUNTS COMMAND =====
+program.command('accounts')
+  .description('List all connected accounts')
+  .option('--json', 'Output as JSON')
+  .option('--balances-only', 'Only show balances, no transactions')
+  .action(async (options) => {
+    const conn = loadConnection();
+    if (!conn) {
+      console.log('Not connected');
+      process.exit(1);
+    }
+    
+    try {
+      const data = await getAccounts({
+        baseUrl: conn.access_url,
+        username: conn.username,
+        password: conn.password,
+        balancesOnly: options.balancesOnly,
+      });
+      
+      if (data.errors && data.errors.length > 0) {
+        console.log('Errors from server:');
+        for (const err of data.errors) {
+          console.log(`  - ${err}`);
+        }
+        console.log('');
+      }
+      
+      const accounts = data.accounts || [];
+      
+      if (options.json) {
+        console.log(JSON.stringify({
+          connected: true,
+          errors: data.errors || [],
+          accounts: accounts.map(acc => ({
+            id: acc.id,
+            name: acc.name,
+            organization: acc.org?.name || acc.org?.domain || 'Unknown',
+            balance: acc.balance,
+            'available-balance': acc['available-balance'],
+            currency: acc.currency,
+            'balance-date': acc['balance-date'],
+            type: acc.type,
+            extra: acc.extra,
+          })),
+          total_accounts: accounts.length,
+        }, null, 2));
+        return;
+      }
+      
+      console.log('Accounts');
+      console.log('--------');
+      for (const acc of accounts) {
+        console.log(`${acc.name} (${acc.org?.name || acc.org?.domain || 'Unknown'})`);
+        console.log(`  Balance: ${acc.balance} ${acc.currency}`);
+        if (acc['available-balance'] && acc['available-balance'] !== acc.balance) {
+          console.log(`  Available: ${acc['available-balance']} ${acc.currency}`);
+        }
+        console.log(`  Last updated: ${formatDate(acc['balance-date'])}`);
+        if (acc.type) {
+          console.log(`  Type: ${acc.type}`);
+        }
+        if (acc.transactions && acc.transactions.length > 0 && !options.balancesOnly) {
+          console.log(`  Transactions: ${acc.transactions.length}`);
+        }
+      }
+      console.log('--------');
+      console.log(`Total: ${accounts.length} account(s)`);
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ===== TRANSACTIONS COMMAND =====
+program.command('transactions')
+  .description('List transactions')
+  .option('-d, --days <days>', 'Number of days to look back', '30')
+  .option('--start-date <date>', 'Start date (Unix timestamp or YYYY-MM-DD)')
+  .option('--end-date <date>', 'End date (Unix timestamp or YYYY-MM-DD)')
+  .option('--account <id>', 'Filter by account ID')
+  .option('--pending', 'Include pending transactions')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    const conn = loadConnection();
+    if (!conn) {
+      console.log('Not connected');
+      process.exit(1);
+    }
+    
+    // Parse dates
+    let startDate, endDate;
+    
+    if (options.startDate) {
+      if (options.startDate.includes('-')) {
+        startDate = Math.floor(new Date(options.startDate).getTime() / 1000);
+      } else {
+        startDate = parseInt(options.startDate);
+      }
+    } else {
+      const days = parseInt(options.days) || 30;
+      startDate = Math.floor(Date.now() / 1000) - (days * 24 * 60 * 60);
+    }
+    
+    if (options.endDate) {
+      if (options.endDate.includes('-')) {
+        endDate = Math.floor(new Date(options.endDate).getTime() / 1000);
+      } else {
+        endDate = parseInt(options.endDate);
+      }
+    }
+    
+    try {
+      const data = await getAccounts({
+        baseUrl: conn.access_url,
+        username: conn.username,
+        password: conn.password,
+        startDate: startDate.toString(),
+        endDate: endDate?.toString(),
+        account: options.account,
+        pending: options.pending,
+      });
+      
+      if (data.errors && data.errors.length > 0) {
+        console.log('Errors from server:');
+        for (const err of data.errors) {
+          console.log(`  - ${err}`);
+        }
+        console.log('');
+      }
+      
+      const accounts = data.accounts || [];
+      const allTransactions = [];
+      
+      for (const acc of accounts) {
+        for (const tx of acc.transactions || []) {
+          allTransactions.push({
+            ...tx,
+            account_name: acc.name,
+            account_id: acc.id,
+          });
+        }
+      }
+      
+      allTransactions.sort((a, b) => b.posted - a.posted);
+      
+      if (options.json) {
+        console.log(JSON.stringify({
+          connected: true,
+          errors: data.errors || [],
+          query: {
+            start_date: startDate,
+            end_date: endDate,
+            account: options.account,
+            pending: options.pending,
+          },
+          transactions: allTransactions,
+          count: allTransactions.length,
+        }, null, 2));
+        return;
+      }
+      
+      console.log('Transactions');
+      console.log('------------');
+      
+      if (startDate && !options.startDate) {
+        const days = parseInt(options.days) || 30;
+        console.log(`From last ${days} days`);
+      } else if (startDate) {
+        console.log(`From ${formatDate(startDate)}`);
+        if (endDate) console.log(`To ${formatDate(endDate)}`);
+      }
+      
+      console.log(`Found ${allTransactions.length} transaction(s)\n`);
+      
+      for (const tx of allTransactions) {
+        const amount = parseFloat(tx.amount).toFixed(2);
+        const sign = tx.amount.startsWith('-') ? '' : '+';
+        const pending = tx.pending ? '[PENDING] ' : '';
+        const date = tx.posted ? formatDateFull(tx.posted) : 'N/A';
+        
+        console.log(`${date}`);
+        console.log(`  ${sign}${amount.padStart(10)}  ${pending}${truncate(tx.description, 50)}`);
+        console.log(`  Account: ${tx.account_name}`);
+        if (tx.transacted_at && tx.transacted_at !== tx.posted) {
+          console.log(`  Transacted: ${formatDateFull(tx.transacted_at)}`);
+        }
+        if (tx.category || (tx.extra && tx.extra.category)) {
+          console.log(`  Category: ${tx.category || tx.extra.category}`);
+        }
+        console.log('');
+      }
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "simplefin-cli",
+  "version": "0.1.0",
+  "description": "CLI tool for accessing financial data via SimpleFIN Bridge",
+  "author": "dilllxd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.dylan.lol/dylan/cli-tools"
+  },
+  "bugs": {
+    "url": "https://git.dylan.lol/dylan/cli-tools/issues"
+  },
+  "homepage": "https://git.dylan.lol/dylan/cli-tools/tree/main/simplefin-cli",
+  "keywords": [
+    "simplefin",
+    "finance",
+    "bank",
+    "cli",
+    "terminal"
+  ],
+  "bin": {
+    "simplefin": "./bin/simplefin.js"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "commander": "^11.0.0"
+  },
+  "devDependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/publish.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# SimpleFIN CLI Publishing Script
+
+set -e
+
+echo "SimpleFIN CLI Publishing Script"
+echo "================================"
+echo ""
+
+# Check if logged in
+if ! npm whoami > /dev/null 2>&1; then
+  echo "You need to log in to npm first:"
+  echo "  npm login"
+  echo ""
+  echo "Or create an account:"
+  echo "  https://www.npmjs.com/signup"
+  echo ""
+  read -p "Press Enter after you've logged in..."
+fi
+
+# Verify login
+echo "Logged in as: $(npm whoami)"
+echo ""
+
+# Go to simplefin-cli directory
+cd "$(dirname "$0")"
+
+# Check package name
+echo "Package name: $(node -e 'console.log(require("./package.json").name)')"
+echo "Version: $(node -e 'console.log(require("./package.json").version)')"
+echo ""
+
+# Confirm publish
+read -p "Publish to npm? (y/n) " -n 1 -r
+echo ""
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+  echo "Aborted."
+  exit 1
+fi
+
+# Publish
+npm publish
+
+echo ""
+echo "Published successfully!"
+echo ""
+echo "To install:"
+echo "  npm install -g simplefin-cli"
+echo ""
+echo "To use:"
+echo "  simplefin connect"
+echo "  simplefin accounts"
+echo "  simplefin transactions"

package/test.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const CLI = path.join(__dirname, 'bin', 'simplefin.js');
+const configDir = path.join(os.homedir(), '.config', 'simplefin-cli');
+const configFile = path.join(configDir, 'connection.json');
+
+let passed = 0;
+let failed = 0;
+
+function run(args) {
+  return new Promise((resolve) => {
+    const proc = spawn('node', [CLI, ...args], { cwd: path.dirname(CLI) });
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', d => stdout += d.toString());
+    proc.stderr.on('data', d => stderr += d.toString());
+
+    proc.on('close', code => resolve({ code, stdout, stderr }));
+  });
+}
+
+async function test(name, args, check) {
+  const result = await run(args);
+  try {
+    check(result);
+    console.log('✓ ' + name);
+    passed++;
+  } catch (e) {
+    console.log('✗ ' + name);
+    console.log('  Error: ' + e.message);
+    console.log('  stdout: ' + result.stdout.substring(0, 200));
+    console.log('  stderr: ' + result.stderr.substring(0, 200));
+    failed++;
+  }
+}
+
+async function testIntegration(name, args, check) {
+  const result = await run(args);
+  try {
+    check(result);
+    console.log('✓ ' + name);
+    passed++;
+  } catch (e) {
+    console.log('✗ ' + name);
+    console.log('  Error: ' + e.message);
+    console.log('  Output: ' + result.stdout.substring(0, 300));
+    failed++;
+  }
+}
+
+async function setup() {
+  console.log('╔════════════════════════════════════════════════════════════╗');
+  console.log('║       SimpleFIN CLI - Comprehensive Test Suite         ║');
+  console.log('╚════════════════════════════════════════════════════════════╝\n');
+
+  // Clean state
+  try { fs.unlinkSync(configFile); } catch (e) {}
+
+  // ===== HELP TESTS =====
+  console.log('━━━ Help & Usage ━━━');
+
+  await test('Main help shows usage', ['--help'], function(r) {
+    if (r.stdout.indexOf('SimpleFIN CLI') === -1) throw new Error('Missing header');
+    if (r.stdout.indexOf('connect') === -1) throw new Error('Missing connect command');
+    if (r.stdout.indexOf('disconnect') === -1) throw new Error('Missing disconnect command');
+    if (r.stdout.indexOf('status') === -1) throw new Error('Missing status command');
+    if (r.stdout.indexOf('accounts') === -1) throw new Error('Missing accounts command');
+    if (r.stdout.indexOf('transactions') === -1) throw new Error('Missing transactions command');
+    if (r.stdout.indexOf('info') === -1) throw new Error('Missing info command');
+  });
+
+  await test('Connect help shows token option', ['connect', '--help'], function(r) {
+    if (r.stdout.indexOf('--token') === -1) throw new Error('Missing --token option');
+  });
+
+  await test('Transactions help shows all options', ['transactions', '--help'], function(r) {
+    if (r.stdout.indexOf('--days') === -1) throw new Error('Missing --days option');
+    if (r.stdout.indexOf('--start-date') === -1) throw new Error('Missing --start-date option');
+    if (r.stdout.indexOf('--end-date') === -1) throw new Error('Missing --end-date option');
+    if (r.stdout.indexOf('--account') === -1) throw new Error('Missing --account option');
+    if (r.stdout.indexOf('--pending') === -1) throw new Error('Missing --pending option');
+  });
+
+  await test('Accounts help shows balances-only', ['accounts', '--help'], function(r) {
+    if (r.stdout.indexOf('--balances-only') === -1) throw new Error('Missing --balances-only option');
+  });
+
+  await test('Info help shows usage', ['info', '--help'], function(r) {
+    if (r.stdout.indexOf('info') === -1) throw new Error('Missing info help');
+  });
+
+  // ===== ERROR HANDLING TESTS =====
+  console.log('\n━━━ Error Handling ━━━');
+
+  await test('Status exits 1 when not connected', ['status'], function(r) {
+    if (r.code !== 1) throw new Error('Expected exit 1, got ' + r.code);
+    if (r.stdout.toLowerCase().indexOf('not connected') === -1) throw new Error('Missing error msg');
+  });
+
+  await test('Accounts exits 1 when not connected', ['accounts'], function(r) {
+    if (r.code !== 1) throw new Error('Expected exit 1, got ' + r.code);
+  });
+
+  await test('Transactions exits 1 when not connected', ['transactions'], function(r) {
+    if (r.code !== 1) throw new Error('Expected exit 1, got ' + r.code);
+  });
+
+  await test('Info exits 1 when not connected', ['info'], function(r) {
+    if (r.code !== 1) throw new Error('Expected exit 1, got ' + r.code);
+  });
+
+  await test('Connect without token shows error', ['connect'], function(r) {
+    if (r.code !== 1) throw new Error('Expected exit 1, got ' + r.code);
+    if (r.stdout.toLowerCase().indexOf('token') === -1) throw new Error('Missing token error');
+  });
+
+  await test('Disconnect succeeds even when not connected', ['disconnect'], function(r) {
+    if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+  });
+
+  // ===== ARGUMENT PARSING TESTS =====
+  console.log('\n━━━ Argument Parsing ━━━');
+
+  var argTests = [
+    ['transactions', '--days', '7'],
+    ['transactions', '--start-date', '2026-01-01'],
+    ['transactions', '--end-date', '2026-01-10'],
+    ['transactions', '--account', 'ACT-123'],
+    ['transactions', '--pending'],
+    ['transactions', '--days', '30', '--json'],
+    ['accounts', '--balances-only'],
+    ['accounts', '--json'],
+  ];
+
+  for (var i = 0; i < argTests.length; i++) {
+    var args = argTests[i];
+    await test('Parses: ' + args.join(' '), args, function(r) {
+      if (r.code !== 1) throw new Error('Should exit 1 (not connected), got ' + r.code);
+    });
+  }
+
+  // ===== EDGE CASES =====
+  console.log('\n━━━ Edge Cases ━━━');
+
+  await test('Unknown command shows error', ['unknown-command'], function(r) {
+    if (r.code !== 1) throw new Error('Expected exit 1, got ' + r.code);
+  });
+
+  await test('Missing required argument shows usage', ['transactions', '--start-date'], function(r) {
+    if (r.code !== 1) throw new Error('Expected exit 1, got ' + r.code);
+  });
+
+  // ===== INTEGRATION TESTS =====
+  console.log('\n━━━ Integration Tests ━━━');
+
+  var realToken = process.env.SIMPLEFIN_TOKEN || 'aHR0cHM6Ly9iZXRhLWJyaWRnZS5zaW1wbGVmaW4ub3JnL3NpbXBsZWZpbi9jbGFpbS85RUE5MjM5NzlDN0ZCMDk3REFDQTU0NDJDOTcwNUZGNDRDODkyNDk1NkQzRDQxOTkyMUVDNDNCNEFBNTE3QTEwMzM1MUMxNDhGRDRFQzdFMTYxRUZDNTQwMUE5QzVENjI0MEZFNEZDRkEyN0VFMjM1RUIwRDRCRjI4NDYyODNBOQ==';
+
+  try {
+    await testIntegration('Connect with real token', ['connect', '--token', realToken], function(r) {
+      if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+      if (r.stdout.toLowerCase().indexOf('connected') === -1) throw new Error('Missing success message');
+    });
+
+    await testIntegration('Status shows connected', ['status'], function(r) {
+      if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+      if (r.stdout.toLowerCase().indexOf('connected') === -1) throw new Error('Missing connected status');
+    });
+
+    await testIntegration('Status --json outputs valid JSON', ['status', '--json'], function(r) {
+      if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+      try {
+        JSON.parse(r.stdout);
+      } catch (e) {
+        throw new Error('Invalid JSON: ' + e.message);
+      }
+    });
+
+    await testIntegration('Accounts lists accounts', ['accounts'], function(r) {
+      if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+      if (r.stdout.toLowerCase().indexOf('accounts') === -1) throw new Error('Missing accounts header');
+    });
+
+    await testIntegration('Accounts --json outputs valid JSON', ['accounts', '--json'], function(r) {
+      if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+      try {
+        var data = JSON.parse(r.stdout);
+        if (!data.accounts) throw new Error('Missing accounts array');
+      } catch (e) {
+        throw new Error('Invalid JSON: ' + e.message);
+      }
+    });
+
+    await testIntegration('Transactions shows transactions', ['transactions', '--days', '7'], function(r) {
+      if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+      if (r.stdout.toLowerCase().indexOf('transactions') === -1) throw new Error('Missing transactions header');
+    });
+
+    await testIntegration('Transactions --json outputs valid JSON with count', ['transactions', '--days', '7', '--json'], function(r) {
+      if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+      try {
+        var data = JSON.parse(r.stdout);
+        if (typeof data.count !== 'number') throw new Error('Missing count field');
+        if (!Array.isArray(data.transactions)) throw new Error('Missing transactions array');
+      } catch (e) {
+        throw new Error('Invalid JSON: ' + e.message);
+      }
+    });
+
+    await testIntegration('Info shows server info', ['info'], function(r) {
+      if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+      if (r.stdout.toLowerCase().indexOf('server') === -1) throw new Error('Missing server info');
+    });
+
+    await testIntegration('Disconnect succeeds', ['disconnect'], function(r) {
+      if (r.code !== 0) throw new Error('Expected exit 0, got ' + r.code);
+    });
+
+    await testIntegration('Status shows disconnected after disconnect', ['status'], function(r) {
+      if (r.code !== 1) throw new Error('Expected exit 1, got ' + r.code);
+      if (r.stdout.toLowerCase().indexOf('not connected') === -1) throw new Error('Missing not connected');
+    });
+
+  } catch (e) {
+    console.log('⚠ Integration tests skipped: ' + e.message);
+  }
+
+  // ===== SUMMARY =====
+  console.log('\n╔════════════════════════════════════════════════════════════╗');
+  console.log('║  Results: ' + passed + ' passed, ' + failed + ' failed                              ║');
+  console.log('╚════════════════════════════════════════════════════════════╝');
+
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+setup();