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.

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:

See 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 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 for implementation patterns across languages.

Output Formatting

Format Selection:

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 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/ 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 examples/go/ for complete working examples including Viper config and multi-level subcommands.

Rust with clap

Installation (Cargo.toml):

[dependencies]
clap = { version = "4.5", features = ["derive"] }

Basic Example (Derive API):

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/ for complete working examples including subcommands and builder API patterns.

Interactive Features

Progress Indicators

Python (rich):

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

Go (progressbar):

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

Rust (indicatif):

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

Prompts and Confirmations

Python:

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

Go:

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

Rust:

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

Shell Completion

Generating Completions

Python (Typer):

_MYAPP_COMPLETE=bash_source myapp > ~/.myapp-complete.bash
_MYAPP_COMPLETE=zsh_source myapp > ~/.myapp-complete.zsh

Go (Cobra):

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)
        }
    },
})

Rust (clap):

use clap_complete::{generate, shells::Bash};
generate(Bash, &mut Cli::command(), "myapp", &mut io::stdout())

See references/shell-completion.md for installation instructions.

Distribution and Packaging

Python (PyPI)

pyproject.toml:

[project]
name = "myapp"
version = "1.0.0"
scripts = { myapp = "myapp.cli:app" }

Publish:

pip install build twine
python -m build
twine upload dist/*

Go (Homebrew)

Formula:

class Myapp < Formula
  desc "My CLI application"
  url "https://github.com/user/myapp/archive/v1.0.0.tar.gz"

  def install
    system "go", "build", "-o", bin/"myapp"
  end
end

Rust (Cargo)

Publish:

cargo login
cargo publish

Installation:

cargo install myapp

See references/distribution.md for comprehensive packaging strategies including binary releases.

Best Practices

Universal CLI Conventions

Always Provide:

• --help and -h for usage information
• --version and -V for version display
• Clear error messages with actionable suggestions

Argument Handling:

• Use -- separator for options vs. positional args
• Support both short (-v) and long (--verbose) forms
• Validate and sanitize all user inputs

Error Handling:

• Exit code 0 for success
• Exit code 1 for general errors
• Exit code 2 for usage errors
• Write errors to stderr, data to stdout

Interactivity:

• Detect TTY (interactive vs. piped input)
• Provide --yes/--force to skip prompts for automation
• Show progress for operations longer than 2 seconds

Configuration Best Practices

File Formats:

• Use YAML, TOML, or JSON consistently
• Separate files per environment (dev, staging, prod)
• Validate configuration in CI/CD with --check-config

Secret Management:

• Never commit secrets to config files
• Use environment variables or secret managers
• Document required environment variables

Precedence:

• CLI args > env vars > config file > defaults
• Document precedence in help text
• Provide --print-config to show effective configuration

Integration with Other Skills

testing-strategies:

• CLI testing with mocks and fixtures
• Integration tests for end-to-end workflows
• See examples/python/test_cli.py

building-ci-pipelines:

• Binary builds for multiple platforms
• Automated releases via GitHub Actions
• See references/distribution.md

api-patterns:

• Building API client CLIs
• Authentication and token management
• Formatting API responses

secret-management:

• Secure credential storage
• Environment variable integration
• Vault/secrets manager integration

Reference Files

Decision Frameworks:

• framework-selection.md - Which framework to choose
• argument-patterns.md - Arguments vs. options vs. flags
• subcommand-design.md - Structuring command hierarchies

Implementation Guides:

• configuration-management.md - Config files and precedence
• output-formatting.md - Human vs. machine-readable output
• shell-completion.md - Generating completions
• distribution.md - Packaging and releasing CLIs

Code Examples:

• examples/python/ - Typer examples (basic, subcommands, config, interactive)
• examples/go/ - Cobra examples (basic, subcommands, Viper integration)
• examples/rust/ - clap examples (derive, builder, subcommands)

Quick Reference

Framework Recommendations:

• Python: Typer (modern) or Click (mature)
• Go: Cobra (enterprise) or urfave/cli (simple)
• Rust: clap v4 (derive or builder)

Common Patterns:

• Arguments: Primary inputs (max 2-3)
• Options: Named parameters with values
• Flags: Boolean switches
• Subcommands: Group related operations
• Config: CLI args > env vars > files > defaults

Output Standards:

• Default: Human-readable (colored, tables)
• Machine: JSON/YAML via --output flag
• Errors: stderr, data: stdout
• Exit: 0 = success, 1 = error, 2 = usage

Distribution:

• Python: PyPI (pip install)
• Go: Homebrew, binary releases
• Rust: Cargo (cargo install), binary releases

Argument Parsing Patterns

Comprehensive guide to arguments, options, and flags with decision frameworks and multi-language implementations.

Table of Contents

• Core Concepts
• Argument Types
• Decision Matrix
• Validation Patterns
• Multi-Value Arguments
• Language-Specific Patterns

Core Concepts

Definitions

Positional Argument:

• Value identified by position, not name
• Can be required or optional
• Order matters
• Example: git commit -m "message" (message is argument to -m)

Option (Named Parameter):

• Named parameter with a value
• Identified by flag name (short or long form)
• Example: --output file.txt, -o file.txt

Flag (Boolean Option):

• Boolean parameter (presence = true, absence = false)
• No value required
• Example: --verbose, --dry-run, -v

GNU Conventions

Follow POSIX and GNU standards:

Short Form:

• Single dash + single character: -v, -o file.txt
• Can be combined: -vf = -v -f

Long Form:

• Double dash + descriptive name: --verbose, --output file.txt
• More readable, self-documenting

Mixed Usage:

command -v --output file.txt input.txt
# -v: short flag
# --output file.txt: long option
# input.txt: positional argument

Argument Separator:

command --option value -- --file-starting-with-dash.txt
# -- separates options from positional arguments
# Allows files/args that start with dashes

Argument Types

1. Required Positional Arguments

Use Case: Primary input that is always needed

Example:

convert input.jpg output.png
# input.jpg and output.png are required positional args

Implementation:

Python (Typer):

def convert(
    input_file: Annotated[str, typer.Argument(help="Input file")],
    output_file: Annotated[str, typer.Argument(help="Output file")]
):
    pass

Go (Cobra):

var convertCmd = &cobra.Command{
    Use:   "convert <input> <output>",
    Args:  cobra.ExactArgs(2),  // Exactly 2 required
    Run: func(cmd *cobra.Command, args []string) {
        inputFile := args[0]
        outputFile := args[1]
    },
}

Rust (clap):

#[derive(Parser)]
struct Cli {
    /// Input file
    input_file: String,
    /// Output file
    output_file: String,
}

2. Optional Positional Arguments

Use Case: Input that has a sensible default

Example:

log show error.log  # Use error.log
log show            # Use default log file

Implementation:

Python (Typer):

def show(
    log_file: Annotated[str, typer.Argument()] = "app.log"
):
    pass

Go (Cobra):

var showCmd = &cobra.Command{
    Use:   "show [log_file]",
    Args:  cobra.MaximumNArgs(1),  // 0 or 1 arg
    Run: func(cmd *cobra.Command, args []string) {
        logFile := "app.log"
        if len(args) > 0 {
            logFile = args[0]
        }
    },
}

Rust (clap):

#[derive(Parser)]
struct Cli {
    /// Log file to show
    #[arg(default_value = "app.log")]
    log_file: String,
}

3. Required Options

Use Case: Configuration that must be explicitly set

Example:

deploy --env production
# --env is required, no default

Implementation:

Python (Typer):

def deploy(
    env: Annotated[str, typer.Option("--env", help="Environment")] = ...
    # ... means required
):
    pass

Go (Cobra):

var env string

var deployCmd = &cobra.Command{
    Use: "deploy",
    Run: func(cmd *cobra.Command, args []string) {
        // env is populated
    },
}

deployCmd.Flags().StringVar(&env, "env", "", "Environment")
deployCmd.MarkFlagRequired("env")

Rust (clap):

#[derive(Parser)]
struct Cli {
    /// Environment (required)
    #[arg(long)]
    env: String,  // No Option<> = required
}

4. Optional Options with Defaults

Use Case: Configuration with sensible defaults

Example:

serve --port 8080  # Use 8080
serve              # Use default port 3000

Implementation:

Python (Typer):

def serve(
    port: Annotated[int, typer.Option("--port")] = 3000
):
    pass

Go (Cobra):

var port int

rootCmd.Flags().IntVar(&port, "port", 3000, "Server port")

Rust (clap):

#[derive(Parser)]
struct Cli {
    /// Server port
    #[arg(long, default_value_t = 3000)]
    port: u16,
}

5. Boolean Flags

Use Case: Toggle behaviors on/off

Example:

build --verbose --dry-run
# Both flags are present = true

Implementation:

Python (Typer):

def build(
    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
    dry_run: Annotated[bool, typer.Option("--dry-run")] = False
):
    pass

Go (Cobra):

var verbose bool
var dryRun bool

rootCmd.Flags().BoolVarP(&verbose, "verbose", "v", false, "Verbose output")
rootCmd.Flags().BoolVar(&dryRun, "dry-run", false, "Dry run mode")

Rust (clap):

#[derive(Parser)]
struct Cli {
    /// Verbose output
    #[arg(short, long)]
    verbose: bool,

    /// Dry run mode
    #[arg(long)]
    dry_run: bool,
}

6. Counting Flags

Use Case: Increase level by repetition (e.g., verbosity)

Example:

command -v      # verbosity level 1
command -vv     # verbosity level 2
command -vvv    # verbosity level 3

Implementation:

Python (Typer):

def command(
    verbose: Annotated[int, typer.Option("--verbose", "-v", count=True)] = 0
):
    # verbose = number of -v flags
    pass

Go (Cobra):

var verbose int

rootCmd.Flags().CountVarP(&verbose, "verbose", "v", "Increase verbosity")

Rust (clap):

#[derive(Parser)]
struct Cli {
    /// Increase verbosity (-v, -vv, -vvv)
    #[arg(short, long, action = clap::ArgAction::Count)]
    verbose: u8,
}

Decision Matrix

When to Use Each Type

Argument Limits

Best Practices:

• Max 2-3 positional arguments: More becomes confusing
• Use options for 3+ parameters: Named params are clearer
• Limit flags to 10-15: Too many options overwhelm users

Example of Too Many Positional Args (BAD):

deploy production us-west-2 blue-green v1.2.3 true false
# What do these mean? Use options instead!

Better Approach:

deploy \
  --env production \
  --region us-west-2 \
  --strategy blue-green \
  --version v1.2.3 \
  --verbose \
  --no-backup

Validation Patterns

Type Validation

Python (Typer with Pydantic):

from typing import Annotated
from pydantic import validator

def deploy(
    port: Annotated[int, typer.Option(min=1, max=65535)] = 8080
):
    # Automatic validation: port must be 1-65535
    pass

Go (Cobra with Custom Validation):

var port int

deployCmd.Flags().IntVar(&port, "port", 8080, "Port number")

deployCmd.PreRunE = func(cmd *cobra.Command, args []string) error {
    if port < 1 || port > 65535 {
        return fmt.Errorf("port must be between 1 and 65535")
    }
    return nil
}

Rust (clap with value_parser):

use clap::{Parser, value_parser};

#[derive(Parser)]
struct Cli {
    /// Port number (1-65535)
    #[arg(long, value_parser = value_parser!(u16).range(1..=65535))]
    port: u16,
}

Choice/Enum Validation

Python (Typer with Enum):

from enum import Enum

class Environment(str, Enum):
    dev = "dev"
    staging = "staging"
    prod = "prod"

def deploy(env: Annotated[Environment, typer.Option()]):
    # env is automatically validated
    pass

Go (Cobra with ValidArgs):

var deployCmd = &cobra.Command{
    Use:       "deploy [env]",
    ValidArgs: []string{"dev", "staging", "prod"},
    Args:      cobra.OnlyValidArgs,
}

Rust (clap with value_enum):

use clap::{Parser, ValueEnum};

#[derive(ValueEnum, Clone)]
enum Environment {
    Dev,
    Staging,
    Prod,
}

#[derive(Parser)]
struct Cli {
    #[arg(long, value_enum)]
    env: Environment,
}

Path Validation

Python (Typer with Path):

from pathlib import Path

def process(
    input_file: Annotated[Path, typer.Argument(exists=True, dir_okay=False)]
):
    # Validates file exists and is not a directory
    pass

Go (Cobra with Custom Validation):

deployCmd.PreRunE = func(cmd *cobra.Command, args []string) error {
    if _, err := os.Stat(configFile); os.IsNotExist(err) {
        return fmt.Errorf("config file %s does not exist", configFile)
    }
    return nil
}

Rust (clap with value_parser):

use std::path::PathBuf;

#[derive(Parser)]
struct Cli {
    /// Input file (must exist)
    #[arg(value_parser = validate_file_exists)]
    input_file: PathBuf,
}

fn validate_file_exists(s: &str) -> Result<PathBuf, String> {
    let path = PathBuf::from(s);
    if path.exists() {
        Ok(path)
    } else {
        Err(format!("File {} does not exist", s))
    }
}

Multi-Value Arguments

Variadic Positional Arguments

Use Case: Accept multiple files or values

Example:

process file1.txt file2.txt file3.txt

Python (Typer):

def process(
    files: Annotated[list[str], typer.Argument()]
):
    for file in files:
        # Process each file
        pass

Go (Cobra):

var processCmd = &cobra.Command{
    Use:   "process <files...>",
    Args:  cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        for _, file := range args {
            // Process each file
        }
    },
}

Rust (clap):

#[derive(Parser)]
struct Cli {
    /// Files to process
    #[arg(required = true)]
    files: Vec<String>,
}

Multi-Value Options

Use Case: Accept multiple values for an option

Example:

deploy --tag v1.0.0 --tag latest --tag stable

Python (Typer):

def deploy(
    tags: Annotated[list[str], typer.Option("--tag")] = []
):
    pass

Go (Cobra):

var tags []string

deployCmd.Flags().StringSliceVar(&tags, "tag", []string{}, "Tags to apply")

Rust (clap):

#[derive(Parser)]
struct Cli {
    /// Tags to apply
    #[arg(long)]
    tags: Vec<String>,
}

Language-Specific Patterns

Python: Type Hint Patterns

Optional Values:

from typing import Optional

def command(
    value: Annotated[Optional[str], typer.Option()] = None
):
    if value is not None:
        # Use value
        pass

Union Types (Multiple Allowed Types):

from typing import Union

def command(
    value: Annotated[Union[str, int], typer.Option()]
):
    # value can be string or int
    pass

Literal Types (Specific Values):

from typing import Literal

def deploy(
    env: Annotated[Literal["dev", "staging", "prod"], typer.Option()]
):
    pass

Go: Persistent vs. Local Flags

Persistent Flags (Available to All Subcommands):

var verbose bool

rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Verbose")

// Available in all subcommands

Local Flags (Specific to Command):

var dryRun bool

deployCmd.Flags().BoolVar(&dryRun, "dry-run", false, "Dry run")

// Only available for 'deploy' command

Rust: Derive vs. Builder API

Derive API (Declarative):

#[derive(Parser)]
struct Cli {
    #[arg(short, long)]
    verbose: bool,
}

Builder API (Programmatic):

use clap::{Arg, Command};

let matches = Command::new("myapp")
    .arg(Arg::new("verbose")
        .short('v')
        .long("verbose")
        .action(clap::ArgAction::SetTrue))
    .get_matches();

let verbose = matches.get_flag("verbose");

Best Practices Summary

Argument Design:

• Limit positional arguments to 2-3
• Use options for most parameters
• Provide both short and long forms for common flags
• Use descriptive long-form names

Validation:

• Validate early (before processing)
• Provide helpful error messages with suggestions
• Use type system for automatic validation when possible

Defaults:

• Provide sensible defaults
• Document all defaults in help text
• Allow environment variables to override defaults

Help Text:

• Write clear, concise help for each parameter
• Include examples in command help
• Document valid ranges and choices

Configuration Management Guide

Comprehensive guide to managing CLI configuration from multiple sources with proper precedence and validation.

Table of Contents

• Configuration Sources
• Precedence Strategy
• File Formats
• Multi-Language Implementation
• Best Practices

Configuration Sources

Standard Configuration Hierarchy

1. CLI Arguments/Flags (Highest Priority)

• Explicitly provided by user
• Always takes precedence
• Example: --port 8080

2. Environment Variables

• Session-specific overrides
• Useful for CI/CD and containers
• Example: export MYAPP_PORT=8080

3. Config File - Local (Project-Level)

• Project-specific settings
• Location: ./myapp.yaml or ./.myapp.yaml
• Committed to version control (usually)

4. Config File - User (User-Level)

• User-specific settings across projects
• Location: ~/.config/myapp/config.yaml (XDG)
• Not committed to version control

5. Config File - System (System-Level)

• System-wide defaults for all users
• Location: /etc/myapp/config.yaml (Unix)
• Managed by system administrators

6. Built-in Defaults (Lowest Priority)

• Hardcoded in application
• Fallback when nothing else is specified

Precedence Strategy

Implementation Pattern

Merge Strategy:

final_value = (
    cli_arg
    OR env_var
    OR local_config_value
    OR user_config_value
    OR system_config_value
    OR default_value
)

Example:

# System config: port = 3000
# User config: port = 4000
# Local config: port = 5000
# Environment: MYAPP_PORT=6000
# CLI arg: --port 8080

# Result: port = 8080 (CLI arg wins)

Partial Override Strategy

Some configurations support partial overrides (merge, not replace):

Example:

# System config
database:
  host: localhost
  port: 5432

# User config (merges with system)
database:
  port: 5433  # Overrides port only

# Result:
database:
  host: localhost  # From system
  port: 5433       # From user

File Formats

YAML (Recommended)

Advantages:

• Human-readable
• Supports comments
• Natural for nested data
• Wide ecosystem support

Example (myapp.yaml):

# Server configuration
server:
  host: localhost
  port: 8080
  workers: 4

# Database configuration
database:
  host: db.example.com
  port: 5432
  name: myapp_db
  credentials:
    user: dbuser
    # password loaded from environment

# Feature flags
features:
  enable_cache: true
  enable_metrics: true
  log_level: info

TOML (Alternative)

Advantages:

• Explicit types
• Good for flat or moderately nested data
• Popular in Rust ecosystem (Cargo.toml)

Example (myapp.toml):

[server]
host = "localhost"
port = 8080
workers = 4

[database]
host = "db.example.com"
port = 5432
name = "myapp_db"

[database.credentials]
user = "dbuser"

[features]
enable_cache = true
enable_metrics = true
log_level = "info"

JSON (Machine-Friendly)

Advantages:

• Universal support
• Strict validation
• Good for programmatic generation

Disadvantages:

• No comments (limitation)
• Less human-friendly

Example (myapp.json):

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "workers": 4
  },
  "database": {
    "host": "db.example.com",
    "port": 5432,
    "name": "myapp_db"
  }
}

Recommendation: Use YAML for user-facing configs, JSON for machine-generated configs.

Multi-Language Implementation

Python: YAML + Environment Variables

Implementation:

import os
import yaml
from pathlib import Path
from typing import Any, Optional

class Config:
    def __init__(self):
        self.config = {}
        self.load_config()

    def load_config(self):
        """Load configuration from multiple sources with precedence."""
        # 1. System config
        system_config = Path("/etc/myapp/config.yaml")
        if system_config.exists():
            self.config.update(yaml.safe_load(system_config.read_text()))

        # 2. User config (XDG)
        user_config = Path.home() / ".config" / "myapp" / "config.yaml"
        if user_config.exists():
            self.config.update(yaml.safe_load(user_config.read_text()))

        # 3. Local config
        local_config = Path("./myapp.yaml")
        if not local_config.exists():
            local_config = Path("./.myapp.yaml")
        if local_config.exists():
            self.config.update(yaml.safe_load(local_config.read_text()))

    def get(self, key: str, env_var: Optional[str] = None, default: Any = None) -> Any:
        """Get config value with environment variable override."""
        # 1. Check environment variable
        if env_var and (value := os.getenv(env_var)):
            return value

        # 2. Check config file
        if key in self.config:
            return self.config[key]

        # 3. Return default
        return default

# Usage in Typer app
import typer

app = typer.Typer()
config = Config()

@app.command()
def serve(
    host: Optional[str] = typer.Option(None, "--host", help="Server host"),
    port: Optional[int] = typer.Option(None, "--port", help="Server port"),
):
    """Start server with merged configuration."""
    # Precedence: CLI arg > env var > config file > default
    final_host = host or config.get("server.host", "MYAPP_HOST", "localhost")
    final_port = port or config.get("server.port", "MYAPP_PORT", 8080)

    typer.echo(f"Starting server at {final_host}:{final_port}")

With Pydantic for Validation:

from pydantic import BaseSettings, Field

class ServerConfig(BaseSettings):
    host: str = Field(default="localhost", env="MYAPP_HOST")
    port: int = Field(default=8080, env="MYAPP_PORT")
    workers: int = Field(default=4, env="MYAPP_WORKERS")

    class Config:
        # Automatically load from environment variables
        case_sensitive = False
        env_prefix = "MYAPP_"

# Usage
server_config = ServerConfig()
print(f"Host: {server_config.host}, Port: {server_config.port}")

Go: Viper for Configuration

Implementation:

package main

import (
    "fmt"
    "github.com/spf13/cobra"
    "github.com/spf13/viper"
)

func initConfig() {
    // Set config file name and type
    viper.SetConfigName("config")
    viper.SetConfigType("yaml")

    // Add config search paths (precedence: local > user > system)
    viper.AddConfigPath(".")                      // Local
    viper.AddConfigPath("$HOME/.config/myapp")   // User
    viper.AddConfigPath("/etc/myapp")            // System

    // Environment variable support
    viper.SetEnvPrefix("MYAPP")  // MYAPP_HOST, MYAPP_PORT
    viper.AutomaticEnv()         // Automatically bind env vars

    // Read config file
    if err := viper.ReadInConfig(); err == nil {
        fmt.Println("Using config file:", viper.ConfigFileUsed())
    }
}

var rootCmd = &cobra.Command{
    Use:   "myapp",
    Short: "My application",
}

var serveCmd = &cobra.Command{
    Use:   "serve",
    Short: "Start server",
    Run: func(cmd *cobra.Command, args []string) {
        // Get values with precedence: flag > env > config > default
        host := viper.GetString("host")
        port := viper.GetInt("port")

        fmt.Printf("Starting server at %s:%d\n", host, port)
    },
}

func init() {
    // Initialize config before commands run
    cobra.OnInitialize(initConfig)

    // Define flags
    serveCmd.Flags().String("host", "localhost", "Server host")
    serveCmd.Flags().Int("port", 8080, "Server port")

    // Bind flags to viper
    viper.BindPFlag("host", serveCmd.Flags().Lookup("host"))
    viper.BindPFlag("port", serveCmd.Flags().Lookup("port"))

    rootCmd.AddCommand(serveCmd)
}

func main() {
    rootCmd.Execute()
}

Viper Features:

• Automatic precedence handling
• Environment variable binding
• Multiple config file formats (YAML, TOML, JSON)
• Live config reloading (optional)
• Default value management

Rust: config crate + Environment

Cargo.toml:

[dependencies]
config = "0.13"
serde = { version = "1.0", features = ["derive"] }

Implementation:

use config::{Config, ConfigError, Environment, File};
use serde::Deserialize;
use std::env;

#[derive(Debug, Deserialize)]
struct ServerConfig {
    host: String,
    port: u16,
    workers: usize,
}

#[derive(Debug, Deserialize)]
struct AppConfig {
    server: ServerConfig,
}

fn load_config() -> Result<AppConfig, ConfigError> {
    let mut settings = Config::builder()
        // 1. System config
        .add_source(File::with_name("/etc/myapp/config").required(false))
        // 2. User config (XDG)
        .add_source(
            File::with_name(&format!(
                "{}/.config/myapp/config",
                env::var("HOME").unwrap_or_default()
            ))
            .required(false),
        )
        // 3. Local config
        .add_source(File::with_name("./myapp").required(false))
        .add_source(File::with_name("./.myapp").required(false))
        // 4. Environment variables (MYAPP_SERVER_HOST, MYAPP_SERVER_PORT)
        .add_source(Environment::with_prefix("MYAPP").separator("_"))
        // 5. Defaults
        .set_default("server.host", "localhost")?
        .set_default("server.port", 8080)?
        .set_default("server.workers", 4)?
        .build()?;

    settings.try_deserialize()
}

use clap::Parser;

#[derive(Parser)]
struct Cli {
    /// Server host
    #[arg(long)]
    host: Option<String>,

    /// Server port
    #[arg(long)]
    port: Option<u16>,
}

fn main() -> Result<(), ConfigError> {
    let cli = Cli::parse();
    let mut config = load_config()?;

    // CLI args override config
    if let Some(host) = cli.host {
        config.server.host = host;
    }
    if let Some(port) = cli.port {
        config.server.port = port;
    }

    println!(
        "Starting server at {}:{}",
        config.server.host, config.server.port
    );

    Ok(())
}

Best Practices

1. Document Configuration Precedence

In Help Text:

@app.command(help="""
Start the server.

Configuration precedence (highest to lowest):
1. CLI arguments (--host, --port)
2. Environment variables (MYAPP_HOST, MYAPP_PORT)
3. Local config file (./myapp.yaml)
4. User config file (~/.config/myapp/config.yaml)
5. System config file (/etc/myapp/config.yaml)
6. Built-in defaults
""")
def serve():
    pass

2. Provide Config Inspection

Show Effective Configuration:

@app.command()
def config_show():
    """Show effective configuration (after merging all sources)."""
    config = load_config()
    print(yaml.dump(config, default_flow_style=False))

Usage:

$ myapp config show
server:
  host: localhost
  port: 8080
  workers: 4
database:
  host: db.example.com
  port: 5432

3. Validate Configuration Early

Python (Pydantic):

from pydantic import BaseModel, Field, validator

class ServerConfig(BaseModel):
    host: str
    port: int = Field(ge=1, le=65535)  # Valid port range
    workers: int = Field(ge=1, le=100)

    @validator('host')
    def validate_host(cls, v):
        if not v or v.strip() == "":
            raise ValueError('host cannot be empty')
        return v

# Automatic validation on load
config = ServerConfig(**config_dict)  # Raises ValidationError if invalid

Go (Validation):

func validateConfig() error {
    if port := viper.GetInt("port"); port < 1 || port > 65535 {
        return fmt.Errorf("invalid port: %d (must be 1-65535)", port)
    }
    if workers := viper.GetInt("workers"); workers < 1 {
        return fmt.Errorf("workers must be at least 1")
    }
    return nil
}

4. Support Config File Generation

Generate Template:

@app.command()
def config_init(output: Path = typer.Option("./myapp.yaml")):
    """Generate a configuration file template."""
    template = """
# MyApp Configuration

server:
  host: localhost
  port: 8080
  workers: 4

database:
  host: localhost
  port: 5432
  name: myapp_db
"""
    output.write_text(template)
    typer.echo(f"Config template created at {output}")

5. Separate Secrets from Config

Never commit secrets to config files!

Use environment variables for secrets:

# config.yaml (safe to commit)
database:
  host: db.example.com
  port: 5432
  name: myapp_db
  # password loaded from MYAPP_DB_PASSWORD environment variable

Load secrets from environment:

import os

db_password = os.getenv("MYAPP_DB_PASSWORD")
if not db_password:
    raise ValueError("MYAPP_DB_PASSWORD environment variable required")

Or use secrets management tools:

• HashiCorp Vault
• AWS Secrets Manager
• Azure Key Vault
• Kubernetes Secrets

6. Support Environment-Specific Configs

Structure:

config/
├── base.yaml           # Common settings
├── development.yaml    # Dev overrides
├── staging.yaml        # Staging overrides
└── production.yaml     # Prod overrides

Load based on environment:

import os

env = os.getenv("APP_ENV", "development")
config_file = f"config/{env}.yaml"

config = yaml.safe_load(Path(config_file).read_text())

7. XDG Base Directory Specification (Linux/macOS)

Follow XDG standards for config file locations:

from pathlib import Path
import os

# XDG_CONFIG_HOME defaults to ~/.config
xdg_config_home = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config"))
user_config = xdg_config_home / "myapp" / "config.yaml"

# XDG_DATA_HOME defaults to ~/.local/share
xdg_data_home = Path(os.getenv("XDG_DATA_HOME", Path.home() / ".local" / "share"))
user_data = xdg_data_home / "myapp"

# XDG_CACHE_HOME defaults to ~/.cache
xdg_cache_home = Path(os.getenv("XDG_CACHE_HOME", Path.home() / ".cache"))
user_cache = xdg_cache_home / "myapp"

Configuration Checklist

• [ ] Support multiple config sources (CLI, env, files)
• [ ] Implement clear precedence (CLI > env > local > user > system > default)
• [ ] Validate configuration on load
• [ ] Provide config show command to inspect effective config
• [ ] Provide config init to generate template
• [ ] Document precedence in help text
• [ ] Use environment variables for secrets
• [ ] Follow XDG Base Directory specification
• [ ] Support environment-specific configs (dev, staging, prod)
• [ ] Never commit secrets to version control

CLI Distribution Guide

Guide to packaging and distributing CLIs across platforms and package managers.

Table of Contents

• Python Distribution
• Go Distribution
• Rust Distribution
• Cross-Platform Binary Releases

Python Distribution

PyPI (Python Package Index)

Project Structure:

myapp/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── myapp/
│       ├── __init__.py
│       └── cli.py
└── tests/

pyproject.toml:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "myapp"
version = "1.0.0"
description = "My CLI application"
readme = "README.md"
license = {file = "LICENSE"}
requires-python = ">=3.8"
dependencies = [
    "typer[all]>=0.9.0",
    "rich>=13.0.0",
]

[project.scripts]
myapp = "myapp.cli:app"

[project.urls]
Homepage = "https://github.com/user/myapp"
Repository = "https://github.com/user/myapp"

Build and Publish:

# Install build tools
pip install build twine

# Build distribution
python -m build

# Upload to PyPI
twine upload dist/*

# Or upload to TestPyPI first
twine upload --repository testpypi dist/*

Installation:

pip install myapp

Go Distribution

Homebrew (macOS/Linux)

Create Formula (myapp.rb):

class Myapp < Formula
  desc "My CLI application"
  homepage "https://github.com/user/myapp"
  url "https://github.com/user/myapp/archive/refs/tags/v1.0.0.tar.gz"
  sha256 "abc123..."  # sha256 of the tarball
  license "MIT"

  depends_on "go" => :build

  def install
    system "go", "build", *std_go_args(ldflags: "-s -w")
  end

  test do
    system "#{bin}/myapp", "--version"
  end
end

Tap Repository:

# Create tap repository
mkdir homebrew-tap
cd homebrew-tap
git init
cp myapp.rb Formula/myapp.rb
git add .
git commit -m "Add myapp formula"
git push origin main

Installation:

brew tap user/tap
brew install myapp

Go Install

Direct Installation:

go install github.com/user/myapp@latest

Requirements:

• go.mod in repository root
• Main package in cmd/myapp/ or root

Binary Releases (GitHub Actions)

.github/workflows/release.yml:

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        arch: [amd64, arm64]

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v4
        with:
          go-version: '1.21'

      - name: Build
        run: |
          GOOS=${{ matrix.os }} GOARCH=${{ matrix.arch }} \
          go build -o myapp-${{ matrix.os }}-${{ matrix.arch }}

      - uses: actions/upload-artifact@v3
        with:
          name: myapp-${{ matrix.os }}-${{ matrix.arch }}
          path: myapp-${{ matrix.os }}-${{ matrix.arch }}*

      - uses: softprops/action-gh-release@v1
        with:
          files: myapp-${{ matrix.os }}-${{ matrix.arch }}*

Rust Distribution

Cargo Install

Publish to crates.io:

Cargo.toml:

[package]
name = "myapp"
version = "1.0.0"
edition = "2021"
license = "MIT"
description = "My CLI application"
repository = "https://github.com/user/myapp"

[[bin]]
name = "myapp"
path = "src/main.rs"

[dependencies]
clap = { version = "4.5", features = ["derive"] }

Publish:

# Login to crates.io
cargo login

# Publish
cargo publish

Installation:

cargo install myapp

Binary Releases (GitHub Actions)

.github/workflows/release.yml:

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
          - os: ubuntu-latest
            target: aarch64-unknown-linux-gnu
          - os: macos-latest
            target: x86_64-apple-darwin
          - os: macos-latest
            target: aarch64-apple-darwin
          - os: windows-latest
            target: x86_64-pc-windows-msvc

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}

      - name: Build
        run: cargo build --release --target ${{ matrix.target }}

      - name: Package
        run: |
          cd target/${{ matrix.target }}/release
          tar czf myapp-${{ matrix.target }}.tar.gz myapp*

      - uses: softprops/action-gh-release@v1
        with:
          files: target/${{ matrix.target }}/release/myapp-*.tar.gz

Homebrew for Rust

Formula:

class Myapp < Formula
  desc "My CLI application"
  homepage "https://github.com/user/myapp"
  url "https://github.com/user/myapp/archive/refs/tags/v1.0.0.tar.gz"
  sha256 "abc123..."
  license "MIT"

  depends_on "rust" => :build

  def install
    system "cargo", "install", *std_cargo_args
  end

  test do
    system "#{bin}/myapp", "--version"
  end
end

Cross-Platform Binary Releases

Using GoReleaser (Go)

Install:

brew install goreleaser

.goreleaser.yaml:

builds:
  - env:
      - CGO_ENABLED=0
    goos:
      - linux
      - darwin
      - windows
    goarch:
      - amd64
      - arm64

archives:
  - format: tar.gz
    name_template: >-
      {{ .ProjectName }}_
      {{- .Version }}_
      {{- .Os }}_
      {{- .Arch }}

brews:
  - name: myapp
    tap:
      owner: user
      name: homebrew-tap
    homepage: "https://github.com/user/myapp"
    description: "My CLI application"

Release:

goreleaser release --clean

Using cargo-dist (Rust)

Install:

cargo install cargo-dist

Initialize:

cargo dist init

Build:

cargo dist build

Installation Scripts

Universal Install Script

install.sh:

#!/bin/bash
set -e

REPO="user/myapp"
BINARY="myapp"

# Detect OS and architecture
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)

case $ARCH in
    x86_64) ARCH="amd64" ;;
    aarch64|arm64) ARCH="arm64" ;;
    *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
esac

# Download latest release
LATEST=$(curl -s "https://api.github.com/repos/$REPO/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
URL="https://github.com/$REPO/releases/download/$LATEST/${BINARY}-${OS}-${ARCH}"

echo "Installing $BINARY $LATEST..."
curl -L -o "$BINARY" "$URL"
chmod +x "$BINARY"

# Install to /usr/local/bin
sudo mv "$BINARY" /usr/local/bin/

echo "$BINARY installed successfully!"
$BINARY --version

Usage:

curl -sSfL https://raw.githubusercontent.com/user/myapp/main/install.sh | bash

Best Practices

Versioning:

• Use semantic versioning (1.0.0)
• Tag releases in git (v1.0.0)
• Update version in source code

Changelog:

• Maintain CHANGELOG.md
• Document breaking changes
• Include migration guides

Documentation:

• Include installation instructions in README
• Document all package managers
• Provide troubleshooting guides

Testing:

• Test installation on all supported platforms
• Verify binary compatibility
• Test upgrade paths

CLI Framework Selection Guide

Comprehensive decision framework for choosing the appropriate CLI framework based on language, complexity, and requirements.

Table of Contents

• Decision Tree
• Python Frameworks
• Go Frameworks
• Rust Frameworks
• Comparison Matrix
• Migration Paths

Decision Tree

Start: Choose Based on Existing Project

Q1: What language is the project using?
  ├─ Python → Go to Python Frameworks
  ├─ Go → Go to Go Frameworks
  ├─ Rust → Go to Rust Frameworks
  └─ New Project/Flexible → Go to Requirements-Based Selection

Requirements-Based Selection (New Projects)

What is most important?

├─ Fast Development + Python Ecosystem
│  → Use Typer (Python)
│     - Type-safe, minimal boilerplate
│     - Rich ecosystem, easy distribution via PyPI
│     - 5-10 minutes to first working CLI
│
├─ Performance + Low Memory Footprint
│  → Use clap (Rust)
│     - Compile to native binary
│     - Minimal runtime overhead
│     - Type-safe at compile time
│
├─ Enterprise Integration + Go Ecosystem
│  → Use Cobra (Go)
│     - Industry standard (Kubernetes, Docker)
│     - Strong stdlib, easy cross-compilation
│     - Native binary distribution
│
└─ Quick Script (<100 lines)
   → Use Typer (Python)
      - Fastest time to working CLI
      - No compilation required
      - Easy to modify and iterate

Python Frameworks

Typer (Recommended for New Projects)

When to Use:

• New Python CLI projects (2025 standard)
• Type-safe applications with Python 3.7+
• Need auto-completion and validation
• Want minimal boilerplate with modern ergonomics
• Building CLI for FastAPI project (consistent tooling)

Strengths:

• Type hints for automatic validation and documentation
• Minimal code for full-featured CLIs
• Excellent error messages with suggestions
• Auto-completion support (bash, zsh, fish)
• Rich/colorful output built-in
• Built on Click (can drop down when needed)

Considerations:

• Requires Python 3.6+ (type hints)
• Younger ecosystem than Click
• Slightly slower than Click (minimal difference)

Installation:

pip install "typer[all]"  # Includes rich, shellingham

Best For:

• Developer tools and automation
• API client CLIs
• Modern Python projects
• Interactive CLIs with prompts/progress

Click (Alternative for Complex/Legacy Projects)

When to Use:

• Existing projects already using Click
• Need specific Click plugins
• Complex nested command structures
• Python <3.6 support required (rare in 2025)
• Large existing Click codebase

Strengths:

• Very mature and stable (2014+)
• Large ecosystem of plugins
• Flexible and composable
• Excellent documentation
• Battle-tested in production

Considerations:

• More verbose than Typer
• No type hint integration
• Manual validation required

Installation:

pip install click

Best For:

• Complex multi-level command trees
• Legacy Python codebases
• Projects requiring specific Click plugins

Comparison: Typer vs. Click

Decision: Use Typer for new projects, Click for existing codebases or if specific plugins required.

Go Frameworks

Cobra (Recommended for Most Projects)

When to Use:

• Enterprise-grade CLI tools
• Complex subcommand hierarchies (like git, docker, kubectl)
• Go projects requiring configuration management (with Viper)
• Need POSIX-compliant flags
• Building developer tooling

Strengths:

• Industry standard (Kubernetes, Docker, GitHub CLI, Hugo, Terraform)
• Designed for complex multi-command CLIs
• Excellent subcommand support
• Viper integration for configuration
• Automatic help and usage generation
• Shell completion for all major shells
• Generator tool (cobra-cli) for scaffolding

Considerations:

• Can be overkill for simple CLIs (5-10 commands)
• More boilerplate than alternatives
• Steeper learning curve for beginners

Installation:

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

Best For:

• Multi-command CLIs with 10+ commands
• Infrastructure tools (deployment, monitoring)
• Cloud provider CLIs
• Developer tooling (build systems, test runners)

urfave/cli (Alternative for Simple CLIs)

When to Use:

• Simple CLI tools (5-10 commands max)
• Quick scripts and utilities
• Prefer minimal boilerplate
• Lightweight dependency footprint

Strengths:

• Simpler API than Cobra
• Less boilerplate for basic CLIs
• Good documentation with clear examples
• Lightweight (smaller binary size)

Considerations:

• Less powerful for complex command trees
• Smaller ecosystem than Cobra
• Less common in enterprise projects

Installation:

go get github.com/urfave/cli/v2

Best For:

• Single-purpose utilities
• Quick automation scripts
• Learning Go CLI development

Comparison: Cobra vs. urfave/cli

Decision: Use Cobra for enterprise tools and complex CLIs, urfave/cli for simple utilities.

Rust Frameworks

clap v4 (Recommended for All Rust CLIs)

When to Use:

• All Rust CLI projects (default choice in 2025)
• Need compile-time safety (derive API)
• Performance-critical CLIs
• Want excellent error messages
• Building system utilities or developer tools

Strengths:

• Two APIs: Derive (declarative, type-safe) and Builder (programmatic, flexible)
• Compile-time validation (derive API catches errors before runtime)
• Improved v4: Faster compile times, better error messages
• Comprehensive feature set (subcommands, validation, shell completion, colored help)
• Active development with modern Rust idioms
• Performance: Minimal runtime overhead

API Choice:

Derive API:

• Type-safe at compile time
• Declarative (attributes on structs)
• Best for: Static command structures
• Example: Most CLIs with fixed commands

Builder API:

• Runtime flexibility
• Programmatic construction
• Best for: Dynamic commands, plugin systems
• Example: CLIs with runtime-loaded subcommands

Considerations:

• Derive API requires feature flag
• Learning curve for advanced features
• Compile times (improved in v4, still slower than interpreted languages)

Installation:

[dependencies]
clap = { version = "4.5", features = ["derive"] }

Best For:

• Performance-critical tools
• System utilities (replacements for coreutils)
• Developer tools requiring fast startup
• Cross-platform binaries

Alternative: structopt (Legacy)

Note: structopt is now deprecated. clap v3+ absorbed structopt's derive functionality. Migrate existing structopt projects to clap v4 derive API.

Comparison Matrix

Cross-Language Framework Comparison

Feature Support Matrix

Migration Paths

Python: Click → Typer

Why Migrate:

• Modern type safety with type hints
• Reduced boilerplate
• Better auto-completion support

Migration Strategy:

# Click
import click

@click.command()
@click.argument('name')
@click.option('--count', default=1)
def hello(name, count):
    click.echo(f'Hello {name}!' * count)

# Typer equivalent
import typer
from typing import Annotated

app = typer.Typer()

@app.command()
def hello(
    name: Annotated[str, typer.Argument()],
    count: Annotated[int, typer.Option()] = 1
):
    typer.echo(f'Hello {name}!' * count)

Gradual Migration:

• Typer is built on Click (can coexist)
• Migrate command by command
• Use Click's @click.pass_context for interop

Go: urfave/cli → Cobra

Why Migrate:

• Better subcommand support
• Viper configuration integration
• Industry standard tooling

Migration Strategy:

// urfave/cli
app := &cli.App{
    Name: "myapp",
    Action: func(c *cli.Context) error {
        fmt.Println("Hello")
        return nil
    },
}

// Cobra equivalent
var rootCmd = &cobra.Command{
    Use:   "myapp",
    Short: "My application",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("Hello")
    },
}

Gradual Migration:

• Start with root command
• Migrate subcommands one at a time
• Test thoroughly (API differences)

Rust: structopt → clap v4

Why Migrate:

• structopt is deprecated
• clap v4 has better compile times
• More features and active development

Migration Strategy:

// Old structopt
use structopt::StructOpt;

#[derive(StructOpt)]
struct Cli {
    #[structopt(short, long)]
    verbose: bool,
}

// New clap v4
use clap::Parser;

#[derive(Parser)]
struct Cli {
    #[arg(short, long)]
    verbose: bool,
}

Changes:

• #[structopt(...)] → #[arg(...)]
• #[derive(StructOpt)] → #[derive(Parser)]
• Import from clap instead of structopt

Decision Checklist

Use this checklist to select the appropriate framework:

Project Context:

• [ ] What language is the project using?
• [ ] Is this a new project or existing codebase?
• [ ] What is the expected complexity (simple, medium, complex)?

Requirements:

• [ ] Performance requirements (startup time, memory)?
• [ ] Type safety requirements?
• [ ] Distribution method (PyPI, Homebrew, binary)?
• [ ] Team expertise (language familiarity)?

Features Needed:

• [ ] Subcommand support?
• [ ] Configuration file management?
• [ ] Shell completion?
• [ ] Interactive features (prompts, progress)?

Recommendations Based on Answers:

Python:

• New project + type safety → Typer
• Existing Click project → Click (or migrate to Typer)
• Complex command trees → Click or Typer

Go:

• Enterprise tool + complex commands → Cobra
• Simple utility → urfave/cli
• Need configuration management → Cobra + Viper

Rust:

• Any Rust CLI → clap v4 (derive or builder)
• Static commands → derive API
• Dynamic commands → builder API

Output Formatting Guide

Guide to formatting CLI output for both human and machine consumption.

Table of Contents

• Output Modes
• Human-Readable Output
• Machine-Readable Output
• Progress Indicators
• Error Handling

Output Modes

Standard Output Streams

stdout (Standard Output):

• Use for data and results
• Pipe-friendly (can be piped to other commands)
• Example: myapp list | jq '.'

stderr (Standard Error):

• Use for errors, warnings, and log messages
• Not captured by pipes (unless explicitly redirected)
• Example: Progress bars, debug messages

Exit Codes:

• 0: Success
• 1: General error
• 2: Usage error (invalid arguments)
• Custom codes: Document in help text

Human-Readable Output

Tables

Python (rich):

from rich.console import Console
from rich.table import Table

console = Console()

table = Table(title="Deployments")
table.add_column("Name", style="cyan")
table.add_column("Status", style="magenta")
table.add_column("Age", style="green")

table.add_row("web-app", "Running", "2d")
table.add_row("api-server", "Stopped", "5h")

console.print(table)

Go (tablewriter):

import "github.com/olekukonko/tablewriter"

table := tablewriter.NewWriter(os.Stdout)
table.SetHeader([]string{"Name", "Status", "Age"})
table.Append([]string{"web-app", "Running", "2d"})
table.Append([]string{"api-server", "Stopped", "5h"})
table.Render()

Rust (comfy-table):

use comfy_table::{Table, Row};

let mut table = Table::new();
table.set_header(vec!["Name", "Status", "Age"]);
table.add_row(vec!["web-app", "Running", "2d"]);
table.add_row(vec!["api-server", "Stopped", "5h"]);
println!("{table}");

Colored Output

Auto-detect TTY:

import sys

def supports_color():
    return sys.stdout.isatty()

if supports_color():
    # Use colors
    print("\033[32mSuccess!\033[0m")
else:
    # Plain text
    print("Success!")

Python (rich):

from rich.console import Console

console = Console()
console.print("[green]Success![/green]")
console.print("[red]Error![/red]")
console.print("[yellow]Warning[/yellow]")

Go (color):

import "github.com/fatih/color"

color.Green("Success!")
color.Red("Error!")
color.Yellow("Warning")

Rust (colored):

use colored::*;

println!("{}", "Success!".green());
println!("{}", "Error!".red());
println!("{}", "Warning".yellow());

Machine-Readable Output

JSON Output

Python:

import json

@app.command()
def list_items(output: str = typer.Option("table", "--output", "-o")):
    items = [
        {"name": "web-app", "status": "running"},
        {"name": "api-server", "status": "stopped"},
    ]

    if output == "json":
        print(json.dumps(items, indent=2))
    elif output == "table":
        # ... table rendering
        pass

Go:

import "encoding/json"

if outputFormat == "json" {
    data, _ := json.MarshalIndent(items, "", "  ")
    fmt.Println(string(data))
}

Rust:

use serde_json;

if output_format == "json" {
    println!("{}", serde_json::to_string_pretty(&items)?);
}

YAML Output

Python:

import yaml

print(yaml.dump(items, default_flow_style=False))

Go:

import "gopkg.in/yaml.v3"

data, _ := yaml.Marshal(items)
fmt.Println(string(data))

Rust:

use serde_yaml;

println!("{}", serde_yaml::to_string(&items)?);

Progress Indicators

Progress Bars

Python (rich):

from rich.progress import Progress
import time

with Progress() as progress:
    task = progress.add_task("[cyan]Processing...", total=100)
    for i in range(100):
        time.sleep(0.01)
        progress.update(task, advance=1)

Go (progressbar):

import "github.com/schollz/progressbar/v3"

bar := progressbar.Default(100)
for i := 0; i < 100; i++ {
    bar.Add(1)
    time.Sleep(10 * time.Millisecond)
}

Rust (indicatif):

use indicatif::ProgressBar;

let bar = ProgressBar::new(100);
for _ in 0..100 {
    bar.inc(1);
    thread::sleep(Duration::from_millis(10));
}
bar.finish_with_message("Done!");

Spinners

Python (rich):

from rich.console import Console

console = Console()
with console.status("[bold green]Working..."):
    time.sleep(3)  # Do work

Go (spinner):

import "github.com/briandowns/spinner"

s := spinner.New(spinner.CharSets[9], 100*time.Millisecond)
s.Start()
time.Sleep(3 * time.Second)
s.Stop()

Rust (indicatif):

use indicatif::ProgressBar;

let spinner = ProgressBar::new_spinner();
spinner.set_message("Working...");
thread::sleep(Duration::from_secs(3));
spinner.finish_with_message("Done!");

Error Handling

Error Messages

Best Practices:

• Write errors to stderr
• Provide actionable suggestions
• Include error codes for scripting
• Use colors for visibility (if TTY)

Python:

import sys

def error(message: str, exit_code: int = 1):
    console.print(f"[red]Error:[/red] {message}", file=sys.stderr)
    raise typer.Exit(exit_code)

# Usage
if not file_exists:
    error("Config file not found. Run 'myapp config init' to create one.")

Go:

import (
    "fmt"
    "os"
)

func error(message string, exitCode int) {
    fmt.Fprintf(os.Stderr, "Error: %s\n", message)
    os.Exit(exitCode)
}

Rust:

eprintln!("Error: {}", message);
std::process::exit(1);

Warnings

Python:

console.print("[yellow]Warning:[/yellow] Using default configuration", file=sys.stderr)

Go:

fmt.Fprintf(os.Stderr, "Warning: %s\n", message)

Rust:

eprintln!("Warning: {}", message);

Best Practices Summary

Output Design:

• Default to human-readable (tables, colors)
• Provide --output flag for JSON/YAML
• Write data to stdout, logs to stderr
• Disable colors when not a TTY

Progress Indicators:

• Use progress bars for operations >2 seconds
• Use spinners for indeterminate operations
• Write to stderr (keeps stdout clean)

Error Handling:

• Clear error messages with suggestions
• Use exit codes: 0 = success, 1 = error, 2 = usage
• Log errors to stderr
• Provide --verbose for debugging

Shell Completion Guide

Guide to generating and installing shell completions for bash, zsh, fish, and PowerShell.

Table of Contents

• Python (Typer)
• Go (Cobra)
• Rust (clap)
• Installation Instructions

Python (Typer)

Generating Completions

Typer supports automatic completion generation via environment variables:

# Bash
_MYAPP_COMPLETE=bash_source myapp > ~/.myapp-complete.bash

# Zsh
_MYAPP_COMPLETE=zsh_source myapp > ~/.myapp-complete.zsh

# Fish
_MYAPP_COMPLETE=fish_source myapp > ~/.config/fish/completions/myapp.fish

# PowerShell
_MYAPP_COMPLETE=powershell_source myapp > ~/.myapp-complete.ps1

Implementation

No special code required - Typer handles completion automatically via Click.

Installation

Bash:

echo "source ~/.myapp-complete.bash" >> ~/.bashrc
source ~/.bashrc

Zsh:

echo "source ~/.myapp-complete.zsh" >> ~/.zshrc
source ~/.zshrc

Fish:

# Completion file already in correct location
# Restart fish shell

PowerShell:

Add-Content $PROFILE ". ~/.myapp-complete.ps1"

Go (Cobra)

Generating Completions

Add completion command to your CLI:

package main

import (
    "github.com/spf13/cobra"
    "os"
)

var rootCmd = &cobra.Command{
    Use:   "myapp",
    Short: "My application",
}

var completionCmd = &cobra.Command{
    Use:   "completion [bash|zsh|fish|powershell]",
    Short: "Generate shell completion scripts",
    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)
        case "fish":
            rootCmd.GenFishCompletion(os.Stdout, true)
        case "powershell":
            rootCmd.GenPowerShellCompletionWithDesc(os.Stdout)
        }
    },
}

func init() {
    rootCmd.AddCommand(completionCmd)
}

func main() {
    rootCmd.Execute()
}

Usage

# Generate completion
myapp completion bash > /etc/bash_completion.d/myapp
myapp completion zsh > "${fpath[1]}/_myapp"
myapp completion fish > ~/.config/fish/completions/myapp.fish
myapp completion powershell > ~/.myapp-complete.ps1

Custom Completions

For dynamic completions (e.g., resource names from API):

var getCmd = &cobra.Command{
    Use:   "get [resource]",
    Short: "Get a resource",
    ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
        if len(args) == 0 {
            // Complete resource types
            return []string{"pods", "services", "deployments"}, cobra.ShellCompDirectiveNoFileComp
        }
        return nil, cobra.ShellCompDirectiveNoFileComp
    },
}

Rust (clap)

Dependencies

Add to Cargo.toml:

[dependencies]
clap = { version = "4.5", features = ["derive"] }
clap_complete = "4.5"

Implementation

use clap::{CommandFactory, Parser, Subcommand};
use clap_complete::{generate, shells::{Bash, Zsh, Fish, PowerShell}};
use std::io;

#[derive(Parser)]
#[command(name = "myapp")]
struct Cli {
    #[command(subcommand)]
    command: Option<Commands>,
}

#[derive(Subcommand)]
enum Commands {
    /// Generate shell completion scripts
    Completion {
        #[arg(value_enum)]
        shell: Shell,
    },
}

#[derive(clap::ValueEnum, Clone)]
enum Shell {
    Bash,
    Zsh,
    Fish,
    PowerShell,
}

fn main() {
    let cli = Cli::parse();

    if let Some(Commands::Completion { shell }) = cli.command {
        let mut cmd = Cli::command();
        match shell {
            Shell::Bash => generate(Bash, &mut cmd, "myapp", &mut io::stdout()),
            Shell::Zsh => generate(Zsh, &mut cmd, "myapp", &mut io::stdout()),
            Shell::Fish => generate(Fish, &mut cmd, "myapp", &mut io::stdout()),
            Shell::PowerShell => generate(PowerShell, &mut cmd, "myapp", &mut io::stdout()),
        }
    }
}

Usage

myapp completion bash > /etc/bash_completion.d/myapp
myapp completion zsh > "${fpath[1]}/_myapp"
myapp completion fish > ~/.config/fish/completions/myapp.fish

Installation Instructions

Bash

System-wide:

sudo myapp completion bash > /etc/bash_completion.d/myapp

User-level:

myapp completion bash > ~/.myapp-complete.bash
echo "source ~/.myapp-complete.bash" >> ~/.bashrc

Zsh

System-wide:

sudo myapp completion zsh > /usr/local/share/zsh/site-functions/_myapp

User-level:

mkdir -p ~/.zsh/completion
myapp completion zsh > ~/.zsh/completion/_myapp
echo 'fpath=(~/.zsh/completion $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

Fish

User-level (standard location):

myapp completion fish > ~/.config/fish/completions/myapp.fish

PowerShell

User-level:

myapp completion powershell > ~/.myapp-complete.ps1
Add-Content $PROFILE ". ~/.myapp-complete.ps1"

Testing Completions

Bash:

# Type command and press TAB twice
myapp <TAB><TAB>

# Should show available subcommands

Zsh:

# Type command and press TAB
myapp <TAB>

# Should show completions with descriptions

Fish:

# Type command and press TAB
myapp <TAB>

# Should show completions with descriptions

Best Practices

• Add completion command to CLI (myapp completion bash)
• Include installation instructions in README
• Test completions in all supported shells
• Document completion in --help output
• Provide installation script for ease of use

Subcommand Design Guide

Comprehensive guide to structuring CLI command hierarchies with subcommands, nesting strategies, and organization patterns.

Table of Contents

• Command Structure Patterns
• Organization Strategies
• Naming Conventions
• Language-Specific Implementation
• Best Practices

Command Structure Patterns

Pattern 1: Flat Structure (Single Level)

Structure:

app command1 [args]
app command2 [args]
app command3 [args]

When to Use:

• Small CLIs with 5-10 distinct operations
• Commands are independent (no natural groupings)
• Simplicity is priority

Example:

myapp deploy
myapp logs
myapp status
myapp restart
myapp rollback

Advantages:

• Simple to understand and use
• Low cognitive load
• Easy to implement

Disadvantages:

• Doesn't scale beyond 10-15 commands
• No logical grouping of related operations

Pattern 2: Grouped Structure (Two Levels)

Structure:

app group1 subcommand [args]
app group2 subcommand [args]

When to Use:

• Medium CLIs with logical groupings (10-30 commands)
• Commands naturally cluster by resource or action
• Need organization without overwhelming complexity

Example (Resource-Based Grouping):

kubectl get pods
kubectl get services
kubectl create deployment
kubectl create service
kubectl delete pod
kubectl delete deployment

Example (Action-Based Grouping):

docker container start
docker container stop
docker container list
docker image build
docker image push
docker image pull

Advantages:

• Logical organization
• Scalable to 30-40 commands
• Discoverable via help

Disadvantages:

• Slightly more typing
• Requires choosing between resource-based or action-based grouping

Pattern 3: Nested Structure (Three+ Levels)

Structure:

app group subgroup command [args]

When to Use:

• Large CLIs with deep hierarchies (30+ commands)
• Complex domains with multiple dimensions of organization
• Cloud provider CLIs, infrastructure tools

Example:

gcloud compute instances create
gcloud compute instances delete
gcloud compute disks create
gcloud container clusters create
aws ec2 describe-instances
aws s3 cp

Advantages:

• Handles very large command sets
• Precise organization

Disadvantages:

• Can become unwieldy (typing overhead)
• Difficult to remember deep paths
• Risk of over-nesting

⚠️ Warning: Avoid nesting beyond 3 levels. Beyond this, consider:

• Flattening hierarchy
• Splitting into multiple CLI tools
• Using aliases for common paths

Organization Strategies

Strategy 1: Resource-Based (CRUD Pattern)

Organization: Group by resource type (nouns)

Structure:

app resource action [args]

Example:

# Kubernetes-style
kubectl get pods
kubectl get services
kubectl create deployment
kubectl delete pod

# Database CLI
dbcli users list
dbcli users create
dbcli tables describe
dbcli tables drop

When to Use:

• Managing resources (infrastructure, databases)
• CRUD operations are primary use case
• Users think in terms of "what" they're managing

Advantages:

• Natural for resource management
• Clear resource boundaries
• Easy to add new resources

Implementation:

Python (Typer):

import typer

app = typer.Typer()

# Create subapps for each resource
pods_app = typer.Typer()
services_app = typer.Typer()

@pods_app.command("list")
def list_pods():
    """List all pods."""
    pass

@pods_app.command("create")
def create_pod(name: str):
    """Create a pod."""
    pass

# Mount subapps
app.add_typer(pods_app, name="pods")
app.add_typer(services_app, name="services")

Go (Cobra):

var rootCmd = &cobra.Command{Use: "myapp"}

var podsCmd = &cobra.Command{Use: "pods"}
var listPodsCmd = &cobra.Command{
    Use:   "list",
    Run: func(cmd *cobra.Command, args []string) {
        // List pods
    },
}

podsCmd.AddCommand(listPodsCmd)
rootCmd.AddCommand(podsCmd)

Strategy 2: Action-Based (Verb-First Pattern)

Organization: Group by action type (verbs)

Structure:

app action resource [args]

Example:

# Git-style
git add file.txt
git commit -m "message"
git push origin main

# Build tool
build compile src/
build test unit
build package dist/

When to Use:

• Actions are the primary mental model
• Workflows are action-centric
• Consistent actions across different resources

Advantages:

• Natural for workflow-oriented CLIs
• Actions are prominent
• Good for task-based thinking

Implementation:

Python (Typer):

app = typer.Typer()

create_app = typer.Typer()
delete_app = typer.Typer()

@create_app.command("pod")
def create_pod(name: str):
    pass

@create_app.command("service")
def create_service(name: str):
    pass

app.add_typer(create_app, name="create")
app.add_typer(delete_app, name="delete")

Strategy 3: Hybrid (Context-Dependent)

Organization: Mix resource-based and action-based as appropriate

Structure:

app [context] action [resource] [args]

Example:

# Docker uses hybrid approach
docker container run    # resource-based
docker build           # action-based
docker image ls        # resource-based
docker login           # action-based

# AWS CLI
aws s3 cp              # action on resource
aws ec2 describe-instances  # action on resource
aws configure          # standalone action

When to Use:

• Some commands are clearly resource-bound
• Other commands are standalone actions
• Pragmatic balance between consistency and usability

Best Practice: Be consistent within each command group, even if different groups use different patterns.

Naming Conventions

Command Naming

Use Verbs for Actions:

• create, delete, update, list, get, show
• deploy, rollback, restart, stop, start
• build, test, run, clean

Use Nouns for Resources:

• pod, service, deployment, node
• user, database, table, index
• instance, volume, snapshot, image

Avoid Ambiguity:

• ✅ list or ls (clear)
• ❌ l (too short, unclear)
• ✅ delete or remove or rm (pick one, be consistent)
• ❌ Mix of delete, remove, del, rm (inconsistent)

Consistency Rules

Verb Consistency:

• Choose one verb per action and stick to it
• ✅ Always use create (not mix of create, new, add)
• ✅ Always use list (not mix of list, ls, show)

Noun Consistency:

• Use singular or plural consistently
• ✅ pod, service (singular)
• ✅ pods, services (plural)
• ❌ Mix of pod and services (inconsistent)

Abbreviations:

• Support both full and short forms where appropriate
• list and ls, delete and rm
• Document abbreviations in help text

Alias Support

Common Aliases:

# kubectl supports aliases
kubectl get pods  # full
kubectl get po    # abbreviated

# git supports aliases
git checkout      # full
git co            # alias

Implementation:

Python (Typer):

@app.command("list", help="List resources")
@app.command("ls", help="List resources (alias)")
def list_resources():
    pass

Go (Cobra):

var listCmd = &cobra.Command{
    Use:     "list",
    Aliases: []string{"ls"},
    Short:   "List resources",
}

Rust (clap):

#[derive(Subcommand)]
enum Commands {
    #[command(alias = "ls")]
    List,
}

Language-Specific Implementation

Python: Nested Typer Apps

Pattern:

import typer

# Root app
app = typer.Typer()

# Resource group apps
pods_app = typer.Typer()
services_app = typer.Typer()

# Commands within resource groups
@pods_app.command("list")
def list_pods():
    """List all pods."""
    typer.echo("Listing pods...")

@pods_app.command("create")
def create_pod(name: str):
    """Create a pod."""
    typer.echo(f"Creating pod: {name}")

@services_app.command("list")
def list_services():
    """List all services."""
    typer.echo("Listing services...")

# Mount resource groups to root
app.add_typer(pods_app, name="pods", help="Manage pods")
app.add_typer(services_app, name="services", help="Manage services")

if __name__ == "__main__":
    app()

Usage:

python app.py pods list
python app.py pods create my-pod
python app.py services list

Go: Nested Cobra Commands

Pattern:

package main

import (
    "fmt"
    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "myapp",
    Short: "My application",
}

// Resource group commands
var podsCmd = &cobra.Command{
    Use:   "pods",
    Short: "Manage pods",
}

var servicesCmd = &cobra.Command{
    Use:   "services",
    Short: "Manage services",
}

// Subcommands
var listPodsCmd = &cobra.Command{
    Use:   "list",
    Short: "List pods",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("Listing pods...")
    },
}

var createPodCmd = &cobra.Command{
    Use:   "create [name]",
    Short: "Create pod",
    Args:  cobra.ExactArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Creating pod: %s\n", args[0])
    },
}

func init() {
    // Build hierarchy
    podsCmd.AddCommand(listPodsCmd, createPodCmd)
    servicesCmd.AddCommand(/* service commands */)
    rootCmd.AddCommand(podsCmd, servicesCmd)
}

