cli-tool-design

CLI Tool Design

Build command-line tools that are discoverable, composable, and pleasant to use.

Design Principles

The UNIX Philosophy Applied

1. Do one thing well — Each command has a clear, singular purpose
2. Compose through pipes — Support stdin/stdout for chaining
3. Fail loudly — Non-zero exit codes and stderr for errors
4. Be predictable — Consistent flags, consistent output format

Command Structure

program [global-options] command [command-options] [arguments]

Example:

organvm --verbose registry update --organ IV a-i--skills

Framework Selection

Building with Typer (Recommended for Python)

Basic Command

import typer

app = typer.Typer(help="ORGANVM system management CLI")

@app.command()
def status(
    organ: str = typer.Argument(help="Organ number (I-VII or META)"),
    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
):
    """Show the status of an organ's repositories."""
    # Implementation here

Subcommand Groups

app = typer.Typer()
registry_app = typer.Typer(help="Registry operations")
app.add_typer(registry_app, name="registry")

@registry_app.command("update")
def registry_update(
    organ: str = typer.Argument(help="Target organ"),
    dry_run: bool = typer.Option(False, "--dry-run", "-n"),
):
    """Update registry entries for an organ."""

Rich Output Integration

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

console = Console(stderr=True)  # Status to stderr

def show_repos(repos: list[dict]):
    table = Table(title="Repositories")
    table.add_column("Name", style="cyan")
    table.add_column("Status", style="green")
    table.add_column("Tier")
    for repo in repos:
        table.add_row(repo["name"], repo["status"], repo["tier"])
    console.print(table)