/building-clis

name: building-clis
description: Build professional command-line interfaces in Python, Go, and Rust using modern frameworks like Typer, Cobra, and clap. Use when creating developer tools, automation scripts, or infrastructure management CLIs with robust argument parsing, interactive features, and multi-platform distribution.

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

pip install "typer[all]"  # Includes rich for colored output

**Basic Example:**

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

go get -u github.com/spf13/cobra@latest

**Basic Example:**

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 [examp