func main() {
    rootCmd.Execute()
}

Rust: Nested clap Subcommands

Pattern:

use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(name = "myapp")]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    /// Manage pods
    Pods {
        #[command(subcommand)]
        subcommand: PodCommands,
    },
    /// Manage services
    Services {
        #[command(subcommand)]
        subcommand: ServiceCommands,
    },
}

#[derive(Subcommand)]
enum PodCommands {
    /// List all pods
    List,
    /// Create a pod
    Create {
        /// Pod name
        name: String,
    },
}

#[derive(Subcommand)]
enum ServiceCommands {
    /// List all services
    List,
}

fn main() {
    let cli = Cli::parse();

    match cli.command {
        Commands::Pods { subcommand } => match subcommand {
            PodCommands::List => println!("Listing pods..."),
            PodCommands::Create { name } => println!("Creating pod: {}", name),
        },
        Commands::Services { subcommand } => match subcommand {
            ServiceCommands::List => println!("Listing services..."),
        },
    }
}

Best Practices

1. Keep Command Paths Short

Good:

docker run nginx
kubectl get pods
git commit -m "message"

Too Deep:

myapp infrastructure cloud aws ec2 instances list region us-west-2
# 7 levels deep - too much!

Better:

myapp aws ec2 list --region us-west-2
# Flatten hierarchy, use flags for details

