building-clis

# Building CLIs

Build professional command-line interfaces across Python, Go, and Rust using modern frameworks with robust argument parsing, configuration management, and shell integration.

## When to Use This Skill

Use this skill when:
- Building developer tooling or automation CLIs
- Creating infrastructure management tools (deployment, monitoring)
- Implementing API client command-line tools
- Adding CLI capabilities to existing projects
- Packaging utilities for distribution (PyPI, Homebrew, binary releases)

Common triggers: "create a CLI tool", "build a command-line interface", "add CLI arguments", "parse command-line options", "generate shell completions"

## Framework Selection

### Quick Decision Guide

**Python Projects:**
- **Typer** (recommended): Modern type-safe CLIs with minimal boilerplate
- **Click**: Mature, flexible CLIs for complex command hierarchies

**Go Projects:**
- **Cobra** (recommended): Industry standard for enterprise tools (Kubernetes, Docker, GitHub CLI)
- **urfave/cli**: Lightweight alternative for simple CLIs

**Rust Projects:**
- **clap v4** (recommended): Type-safe with derive API or builder API for runtime flexibility

For detailed framework comparison and selection criteria, see [references/framework-selection.md](references/framework-selection.md).

## Core Patterns

### Arguments vs. Options vs. Flags

**Positional Arguments:**
- Primary input, identified by position
- Use for required inputs (max 2-3 arguments)
- Example: `convert input.jpg output.png`

**Options:**
- Named parameters with values
- Use for configuration and optional inputs
- Example: `--output file.txt`, `--config app.yaml`

**Flags:**
- Boolean options (presence = true)
- Use for switches and toggles
- Example: `--verbose`, `--dry-run`, `--force`

**Decision Matrix:**

| Use Case | Type | Example |
|----------|------|---------|
| Primary required input | Positional Argument | `git commit -m "message"` |
| Optional configuration | Option | `--config app.yaml` |
| Boolean setting | Flag | `--verbose`, `--force` |
| Multiple values | Variadic Argument | `files...` |

See [references/argument-patterns.md](references/argument-patterns.md) for comprehensive parsing patterns.

### Subcommand Organization

**Flat Structure (1 Level):**
```
app command1 [args]
app command2 [args]
```
Use for: Small CLIs with 5-10 operations

**Grouped Structure (2 Levels):**
```
app group subcommand [args]
```
Use for: Medium CLIs with logical groupings (10-30 commands)
Example: `kubectl get pods`, `kubectl create deployment`

**Nested Structure (3+ Levels):**
```
app group subgroup command [args]
```
Use for: Large CLIs with deep hierarchies (30+ commands)
Example: `gcloud compute instances create`

See [references/subcommand-design.md](references/subcommand-design.md) for structuring strategies.

### Configuration Management

**Standard Precedence (Highest to Lowest):**

1. CLI Arguments/Flags (explicit user input)
2. Environment Variables (session overrides)
3. Config File - Local (`./config.yaml`)
4. Config File - User (`~/.config/app/config.yaml`)
5. Config File - System (`/etc/app/config.yaml`)
6. Built-in Defaults (hardcoded)

**Best Practices:**
- Document precedence in `--help`
- Validate config files before execution
- Provide `--print-config` to show effective configuration
- Use XDG Base Directory (`~/.config/app/`) for config files

See [references/configuration-management.md](references/configuration-management.md) for implementation patterns across languages.

### Output Formatting

**Format Selection:**

| Use Case | Format | When |
|----------|--------|------|
| Human consumption | Colored text, tables | Default interactive mode |
| Machine consumption | JSON, YAML | `--output json`, piping |
| Logging/debugging | Plain text | `--verbose`, stderr |
| Progress tracking | Progress bars, spinners | Long operations |

**Best Practices:**
- Default to human-readable output
- Provide `--output` flag (json, yaml, table)
- Use stderr for logs, stdout for data
- Auto-detect TTY (disable colors if not interactive)
- Use exit codes: 0 = success, 1 = error, 2 = usage error

See [references/output-formatting.md](references/output-formatting.md) for formatting strategies.

## Language-Specific Quick Starts

### Python with Typer

**Installation:**
```bash
pip install "typer[all]"  # Includes rich for colored output
```

**Basic Example:**
```python
import typer
from typing import Annotated

app = typer.Typer()

@app.command()
def greet(
    name: Annotated[str, typer.Argument(help="Name to greet")],
    formal: Annotated[bool, typer.Option(help="Use formal greeting")] = False
):
    """Greet someone with a message."""
    greeting = "Good day" if formal else "Hello"
    typer.echo(f"{greeting}, {name}!")

if __name__ == "__main__":
    app()
```

**Key Features:**
- Type hints for automatic validation
- Minimal boilerplate with decorators
- Auto-generated help text
- Rich integration for colored output

See [examples/python/](examples/python/) for complete working examples including subcommands, config management, and interactive features.

### Go with Cobra

**Installation:**
```bash
go get -u github.com/spf13/cobra@latest
```

**Basic Example:**
```go
var rootCmd = &cobra.Command{
    Use:   "greet [name]",
    Args:  cobra.ExactArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Hello, %s!\n", args[0])
    },
}

rootCmd.Flags().Bool("formal", false, "Use formal greeting")
rootCmd.Execute()
```

**Key Features:**
- POSIX-compliant flags
- Viper integration for configuration
- Subcommand architecture
- Shell completion generation

See [examples/go/](examples/go/) for complete working examples including Viper config and multi-level subcommands.

### Rust with clap

**Installation (Cargo.toml):**
```toml
[dependencies]
clap = { version = "4.5", features = ["derive"] }
```

**Basic Example (Derive API):**
```rust
use clap::Parser;

#[derive(Parser)]
#[command(about = "Gree