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

Modular CLI Architecture (v3.2.0 - MAJOR REFACTORING)

🚀 CLI Refactoring Completed (2025-09-30)

A comprehensive CLI refactoring transforming the monolithic 1,329-line script into a modular, maintainable architecture with domain-driven design.

Architecture Improvements

• Main File Reduction: 1,329 lines → 211 lines (84% reduction)
• Domain Handlers: 7 focused modules (infrastructure, orchestration, development, workspace, configuration, utilities, generation)
• Code Duplication: 50+ instances eliminated through centralized flag handling
• Command Registry: 80+ shortcuts for improved user experience
• Bi-directional Help: provisioning help ws = provisioning ws help
• Test Coverage: Comprehensive test suite with 6 test groups

Command Shortcuts Reference

Infrastructure

[Full docs: provisioning help infra]

• s → server (create, delete, list, ssh, price)
• t, task → taskserv (create, delete, list, generate, check-updates)
• cl → cluster (create, delete, list)
• i, infras → infra (list, validate)

Orchestration

[Full docs: provisioning help orch]

• wf, flow → workflow (list, status, monitor, stats, cleanup)
• bat → batch (submit, list, status, monitor, rollback, cancel, stats)
• orch → orchestrator (start, stop, status, health, logs)

Development

[Full docs: provisioning help dev]

• mod → module (discover, load, list, unload, sync-nickel)
• lyr → layer (explain, show, test, stats)
• version (check, show, updates, apply, taskserv)
• pack (core, provider, list, clean)

Workspace

[Full docs: provisioning help ws]

• ws → workspace (init, create, validate, info, list, migrate)
• tpl, tmpl → template (list, types, show, apply, validate)

Configuration

[Full docs: provisioning help config]

• e → env (show environment variables)
• val → validate (validate configuration)
• st, config → setup (setup wizard)
• show (show configuration details)
• init (initialize infrastructure)
• allenv (show all config and environment)

Utilities

• l, ls, list → list (list resources)
• ssh (SSH operations)
• sops (edit encrypted files)
• cache (cache management)
• providers (provider operations)
• nu (start Nushell session with provisioning library)
• qr (QR code generation)
• nuinfo (Nushell information)
• plugin, plugins (plugin management)

Generation

[Full docs: provisioning generate help]

• g, gen → generate (server, taskserv, cluster, infra, new)

Special Commands

• c → create (create resources)
• d → delete (delete resources)
• u → update (update resources)
• price, cost, costs → price (show pricing)
• cst, csts → create-server-task (create server with taskservs)

Bi-directional Help System

The help system works in both directions:

# All these work identically:
provisioning help workspace
provisioning workspace help
provisioning ws help
provisioning help ws

# Same for all categories:
provisioning help infra    = provisioning infra help
provisioning help orch     = provisioning orch help
provisioning help dev      = provisioning dev help
provisioning help ws       = provisioning ws help
provisioning help plat     = provisioning plat help
provisioning help concept  = provisioning concept help

CLI Internal Architecture

File Structure:

provisioning/core/nulib/
├── provisioning (211 lines) - Main entry point
├── main_provisioning/
│   ├── flags.nu (139 lines) - Centralized flag handling
│   ├── dispatcher.nu (264 lines) - Command routing
│   ├── help_system.nu - Categorized help
│   └── commands/ - Domain-focused handlers
│       ├── infrastructure.nu (117 lines)
│       ├── orchestration.nu (64 lines)
│       ├── development.nu (72 lines)
│       ├── workspace.nu (56 lines)
│       ├── generation.nu (78 lines)
│       ├── utilities.nu (157 lines)
│       └── configuration.nu (316 lines)

For Developers:

• Adding commands: Update appropriate domain handler in commands/
• Adding shortcuts: Update command registry in dispatcher.nu
• Flag changes: Modify centralized functions in flags.nu
• Testing: Run nu tests/test_provisioning_refactor.nu

See ADR-006: CLI Refactoring for complete refactoring details.