2. Group Logically

Resource-Based (Good for CRUD):

myapp users list
myapp users create
myapp users delete

Action-Based (Good for Workflows):

myapp deploy prod
myapp deploy staging
myapp rollback

3. Provide Clear Help at Each Level

Root Level Help:

$ myapp --help
Usage: myapp <COMMAND>

Commands:
  pods      Manage pods
  services  Manage services
  deploy    Deploy application
  logs      View logs

Subcommand Level Help:

$ myapp pods --help
Usage: myapp pods <COMMAND>

Commands:
  list    List all pods
  create  Create a pod
  delete  Delete a pod
  get     Get pod details

4. Support Common Patterns

CRUD Operations:

app resource create
app resource list
app resource get <id>
app resource update <id>
app resource delete <id>

Lifecycle Operations:

app resource start
app resource stop
app resource restart
app resource status

5. Design for Discoverability

Use `--help` liberally:

myapp --help           # Root help
myapp pods --help      # Group help
myapp pods list --help # Command help

Show examples in help:

@app.command(help="""
List all pods.

Examples:
  myapp pods list
  myapp pods list --namespace default
  myapp pods list --output json
""")
def list_pods():
    pass

6. Handle Global Flags

Persistent Flags (Go Cobra):

// Available to all subcommands
rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Verbose")
rootCmd.PersistentFlags().StringVar(&config, "config", "", "Config file")

