@celilo/cli 0.1.0

package/src/cli/index.ts

@@ -0,0 +1,1583 @@
+/**
+ * CLI Entry Point
+ *
+ * Orchestration function (Rule 10.1) - routes commands to handlers
+ */
+
+import * as p from '@clack/prompts';
+import { CLIServerRequestSchema, parseJsonWithValidation } from '../validation/schemas';
+import { COMMANDS, type CommandDef } from './command-registry';
+import { handleCapabilityInfo } from './commands/capability-info';
+import { handleCapabilityList } from './commands/capability-list';
+import { handleCompletion } from './commands/completion';
+import { handleHookRun } from './commands/hook-run';
+import {
+  handleIpamIpListReservations,
+  handleIpamIpReserve,
+  handleIpamIpUnreserve,
+  handleIpamListAllocations,
+  handleIpamShow,
+  handleIpamVmidListReservations,
+  handleIpamVmidReserve,
+  handleIpamVmidUnreserve,
+} from './commands/ipam';
+import { handleMachineAdd } from './commands/machine-add';
+import { handleMachineEarmark } from './commands/machine-earmark';
+import { handleMachineList } from './commands/machine-list';
+import { handleMachineRemove } from './commands/machine-remove';
+import { handleMachineStatus } from './commands/machine-status';
+import { moduleAudit } from './commands/module-audit';
+import { handleModuleBuild } from './commands/module-build';
+import { handleModuleConfigGet, handleModuleConfigSet } from './commands/module-config';
+import { handleModuleDeploy } from './commands/module-deploy';
+import { handleModuleGenerate } from './commands/module-generate';
+import { handleModuleHealth } from './commands/module-health';
+import { handleModuleImport } from './commands/module-import';
+import { handleModuleList } from './commands/module-list';
+import { handleModuleLogs } from './commands/module-logs';
+import { handleModuleRemove } from './commands/module-remove';
+import { handleModuleShowConfig, handleModuleShowZone } from './commands/module-show';
+import { handleModuleStatus } from './commands/module-status';
+import { handleModuleTypesCheck, handleModuleTypesGenerate } from './commands/module-types';
+import { handleModuleUpgrade } from './commands/module-upgrade';
+import { handlePackage } from './commands/package';
+import { handleSecretList } from './commands/secret-list';
+import { handleSecretSet } from './commands/secret-set';
+import { handleServiceAddDigitalOcean } from './commands/service-add-digitalocean';
+import { handleServiceAddProxmox } from './commands/service-add-proxmox';
+import { handleServiceConfigGet } from './commands/service-config-get';
+import { handleServiceConfigSet } from './commands/service-config-set';
+import { handleServiceList } from './commands/service-list';
+import { handleServiceReconfigure } from './commands/service-reconfigure';
+import { handleServiceRemove } from './commands/service-remove';
+import { handleServiceVerify } from './commands/service-verify';
+import { handleStatus } from './commands/status';
+import { handleSystemConfigGet, handleSystemConfigSet } from './commands/system-config';
+import { handleSystemInit } from './commands/system-init';
+import { handleSystemSecretGet } from './commands/system-secret-get';
+import { handleSystemSecretSet } from './commands/system-secret-set';
+import { handleSystemVaultPassword } from './commands/system-vault-password';
+import { getCompletions } from './completion';
+import { parseArguments, validateFlags } from './parser';
+import type { CommandResult } from './types';
+
+/**
+ * Look up a command definition from the registry and validate flags.
+ * Walks the full subcommand chain (e.g., ipam -> ip -> reserve) to find
+ * the leaf command where flags are defined.
+ * Returns an error CommandResult if unknown flags are found, or null if valid.
+ */
+function checkFlags(
+  command: string,
+  subcommand: string | undefined,
+  flags: Record<string, string | boolean>,
+  args: string[] = [],
+): CommandResult | null {
+  // Skip validation for help requests
+  if (flags.help || flags.h) return null;
+
+  const topDef = COMMANDS.find((c) => c.name === command);
+  if (!topDef) return null;
+
+  let commandDef: CommandDef | undefined = subcommand
+    ? topDef.subcommands?.find((s) => s.name === subcommand)
+    : topDef;
+  if (!commandDef) return null;
+
+  // Walk deeper into nested subcommands using args
+  // e.g., for "ipam ip reserve", subcommand='ip' and args=['reserve', ...]
+  // We need to find the 'reserve' sub-subcommand to get its flags
+  for (const arg of args) {
+    const deeper: CommandDef | undefined = commandDef?.subcommands?.find((s) => s.name === arg);
+    if (!deeper) break;
+    commandDef = deeper;
+  }
+
+  if (!commandDef) return null;
+
+  const error = validateFlags(flags, commandDef);
+  if (error) {
+    return { success: false, error };
+  }
+  return null;
+}
+
+/**
+ * Display general help message
+ */
+function displayHelp(): CommandResult {
+  const helpText = `
+Celilo - Home Lab Orchestration System
+
+Usage:
+  celilo <command> [subcommand] [args...] [options]
+
+Commands:
+  status                   Show system and module status
+  capability               View registered module capabilities
+  package                  Create distributable .netapp packages from module source
+  module                   Manage modules (import, list, configure, build, generate)
+  service                  Manage container services (Proxmox, Digital Ocean)
+  storage                  Manage backup storage destinations
+  backup                   Create and manage backups
+  machine                  Manage machine pool (bring-your-own-hardware)
+  system                   Manage system configuration
+  ipam                     Manage IP address and VMID allocations and reservations
+  completion               Generate shell completion scripts (bash/zsh)
+
+  help, --help, -h         Show this help message
+
+For command-specific help:
+  celilo package --help
+  celilo module --help
+  celilo secret --help
+  celilo service --help
+  celilo machine --help
+  celilo system --help
+  celilo ipam --help
+
+Enable tab completion:
+  # Bash
+  celilo completion bash >> ~/.bashrc && source ~/.bashrc
+  # Zsh
+  celilo completion zsh >> ~/.zshrc && source ~/.zshrc
+
+Examples:
+  celilo package ./modules/homebridge
+  celilo module import ./modules/homebridge
+  celilo module list
+  celilo module build caddy
+  celilo module secret set homebridge api_key mykey123
+  celilo system config set dns.primary 192.168.0.1
+  celilo system vault-password
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Display package command help
+ */
+function displayPackageHelp(): CommandResult {
+  const helpText = `
+Celilo - Module Packaging
+
+Usage:
+  celilo package <source-directory> [options]
+
+Description:
+  Creates a distributable .netapp package from a module source directory.
+  The package includes checksums and a signature for integrity verification.
+
+Options:
+  --output <path>    Output path for the package (default: <source-dir>/<module-id>.netapp)
+
+Examples:
+  celilo package ./modules/homebridge
+  celilo package ./my-module --output /tmp/test.netapp
+  celilo package ../custom-module
+
+Related Commands:
+  celilo module import <package.netapp>    Import a packaged module
+  celilo module audit <module-id>          Verify package integrity
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Display capability command help
+ */
+function displayCapabilityHelp(): CommandResult {
+  const helpText = `
+Celilo - Capability Management
+
+Usage:
+  celilo capability <subcommand> [args...]
+
+Subcommands:
+  list                    List all registered capabilities
+  info <name>             Show detailed capability information
+
+Description:
+  Capabilities are cross-module data contracts. A module can "provide" a capability
+  (e.g., dns_registrar) and other modules can "require" it to access shared data
+  and secrets.
+
+  Capabilities are automatically registered when importing modules that declare
+  "provides.capabilities" in their manifest.
+
+Examples:
+  celilo capability list
+  celilo capability info dns_registrar
+  celilo capability info public_web
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Display module command help
+ */
+function displayModuleHelp(): CommandResult {
+  const helpText = `
+Celilo - Module Management
+
+Usage:
+  celilo module <subcommand> [args...] [options]
+
+Subcommands:
+  import <path>                        Import a module from directory or .netapp file
+    Options:
+      --target <path>                  Target base directory (default: platform-specific)
+      --auto-generate-secrets          Auto-generate all secrets without prompting
+
+  list                                 List all installed modules
+
+  remove <id>                          Remove a module and all its data
+
+  audit <id>                           Verify module integrity (checksums)
+
+  config set <id> <key> <value>        Set module configuration value
+  config get <id> [key]                Get module configuration value(s)
+
+  secret set <id> <key> <value>        Set encrypted module secret
+  secret list <id>                     List module secrets
+
+  show-config <id>                     Show all config including auto-derived values
+  show-zone <id>                       Show module's network zone and config
+
+  build <module-id>                    Execute build scripts (Nix + Ansible)
+
+  generate <id>                        Generate infrastructure code for module
+    Options:
+      --output <path>                  Output directory (default: <module>/generated)
+
+  deploy <module-id>                   Deploy module to infrastructure (auto-generates/builds if needed)
+    Options:
+      --debug                            Run hooks with visible browser (Playwright)
+      --no-interactive                   Fail instead of prompting for missing config
+
+  health [module-id]                    Run health checks (transitions to VERIFIED on success)
+    Options:
+      --json                             Machine-readable JSON output
+      --debug                            Show detailed check output
+
+  run-hook <id> <hook-name> [k=v...]   Run a module hook (e.g., retry on_install after fixing an issue)
+    Options:
+      --debug                            Run with visible browser (Playwright hooks)
+
+  update <path> [path...]               Update module code while preserving state (configs, secrets, infra)
+
+Examples:
+  celilo module import ./modules/homebridge
+  celilo module import homebridge.netapp
+  celilo module import /abs/path/to/module --target /custom/location
+  celilo module list
+  celilo module remove homebridge
+  celilo module audit homebridge
+  celilo module config set homebridge hostname myhost
+  celilo module config set homebridge container_ip "192.168.0.110/24"
+  celilo module config get homebridge
+  celilo module config get homebridge hostname
+  celilo module show-config homebridge
+  celilo module show-zone homebridge
+  celilo module build caddy
+  celilo module generate homebridge
+  celilo module generate homebridge --output /custom/output
+  celilo module deploy homebridge
+  celilo module deploy caddy
+  celilo module run-hook caddy on_install
+  celilo module run-hook namecheap validate_config --debug
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Display service command help
+ */
+function displayServiceHelp(): CommandResult {
+  const helpText = `
+Celilo - Container Service Management
+
+Usage:
+  celilo service <subcommand> [args...] [options]
+
+Subcommands:
+  add proxmox           Configure a Proxmox container service
+  add digitalocean      Configure a Digital Ocean VPS service
+  list                  List all configured container services
+    Options:
+      --zone <zone>     Filter by network zone
+  verify <service-id>   Re-verify a container service connection
+  reconfigure <service-id>  Re-run configuration interview (change template, storage, etc.)
+  remove <id>           Remove a container service
+    Options:
+      --force           Skip confirmation prompts
+  config get <service-id> [key]       Get service configuration
+  config set <service-id> <key> <value>  Set service configuration
+
+Description:
+  Container services are API-driven infrastructure providers that can automatically
+  provision containers/VMs for modules. Celilo prefers container services over
+  manually-added machines when selecting infrastructure during module generation.
+
+  Supported providers:
+    - Proxmox: LXC containers on home lab hardware
+    - Digital Ocean: Cloud VPS instances
+
+Examples:
+  # Add container services
+  celilo service add proxmox
+  celilo service add digitalocean
+
+  # List all services
+  celilo service list
+
+  # List services for specific zone
+  celilo service list --zone dmz
+
+  # Verify a service connection
+  celilo service verify proxmox-home-lab
+
+  # Get service configuration
+  celilo service config get proxmox-home-lab
+  celilo service config get proxmox-home-lab name
+  celilo service config get proxmox-home-lab zones
+
+  # Set service configuration
+  celilo service config set proxmox-home-lab name "New Service Name"
+  celilo service config set proxmox-home-lab zones '["dmz", "app"]'
+  celilo service config set proxmox-home-lab providerConfig '{"storage": "local-lvm"}'
+
+  # Remove service
+  celilo service remove <service-id>
+  celilo service remove <service-id> --force
+
+Related Commands:
+  celilo module generate <module-id>    Generate infrastructure code (uses services)
+  celilo module deploy <module-id>      Deploy module to infrastructure
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Display backup command help
+ */
+function displayBackupHelp(): CommandResult {
+  const helpText = `
+Celilo - Backup Management
+
+Usage:
+  celilo backup <subcommand> [args...] [options]
+
+Subcommands:
+  create [module-id]       Create a backup (system state + modules, or specific module)
+    Options:
+      --force              Ignore schedule, back up now
+      --storage <id>       Use specific storage destination
+      --no-interactive     Non-interactive mode (for cron)
+
+  list [module-id]         List available backups
+    Options:
+      --limit <n>          Number of backups to show (default: 20)
+
+  restore <backup-id>      Restore from a backup
+    Options:
+      --yes                Skip confirmation prompt
+
+  delete <backup-id>       Delete a specific backup
+    Options:
+      --force              Skip confirmation prompt
+
+  prune [module-id]        Remove old backups per retention policies
+    Options:
+      --dry-run            Show what would be deleted without deleting
+
+  name <backup-id> [name]  Get or set a human-readable name on a backup
+    Options:
+      --clear              Remove the name
+
+  import <file> <module>   Import a local file as a module backup
+    Options:
+      --name <name>        Human-readable name for the backup
+      --schema-version <v> Schema version metadata
+      --storage <id>       Use specific storage destination
+      --yes                Skip confirmation prompt
+
+Description:
+  Backups are encrypted with the master key and uploaded to a configured
+  storage destination. System state backups capture the Celilo database.
+  Module data backups use on_backup hooks defined in module manifests.
+
+  Any command that accepts a <backup-id> also accepts a backup name.
+  Use "celilo backup name" to assign human-readable names.
+
+Examples:
+  # Create a full backup (system + all due modules)
+  celilo backup create
+
+  # Back up a specific module
+  celilo backup create authentik --force
+
+  # List recent backups
+  celilo backup list
+  celilo backup list authentik --limit 5
+
+  # Restore from a backup
+  celilo backup restore <backup-id>
+
+  # Name a backup
+  celilo backup name <backup-id> Data from beso before migration
+  celilo backup name <backup-id> --clear
+
+  # Prune old backups
+  celilo backup prune --dry-run
+  celilo backup prune
+
+  # Import a local file as a backup
+  celilo backup import ./backups/db.sqlite lunacycle --name "pre-migration"
+
+Related Commands:
+  celilo storage add local         Add backup storage destination
+  celilo storage list              List storage destinations
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Display storage command help
+ */
+function displayStorageHelp(): CommandResult {
+  const helpText = `
+Celilo - Backup Storage Management
+
+Usage:
+  celilo storage <subcommand> [args...] [options]
+
+Subcommands:
+  add local             Add local filesystem storage
+  add s3                Add S3-compatible storage (AWS, MinIO, B2, Wasabi, GCS)
+  list                  List all configured storage destinations
+  verify <storage-id>   Test storage connectivity and permissions
+  set-default <id>      Set the default backup storage destination
+  remove <storage-id>   Remove a storage destination
+    Options:
+      --force           Skip confirmation prompts
+
+Description:
+  Backup storage destinations are where Celilo sends encrypted backup archives.
+  You must configure at least one storage destination before creating backups.
+
+Examples:
+  # Add local storage
+  celilo storage add local
+
+  # List storage destinations
+  celilo storage list
+
+  # Verify storage connectivity
+  celilo storage verify local-backups
+
+  # Set default destination
+  celilo storage set-default local-backups
+
+  # Remove storage
+  celilo storage remove local-backups --force
+
+Related Commands:
+  celilo backup create              Create a backup
+  celilo backup list                List available backups
+  celilo backup restore <id>        Restore from a backup
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Display machine command help
+ */
+function displayMachineHelp(): CommandResult {
+  const helpText = `
+Celilo - Machine Pool Management
+
+Usage:
+  celilo machine <subcommand> [args...] [options]
+
+Subcommands:
+  add                   Add a machine to the pool with auto-detection
+    Interactive mode (prompts for input):
+      celilo machine add
+
+    Non-interactive mode:
+      celilo machine add --ip <ip> --ssh-user <user> --ssh-key-file <path>
+    Options:
+      --ip <ip>              Machine IP address
+      --ssh-user <user>      SSH username (default: root)
+      --ssh-key-file <path>  Path to SSH private key
+
+  list                  List all machines in the pool
+    Options:
+      --zone <zone>        Filter by network zone
+
+  status <hostname>     Show detailed machine status with live connectivity
+
+  remove <hostname>     Remove a machine from the pool
+    Options:
+      --force              Skip confirmation prompts
+
+Description:
+  The machine pool contains bring-your-own-hardware: existing machines like
+  Raspberry Pis, VPS instances, or bare metal servers that you manually add
+  to Celilo.
+
+  When adding a machine, Celilo automatically:
+    - Tests SSH connectivity
+    - Detects hostname, CPU, memory, disk
+    - Detects network zone from IP address
+    - Encrypts and stores SSH key for Ansible deployments
+
+  Celilo prefers container services over machine pool when selecting
+  infrastructure during module generation.
+
+Examples:
+  # Add machine interactively
+  celilo machine add
+
+  # Add machine non-interactively
+  celilo machine add --ip 192.168.1.100 --ssh-user ubuntu --ssh-key-file ~/.ssh/id_ed25519
+
+  # List all machines
+  celilo machine list
+
+  # List machines in specific zone
+  celilo machine list --zone dmz
+
+  # Show machine status
+  celilo machine status pi-01
+
+  # Earmark machine for a module
+  celilo machine earmark 10.0.10.10 caddy
+  celilo machine earmark pi-01 --clear
+
+  # Remove machine (by hostname or IP)
+  celilo machine remove pi-01
+  celilo machine remove 10.0.10.10 --force
+
+Related Commands:
+  celilo service list              List container services
+  celilo module generate <id>      Generate infrastructure code (selects infrastructure)
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Display IPAM command help
+ */
+function displayIpamHelp(): CommandResult {
+  const helpText = `
+Celilo - IPAM (IP Address Management)
+
+Usage:
+  celilo ipam <resource> <action> [args...] [options]
+
+Resources:
+  vmid          Manage VMID reservations and allocations
+  ip            Manage IP address reservations
+  list-allocations    List all IPAM allocations (VMIDs and IPs)
+
+VMID Commands:
+  celilo ipam vmid reserve <vmid-or-range> --reason <reason>
+  celilo ipam vmid unreserve <vmid-or-range>
+  celilo ipam vmid list-reservations
+
+IP Commands:
+  celilo ipam ip exclude <ip-range> --reason <reason> [--zone <zone>]
+  celilo ipam ip include <ip-or-range> [--zone <zone>]
+  celilo ipam ip list-exclusions
+
+Description:
+  IPAM automatically allocates VMIDs and IP addresses during module generation.
+  Exclusions prevent IPAM from allocating specific IPs (e.g., DHCP ranges, infrastructure).
+
+  VMIDs start at 2100 and increment sequentially.
+  IPs are allocated from zone subnets (network.{zone}.subnet).
+  Zone is auto-detected from the IP address unless overridden with --zone.
+
+Examples:
+  # Reserve VMID for existing VM
+  celilo ipam vmid reserve 2100 --reason "Existing Proxmox VM"
+  celilo ipam vmid reserve 2100-2110 --reason "Reserved range"
+
+  # Exclude IPs from IPAM allocation (zone auto-detected from IP)
+  celilo ipam ip exclude 10.0.10.1-10.0.10.9 --reason "Infrastructure"
+  celilo ipam ip exclude 192.168.0.1-192.168.0.150 --reason "DHCP managed range"
+
+  # List allocations and reservations
+  celilo ipam list-allocations
+  celilo ipam vmid list-reservations
+  celilo ipam ip list-reservations
+
+  # Remove reservations
+  celilo ipam vmid unreserve 2100
+  celilo ipam ip unreserve 10.0.10.1 --zone dmz
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Display system command help
+ */
+function displaySystemHelp(): CommandResult {
+  const helpText = `
+Celilo - System Configuration
+
+Usage:
+  celilo system <subcommand> [args...]
+
+Subcommands:
+  init [--accept-defaults] [key=val...] Initialize system with guided setup or defaults
+
+  config set <key> <value>             Set system-wide configuration value
+  config get [key]                     Get system configuration value(s)
+
+  secret set <key> <value>             Set encrypted system-level secret
+  secret get [key]                     Get decrypted system secret value(s)
+
+  vault-password                       Get Ansible Vault password for decrypting secrets.yml
+
+Description:
+  System initialization (init) guides you through first-time setup with interactive
+  prompts or applies sensible defaults for testing.
+
+  System configuration stores values that are shared across all modules, such as
+  DNS servers, network settings, and domain information. These values can be
+  referenced in module templates using $system:key.path syntax.
+
+  System secrets store encrypted sensitive values like passwords and tokens.
+  Note: Provider-specific credentials (Proxmox, DigitalOcean, etc.) are managed
+  via 'celilo service' commands, not system secrets.
+
+Examples:
+  # Initialize system (first-time setup)
+  celilo system init
+  celilo system init --accept-defaults
+  celilo system init --accept-defaults primary_domain=example.com dns.primary=1.1.1.1
+
+  # Set DNS configuration
+  celilo system config set dns.primary 192.168.0.1
+  celilo system config set dns.fallback "8.8.8.8 1.1.1.1"
+
+  # Set network configuration
+  celilo system config set network.bridge vmbr0
+  celilo system config set network.dmz.subnet 10.0.10.0/24
+
+  # Get specific value
+  celilo system config get dns.primary
+
+  # Get all system config
+  celilo system config get
+  celilo system secret get
+
+  # Get vault password for Ansible
+  celilo system vault-password
+
+Using Vault Password:
+  # View encrypted Ansible secrets
+  ansible-vault view secrets.yml \\
+    --vault-password-file=<(celilo system vault-password)
+
+  # Run Ansible playbook with encrypted secrets
+  ansible-playbook playbook.yml \\
+    --vault-password-file=<(celilo system vault-password)
+
+  # Edit encrypted secrets
+  ansible-vault edit secrets.yml \\
+    --vault-password-file=<(celilo system vault-password)
+`;
+
+  return {
+    success: true,
+    message: helpText.trim(),
+  };
+}
+
+/**
+ * Route command to appropriate handler
+ *
+ * @param argv - Command-line arguments
+ * @returns Command result
+ */
+export async function runCli(argv: string[]): Promise<CommandResult> {
+  const parsed = parseArguments(argv);
+
+  // Handle --get-completions for shell completion (must be before other processing)
+  if (parsed.flags['get-completions']) {
+    try {
+      // Arguments: celilo --get-completions word1 word2 ... currentIndex
+      // The words array and current index are passed as remaining args
+      const words = parsed.args.slice(0, -1); // All args except last
+      const currentStr = parsed.args[parsed.args.length - 1]; // Last arg is the index
+      const current = Number.parseInt(currentStr || '0', 10);
+
+      const suggestions = await getCompletions(words, current);
+
+      // Return suggestions as newline-separated list (for zsh array splitting)
+      return {
+        success: true,
+        message: suggestions.join('\n'),
+      };
+    } catch (_error) {
+      // Silent failure for completion errors
+      return { success: true, message: '' };
+    }
+  }
+
+  // Handle general help (only if no specific command, or command is 'help')
+  if (parsed.command === 'help') {
+    return displayHelp();
+  }
+
+  // Handle completion command
+  if (parsed.command === 'completion') {
+    // Completion is a simple command without subcommands
+    // If parser treated first arg as subcommand, prepend it to args
+    const completionArgs = parsed.subcommand ? [parsed.subcommand, ...parsed.args] : parsed.args;
+    return handleCompletion(completionArgs, parsed.flags);
+  }
+
+  // Handle status command
+  if (parsed.command === 'status') {
+    return handleStatus();
+  }
+
+  // Route commands
+  if (parsed.command === 'package') {
+    // Handle package --help
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayPackageHelp();
+    }
+
+    // Package is a simple command without subcommands
+    // If parser treated first arg as subcommand, prepend it to args
+    const packageArgs = parsed.subcommand ? [parsed.subcommand, ...parsed.args] : parsed.args;
+    return handlePackage(packageArgs, parsed.flags);
+  }
+
+  if (parsed.command === 'hook') {
+    if (parsed.flags.help || parsed.flags.h) {
+      return {
+        success: true,
+        message: [
+          'Hook commands:',
+          '',
+          '  celilo hook run <module-id> <hook-name> [--debug] [key=value...]',
+          '',
+          'Options:',
+          '  --debug    Run with visible browser (Playwright hooks)',
+          '',
+          'Examples:',
+          '  celilo hook run namecheap validate_config --debug',
+          '  celilo hook run namecheap container_created vps_ip=138.68.140.177',
+        ].join('\n'),
+      };
+    }
+
+    if (parsed.subcommand === 'run') {
+      return handleHookRun(parsed.args, parsed.flags);
+    }
+
+    return {
+      success: false,
+      error: 'Hook subcommand required\n\nRun "celilo hook --help" for usage',
+    };
+  }
+
+  if (parsed.command === 'capability') {
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayCapabilityHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'Capability subcommand required\n\nRun "celilo capability --help" for usage',
+      };
+    }
+
+    const capFlagError = checkFlags('capability', parsed.subcommand, parsed.flags, parsed.args);
+    if (capFlagError) return capFlagError;
+
+    if (parsed.subcommand === 'list') {
+      return handleCapabilityList();
+    }
+
+    if (parsed.subcommand === 'info') {
+      return handleCapabilityInfo(parsed.args);
+    }
+
+    return {
+      success: false,
+      error: `Unknown capability subcommand: ${parsed.subcommand}\n\nRun "celilo capability --help" for usage`,
+    };
+  }
+
+  if (parsed.command === 'module') {
+    // Handle module --help
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayModuleHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'Module subcommand required\n\nRun "celilo module --help" for usage',
+      };
+    }
+
+    const flagError = checkFlags('module', parsed.subcommand, parsed.flags, parsed.args);
+    if (flagError) return flagError;
+
+    switch (parsed.subcommand) {
+      case 'import':
+        return handleModuleImport(parsed.args, parsed.flags);
+      case 'list':
+        return handleModuleList();
+      case 'status':
+        return handleModuleStatus(parsed.args);
+      case 'logs':
+        return handleModuleLogs(parsed.args, parsed.flags);
+      case 'health':
+        return handleModuleHealth(parsed.args, parsed.flags);
+      case 'remove':
+        return handleModuleRemove(parsed.args, parsed.flags);
+      case 'update':
+        return handleModuleUpgrade(parsed.args, parsed.flags);
+      case 'audit':
+        return moduleAudit(parsed.args);
+      case 'config': {
+        // Config requires additional subcommand (set/get)
+        const configSubcommand = parsed.args[0];
+        if (!configSubcommand) {
+          return {
+            success: false,
+            error: 'Config action required (set or get)\n\nRun "celilo help" for usage',
+          };
+        }
+        const configArgs = parsed.args.slice(1);
+        if (configSubcommand === 'set') {
+          return handleModuleConfigSet(configArgs);
+        }
+        if (configSubcommand === 'get') {
+          return handleModuleConfigGet(configArgs);
+        }
+        return {
+          success: false,
+          error: `Unknown config action: ${configSubcommand}`,
+        };
+      }
+      case 'secret': {
+        // Module secret requires additional subcommand (set/list)
+        const moduleSecretSubcommand = parsed.args[0];
+        if (!moduleSecretSubcommand) {
+          return {
+            success: false,
+            error:
+              'Secret action required (set or list)\n\nUsage:\n  celilo module secret set <module-id> <key> <value>\n  celilo module secret list <module-id>',
+          };
+        }
+        const moduleSecretArgs = parsed.args.slice(1);
+        if (moduleSecretSubcommand === 'set') {
+          return handleSecretSet(moduleSecretArgs);
+        }
+        if (moduleSecretSubcommand === 'list') {
+          return handleSecretList(moduleSecretArgs);
+        }
+        return {
+          success: false,
+          error: `Unknown secret action: ${moduleSecretSubcommand}`,
+        };
+      }
+      case 'types': {
+        // Types requires additional subcommand (generate/check)
+        const typesSubcommand = parsed.args[0];
+        if (!typesSubcommand) {
+          return {
+            success: false,
+            error:
+              'Types action required (generate or check)\n\nUsage:\n  celilo module types generate <module-dir>\n  celilo module types check <module-dir>',
+          };
+        }
+        const typesArgs = parsed.args.slice(1);
+        if (typesSubcommand === 'generate') {
+          return handleModuleTypesGenerate(typesArgs);
+        }
+        if (typesSubcommand === 'check') {
+          return handleModuleTypesCheck(typesArgs);
+        }
+        return {
+          success: false,
+          error: `Unknown types action: ${typesSubcommand}\n\nAvailable: generate, check`,
+        };
+      }
+      case 'generate':
+        return handleModuleGenerate(parsed.args, parsed.flags);
+      case 'build':
+        return handleModuleBuild(parsed.args, parsed.flags);
+      case 'deploy':
+        return handleModuleDeploy(parsed.args, parsed.flags);
+      case 'validate':
+        // Alias for `module deploy --preflight`
+        return handleModuleDeploy(parsed.args, { ...parsed.flags, preflight: true });
+      case 'run-hook':
+        return handleHookRun(parsed.args, parsed.flags);
+      case 'show-config':
+        return handleModuleShowConfig(parsed.args);
+      case 'show-zone':
+        return handleModuleShowZone(parsed.args);
+      default:
+        return {
+          success: false,
+          error: `Unknown module subcommand: ${parsed.subcommand}\n\nRun "celilo help" for usage`,
+        };
+    }
+  }
+
+  if (parsed.command === 'secret') {
+    return {
+      success: false,
+      error:
+        'The top-level "secret" command has been moved.\n\nUse:\n  celilo module secret set <module-id> <key> <value>\n  celilo module secret list <module-id>\n  celilo system secret set <key> <value>\n  celilo system secret get <key>',
+    };
+  }
+
+  if (parsed.command === 'service') {
+    // Handle service --help
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayServiceHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'Service subcommand required\n\nRun "celilo service --help" for usage',
+      };
+    }
+
+    const svcFlagError = checkFlags('service', parsed.subcommand, parsed.flags, parsed.args);
+    if (svcFlagError) return svcFlagError;
+
+    if (parsed.subcommand === 'add') {
+      // Add requires provider type
+      const provider = parsed.args[0];
+      if (!provider) {
+        return {
+          success: false,
+          error:
+            'Provider type required (proxmox or digitalocean)\n\nRun "celilo service --help" for usage',
+        };
+      }
+      const addArgs = parsed.args.slice(1);
+      if (provider === 'proxmox') {
+        return handleServiceAddProxmox(addArgs, parsed.flags);
+      }
+      if (provider === 'digitalocean') {
+        return handleServiceAddDigitalOcean(addArgs, parsed.flags);
+      }
+      return {
+        success: false,
+        error: `Unknown provider: ${provider}\n\nSupported providers: proxmox, digitalocean`,
+      };
+    }
+
+    if (parsed.subcommand === 'list') {
+      return handleServiceList(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'remove') {
+      return handleServiceRemove(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'verify') {
+      return handleServiceVerify(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'reconfigure') {
+      return handleServiceReconfigure(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'config') {
+      const configSubcommand = parsed.args[0];
+      if (!configSubcommand) {
+        return {
+          success: false,
+          error: 'Config action required (set or get)\n\nRun "celilo help" for usage',
+        };
+      }
+      const configArgs = parsed.args.slice(1);
+      if (configSubcommand === 'set') {
+        return handleServiceConfigSet(configArgs);
+      }
+      if (configSubcommand === 'get') {
+        return handleServiceConfigGet(configArgs);
+      }
+      return {
+        success: false,
+        error: `Unknown config action: ${configSubcommand}`,
+      };
+    }
+
+    return {
+      success: false,
+      error: `Unknown service subcommand: ${parsed.subcommand}\n\nRun "celilo service --help" for usage`,
+    };
+  }
+
+  if (parsed.command === 'storage') {
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayStorageHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'Storage subcommand required\n\nRun "celilo storage --help" for usage',
+      };
+    }
+
+    // Skip flag validation for 'add' — flags belong to the sub-subcommand (local/s3)
+    if (parsed.subcommand !== 'add') {
+      const storageFlagError = checkFlags('storage', parsed.subcommand, parsed.flags, parsed.args);
+      if (storageFlagError) return storageFlagError;
+    }
+
+    if (parsed.subcommand === 'add') {
+      const provider = parsed.args[0];
+      if (!provider) {
+        return {
+          success: false,
+          error: 'Provider type required (local or s3)\n\nRun "celilo storage --help" for usage',
+        };
+      }
+      const addArgs = parsed.args.slice(1);
+      if (provider === 'local') {
+        const { handleStorageAddLocal } = await import('./commands/storage-add-local');
+        return handleStorageAddLocal(addArgs, parsed.flags);
+      }
+      if (provider === 's3') {
+        const { handleStorageAddS3 } = await import('./commands/storage-add-s3');
+        return handleStorageAddS3(addArgs, parsed.flags);
+      }
+      return {
+        success: false,
+        error: `Unknown storage provider: ${provider}\n\nSupported providers: local, s3`,
+      };
+    }
+
+    if (parsed.subcommand === 'list') {
+      const { handleStorageList } = await import('./commands/storage-list');
+      return handleStorageList(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'remove') {
+      const { handleStorageRemove } = await import('./commands/storage-remove');
+      return handleStorageRemove(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'verify') {
+      const { handleStorageVerify } = await import('./commands/storage-verify');
+      return handleStorageVerify(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'set-default') {
+      const { handleStorageSetDefault } = await import('./commands/storage-set-default');
+      return handleStorageSetDefault(parsed.args, parsed.flags);
+    }
+
+    return {
+      success: false,
+      error: `Unknown storage subcommand: ${parsed.subcommand}\n\nRun "celilo storage --help" for usage`,
+    };
+  }
+
+  if (parsed.command === 'backup') {
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayBackupHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'Backup subcommand required\n\nRun "celilo backup --help" for usage',
+      };
+    }
+
+    const backupFlagError = checkFlags('backup', parsed.subcommand, parsed.flags, parsed.args);
+    if (backupFlagError) return backupFlagError;
+
+    if (parsed.subcommand === 'create') {
+      const { handleBackupCreate } = await import('./commands/backup-create');
+      return handleBackupCreate(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'list') {
+      const { handleBackupList } = await import('./commands/backup-list');
+      return handleBackupList(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'restore') {
+      const { handleBackupRestore } = await import('./commands/backup-restore');
+      return handleBackupRestore(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'prune') {
+      const { handleBackupPrune } = await import('./commands/backup-prune');
+      return handleBackupPrune(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'delete') {
+      const { handleBackupDelete } = await import('./commands/backup-delete');
+      return handleBackupDelete(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'name') {
+      const { handleBackupName } = await import('./commands/backup-name');
+      return handleBackupName(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'import') {
+      const { handleBackupImport } = await import('./commands/backup-import');
+      return handleBackupImport(parsed.args, parsed.flags);
+    }
+
+    return {
+      success: false,
+      error: `Unknown backup subcommand: ${parsed.subcommand}\n\nRun "celilo backup --help" for usage`,
+    };
+  }
+
+  if (parsed.command === 'machine') {
+    // Handle machine --help
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayMachineHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'Machine subcommand required\n\nRun "celilo machine --help" for usage',
+      };
+    }
+
+    const machFlagError = checkFlags('machine', parsed.subcommand, parsed.flags, parsed.args);
+    if (machFlagError) return machFlagError;
+
+    if (parsed.subcommand === 'add') {
+      return handleMachineAdd(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'list') {
+      return handleMachineList(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'status') {
+      return handleMachineStatus(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'remove') {
+      return handleMachineRemove(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'earmark') {
+      return handleMachineEarmark(parsed.args, parsed.flags);
+    }
+
+    return {
+      success: false,
+      error: `Unknown machine subcommand: ${parsed.subcommand}\n\nRun "celilo machine --help" for usage`,
+    };
+  }
+
+  if (parsed.command === 'system') {
+    // Handle system --help
+    if (parsed.flags.help || parsed.flags.h) {
+      return displaySystemHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'System subcommand required\n\nRun "celilo system --help" for usage',
+      };
+    }
+
+    const sysFlagError = checkFlags('system', parsed.subcommand, parsed.flags, parsed.args);
+    if (sysFlagError) return sysFlagError;
+
+    if (parsed.subcommand === 'init') {
+      return handleSystemInit(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'config') {
+      const configSubcommand = parsed.args[0];
+      if (!configSubcommand) {
+        return {
+          success: false,
+          error: 'Config action required (set or get)\n\nRun "celilo system --help" for usage',
+        };
+      }
+      const configArgs = parsed.args.slice(1);
+      if (configSubcommand === 'set') {
+        return handleSystemConfigSet(configArgs);
+      }
+      if (configSubcommand === 'get') {
+        return handleSystemConfigGet(configArgs);
+      }
+      return {
+        success: false,
+        error: `Unknown config action: ${configSubcommand}`,
+      };
+    }
+
+    if (parsed.subcommand === 'secret') {
+      const secretSubcommand = parsed.args[0];
+      if (!secretSubcommand) {
+        return {
+          success: false,
+          error: 'Secret action required (set or get)\n\nRun "celilo system --help" for usage',
+        };
+      }
+      const secretArgs = parsed.args.slice(1);
+      if (secretSubcommand === 'set') {
+        return handleSystemSecretSet(secretArgs);
+      }
+      if (secretSubcommand === 'get') {
+        return handleSystemSecretGet(secretArgs);
+      }
+      return {
+        success: false,
+        error: `Unknown secret action: ${secretSubcommand}`,
+      };
+    }
+
+    if (parsed.subcommand === 'vault-password') {
+      return handleSystemVaultPassword();
+    }
+
+    return {
+      success: false,
+      error: `Unknown system subcommand: ${parsed.subcommand}\n\nRun "celilo system --help" for usage`,
+    };
+  }
+
+  if (parsed.command === 'ipam') {
+    // Handle ipam --help
+    if (parsed.flags.help || parsed.flags.h) {
+      return displayIpamHelp();
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'IPAM subcommand required\n\nRun "celilo ipam --help" for usage',
+      };
+    }
+
+    const ipamFlagError = checkFlags('ipam', parsed.subcommand, parsed.flags, parsed.args);
+    if (ipamFlagError) return ipamFlagError;
+
+    // Handle show command (comprehensive summary)
+    if (parsed.subcommand === 'show') {
+      return handleIpamShow(parsed.args, parsed.flags);
+    }
+
+    // Handle list-allocations (no additional subcommand)
+    if (parsed.subcommand === 'list-allocations') {
+      return handleIpamListAllocations(parsed.args, parsed.flags);
+    }
+
+    // VMID commands
+    if (parsed.subcommand === 'vmid') {
+      const vmidSubcommand = parsed.args[0];
+      if (!vmidSubcommand) {
+        return {
+          success: false,
+          error:
+            'VMID action required (reserve, unreserve, list-reservations)\n\nRun "celilo ipam --help" for usage',
+        };
+      }
+      const vmidArgs = parsed.args.slice(1);
+      if (vmidSubcommand === 'reserve') {
+        return handleIpamVmidReserve(vmidArgs, parsed.flags);
+      }
+      if (vmidSubcommand === 'unreserve') {
+        return handleIpamVmidUnreserve(vmidArgs, parsed.flags);
+      }
+      if (vmidSubcommand === 'list-reservations') {
+        return handleIpamVmidListReservations(vmidArgs, parsed.flags);
+      }
+      return {
+        success: false,
+        error: `Unknown VMID action: ${vmidSubcommand}`,
+      };
+    }
+
+    // IP commands
+    if (parsed.subcommand === 'ip') {
+      const ipSubcommand = parsed.args[0];
+      if (!ipSubcommand) {
+        return {
+          success: false,
+          error:
+            'IP action required (exclude, include, list-exclusions)\n\nRun "celilo ipam --help" for usage',
+        };
+      }
+      const ipArgs = parsed.args.slice(1);
+      if (ipSubcommand === 'exclude') {
+        return handleIpamIpReserve(ipArgs, parsed.flags);
+      }
+      if (ipSubcommand === 'include') {
+        return handleIpamIpUnreserve(ipArgs, parsed.flags);
+      }
+      if (ipSubcommand === 'list-exclusions') {
+        return handleIpamIpListReservations(ipArgs, parsed.flags);
+      }
+      return {
+        success: false,
+        error: `Unknown IP action: ${ipSubcommand}`,
+      };
+    }
+
+    return {
+      success: false,
+      error: `Unknown IPAM subcommand: ${parsed.subcommand}\n\nRun "celilo ipam --help" for usage`,
+    };
+  }
+
+  return {
+    success: false,
+    error: `Unknown command: ${parsed.command}\n\nRun "celilo help" for usage`,
+  };
+}
+
+/**
+ * Server Mode - Persistent CLI Process
+ *
+ * Accepts commands via stdin, executes them, and returns results via stdout.
+ * Used by test infrastructure for efficient command execution without spawning
+ * fresh processes.
+ *
+ * Protocol:
+ * - Input (stdin): JSON lines with `{ command: string, id: number }`
+ * - Output (stdout): JSON lines with `{ id: number, success: boolean, message?: string, error?: string, exitCode: number, duration: number }`
+ * - Special command "__exit__" terminates server
+ * - Special command "__ping__" returns pong (health check)
+ */
+/**
+ * Parse command string respecting quotes
+ * Handles: system config set dns.fallback "8.8.8.8 1.1.1.1"
+ * Returns: ['system', 'config', 'set', 'dns.fallback', '8.8.8.8 1.1.1.1']
+ */
+function parseCommand(command: string): string[] {
+  const args: string[] = [];
+  let current = '';
+  let inQuotes = false;
+  let quoteChar = '';
+
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i];
+
+    if ((char === '"' || char === "'") && !inQuotes) {
+      // Start of quoted string
+      inQuotes = true;
+      quoteChar = char;
+    } else if (char === quoteChar && inQuotes) {
+      // End of quoted string
+      inQuotes = false;
+      quoteChar = '';
+    } else if (char === ' ' && !inQuotes) {
+      // Space outside quotes - word boundary
+      if (current) {
+        args.push(current);
+        current = '';
+      }
+    } else {
+      // Regular character
+      current += char;
+    }
+  }
+
+  // Add final argument
+  if (current) {
+    args.push(current);
+  }
+
+  return args;
+}
+
+async function serverMode(): Promise<void> {
+  const readline = await import('node:readline');
+
+  // Signal ready
+  console.log(JSON.stringify({ type: 'ready', pid: process.pid }));
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
+
+  // Keep process alive - don't exit when stdin ends
+  rl.on('close', () => {
+    // Stdin closed - exit gracefully
+    process.exit(0);
+  });
+
+  for await (const line of rl) {
+    try {
+      const request = parseJsonWithValidation(line, CLIServerRequestSchema, 'CLI server request');
+
+      // Health check
+      if (request.command === '__ping__') {
+        console.log(
+          JSON.stringify({
+            id: request.id,
+            success: true,
+            message: 'pong',
+            exitCode: 0,
+            duration: 0,
+          }),
+        );
+        continue;
+      }
+
+      // Exit command
+      if (request.command === '__exit__') {
+        console.log(
+          JSON.stringify({
+            id: request.id,
+            success: true,
+            message: 'exiting',
+            exitCode: 0,
+            duration: 0,
+          }),
+        );
+        process.exit(0);
+      }
+
+      // Execute command
+      const startTime = Date.now();
+      const argv = ['bun', 'celilo', ...parseCommand(request.command)];
+      const result = await runCli(argv);
+      const duration = Date.now() - startTime;
+
+      // Send response
+      console.log(
+        JSON.stringify({
+          id: request.id,
+          success: result.success,
+          message: result.success ? result.message : undefined,
+          error: !result.success ? result.error : undefined,
+          details: !result.success ? result.details : undefined,
+          exitCode: result.success ? 0 : 1,
+          duration,
+        }),
+      );
+    } catch (error) {
+      // Parse or execution error
+      console.error(
+        JSON.stringify({
+          id: -1,
+          success: false,
+          error: `Server error: ${error}`,
+          exitCode: 1,
+          duration: 0,
+        }),
+      );
+    }
+  }
+}
+
+/**
+ * Main CLI entry point
+ *
+ * Executes CLI and handles output/exit codes.
+ * If CLI_SERVER_MODE=true, runs in persistent server mode for testing.
+ */
+export async function main(): Promise<void> {
+  // Check for server mode
+  if (process.env.CLI_SERVER_MODE === 'true') {
+    await serverMode();
+    return;
+  }
+
+  // Normal single-command execution
+  try {
+    const result = await runCli(process.argv);
+
+    if (result.success) {
+      // For completion mode, output raw text without formatting
+      if (process.argv.includes('--get-completions') || process.argv.includes('completion')) {
+        console.log(result.message);
+        process.exit(0);
+      }
+
+      // Handle multi-line messages: split on section boundaries (\n\n) so
+      // lines within a section are logged together (avoiding clack's per-call spacing).
+      const sections = result.message.split('\n\n');
+      p.log.success(sections[0]);
+      for (let i = 1; i < sections.length; i++) {
+        if (sections[i].trim()) {
+          p.log.message(sections[i]);
+        }
+      }
+      process.exit(0);
+    }
+
+    p.log.error(`Error: ${result.error}`);
+    if (result.details) {
+      console.error('Details:', result.details);
+    }
+    process.exit(1);
+  } catch (error) {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  }
+}
+
+// Execute main only when run directly (not when imported by tests)
+if (import.meta.main) {
+  await main();
+}