building-clis

What this skill does

# 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 = "Greet someone")]
struct Cli {
    /// Name to greet
    name: String,

    /// Use formal greeting
    #[arg(long)]
    formal: bool,
}

fn main() {
    let cli = Cli::parse();
    let greeting = if cli.formal { "Good day" } else { "Hello" };
    println!("{}, {}!", greeting, cli.name);
}
```

**Key Features:**
- Compile-time type safety
- Derive API (declarative) or Builder API (programmatic)
- Comprehensive validation
- Performance optimized

See [examples/rust/](examples/rust/) for complete working examples including subcommands and builder API patterns.

## Interactive Features

### Progress Indicators

**Python (rich):**
```python
from rich.progress import track
for _ in track(range(100), description="Processing..."):
    time.sleep(0.01)
```

**Go (progressbar):**
```go
import "github.com/schollz/progressbar/v3"
bar := progressbar.Default(100)
for i := 0; i < 100; i++ {
    bar.Add(1)
}
```

**Rust (indicatif):**
```rust
use indicatif::ProgressBar;
let bar = ProgressBar::new(100);
for _ in 0..100 {
    bar.inc(1);
}
```

### Prompts and Confirmations

**Python:**
```python
confirm = typer.confirm("Are you sure?")
if not confirm:
    raise typer.Abort()
```

**Go:**
```go
reader := bufio.NewReader(os.Stdin)
fmt.Print("Are you sure? (y/n): ")
response, _ := reader.ReadString('\n')
```

**Rust:**
```rust
use dialoguer::Confirm;
if Confirm::new().with_prompt("Are you sure?").interact()? {
    // Proceed
}
```

## Shell Completion

### Generating Completions

**Python (Typer):**
```bash
_MYAPP_COMPLETE=bash_source myapp > ~/.myapp-complete.bash
_MYAPP_COMPLETE=zsh_source myapp > ~/.myapp-complete.zsh
```

**Go (Cobra):**
```go
rootCmd.AddCommand(&cobra.Command{
    Use:   "completion [bash|zsh|fish|powershell]",
    Args:  cobra.ExactArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        switch args[0] {
        case "bash":
            rootCmd.GenBashCompletion(os.Stdout)
        case "zsh":
            rootCmd.GenZshCompletion(os.Stdout)
        }
    },