Global Options (Python Typer):

app = typer.Typer()

@app.callback()
def main(
    verbose: bool = typer.Option(False, "--verbose", "-v"),
    config: str = typer.Option("config.yaml", "--config")
):
    """Global options available to all commands."""
    # Store in context or global state
    pass

Anti-Patterns to Avoid

❌ Inconsistent Naming

myapp create user
myapp new-database  # Should be: myapp create database
myapp add-role      # Should be: myapp create role

❌ Over-Nesting

myapp infrastructure cloud provider aws region us-west-2 ec2 instances list
# Too deep! Simplify to:
myapp aws ec2 list --region us-west-2

❌ Ambiguous Commands

myapp run      # Run what? Tests? Server? Script?
myapp process  # Process what?

# Better:
myapp server run
myapp tests run

❌ Mixing Patterns Randomly

myapp user create   # resource-based
myapp create role   # action-based
myapp delete user   # action-based
# Pick one pattern and stick to it!

Command Hierarchy Checklist

• [ ] Commands grouped logically (resource or action based)
• [ ] Maximum nesting depth of 3 levels
• [ ] Consistent verb usage (create, list, delete)
• [ ] Consistent noun usage (singular or plural)
• [ ] Help available at each level
• [ ] Common aliases provided (ls, rm)
• [ ] Global flags available to all subcommands
• [ ] Examples in help text
• [ ] Clear, descriptive command names