# 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:

```bash
# 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
```plaintext

## CLI Internal Architecture

**File Structure:**

```plaintext
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)
```plaintext

**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](../architecture/adr/adr-006-provisioning-cli-refactoring.md) for complete refactoring details.