python-cli-engineering

# Python CLI Engineering

Modern patterns for building production-grade Python command-line applications.

## When to Use This Skill

Use when building:
- Command-line tools and utilities
- Data processing applications
- Admin/operations tooling
- Developer utilities
- ETL/sync scripts with user interaction
- Analysis tools with formatted output
- Database management CLIs

---

## Technology Stack Overview

### Core Tools
- **UV** - Package manager (10-100x faster than pip/poetry)
- **Ruff** - Linting + formatting (Rust-based, replaces 6+ tools)
- **Pyright** - Type checking in strict mode (3-5x faster than mypy)
- **Typer** - CLI framework with type hints + auto-help
- **Rich** - Console output with colors, tables, progress bars

**Installation:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh  # Install UV
uv init my-cli          # Initialize project
uv add typer rich       # Add dependencies
```

**For complete tool guides, configuration examples, and advanced patterns:**
See [references/tech-stack.md](references/tech-stack.md)

---

## Fail-Fast Discipline

### Core Principles

1. **No default values** (except in explicit config files)
2. **No try/catch swallowing** (let exceptions propagate)
3. **No fallback mechanisms** (fail immediately on errors)
4. **Explicit configuration** (missing config = app stops)
5. **Type everything** (strict Pyright mode)

### Exception Handling Pattern

```python
# Custom exceptions (core/exceptions.py)
class AppError(Exception):
    """Base exception - let it bubble up."""
    pass

# CLI main entry (cli/main.py)
def main() -> None:
    """Main entry point - ONLY catch at top level."""
    try:
        app()
    except AppError as e:
        console.print(f"[red]ERROR: {e}[/red]")
        raise typer.Exit(code=1) from e
```

**Key Rules:**
- ❌ **Never**: `except Exception: pass` or `except: return None`
- ✅ **Always**: Let exceptions bubble to main entry point
- ✅ **Always**: Use specific exception types for different fa