portok 1.0.0

package/portok.mjs

@@ -0,0 +1,793 @@
+#!/usr/bin/env node
+
+/**
+ * Portok CLI - Command-line interface for portokd daemon
+ * Communicates with the daemon via HTTP to query status, metrics, and trigger switches.
+ */
+
+// =============================================================================
+// ANSI Colors (only if TTY)
+// =============================================================================
+
+const isTTY = process.stdout.isTTY;
+
+const colors = {
+  reset: isTTY ? '\x1b[0m' : '',
+  bold: isTTY ? '\x1b[1m' : '',
+  dim: isTTY ? '\x1b[2m' : '',
+  red: isTTY ? '\x1b[31m' : '',
+  green: isTTY ? '\x1b[32m' : '',
+  yellow: isTTY ? '\x1b[33m' : '',
+  blue: isTTY ? '\x1b[34m' : '',
+  cyan: isTTY ? '\x1b[36m' : '',
+};
+
+// =============================================================================
+// Argument Parsing
+// =============================================================================
+
+function parseArgs(args) {
+  const result = {
+    command: null,
+    positional: [],
+    options: {},
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const nextArg = args[i + 1];
+
+      // Check if it's a flag (no value) or has a value
+      if (!nextArg || nextArg.startsWith('--')) {
+        result.options[key] = true;
+      } else {
+        result.options[key] = nextArg;
+        i++;
+      }
+    } else if (!result.command) {
+      result.command = arg;
+    } else {
+      result.positional.push(arg);
+    }
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Env File Parser (for --instance support)
+// =============================================================================
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ENV_FILE_DIR = '/etc/portok';
+
+/**
+ * Parse an env file (KEY=VALUE format)
+ * Ignores comments (#) and blank lines
+ */
+function parseEnvFile(filePath) {
+  const result = {};
+  
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+    
+    for (const line of lines) {
+      const trimmed = line.trim();
+      
+      // Skip empty lines and comments
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      
+      // Parse KEY=VALUE
+      const eqIndex = trimmed.indexOf('=');
+      if (eqIndex === -1) continue;
+      
+      const key = trimmed.slice(0, eqIndex).trim();
+      let value = trimmed.slice(eqIndex + 1).trim();
+      
+      // Remove surrounding quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      
+      result[key] = value;
+    }
+  } catch (err) {
+    // File doesn't exist or can't be read
+    return null;
+  }
+  
+  return result;
+}
+
+/**
+ * Resolve instance configuration from env file
+ */
+function resolveInstanceConfig(instanceName) {
+  const envFilePath = path.join(ENV_FILE_DIR, `${instanceName}.env`);
+  const envVars = parseEnvFile(envFilePath);
+  
+  if (!envVars) {
+    return null;
+  }
+  
+  const listenPort = envVars.LISTEN_PORT;
+  if (!listenPort) {
+    return null;
+  }
+  
+  return {
+    url: `http://127.0.0.1:${listenPort}`,
+    token: envVars.ADMIN_TOKEN || null,
+    instanceName,
+    envFilePath,
+  };
+}
+
+// =============================================================================
+// HTTP Client
+// =============================================================================
+
+async function request(url, options = {}) {
+  try {
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        ...options.headers,
+      },
+    });
+
+    const text = await response.text();
+    let data;
+
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = { raw: text };
+    }
+
+    return {
+      ok: response.ok,
+      status: response.status,
+      data,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      status: 0,
+      data: { error: err.message },
+    };
+  }
+}
+
+// =============================================================================
+// Commands
+// =============================================================================
+
+async function cmdStatus(baseUrl, token, options) {
+  const res = await request(`${baseUrl}/__status`, {
+    headers: { 'x-admin-token': token },
+  });
+
+  if (!res.ok) {
+    console.error(`${colors.red}Error:${colors.reset} ${res.data.error || 'Failed to fetch status'}`);
+    return 1;
+  }
+
+  const { instanceName, activePort, drainUntil, lastSwitch } = res.data;
+
+  if (options.json) {
+    console.log(JSON.stringify(res.data, null, 2));
+    return 0;
+  }
+
+  const title = instanceName && instanceName !== 'default' 
+    ? `Portok Status [${instanceName}]` 
+    : 'Portok Status';
+  console.log(`${colors.bold}${title}${colors.reset}`);
+  console.log(`${'─'.repeat(40)}`);
+  if (instanceName && instanceName !== 'default') {
+    console.log(`${colors.dim}Instance:${colors.reset}     ${instanceName}`);
+  }
+  console.log(`${colors.cyan}Active Port:${colors.reset}  ${colors.bold}${activePort}${colors.reset}`);
+
+  if (drainUntil) {
+    const drainTime = new Date(drainUntil);
+    const remaining = Math.max(0, drainTime - Date.now());
+    console.log(`${colors.yellow}Drain Until:${colors.reset}  ${drainUntil} (${Math.ceil(remaining / 1000)}s remaining)`);
+  } else {
+    console.log(`${colors.dim}Drain Until:${colors.reset}  ${colors.dim}none${colors.reset}`);
+  }
+
+  if (lastSwitch.at) {
+    console.log(`\n${colors.bold}Last Switch${colors.reset}`);
+    console.log(`  From:    ${lastSwitch.from}`);
+    console.log(`  To:      ${lastSwitch.to}`);
+    console.log(`  At:      ${lastSwitch.at}`);
+    console.log(`  Reason:  ${lastSwitch.reason}`);
+    console.log(`  ID:      ${colors.dim}${lastSwitch.id}${colors.reset}`);
+  }
+
+  return 0;
+}
+
+async function cmdMetrics(baseUrl, token, options) {
+  const res = await request(`${baseUrl}/__metrics`, {
+    headers: { 'x-admin-token': token },
+  });
+
+  if (!res.ok) {
+    console.error(`${colors.red}Error:${colors.reset} ${res.data.error || 'Failed to fetch metrics'}`);
+    return 1;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(res.data, null, 2));
+    return 0;
+  }
+
+  const m = res.data;
+
+  console.log(`${colors.bold}Portok Metrics${colors.reset}`);
+  console.log(`${'─'.repeat(50)}`);
+
+  console.log(`\n${colors.cyan}Traffic${colors.reset}`);
+  console.log(`  Total Requests:   ${m.totalRequests.toLocaleString()}`);
+  console.log(`  Rolling RPS(60s): ${colors.bold}${m.rollingRps60}${colors.reset}`);
+  console.log(`  Inflight:         ${m.inflight} (max: ${m.inflightMax})`);
+
+  console.log(`\n${colors.cyan}Status Codes${colors.reset}`);
+  console.log(`  2xx: ${colors.green}${m.statusCounters['2xx']}${colors.reset}`);
+  console.log(`  3xx: ${colors.blue}${m.statusCounters['3xx']}${colors.reset}`);
+  console.log(`  4xx: ${colors.yellow}${m.statusCounters['4xx']}${colors.reset}`);
+  console.log(`  5xx: ${colors.red}${m.statusCounters['5xx']}${colors.reset}`);
+
+  console.log(`\n${colors.cyan}Errors${colors.reset}`);
+  console.log(`  Proxy Errors:     ${m.totalProxyErrors}`);
+  if (m.lastProxyError) {
+    console.log(`  Last Error:       ${m.lastProxyError.message} @ ${m.lastProxyError.timestamp}`);
+  }
+
+  console.log(`\n${colors.cyan}Health${colors.reset}`);
+  const healthIcon = m.health.activePortOk ? `${colors.green}✓${colors.reset}` : `${colors.red}✗${colors.reset}`;
+  console.log(`  Active Port OK:   ${healthIcon}`);
+  console.log(`  Last Checked:     ${m.health.lastCheckedAt || 'never'}`);
+  console.log(`  Consecutive Fails: ${m.health.consecutiveFails}`);
+
+  console.log(`\n${colors.dim}Started: ${m.startedAt}${colors.reset}`);
+
+  return 0;
+}
+
+async function cmdSwitch(baseUrl, token, port, options) {
+  if (!port) {
+    console.error(`${colors.red}Error:${colors.reset} Port is required`);
+    console.error('Usage: portok switch <port>');
+    return 1;
+  }
+
+  const portNum = parseInt(port, 10);
+  if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+    console.error(`${colors.red}Error:${colors.reset} Invalid port: ${port}`);
+    return 1;
+  }
+
+  console.log(`${colors.cyan}Switching to port ${portNum}...${colors.reset}`);
+
+  const res = await request(`${baseUrl}/__switch?port=${portNum}`, {
+    method: 'POST',
+    headers: { 'x-admin-token': token },
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(res.data, null, 2));
+    return res.ok ? 0 : 1;
+  }
+
+  if (!res.ok) {
+    console.error(`${colors.red}Switch failed:${colors.reset} ${res.data.error || res.data.message || 'Unknown error'}`);
+    if (res.status === 409) {
+      console.error(`${colors.yellow}Hint:${colors.reset} The target port failed the health check.`);
+      console.error(`      Make sure your app is running and healthy on port ${portNum}.`);
+    }
+    return 1;
+  }
+
+  console.log(`${colors.green}✓ Switch successful!${colors.reset}`);
+  console.log(`  From: ${res.data.switch.from} → To: ${res.data.switch.to}`);
+  console.log(`  Switch ID: ${colors.dim}${res.data.switch.id}${colors.reset}`);
+
+  return 0;
+}
+
+// =============================================================================
+// Management Commands (init, add, list)
+// =============================================================================
+
+async function cmdInit(options) {
+  const configDir = ENV_FILE_DIR;
+  const stateDir = '/var/lib/portok';
+
+  console.log(`${colors.bold}Initializing Portok...${colors.reset}\n`);
+
+  // Check if running as root (needed for /etc and /var/lib)
+  const isRoot = process.getuid && process.getuid() === 0;
+
+  if (!isRoot && !options.force) {
+    console.log(`${colors.yellow}Warning:${colors.reset} This command typically requires root privileges.`);
+    console.log(`Run with sudo or use --force to attempt anyway.\n`);
+  }
+
+  const results = [];
+
+  // Create config directory
+  try {
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true, mode: 0o755 });
+      results.push({ path: configDir, status: 'created' });
+    } else {
+      results.push({ path: configDir, status: 'exists' });
+    }
+  } catch (err) {
+    results.push({ path: configDir, status: 'error', error: err.message });
+  }
+
+  // Create state directory
+  try {
+    if (!fs.existsSync(stateDir)) {
+      fs.mkdirSync(stateDir, { recursive: true, mode: 0o755 });
+      results.push({ path: stateDir, status: 'created' });
+    } else {
+      results.push({ path: stateDir, status: 'exists' });
+    }
+  } catch (err) {
+    results.push({ path: stateDir, status: 'error', error: err.message });
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, results }, null, 2));
+    return 0;
+  }
+
+  // Display results
+  for (const r of results) {
+    const icon = r.status === 'created' ? `${colors.green}✓${colors.reset}` :
+                 r.status === 'exists' ? `${colors.dim}○${colors.reset}` :
+                 `${colors.red}✗${colors.reset}`;
+    const status = r.status === 'created' ? 'Created' :
+                   r.status === 'exists' ? 'Already exists' :
+                   `Error: ${r.error}`;
+    console.log(`  ${icon} ${r.path} - ${status}`);
+  }
+
+  const hasError = results.some(r => r.status === 'error');
+  if (hasError) {
+    console.log(`\n${colors.red}Some directories could not be created.${colors.reset}`);
+    console.log('Try running with: sudo portok init');
+    return 1;
+  }
+
+  console.log(`\n${colors.green}Portok initialized successfully!${colors.reset}`);
+  console.log(`\nNext steps:`);
+  console.log(`  1. Create a service: ${colors.cyan}portok add <name>${colors.reset}`);
+  console.log(`  2. Or manually create: ${colors.dim}${configDir}/<name>.env${colors.reset}`);
+
+  return 0;
+}
+
+function generateToken(length = 32) {
+  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  let token = '';
+  const randomBytes = require('crypto').randomBytes(length);
+  for (let i = 0; i < length; i++) {
+    token += chars[randomBytes[i] % chars.length];
+  }
+  return token;
+}
+
+async function cmdAdd(name, options) {
+  if (!name) {
+    console.error(`${colors.red}Error:${colors.reset} Service name is required`);
+    console.error('Usage: portok add <name> [--port <listen_port>] [--target <target_port>]');
+    return 1;
+  }
+
+  // Validate name (alphanumeric, dash, underscore)
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name)) {
+    console.error(`${colors.red}Error:${colors.reset} Invalid service name '${name}'`);
+    console.error('Name must start with a letter and contain only letters, numbers, dashes, underscores.');
+    return 1;
+  }
+
+  const envFilePath = path.join(ENV_FILE_DIR, `${name}.env`);
+
+  // Check if already exists
+  if (fs.existsSync(envFilePath) && !options.force) {
+    console.error(`${colors.red}Error:${colors.reset} Service '${name}' already exists at ${envFilePath}`);
+    console.error('Use --force to overwrite.');
+    return 1;
+  }
+
+  // Get or generate configuration
+  const listenPort = options.port || (3000 + Math.floor(Math.random() * 1000));
+  const targetPort = options.target || (8000 + Math.floor(Math.random() * 1000));
+  const adminToken = options.token || generateToken();
+  const healthPath = options.health || '/health';
+
+  const envContent = `# Portok instance configuration for "${name}"
+# Generated by: portok add ${name}
+# Date: ${new Date().toISOString()}
+
+# Required: Port the proxy listens on
+LISTEN_PORT=${listenPort}
+
+# Required: Initial target port (your app's port)
+INITIAL_TARGET_PORT=${targetPort}
+
+# Required: Admin token for API authentication
+ADMIN_TOKEN=${adminToken}
+
+# Optional: Health check configuration
+HEALTH_PATH=${healthPath}
+HEALTH_TIMEOUT_MS=5000
+
+# Optional: Drain configuration (30 seconds)
+DRAIN_MS=30000
+
+# Optional: Rollback configuration
+ROLLBACK_WINDOW_MS=60000
+ROLLBACK_CHECK_EVERY_MS=5000
+ROLLBACK_FAIL_THRESHOLD=3
+`;
+
+  try {
+    // Check if directory exists
+    if (!fs.existsSync(ENV_FILE_DIR)) {
+      console.error(`${colors.red}Error:${colors.reset} Config directory ${ENV_FILE_DIR} does not exist.`);
+      console.error(`Run ${colors.cyan}sudo portok init${colors.reset} first.`);
+      return 1;
+    }
+
+    fs.writeFileSync(envFilePath, envContent, { mode: 0o600 });
+  } catch (err) {
+    console.error(`${colors.red}Error:${colors.reset} Could not create ${envFilePath}`);
+    console.error(err.message);
+    console.error(`Try running with: sudo portok add ${name}`);
+    return 1;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      success: true,
+      name,
+      envFile: envFilePath,
+      listenPort,
+      targetPort,
+      adminToken,
+    }, null, 2));
+    return 0;
+  }
+
+  console.log(`${colors.green}✓ Service '${name}' created successfully!${colors.reset}\n`);
+  console.log(`${colors.bold}Configuration:${colors.reset}`);
+  console.log(`  File:         ${envFilePath}`);
+  console.log(`  Listen Port:  ${colors.cyan}${listenPort}${colors.reset}`);
+  console.log(`  Target Port:  ${targetPort}`);
+  console.log(`  Admin Token:  ${colors.dim}${adminToken}${colors.reset}`);
+  console.log(`  Health Path:  ${healthPath}`);
+
+  console.log(`\n${colors.bold}Next steps:${colors.reset}`);
+  console.log(`  1. Start your app on port ${targetPort} with ${healthPath} endpoint`);
+  console.log(`  2. Start the service:`);
+  console.log(`     ${colors.cyan}sudo systemctl start portok@${name}${colors.reset}`);
+  console.log(`  3. Enable at boot:`);
+  console.log(`     ${colors.cyan}sudo systemctl enable portok@${name}${colors.reset}`);
+  console.log(`  4. Check status:`);
+  console.log(`     ${colors.cyan}portok status --instance ${name}${colors.reset}`);
+
+  return 0;
+}
+
+async function cmdList(options) {
+  const configDir = ENV_FILE_DIR;
+
+  if (!fs.existsSync(configDir)) {
+    if (options.json) {
+      console.log(JSON.stringify({ instances: [], error: 'Config directory not found' }, null, 2));
+    } else {
+      console.log(`${colors.yellow}No instances configured.${colors.reset}`);
+      console.log(`Run ${colors.cyan}sudo portok init${colors.reset} to initialize.`);
+    }
+    return 0;
+  }
+
+  // Find all .env files
+  let files;
+  try {
+    files = fs.readdirSync(configDir).filter(f => f.endsWith('.env'));
+  } catch (err) {
+    console.error(`${colors.red}Error:${colors.reset} Could not read ${configDir}: ${err.message}`);
+    return 1;
+  }
+
+  if (files.length === 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ instances: [] }, null, 2));
+    } else {
+      console.log(`${colors.yellow}No instances configured.${colors.reset}`);
+      console.log(`Run ${colors.cyan}portok add <name>${colors.reset} to create one.`);
+    }
+    return 0;
+  }
+
+  const instances = [];
+
+  for (const file of files) {
+    const name = file.replace('.env', '');
+    const envFilePath = path.join(configDir, file);
+    const config = parseEnvFile(envFilePath);
+
+    if (!config) continue;
+
+    const instance = {
+      name,
+      envFile: envFilePath,
+      listenPort: config.LISTEN_PORT ? parseInt(config.LISTEN_PORT) : null,
+      targetPort: config.INITIAL_TARGET_PORT ? parseInt(config.INITIAL_TARGET_PORT) : null,
+      healthPath: config.HEALTH_PATH || '/health',
+      status: 'unknown',
+    };
+
+    // Check if daemon is running (try to connect)
+    if (instance.listenPort && config.ADMIN_TOKEN) {
+      try {
+        const res = await request(`http://127.0.0.1:${instance.listenPort}/__status`, {
+          headers: { 'x-admin-token': config.ADMIN_TOKEN },
+        });
+        if (res.ok) {
+          instance.status = 'running';
+          instance.activePort = res.data.activePort;
+        } else {
+          instance.status = 'stopped';
+        }
+      } catch {
+        instance.status = 'stopped';
+      }
+    }
+
+    instances.push(instance);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ instances }, null, 2));
+    return 0;
+  }
+
+  console.log(`${colors.bold}Portok Instances${colors.reset}`);
+  console.log(`${'─'.repeat(70)}`);
+
+  if (instances.length === 0) {
+    console.log(`${colors.dim}No instances found.${colors.reset}`);
+    return 0;
+  }
+
+  // Table header
+  console.log(
+    `${'Name'.padEnd(15)} ` +
+    `${'Listen'.padEnd(8)} ` +
+    `${'Target'.padEnd(8)} ` +
+    `${'Active'.padEnd(8)} ` +
+    `${'Status'.padEnd(10)}`
+  );
+  console.log(`${'─'.repeat(70)}`);
+
+  for (const inst of instances) {
+    const statusColor = inst.status === 'running' ? colors.green :
+                        inst.status === 'stopped' ? colors.red : colors.dim;
+    const statusIcon = inst.status === 'running' ? '●' :
+                       inst.status === 'stopped' ? '○' : '?';
+
+    console.log(
+      `${inst.name.padEnd(15)} ` +
+      `${String(inst.listenPort || '-').padEnd(8)} ` +
+      `${String(inst.targetPort || '-').padEnd(8)} ` +
+      `${String(inst.activePort || '-').padEnd(8)} ` +
+      `${statusColor}${statusIcon} ${inst.status}${colors.reset}`
+    );
+  }
+
+  console.log(`\n${colors.dim}Total: ${instances.length} instance(s)${colors.reset}`);
+
+  return 0;
+}
+
+async function cmdHealth(baseUrl, token, options) {
+  const res = await request(`${baseUrl}/__health`, {
+    headers: { 'x-admin-token': token },
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(res.data, null, 2));
+    return res.ok ? 0 : 1;
+  }
+
+  if (res.ok && res.data.healthy) {
+    console.log(`${colors.green}✓ Healthy${colors.reset}`);
+    console.log(`  Active Port: ${res.data.activePort}`);
+    console.log(`  Checked At:  ${res.data.checkedAt}`);
+    return 0;
+  } else {
+    console.error(`${colors.red}✗ Unhealthy${colors.reset}`);
+    console.error(`  Active Port: ${res.data.activePort || 'unknown'}`);
+    console.error(`  Checked At:  ${res.data.checkedAt || 'unknown'}`);
+    return 1;
+  }
+}
+
+function showHelp() {
+  console.log(`
+${colors.bold}portok${colors.reset} - CLI for portokd zero-downtime proxy daemon
+
+${colors.bold}USAGE${colors.reset}
+  portok <command> [options]
+
+${colors.bold}COMMANDS${colors.reset}
+  ${colors.cyan}Management:${colors.reset}
+  init            Initialize portok directories (/etc/portok, /var/lib/portok)
+  add <name>      Create a new service instance
+  list            List all configured instances and their status
+
+  ${colors.cyan}Operations:${colors.reset}
+  status          Show current proxy status (activePort, drainUntil, lastSwitch)
+  metrics         Show proxy metrics (requests, errors, health, RPS)
+  switch <port>   Switch to a new target port (with health check)
+  health          Check health of the current active port
+
+${colors.bold}OPTIONS${colors.reset}
+  --url <url>       Daemon URL (default: http://127.0.0.1:3000)
+  --instance <name> Target instance by name (reads /etc/portok/<name>.env)
+  --token <token>   Admin token for authentication
+  --json            Output as JSON (for scripting)
+  --help            Show this help message
+
+  ${colors.dim}For 'add' command:${colors.reset}
+  --port <port>     Listen port (default: random 3000-3999)
+  --target <port>   Target port (default: random 8000-8999)
+  --health <path>   Health check path (default: /health)
+  --force           Overwrite existing config
+
+${colors.bold}EXAMPLES${colors.reset}
+  ${colors.dim}# Initialize portok (run once, requires sudo)${colors.reset}
+  sudo portok init
+
+  ${colors.dim}# Create a new service${colors.reset}
+  sudo portok add api --port 3001 --target 8001
+  sudo portok add web --port 3002 --target 8002
+
+  ${colors.dim}# List all instances${colors.reset}
+  portok list
+
+  ${colors.dim}# Check status of an instance${colors.reset}
+  portok status --instance api
+
+  ${colors.dim}# Switch to new port${colors.reset}
+  portok switch 8081 --instance api
+
+  ${colors.dim}# Get metrics as JSON${colors.reset}
+  portok metrics --instance api --json
+
+  ${colors.dim}# Direct URL mode (without instance)${colors.reset}
+  portok status --url http://127.0.0.1:3000 --token mysecret
+
+${colors.bold}MULTI-INSTANCE${colors.reset}
+  When using --instance, the CLI reads /etc/portok/<name>.env
+  to resolve LISTEN_PORT and ADMIN_TOKEN for that instance.
+  Explicit --url and --token flags override env file values.
+
+${colors.bold}EXIT CODES${colors.reset}
+  0  Success
+  1  Failure (error or unhealthy)
+`);
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  // Help flag
+  if (args.options.help || args.command === 'help') {
+    showHelp();
+    process.exit(0);
+  }
+
+  // Management commands (don't require daemon connection)
+  const managementCommands = ['init', 'add', 'list'];
+
+  if (managementCommands.includes(args.command)) {
+    let exitCode = 1;
+    switch (args.command) {
+      case 'init':
+        exitCode = await cmdInit(args.options);
+        break;
+      case 'add':
+        exitCode = await cmdAdd(args.positional[0], args.options);
+        break;
+      case 'list':
+        exitCode = await cmdList(args.options);
+        break;
+    }
+    process.exit(exitCode);
+  }
+
+  // Operational commands require authentication
+  // Get configuration - support --instance flag
+  let baseUrl = args.options.url || process.env.PORTOK_URL;
+  let token = args.options.token || process.env.PORTOK_TOKEN;
+
+  // If --instance is provided, resolve from env file
+  if (args.options.instance) {
+    const instanceConfig = resolveInstanceConfig(args.options.instance);
+    
+    if (!instanceConfig) {
+      console.error(`${colors.red}Error:${colors.reset} Could not resolve instance '${args.options.instance}'`);
+      console.error(`Make sure ${ENV_FILE_DIR}/${args.options.instance}.env exists and contains LISTEN_PORT`);
+      process.exit(1);
+    }
+    
+    // Env file values are defaults; explicit flags override
+    if (!baseUrl) baseUrl = instanceConfig.url;
+    if (!token) token = instanceConfig.token;
+  }
+
+  // Apply final defaults
+  baseUrl = baseUrl || 'http://127.0.0.1:3000';
+
+  if (!token) {
+    console.error(`${colors.red}Error:${colors.reset} Admin token is required`);
+    console.error('Set --token flag, PORTOK_TOKEN env var, or use --instance with ADMIN_TOKEN in env file');
+    process.exit(1);
+  }
+
+  // Route to operational command
+  let exitCode = 1;
+
+  switch (args.command) {
+    case 'status':
+      exitCode = await cmdStatus(baseUrl, token, args.options);
+      break;
+    case 'metrics':
+      exitCode = await cmdMetrics(baseUrl, token, args.options);
+      break;
+    case 'switch':
+      exitCode = await cmdSwitch(baseUrl, token, args.positional[0], args.options);
+      break;
+    case 'health':
+      exitCode = await cmdHealth(baseUrl, token, args.options);
+      break;
+    default:
+      if (args.command) {
+        console.error(`${colors.red}Unknown command:${colors.reset} ${args.command}`);
+      } else {
+        console.error(`${colors.red}No command specified${colors.reset}`);
+      }
+      showHelp();
+      exitCode = 1;
+  }
+
+  process.exit(exitCode);
+}
+
+main().catch((err) => {
+  console.error(`${colors.red}Fatal error:${colors.reset} ${err.message}`);
+  process.exit(1);
+});
+