Learn Python Series):Command-line interfaces are everywhere in development. git, docker, npm, pip - powerful tools accessed through text commands. Building good CLIs requires understanding both technical implementation and user experience.
This episode is about CLI design and implementation - not just parsing arguments, but building tools developers enjoy using.
Nota bene: A good CLI respects conventions, provides helpful errors, and feels intuitive. Bad CLIs are technically correct but frustrating to use.
GUIs are discoverable. Menus and buttons show what's possible. CLIs aren't - you must know or guess commands.
This makes conventions critical. When a user types mytool --help, they expect help. When they use -v, they expect either "verbose" or "version". Breaking conventions creates friction.
Good CLIs follow the principle of least surprise. Common flags work as expected. Error messages are helpful, not cryptic. Output is readable.
The mental model: CLIs are conversations between user and tool. The user gives commands, the tool responds. Make that conversation natural.
Without a parsing library, you handle sys.argv manually:
import sys
args = sys.argv[1:] # Skip script name
Now what? Is args[0] a command, a flag, or a value? Does -v take a value or is it boolean? How do you handle --config=file.json vs --config file.json?
You end up writing parsing logic, validation, error handling, help text generation. This is undifferentiated work - every CLI needs it, it's not specific to your tool's purpose.
Argument parsing libraries solve this once. You declare what arguments exist, the library handles parsing and validation.
Python includes argparse - comprehensive but verbose. You create a parser, add arguments declaratively, then parse:
parser = argparse.ArgumentParser(description="Process data")
parser.add_argument("input", help="Input file")
parser.add_argument("--format", choices=["json", "csv"], default="json")
args = parser.parse_args()
The parser handles: parsing sys.argv, validating choices, generating help text, providing error messages.
argparse is powerful but imperative. You build a parser object, configure it, then run it. This works but feels ceremonial for simple tools.
Click takes a different philosophy - decorators turn functions into CLI commands:
@click.command()
@click.argument("input")
@click.option("--format", type=click.Choice(["json", "csv"]), default="json")
def process(input, format):
"""Process data from input file."""
pass
Same functionality, less boilerplate. The function signature defines the CLI interface. Decorators add behavior.
This feels more Pythonic for simple tools - the code reads like what it does. For complex multi-command CLIs (like git), click's command groups shine.
Use argparse when:
Use click when:
git commit, git push)Both solve the same problem. Click is generally more ergonomic, but argparse is battle-tested and stdlib.
Respect these conventions:
Help flags: -h and --help show usage. Always.
Version flag: --version shows version. Use semantic versioning.
Quiet/verbose: -q suppresses output, -v increases it. Often stackable (-vvv for very verbose).
Force flag: -f or --force skips confirmations. Use carefully.
Config files: Support --config path/to/file for complex configuration.
Environment variables: Allow critical options via env vars (API keys, endpoints).
POSIX compatibility: Use - for short flags, -- for long flags. Allow flag bundling (-rf = -r -f).
Breaking these creates confused users. They type --help and nothing happens? Frustration.
Raw print() works but looks amateur. Professional CLIs format output thoughtfully:
Progress indication: For long operations, show progress bars or spinners. Silent CLIs feel broken.
Color sparingly: Highlight errors (red), success (green), warnings (yellow). Don't rainbow everything - it's distracting.
Tables for data: Aligned columns are readable. Library: rich provides beautiful tables with minimal code.
Structured output option: Support --json for machine-readable output. Makes your tool scriptable.
Respect NO_COLOR: Environment variable NO_COLOR disables colors. Respect it - CI environments often set this.
The goal: provide feedback without overwhelming the user.
Let's move beyond toy examples and build a multi-command CLI tool — a file utility that handles multiple operations through subcommands, just like git has commit, push, pull as separate subcommands under one binary.
Click's @click.group() turns a function into a group that owns subcommands. Each subcommand is a separate function decorated with @group.command():
import click
import json
import csv
import hashlib
import os
from pathlib import Path
@click.group()
@click.version_option(version="1.0.0")
@click.option("-v", "--verbose", count=True, help="Increase output verbosity (-vv for debug)")
@click.pass_context
def cli(ctx, verbose):
"""fileutil - a Swiss army knife for file operations."""
ctx.ensure_object(dict)
ctx.obj["verbose"] = verbose
@cli.command()
@click.argument("path", type=click.Path(exists=True))
@click.option("--format", "fmt", type=click.Choice(["json", "text"]), default="text")
@click.option("--checksum/--no-checksum", default=False, help="Include SHA-256 hash")
@click.pass_context
def info(ctx, path, fmt, checksum):
"""Show detailed file information."""
p = Path(path)
stat = p.stat()
data = {
"name": p.name,
"size_bytes": stat.st_size,
"size_human": _human_size(stat.st_size),
"type": "directory" if p.is_dir() else p.suffix or "no extension",
"permissions": oct(stat.st_mode)[-3:],
}
if checksum and p.is_file():
sha = hashlib.sha256(p.read_bytes()).hexdigest()
data["sha256"] = sha
if ctx.obj["verbose"] >= 1:
data["absolute_path"] = str(p.resolve())
data["is_symlink"] = p.is_symlink()
if fmt == "json":
click.echo(json.dumps(data, indent=2))
else:
for key, val in data.items():
click.echo(f" {key:.<20s} {val}")
@cli.command()
@click.argument("source", type=click.Path(exists=True))
@click.argument("dest", type=click.Path())
@click.option("--format", "fmt", type=click.Choice(["json", "csv"]),
required=True, help="Target format")
@click.option("--overwrite", is_flag=True, help="Overwrite existing output file")
def convert(source, dest, fmt, overwrite):
"""Convert data files between JSON and CSV formats."""
if Path(dest).exists() and not overwrite:
raise click.ClickException(
f"Output file '{dest}' already exists. Use --overwrite to replace."
)
source_data = Path(source).read_text()
if fmt == "csv":
records = json.loads(source_data)
if not isinstance(records, list) or not records:
raise click.ClickException("JSON source must be a non-empty list of objects.")
with open(dest, "w", newline="") as f:
writer = csv.DictWriter(f, fieldnames=records[0].keys())
writer.writeheader()
writer.writerows(records)
elif fmt == "json":
with open(source, newline="") as f:
reader = csv.DictReader(f)
records = list(reader)
Path(dest).write_text(json.dumps(records, indent=2))
click.echo(f"Converted {source} → {dest} ({fmt}, {len(records)} records)")
@cli.command()
@click.argument("directory", type=click.Path(exists=True, file_okay=False))
@click.option("--ext", multiple=True, help="Filter by extension (repeatable: --ext .py --ext .md)")
@click.option("--min-size", type=int, default=0, help="Minimum file size in bytes")
@click.option("--sort", "sort_by", type=click.Choice(["name", "size", "modified"]),
default="name")
def scan(directory, ext, min_size, sort_by):
"""Scan a directory and report file statistics."""
root = Path(directory)
files = [f for f in root.rglob("*") if f.is_file()]
if ext:
files = [f for f in files if f.suffix in ext]
if min_size:
files = [f for f in files if f.stat().st_size >= min_size]
sort_keys = {
"name": lambda f: f.name.lower(),
"size": lambda f: f.stat().st_size,
"modified": lambda f: f.stat().st_mtime,
}
files.sort(key=sort_keys[sort_by])
total_size = sum(f.stat().st_size for f in files)
click.echo(f"Found {len(files)} files ({_human_size(total_size)} total)\n")
for f in files:
size = _human_size(f.stat().st_size)
rel = f.relative_to(root)
click.echo(f" {size:>8s} {rel}")
def _human_size(nbytes):
for unit in ["B", "KB", "MB", "GB"]:
if nbytes < 1024:
return f"{nbytes:.1f} {unit}"
nbytes /= 1024
return f"{nbytes:.1f} TB"
if __name__ == "__main__":
cli()
Notice several things happening here. @click.pass_context threads state (like the verbose flag) from the group to subcommands without global variables. click.Path(exists=True) validates that a file exists before your code even runs — the error message is automatic and clear. The --ext option uses multiple=True, allowing --ext .py --ext .md to collect into a tuple. And click.ClickException provides clean user-facing error messages without stack traces.
Running this tool:
$ python fileutil.py --help
Usage: fileutil.py [OPTIONS] COMMAND [ARGS]...
fileutil - a Swiss army knife for file operations.
Options:
--version Show the version and exit.
-v, --verbose Increase output verbosity (-vv for debug)
--help Show this message and exit.
Commands:
convert Convert data files between JSON and CSV formats.
info Show detailed file information.
scan Scan a directory and report file statistics.
$ python fileutil.py info --checksum mydata.json
name.................. mydata.json
size_bytes............ 4823
size_human............ 4.7 KB
type.................. .json
permissions........... 644
sha256................ a1b2c3d4e5...
$ python fileutil.py scan ./src --ext .py --sort size
Found 23 files (142.3 KB total)
0.2 KB __init__.py
1.1 KB config.py
3.4 KB utils.py
12.8 KB main.py
That's a properly structured CLI tool. The group/subcommand pattern scales to dozens of commands without becoming unwieldy.
print() gives you plain text. For CLI tools that humans interact with, plain text often isn't enough. The rich library transforms terminal output from functional to beautiful — with tables, colored text, progress bars, and tree views.
Install it: pip install rich
The core concept: rich's Console object replaces print() with styled output. But the real power is in its high-level components:
from rich.console import Console
from rich.table import Table
from rich.progress import Progress, SpinnerColumn, BarColumn, TextColumn
from rich.panel import Panel
from rich.tree import Tree
from rich import print as rprint
import time
import os
console = Console()
# === Tables ===
def show_process_table():
"""Display system info as a formatted table."""
table = Table(title="Python Environment")
table.add_column("Property", style="cyan", no_wrap=True)
table.add_column("Value", style="green")
import sys, platform
rows = [
("Python version", sys.version.split()[0]),
("Platform", platform.system()),
("Architecture", platform.machine()),
("Executable", sys.executable),
("Working dir", os.getcwd()),
("PID", str(os.getpid())),
]
for prop, val in rows:
table.add_row(prop, val)
console.print(table)
# === Progress bars ===
def process_files(file_list):
"""Process files with a detailed progress bar."""
with Progress(
SpinnerColumn(),
TextColumn("[progress.description]{task.description}"),
BarColumn(),
TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
TextColumn("({task.completed}/{task.total})"),
console=console,
) as progress:
task = progress.add_task("Processing files...", total=len(file_list))
for filepath in file_list:
progress.update(task, description=f"Processing {filepath.name}...")
time.sleep(0.1) # simulate work
progress.advance(task)
console.print("[bold green]✓[/] All files processed successfully.")
# === Styled error handling ===
def report_error(message, suggestion=None):
"""Display a formatted error panel."""
body = f"[bold red]Error:[/] {message}"
if suggestion:
body += f"\n[dim]Suggestion: {suggestion}[/]"
console.print(Panel(body, title="[red]Problem[/]", border_style="red"))
# === Directory trees ===
def show_directory_tree(path, max_depth=2):
"""Display directory structure as a tree."""
root = Path(path)
tree = Tree(f"[bold blue]{root.name}/[/]")
def walk(directory, branch, depth=0):
if depth >= max_depth:
return
try:
entries = sorted(directory.iterdir(), key=lambda e: (e.is_file(), e.name))
except PermissionError:
branch.add("[red]Permission denied[/]")
return
for entry in entries:
if entry.name.startswith("."):
continue
if entry.is_dir():
sub = branch.add(f"[bold blue]{entry.name}/[/]")
walk(entry, sub, depth + 1)
else:
size = _human_size(entry.stat().st_size)
branch.add(f"{entry.name} [dim]({size})[/]")
walk(root, tree)
console.print(tree)
# === Combining rich with click ===
@click.command()
@click.argument("directory", type=click.Path(exists=True, file_okay=False))
@click.option("--depth", default=2, help="Maximum tree depth")
def tree_cmd(directory, depth):
"""Display a directory as a styled tree."""
show_directory_tree(directory, max_depth=depth)
Rich's markup syntax ([bold red]text[/]) lets you inline styles without complex escape sequences. The Progress class handles all the terminal rewriting — drawing the bar, updating percentages, respecting terminal width. And Panel wraps content in a box that visually separates it from surrounding output.
One particularly powerful pattern: combining --json output for machines with rich output for humans. Same data, different presentation:
@click.command()
@click.option("--json-output", "as_json", is_flag=True, help="Output as JSON")
def status(as_json):
"""Show system status."""
data = {
"cpu_count": os.cpu_count(),
"pid": os.getpid(),
"cwd": os.getcwd(),
}
if as_json:
import json
click.echo(json.dumps(data)) # plain JSON, no colors, pipeable
else:
table = Table(title="System Status")
table.add_column("Metric", style="cyan")
table.add_column("Value", style="green")
for k, v in data.items():
table.add_row(k, str(v))
console.print(table)
Run it as status and you get a pretty table. Pipe it as status --json-output | jq .cpu_count and downstream tools get clean JSON. That's the mark of a CLI built by someone who understands how these tools get used in practice — both interactively and in scripts.
CLIs should fail gracefully:
Validation errors: Show what's wrong and how to fix it. Not "Error", but "Error: --format must be 'json' or 'csv', got 'xml'".
Exit codes: 0 = success, non-zero = failure. Scripts check exit codes. Be consistent.
Helpful messages: If a file doesn't exist, suggest checking the path. If an API fails, show the HTTP status.
Stack traces: Only in verbose/debug mode. Normal errors should be friendly, not scary.
Good error messages turn failures into learning moments. Bad errors leave users stuck.
Here's something most CLI tutorials never show you. Real-world tools like pip, pytest, and flask support plugins — third-party packages that register new subcommands without modifying the core tool. You install a plugin, and suddenly your CLI has new capabilities. How does that work?
The mechanism is Python's entry points system, combined with importlib.metadata for discovery and click's ability to dynamically register commands. Let's build it from scratch.
The architecture: your CLI defines a named entry point group (like "fileutil.plugins"). Any installed Python package can declare that it provides commands for that group. At startup, your CLI scans all installed packages, finds the ones that registered commands, loads them, and adds them as subcommands. Zero configuration. Zero imports. Just install a plugin package and it appears.
First, the plugin loader:
import click
import importlib.metadata
import importlib
PLUGIN_GROUP = "fileutil.plugins"
class PluginLoader:
"""Discover and load CLI plugins from installed packages."""
def __init__(self, group=PLUGIN_GROUP):
self.group = group
self._plugins = {}
def discover(self):
"""Find all installed plugins via entry points."""
eps = importlib.metadata.entry_points()
# Python 3.12+: eps is a dict-like; 3.9-3.11: use select()
if hasattr(eps, "select"):
plugin_eps = eps.select(group=self.group)
else:
plugin_eps = eps.get(self.group, [])
for ep in plugin_eps:
try:
command = ep.load() # imports the module and returns the object
if isinstance(command, click.BaseCommand):
self._plugins[ep.name] = command
else:
click.echo(f"Warning: plugin '{ep.name}' is not a click command", err=True)
except Exception as e:
click.echo(f"Warning: failed to load plugin '{ep.name}': {e}", err=True)
return self._plugins
def register_all(self, group):
"""Add all discovered plugins to a click group."""
for name, cmd in self._plugins.items():
group.add_command(cmd, name)
The ep.load() call is where the magic happens. It reads the entry point metadata ("mycommand = myplugin.cli:my_command"), imports myplugin.cli, and returns the my_command object — all through standard Python packaging infrastructure. No file system scanning, no naming conventions, no monkey-patching.
Now integrate it with our CLI:
@click.group()
@click.version_option(version="1.0.0")
@click.pass_context
def cli(ctx, **kwargs):
"""fileutil - extensible file operations tool."""
ctx.ensure_object(dict)
# Register built-in commands
cli.add_command(info)
cli.add_command(convert)
cli.add_command(scan)
# Discover and register plugins
loader = PluginLoader()
plugins = loader.discover()
loader.register_all(cli)
if plugins:
# Optional: show loaded plugins in verbose mode
@cli.command(hidden=True)
def plugins_list():
"""List loaded plugins."""
for name in sorted(plugins):
click.echo(f" {name} (from {plugins[name].__module__})")
A plugin author creates a normal Python package. The only special part is the entry point declaration in pyproject.toml:
# pyproject.toml of a plugin package called "fileutil-encrypt"
[project]
name = "fileutil-encrypt"
version = "0.1.0"
dependencies = ["click", "cryptography"]
[project.entry-points."fileutil.plugins"]
encrypt = "fileutil_encrypt.cli:encrypt_cmd"
decrypt = "fileutil_encrypt.cli:decrypt_cmd"
And the plugin's code is just normal click commands:
# fileutil_encrypt/cli.py
import click
from pathlib import Path
from cryptography.fernet import Fernet
@click.command()
@click.argument("path", type=click.Path(exists=True))
@click.option("--key", envvar="FILEUTIL_KEY", help="Encryption key (or set FILEUTIL_KEY)")
def encrypt_cmd(path, key):
"""Encrypt a file using Fernet symmetric encryption."""
if not key:
key = Fernet.generate_key().decode()
click.echo(f"Generated key (save this!): {key}")
f = Fernet(key.encode() if isinstance(key, str) else key)
data = Path(path).read_bytes()
encrypted = f.encrypt(data)
out_path = path + ".enc"
Path(out_path).write_bytes(encrypted)
click.echo(f"Encrypted: {path} → {out_path}")
@click.command()
@click.argument("path", type=click.Path(exists=True))
@click.option("--key", envvar="FILEUTIL_KEY", required=True, help="Decryption key")
def decrypt_cmd(path, key):
"""Decrypt a previously encrypted file."""
f = Fernet(key.encode())
data = Path(path).read_bytes()
decrypted = f.decrypt(data)
out_path = path.removesuffix(".enc") if path.endswith(".enc") else path + ".dec"
Path(out_path).write_bytes(decrypted)
click.echo(f"Decrypted: {path} → {out_path}")
After pip install fileutil-encrypt, the commands appear automatically:
$ python fileutil.py --help
Commands:
convert Convert data files between JSON and CSV formats.
decrypt Decrypt a previously encrypted file.
encrypt Encrypt a file using Fernet symmetric encryption.
info Show detailed file information.
scan Scan a directory and report file statistics.
No code changes to the core tool. No imports. The plugin registered itself through packaging metadata, and the loader picked it up at runtime.
This is the same mechanism pytest uses for plugins (pytest11 entry point group), flask uses for extensions, and pip uses for its own subcommands. It's production-grade infrastructure that separates core tool maintenance from plugin development — different people, different packages, different release cycles, one unified CLI.
Why does this matter beyond "it's clever"? Because it's a real-world application of several Python concepts working together: packaging and distribution (pyproject.toml), the import system (importlib.metadata), duck typing (any click command works, regardless of what package defined it), and the open-closed principle (the tool is open for extension but closed for modification). Understanding plugin architectures like this is what separates script writers from systems engineers.
In this episode, we covered CLI application development:
--help, -v, and exit codes exist for a reasonrich: tables, progress bars, directory trees, and styled error panelsrich), JSON for machines (--json-output)importlib.metadata for extensible CLIs — the same pattern pytest and flask useBuilding CLIs isn't just parsing arguments. It's creating tools that respect user expectations, look professional, and work seamlessly in both interactive and scripted contexts.
@scipio