cli-architecture

CLI Architecture Best Practices

Reference tools: Biome, OxcLint, ripgrep, fd

Core Design Principles

1. Zero-Config by Default

User experience priority:
1. Works out of the box with sensible defaults
2. Configuration is optional enhancement
3. Explicit overrides when needed

// BAD: Requires configuration to work
let config = Config::load("config.yaml")?; // Fails if missing

// GOOD: Sensible defaults, optional config
let config = Config::load_or_default("config.yaml");

2. Modular Composability (Oxc Pattern)

Each component works independently or together:

┌─────────────────────────────────────────────┐
│                    CLI                       │
├─────────────────────────────────────────────┤
│  ┌─────────┐ ┌─────────┐ ┌─────────────┐   │
│  │ Scanner │ │ Reporter│ │ Config      │   │
│  └────┬────┘ └────┬────┘ └──────┬──────┘   │
│       │           │             │           │
├───────┴───────────┴─────────────┴───────────┤
│              Core Engine                     │
├─────────────────────────────────────────────┤
│  ┌────────┐ ┌────────┐ ┌────────┐          │
│  │ Parser │ │ Rules  │ │ Types  │          │
│  └────────┘ └────────┘ └────────┘          │
└─────────────────────────────────────────────┘

3. Performance First

• Parallel by default: Use rayon for file processing
• Streaming output: Don't buffer entire results
• Lazy evaluation: Load resources on demand
• Memory efficiency: Process files without loading all into memory

Crate Organization (Workspace Pattern)

Recommended Structure

my-tool/
├── Cargo.toml              # Workspace root
├── crates/
│   ├── my_tool/            # Main library (pub API)
│   ├── my_tool_cli/        # CLI binary (thin wrapper)
│   ├── my_tool_parser/     # Parser implementation
│   ├── my_tool_rules/      # Rule definitions
│   ├── my_tool_config/     # Configuration handling
│   └── my_tool_reporter/   # Output formatters
├── xtask/                  # Development tasks
└── tests/                  # Integration tests