provisioning/docs/src/infrastructure/cli-architecture.md

Modular CLI Architecture (v3.2.0 - MAJOR REFACTORING)\n\n## 🚀 CLI Refactoring Completed (2025-09-30)\n\nA comprehensive CLI refactoring transforming the monolithic 1,329-line script into a modular, maintainable architecture with domain-driven design.\n\n## Architecture Improvements\n\n- Main File Reduction: 1,329 lines → 211 lines (84% reduction)\n- Domain Handlers: 7 focused modules (infrastructure, orchestration, development, workspace, configuration, utilities, generation)\n- Code Duplication: 50+ instances eliminated through centralized flag handling\n- Command Registry: 80+ shortcuts for improved user experience\n- Bi-directional Help: provisioning help ws = provisioning ws help\n- Test Coverage: Comprehensive test suite with 6 test groups\n\n## Command Shortcuts Reference\n\n### Infrastructure\n\n[Full docs: provisioning help infra]\n\n- s → server (create, delete, list, ssh, price)\n- t, task → taskserv (create, delete, list, generate, check-updates)\n- cl → cluster (create, delete, list)\n- i, infras → infra (list, validate)\n\n### Orchestration\n\n[Full docs: provisioning help orch]\n\n- wf, flow → workflow (list, status, monitor, stats, cleanup)\n- bat → batch (submit, list, status, monitor, rollback, cancel, stats)\n- orch → orchestrator (start, stop, status, health, logs)\n\n### Development\n\n[Full docs: provisioning help dev]\n\n- mod → module (discover, load, list, unload, sync-nickel)\n- lyr → layer (explain, show, test, stats)\n- version (check, show, updates, apply, taskserv)\n- pack (core, provider, list, clean)\n\n### Workspace\n\n[Full docs: provisioning help ws]\n\n- ws → workspace (init, create, validate, info, list, migrate)\n- tpl, tmpl → template (list, types, show, apply, validate)\n\n### Configuration\n\n[Full docs: provisioning help config]\n\n- e → env (show environment variables)\n- val → validate (validate configuration)\n- st, config → setup (setup wizard)\n- show (show configuration details)\n- init (initialize infrastructure)\n- allenv (show all config and environment)\n\n### Utilities\n\n- l, ls, list → list (list resources)\n- ssh (SSH operations)\n- sops (edit encrypted files)\n- cache (cache management)\n- providers (provider operations)\n- nu (start Nushell session with provisioning library)\n- qr (QR code generation)\n- nuinfo (Nushell information)\n- plugin, plugins (plugin management)\n\n### Generation\n\n[Full docs: provisioning generate help]\n\n- g, gen → generate (server, taskserv, cluster, infra, new)\n\n### Special Commands\n\n- c → create (create resources)\n- d → delete (delete resources)\n- u → update (update resources)\n- price, cost, costs → price (show pricing)\n- cst, csts → create-server-task (create server with taskservs)\n\n## Bi-directional Help System\n\nThe help system works in both directions:\n\n\n# All these work identically:\nprovisioning help workspace\nprovisioning workspace help\nprovisioning ws help\nprovisioning help ws\n\n# Same for all categories:\nprovisioning help infra = provisioning infra help\nprovisioning help orch = provisioning orch help\nprovisioning help dev = provisioning dev help\nprovisioning help ws = provisioning ws help\nprovisioning help plat = provisioning plat help\nprovisioning help concept = provisioning concept help\n\n\n## CLI Internal Architecture\n\nFile Structure:\n\n\nprovisioning/core/nulib/\n├── provisioning (211 lines) - Main entry point\n├── main_provisioning/\n│ ├── flags.nu (139 lines) - Centralized flag handling\n│ ├── dispatcher.nu (264 lines) - Command routing\n│ ├── help_system.nu - Categorized help\n│ └── commands/ - Domain-focused handlers\n│ ├── infrastructure.nu (117 lines)\n│ ├── orchestration.nu (64 lines)\n│ ├── development.nu (72 lines)\n│ ├── workspace.nu (56 lines)\n│ ├── generation.nu (78 lines)\n│ ├── utilities.nu (157 lines)\n│ └── configuration.nu (316 lines)\n\n\nFor Developers:\n\n- Adding commands: Update appropriate domain handler in commands/\n- Adding shortcuts: Update command registry in dispatcher.nu\n- Flag changes: Modify centralized functions in flags.nu\n- Testing: Run nu tests/test_provisioning_refactor.nu\n\nSee ADR-006: CLI Refactoring for complete refactoring details.