cli
/cli
Guidance for building command-line interfaces and terminal applications in Python. USE FOR: building CLI tools with argparse/click/typer, rich terminal output, TUI applications with textual, CLI testing strategies, output formatting, exit codes DO NOT USE FOR: Python project setup or packaging (use project-system), installing CLI tools (use package-management)
- Author
- Tyler-R-Kendrick ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 09.06.2026
Assessment and security
- Files in this package
- 16
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 6
No signals detected. Repository changed on 09.06.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Guidance for building command-line interfaces and terminal applications in Python. USE FOR: building CLI tools with argparse/click/typer, rich terminal output, TUI applications with textual, CLI testing strategies, output formatting, exit codes DO NOT USE FOR: Python project setup or packaging (use project-system), installing CLI tools (use package-management)
Original author description
Guidance for building command-line interfaces and terminal applications in Python. USE FOR: building CLI tools with argparse/click/typer, rich terminal output, TUI applications with textual, CLI testing strategies, output formatting, exit codes DO NOT USE FOR: Python project setup or packaging (use project-system), installing CLI tools (use package-management)
How it works
- Overview
- Tool Comparison
- argparse Patterns
- Click Deep Dive
- Typer Deep Dive
- Rich Library
- Textual for TUI Applications
- Output Formatting
- Exit Codes and Error Handling
- CLI Testing Strategies
SKILL.md preview
---
name: cli
description: |
Guidance for building command-line interfaces and terminal applications in Python.
USE FOR: building CLI tools with argparse/click/typer, rich terminal output, TUI applications with textual, CLI testing strategies, output formatting, exit codes
DO NOT USE FOR: Python project setup or packaging (use project-system), installing CLI tools (use package-management)
license: MIT
metadata:
displayName: "Python CLI Development"
author: "Tyler-R-Kendrick"
version: "1.0.0"
tags:
- python
- cli
- argparse
- click
- typer
- rich
- textual
- tui
compatibility: claude, copilot, cursor
references:
- title: "Typer Documentation"
url: "https://typer.tiangolo.com/"
- title: "Click Documentation"
url: "https://click.palletsprojects.com/"
- title: "Rich Documentation"
url: "https://rich.readthedocs.io/"
- title: "Python argparse Documentation"
url: "https://docs.python.org/3/library/argparse.html"
---
# Python CLI Development
## Overview
Python is one of the most popular languages for building command-line tools, from simple scripts to complex multi-command applications. The ecosystem ranges from the standard library's `argparse` to high-level frameworks like `typer` that generate CLIs from type hints, and rich output libraries like `rich` and `textual` for beautiful terminal interfaces.
## Tool Comparison
| Feature | argparse | click | typer | fire | cement |
|---------|----------|-------|-------|------|--------|
| **Stdlib** | Yes | No | No | No | No |
| **Approach** | Imperative | Decorator-based | Type-hint-based | Introspection | Full framework |
| **Subcommands** | Yes (subparsers) | Yes (groups) | Yes (app + commands) | Automatic | Yes |
| **Auto-completion** | No (add-on) | Yes (plugin) | Yes (built-in) | No | Yes |
| **Testing** | Manual | `CliRunner` | `CliRunner` (via click) | Manual | Built-in |
| **Rich output** | Manual | Plugin ecosystem | Built-in (via rich) | No | Yes |
| **Learning curve** | Low | Medium | Low | Very low | High |
| **Dependencies** | None | click | typer, click, rich | fire | cement |
| **Best for** | Simple tools, no-dependency scripts | Medium-to-large CLIs | Modern CLIs with type safety | Quick prototypes | Enterprise CLIs |
**Recommendation**: Use **typer** for new CLI projects -- it provides the best developer experience with type hints, auto-completion, and rich integration. Use **argparse** when you cannot add dependencies. Use **click** for maximum flexibility and a large plugin ecosystem.
## argparse Patterns
argparse is Python's built-in argument parsing library. It requires no external dependencies.
### Basic Usage
```python
import argparse
import sys
def main() -> int:
parser = argparse.ArgumentParser(
prog="mytool",
description="A tool that does useful things",
epilog="Example: mytool process --input data.csv --format json",
)
parser.add_argument("input", help="Input file path")
parser.add_argument("-o", "--output", default="-", help="Output file (default: stdout)")
parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose output")
parser.add_argument("--count", type=int, default=1, help="Number of repetitions")
args = parser.parse_args()
if args.verbose:
print(f"Processing {args.input}...")
return 0
if __name__ == "__main__":
sys.exit(main())
```
### Subcommands
```python
import argparse
def cmd_init(args: argparse.Namespace) -> int:
print(f"Initializing project: {args.name}")
return 0
def cmd_build(args: argparse.Namespace) -> int:
print(f"Building with config: {args.config}")
return 0
def main() -> int:
parser = argparse.ArgumentParser(prog="mytool")
subparsers = parser.add_subparsers(dest="command", required=True)
# init subcommand
init_parser = subparsers.add_parser("init", help="Initialize a new project")
init_parser.add_argument("name", help="Project name")
init_parser.set_defaults(func=cmd_init)
# build subcommand
build_parser = subparsers.add_parser("build", help="Build the project")
build_parser.add_argument("-c", "--config", default="release", help="Build config")
build_parser.set_defaults(func=cmd_build)
args = parser.parse_args()
return args.func(args)
```
### Mutually Exclusive Groups
```python
parser = argparse.ArgumentParser()
group = parser.add_mutually_exclusive_group(required=True)
group.add_argument("--json", action="store_true", help="Output as JSON")
group.add_argument("--csv", action="store_true", help="Output as CSV")
group.add_argument("--table", action="store_true", help="Output as table")
```
### Custom Types
```python
import argparse
from pathlib import Path
def existing_path(value: str) -> Path:
path = Path(value)
if not path.exists():
raise argparse.ArgumentTypeError(f"Path does not exist: {value}")
return path
def port_number(value: str) -> int:
port = int(value)
if not (1 <= port <= 65535):
raise argparse.ArgumentTypeError(f"Invalid port: {value} (must be 1-65535)")
return port
parser = argparse.ArgumentParser()
parser.add_argument("--config", type=existing_path, help="Config file path")
parser.add_argument("--port", type=port_number, default=8080, help="Server port")
```
## Click Deep Dive
Click is a mature, decorator-based framework for building CLIs. It emphasizes composability and testability.
### Installation
```bash
pip install click
```
### Basic Command
```python
import click
@click.command()
@click.argument("name")
@click.option("--greeting", "-g", default="Hello", help="The greeting to use")
@click.option("--count", "-c", default=1, type=int, help="Number of greetings")
@click.option("--verbose", "-v", is_flag=True, help="Enable verbose output")
def greet(name: str, greeting: str, count: int, verbose: bool) -> None:
"""Greet someone NAME times."""
if verbose:
click.echo(f"Greeting {name} {count} time(s)...")
for _ in range(count):
click.echo(f"{greeting}, {name}!")
if __name__ == "__main__":
greet()
```
### Command Groups (Subcommands)
```python
import click
@click.group()
@click.option("--debug/--no-debug", default=False, help="Enable debug mode")
@click.pass_context
def cli(ctx: click.Context, debug: bool) -> None:
"""My multi-command CLI tool."""
ctx.ensure_object(dict)
ctx.obj["debug"] = debug
@cli.command()
@click.argument("name")
@click.pass_context
def init(ctx: click.Context, name: str) -> None:
"""Initialize a new project."""
if ctx.obj["debug"]:
click.echo("Debug mode is on")
click.echo(f"Initializing {name}...")
@cli.command()
@click.option("--config", "-c", default="release", help="Build configuration")
@click.pass_context
def build(ctx: click.Context, config: str) -> None:
"""Build the project."""
click.echo(f"Building with config: {config}")
if __name__ == "__main__":
cli()
```
### Context and State Passing
```python
import click
class AppConfig:
def __init__(self, debug: bool = False, output_format: str = "text"):
self.debug = debug
self.output_format = output_format
pass_config = click.make_pass_decorator(AppConfig, ensure=True)
@click.group()
@click.option("--debug/--no-debug", default=False)
@click.option("--format", "output_format", type=click.Choice(["text", "json", "csv"]))
@click.pass_context
def cli(ctx: click.Context, debug: bool, output_format: str) -> None:
ctx.obj = AppConfig(debug=debug, output_format=output_format or "text")
@cli.command()
@pass_config
def status(config: AppConfig) -> None:
"""Show status."""
if config.output_format == "json":
click.echo('{"status": "ok"}')
else:
click.echo("Status: OK")
```
### File Handling
```python
import click
@click.command()
@click.argument("input_file", type=click.File("r"))
@click.argument("output_file", type=click.File("w"), default="-") # default to stdout
def process(input_file, output_file) -> None:
"""Process INPUT_FILE and write to OUTPUT_FILE."""
for line in input_file:
output_file.write(line.upper())
@click.command()
@click.argument("directory", type=click.Path(exists=True, file_okay=False, resolve_path=True))
def scan(directory: str) -> None:
"""Scan a DIRECTORY for files."""
click.echo(f"Scanning: {directory}")
```
### Testing with CliRunner
```python
from click.testing import CliRunner
from myapp.cli import cli
def test_init_command():
runner = CliRunner()
result = runner.invoke(cli, ["init", "myproject"])
assert result.exit_code == 0
assert "Initializing myproject" in result.output
def test_build_with_debug():
runner = CliRunner()
result = runner.invoke(cli, ["--debug", "build", "--config", "debug"])
assert result.exit_code == 0
def test_file_processing():
runner = CliRunner()
with runner.isolated_filesystem():
with open("input.txt", "w") as f:
f.write("hello\nworld\n")
result = runner.invoke(process, ["input.txt", "output.txt"])
assert result.exit_code == 0
with open("output.txt") as f:
assert f.read() == "HELLO\nWORLD\n"
```
### Useful Click Decorators and Features
```python
import click
# Password prompt (hidden input)
@click.command()
@click.option("--password", prompt=True, hide_input=True, confirmation_prompt=True)
def set_password(password: str) -> None:
click.echo("Password set.")
# Choice type
@click.command()
@click.option("--color", type=click.Choice(["red", "green", "blue"], case_sensitive=False))
def paint(color: str) -> None:
click.echo(f"Painting {color}")
# Range type
@click.command()
@click.option("--count", type=click.IntRange(1, 100), default=10)
def repeat(count: int) -> None:
click.echo(f"Repeating {count} times")
# Progress bar
@click.command()
def download() -> None:
items = range(1000)
with click.progressbar(items, label="Downloading") as bar:
for item in bar:
pass # do work
# Confirmation
@click.command()
@click.confirmation_option(prompt="Are you sure you want to delete everything?")
def delete_all() -> None:
click.echo("Deleted everything.")
```
## Typer Deep Dive
Typer builds on click but uses Python type hints to define CLI interfaces. It produces beautiful help text and integrates with rich out of the box.
### Installation
```bash
pip install typer
# With all optional dependencies (rich, shellingham)
pip install "typer[all]"
```
### Basic Command
```python
import typer
def main(
name: str,
greeting: str = "Hello",
count: int = 1,
verbose: bool = False,
) -> None:
"""Greet someone by NAME."""
if verbose:
typer.echo(f"Greeting {name} {count} time(s)...")
for _ in range(count):
typer.echo(f"{greeting}, {name}!")
if __name__ == "__main__":
typer.run(main)
```
### Multi-Command Application
```python
import typer
from typing import Annotated, Optional
from enum import Enum
from pathlib import Path
app = typer.Typer(help="My awesome CLI tool.")
class OutputFormat(str, Enum):
text = "text"
json = "json"
csv = "csv"
@app.command()
def init(
name: Annotated[str, typer.Argument(help="Project name")],
template: Annotated[str, typer.Option("--template", "-t", help="Template to use")] = "default",
force: Annotated[bool, typer.Option("--force", "-f", help="Overwrite existing")] = False,
) -> None:
"""Initialize a new project."""
if force:
typer.echo(f"Force-creating {name} with template {template}")
else:
typer.echo(f"Creating {name} with template {template}")
@app.command()
def build(
config: Annotated[str, typer.Option(help="Build configuration")] = "release",
output_dir: Annotated[Path, typer.Option("--output", "-o", help="Output directory")] = Path("dist"),
format: Annotated[OutputFormat, typer.Option(help="Output format")] = OutputFormat.text,
) -> None:
"""Build the project."""
typer.echo(f"Building [{config}] -> {output_dir} (format: {format.value})")
@app.command()
def clean(
all: Annotated[bool, typer.Option("--all", help="Remove all artifacts")] = False,
) -> None:
"""Clean build artifacts."""
if all:
confirmed = typer.confirm("Remove ALL artifacts including caches?")
if not confirmed:
raise typer.Abort()
typer.echo("Cleaned.")
if __name__ == "__main__":
app()
```
### Annotated Parameters (Recommended Pattern)
```python
from typing import Annotated
import typer
app = typer.Typer()
@app.command()
def deploy(
# Required argument
environment: Annotated[str, typer.Argument(help="Target environment")],
# Optional with short flag
tag: Annotated[str, typer.Option("--tag", "-t", help="Image tag")] = "latest",
# Boolean flag
dry_run: Annotated[bool, typer.Option("--dry-run", help="Preview without deploying")] = False,
# Prompt for input
token: Annotated[str, typer.Option(prompt=True, hide_input=True, help="Auth token")] = ...,
# Enum choice
region: Annotated[
str,
typer.Option(help="Cloud region", click_type=typer.Choice(["us-east-1", "eu-west-1", "ap-south-1"]))
] = "us-east-1",
) -> None:
"""Deploy the application to a target environment."""
if dry_run:
typer.echo(f"[DRY RUN] Would deploy {tag} to {environment} in {region}")
else:
typer.echo(f"Deploying {tag} to {environment} in {region}...")
```
### Auto-Completion
```bash
# Generate completion script
my-cli --install-completion bash
my-cli --install-completion zsh
my-cli --install-completion fish
# Show completion script without installing
my-cli --show-completion bash
```
### Typer Testing
Typer uses Click's `CliRunner` under the hood:
```python
from typer.testing import CliRunner
from myapp.cli import app
runner = CliRunner()
def test_init():
result = runner.invoke(app, ["init", "myproject"])
assert result.exit_code == 0
assert "Creating myproject" in result.output
def test_init_with_force():
result = runner.invoke(app, ["init", "myproject", "--force"])
assert result.exit_code == 0
assert "Force-creating" in result.output
def test_build_json_format():
result = runner.invoke(app, ["build", "--format", "json"])
assert result.exit_code == 0
assert "json" in result.output
def test_clean_aborted():
result = runner.invoke(app, ["clean", "--all"], input="n\n")
assert result.exit_code == 1 # Aborted
```
### Nested Command Groups (Sub-Applications)
```python
import typer
app = typer.Typer()
users_app = typer.Typer(help="User management commands.")
app.add_typer(users_app, name="users")
@users_app.command("list")
def list_users() -> None:
"""List all users."""
typer.echo("user1\nuser2\nuser3")
@users_app.command("create")
def create_user(name: str, email: str) -> None:
"""Create a new user."""
typer.echo(f"Created user {name} ({email})")
# Usage: mycli users list
# mycli users create "Jane" "jane@example.com"
```
## Rich Library
Rich is a library for beautiful terminal output: colors, tables, progress bars, syntax highlighting, markdown rendering, and more.
### Installation
```bash
pip install rich
```
### Console Markup
```python
from rich.console import Console
console = Console()
# Styled text
console.print("[bold red]Error:[/bold red] Something went wrong")
console.print("[green]Success![/green] Operation completed.")
console.print("[dim italic]This is dimmed and italic[/dim italic]")
# Emoji
console.print(":rocket: Launching...")
# Links
console.print("Visit [link=https://example.com]our website[/link]")
# Print with highlight (auto-detects and highlights numbers, strings, etc.)
console.print({"name": "Alice", "age": 30, "active": True})
```
### Tables
```python
from rich.console import Console
from rich.table import Table
console = Console()
table = Table(title="Deployment Status")
table.add_column("Service", style="cyan", no_wrap=True)
table.add_column("Version", style="magenta")
table.add_column("Status", justify="center")
table.add_column("Uptime", justify="right", style="green")
table.add_row("api-gateway", "2.3.1", "[green]Healthy[/green]", "14d 3h")
table.add_row("auth-service", "1.8.0", "[green]Healthy[/green]", "14d 3h")
table.add_row("worker", "3.0.2", "[red]Degraded[/red]", "2h 15m")
table.add_row("database", "16.1", "[green]Healthy[/green]", "30d 12h")
console.print(table)
```
### Progress Bars
```python
import time
from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TaskProgressColumn
# Simple progress bar
from rich.progress import track
for item in track(range(100), description="Processing..."):
time.sleep(0.02)
# Advanced multi-task progress
with Progress(
SpinnerColumn(),
TextColumn("[progress.description]{task.description}"),
BarColumn(),
TaskProgressColumn(),
) as progress:
download_task = progress.add_task("Downloading...", total=1000)
install_task = progress.add_task("Installing...", total=500)
while not progress.finished:
progress.update(download_task, advance=5)
progress.update(install_task, advance=2)
time.sleep(0.01)
```
### Panels, Trees, and Columns
```python
from rich.console import Console
from rich.panel import Panel
from rich.tree import Tree
from rich.columns import Columns
console = Console()
# Panel
console.print(Panel("This is important information", title="Notice", border_style="yellow"))
# Tree
tree = Tree("[bold]Project Structure[/bold]")
src = tree.add("[folder]src/")
src.add("[file]main.py")
src.add("[file]config.py")
utils = src.add("[folder]utils/")
utils.add("[file]helpers.py")
tests = tree.add("[folder]tests/")
tests.add("[file]test_main.py")
console.print(tree)
# Columns
data = [Panel(f"Item {i}", expand=True) for i in range(12)]
console.print(Columns(data))
```
### Live Display
```python
import time
from rich.live import Live
from rich.table import Table
def generate_table(step: int) -> Table:
table = Table()
table.add_column("Step")
table.add_column("Status")
for i in range(step + 1):
table.add_row(f"Step {i}", "[green]Complete[/green]")
if step < 5:
table.add_row(f"Step {step + 1}", "[yellow]Running...[/yellow]")
return table
with Live(generate_table(0), refresh_per_second=4) as live:
for step in range(6):
time.sleep(0.5)
live.update(generate_table(step))
```
### Syntax Highlighting and Logging
```python
from rich.console import Console
from rich.syntax import Syntax
import logging
from rich.logging import RichHandler
console = Console()
# Syntax highlighting
code = '''
def fibonacci(n: int) -> int:
if n <= 1:
return n
return fibonacci(n - 1) + fibonacci(n - 2)
'''
syntax = Syntax(code, "python", theme="monokai", line_numbers=True)
console.print(syntax)
# Rich logging handler
logging.basicConfig(
level=logging.DEBUG,
format="%(message)s",
handlers=[RichHandler(rich_tracebacks=True)],
)
log = logging.getLogger("myapp")
log.info("Application started")
log.warning("Low disk space")
log.error("Connection failed")
```
## Textual for TUI Applications
Textual is a framework for building terminal user interfaces (TUIs) with a CSS-like styling system and reactive widget model.
### Installation
```bash
pip install textual
# With dev tools (for live CSS editing)
pip install "textual[dev]"
```
### Basic Application
```python
from textual.app import App, ComposeResult
from textual.containers import Horizontal, Vertical
from textual.widgets import Header, Footer, Static, Button, Input, DataTable
class MyApp(App):
"""A simple Textual application."""
CSS = """
Screen {
layout: vertical;
}
#sidebar {
width: 30;
background: $surface;
padding: 1;
}
#main {
width: 1fr;
padding: 1;
}
Button {
margin: 1 0;
}
"""
BINDINGS = [
("q", "quit", "Quit"),
("d", "toggle_dark", "Toggle Dark Mode"),
]
def compose(self) -> ComposeResult:
yield Header()
with Horizontal():
with Vertical(id="sidebar"):
yield Static("Navigation", classes="title")
yield Button("Dashboard", id="btn-dashboard", variant="primary")
yield Button("Settings", id="btn-settings")
yield Button("Logs", id="btn-logs")
with Vertical(id="main"):
yield Static("Welcome to MyApp", id="content")
yield Footer()
def on_button_pressed(self, event: Button.Pressed) -> None:
content = self.query_one("#content", Static)
content.update(f"You clicked: {event.button.id}")
def action_toggle_dark(self) -> None:
self.dark = not self.dark
if __name__ == "__main__":
MyApp().run()
```
### Widgets
```python
from textual.app import App, ComposeResult
from textual.widgets import DataTable, Input, ListView, ListItem, Label, RichLog
class DataApp(App):
def compose(self) -> ComposeResult:
yield Input(placeholder="Search...", id="search")
yield DataTable()
yield RichLog(id="log")
def on_mount(self) -> None:
table = self.query_one(DataTable)
table.add_columns("Name", "Role", "Status")
table.add_rows([
("Alice", "Engineer", "Active"),
("Bob", "Designer", "Away"),
("Carol", "Manager", "Active"),
])
def on_input_changed(self, event: Input.Changed) -> None:
log = self.query_one("#log", RichLog)
log.write(f"Search: {event.value}")
```
### Reactive Attributes
```python
from textual.app import App, ComposeResult
from textual.reactive import reactive
from textual.widgets import Static
class Counter(Static):
count: reactive[int] = reactive(0)
def render(self) -> str:
return f"Count: {self.count}"
def watch_count(self, new_value: int) -> None:
if new_value > 10:
self.styles.color = "red"
def on_click(self) -> None:
self.count += 1
```
### CSS Styling
Textual uses a CSS-like language for styling. Styles can be defined inline, in the `CSS` class variable, or in external `.tcss` files.
```python
class MyApp(App):
CSS_PATH = "styles.tcss" # Load from external file
```
```css
/* styles.tcss */
Screen {
layout: horizontal;
}
#sidebar {
width: 25%;
background: $surface;
border-right: solid $primary;
padding: 1 2;
}
#main {
width: 75%;
padding: 1 2;
}
Button {
width: 100%;
margin: 1 0;
}
Button:hover {
background: $primary-lighten-2;
}
DataTable > .datatable--header {
background: $primary;
color: $text;
}
```
## Output Formatting
### JSON Output Mode
Provide a `--json` flag for machine-readable output:
```python
import json
import typer
from typing import Annotated
app = typer.Typer()
@app.command()
def status(
json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
) -> None:
"""Show system status."""
data = {
"status": "healthy",
"services": [
{"name": "api", "status": "up", "latency_ms": 42},
{"name": "db", "status": "up", "latency_ms": 5},
],
"version": "1.2.0",
}
if json_output:
typer.echo(json.dumps(data, indent=2))
else:
from rich.console import Console
from rich.table import Table
console = Console()
console.print(f"[bold]Status:[/bold] {data['status']}")
table = Table()
table.add_column("Service")
table.add_column("Status")
table.add_column("Latency")
for svc in data["services"]:
table.add_row(svc["name"], svc["status"], f"{svc['latency_ms']}ms")
console.print(table)
```
### Color/No-Color Support
Respect the `NO_COLOR` environment variable (see https://no-color.org):
```python
import os
from rich.console import Console
# Rich automatically respects NO_COLOR
console = Console(no_color=os.environ.get("NO_COLOR") is not None)
# Or force no color via CLI flag
import typer
app = typer.Typer()
@app.callback()
def main(no_color: bool = False) -> None:
if no_color:
os.environ["NO_COLOR"] = "1"
```
### Table Formatting with tabulate
```python
from tabulate import tabulate
data = [
["api-gateway", "2.3.1", "Healthy"],
["auth-service", "1.8.0", "Healthy"],
["worker", "3.0.2", "Degraded"],
]
headers = ["Service", "Version", "Status"]
# Multiple output formats
print(tabulate(data, headers=headers, tablefmt="grid"))
print(tabulate(data, headers=headers, tablefmt="github"))
print(tabulate(data, headers=headers, tablefmt="plain"))
```
## Exit Codes and Error Handling
### Standard Exit Codes
```python
import sys
EXIT_SUCCESS = 0
EXIT_GENERAL_ERROR = 1
EXIT_USAGE_ERROR = 2 # Invalid arguments
EXIT_NOT_FOUND = 3 # Resource not found
EXIT_PERMISSION_DENIED = 4 # Insufficient permissions
def main() -> int:
try:
result = do_work()
return EXIT_SUCCESS
except FileNotFoundError as e:
print(f"Error: {e}", file=sys.stderr)
return EXIT_NOT_FOUND
except PermissionError as e:
print(f"Error: {e}", file=sys.stderr)
return EXIT_PERMISSION_DENIED
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
return EXIT_GENERAL_ERROR
if __name__ == "__main__":
sys.exit(main())
```
### Error Handling in Typer
```python
import typer
from rich.console import Console
app = typer.Typer()
err_console = Console(stderr=True)
@app.command()
def deploy(environment: str) -> None:
"""Deploy to an environment."""
valid_envs = {"dev", "staging", "production"}
if environment not in valid_envs:
err_console.print(f"[red]Error:[/red] Unknown environment '{environment}'")
err_console.print(f"Valid environments: {', '.join(sorted(valid_envs))}")
raise typer.Exit(code=2)
if environment == "production":
confirmed = typer.confirm("Deploy to PRODUCTION?", abort=True)
typer.echo(f"Deploying to {environment}...")
```
### Error Handling in Click
```python
import click
import sys
class AppError(click.ClickException):
"""Custom error with colored output."""
def format_message(self) -> str:
return f"Error: {self.message}"
@click.command()
@click.argument("config_path", type=click.Path(exists=True))
def run(config_path: str) -> None:
try:
load_config(config_path)
except ValueError as e:
raise AppError(str(e))
except Exception as e:
click.echo(f"Fatal: {e}", err=True)
sys.exit(1)
```
## CLI Testing Strategies
### Testing with pytest and CliRunner
```python
import pytest
from typer.testing import CliRunner
from myapp.cli import app
runner = CliRunner()
class TestInitCommand:
def test_basic_init(self):
result = runner.invoke(app, ["init", "myproject"])
assert result.exit_code == 0
assert "myproject" in result.output
def test_init_with_template(self):
result = runner.invoke(app, ["init", "myproject", "--template", "fastapi"])
assert result.exit_code == 0
assert "fastapi" in result.output
def test_init_invalid_name(self):
result = runner.invoke(app, ["init", ""])
assert result.exit_code != 0
def test_help_text(self):
result = runner.invoke(app, ["init", "--help"])
assert result.exit_code == 0
assert "Initialize" in result.output
class TestOutputFormats:
def test_json_output(self):
result = runner.invoke(app, ["status", "--json"])
assert result.exit_code == 0
import json
data = json.loads(result.output)
assert "status" in data
def test_text_output(self):
result = runner.invoke(app, ["status"])
assert result.exit_code == 0
assert "Status:" in result.output
```
### Testing with Filesystem Isolation
```python
from click.testing import CliRunner
from myapp.cli import app
def test_file_creation():
runner = CliRunner()
with runner.isolated_filesystem():
result = runner.invoke(app, ["init", "testproject"])
assert result.exit_code == 0
# Verify files were created
from pathlib import Path
assert Path("testproject/pyproject.toml").exists()
assert Path("testproject/src").is_dir()
```
### Testing with Environment Variables
```python
def test_respects_no_color():
runner = CliRunner()
result = runner.invoke(app, ["status"], env={"NO_COLOR": "1"})
assert result.exit_code == 0
# Verify no ANSI escape codes in output
assert "\033[" not in result.output
```
### Snapshot Testing
```python
import pytest
from syrupy.assertion import SnapshotAssertion
from typer.testing import CliRunner
from myapp.cli import app
runner = CliRunner()
def test_help_output(snapshot: SnapshotAssertion):
result = runner.invoke(app, ["--help"])
assert result.output == snapshot
```
## Best Practices
1. **Write `--help` for everything**. Every command and option should have a clear help string. Users will read it before your docs.
2. **Support `--json` output**. Machine-readable output makes your CLI composable with other tools (`jq`, scripts, CI pipelines).
3. **Write to stderr for diagnostics**. Use `stderr` for progress, warnings, and errors. Reserve `stdout` for data output:
```python
import sys
print("data output") # stdout -- pipeable
print("Warning: ...", file=sys.stderr) # stderr -- visible but not piped
```
4. **Use exit codes consistently**. Return 0 for success, non-zero for errors. Document your exit codes.
5. **Respect `NO_COLOR`**. Check the `NO_COLOR` environment variable and disable colors/formatting when set.
6. **Test with CliRunner**. Both Click and Typer provide `CliRunner` for testing without spawning subprocesses.
7. **Add shell completion**. Typer generates it for free. For Click, use `click-completion` or `click`'s built-in support.
8. **Use `Annotated` parameters in Typer** (not positional defaults) for clearer, more maintainable code.
9. **Provide `--verbose` and `--quiet` flags**. Let users control output verbosity. Consider using Python's `logging` module with configurable levels.
10. **Version flag**. Always provide `--version`:
```python
from importlib.metadata import version
app = typer.Typer()
def version_callback(value: bool) -> None:
if value:
typer.echo(f"myapp {version('my-package')}")
raise typer.Exit()
@app.callback()
def main(
version: Annotated[
bool, typer.Option("--version", callback=version_callback, is_eager=True)
] = False,
) -> None:
pass
```
Files in this package (16)
- AGENTS.md 29 KB
- README.md 1 KB
- SKILL.md 30 KB
- metadata.json 1 KB
- rules/_sections.md 1 KB
- rules/_template.md 1 KB
- rules/cli-add-shell-completion.md 1 KB
- rules/cli-provide-verbose-and-quiet-flags.md 1 KB
- rules/cli-respect-no-color.md 1 KB
- rules/cli-support-json-output.md 1 KB
- rules/cli-test-with-clirunner.md 1 KB
- rules/cli-use-annotated-parameters-in-typer.md 1 KB
- rules/cli-use-exit-codes-consistently.md 1 KB
- rules/cli-version-flag.md 1 KB
- rules/cli-write-help-for-everything.md 1 KB
- rules/cli-write-to-stderr-for-diagnostics.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Tyler-R-Kendrick/agent-skills | 91 | MIT |
| sparq-org/sparq | 100 | MIT |
| xobotyi/cc-foundry | 100 | MIT |
| bendrucker/claude | 100 | MIT |
| yuri-xyz/skills | 100 | MIT |
| appwrite/claude-plugin | 95 | BSD-3-Clause |
| zzstoatzz/plyr-python-client | 95 | MIT |
| Tyler-R-Kendrick/agent-skills | 93 | MIT |
| Esposter/Esposter | 90 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version ae05cebfead6 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100python-cli-ops
CLI application patterns for Python. Triggers on: cli, command line, typer, click, argparse, terminal, rich, console, terminal ui. - 100cli-tool-design
Design command-line interfaces with clear argument parsing, subcommands, help text, output formatting, and exit codes. Covers Click, Typer, argparse, and shell completion. Triggers on CLI tool development, argument parsing, or terminal UX design requests. - 100cli-architecture
This skill should be used when the user is adding a CLI to a Python package, choosing between Click, Typer, and argparse, structuring cli.py or a cli/ directory, creating a __main__.py for python -m support, defining console script entry points, handling exit codes, or… - 95building-python-clis
Builds command-line interfaces for Python libraries using Click or Typer. Includes command groups, argument handling, progress bars, shell completion, and CLI testing with CliRunner. Use when adding CLI functionality to a library or building standalone command-line tools. - 87python-app-conventions
Application and library conventions for plain Python projects (no web framework): src/ package layout, CLI tooling (argparse/click/typer), configuration management (pydantic-settings), logging setup, module design, entry points, and packaging conventions. Activated automatically… - 100help2skill
Use help2skill to give a Python CLI (Click, Typer, argparse, cyclopts or plumbum) an --llms flag, generate or refresh its SKILL.md, and check hand-written CLI examples against the real command tree. Use when adding agent docs to a CLI or when a help2skill check fails.