Adding CLI Commands

Templates and workflow for adding or updating Typer CLI commands.

<cli_app> refers to the name of your CLI application (e.g., task, myapp, todo).

Workflow

1. Identify command type (single command, command group, or destructive)
2. Create file in src/<cli_app>/commands/<command>.py
3. Use appropriate template below
4. Register in src/<cli_app>/commands/__init__.py

Template A: Single Command

For commands taking arguments directly (<cli_app> add "item").

import typer
from typing import Annotated

from <cli_app>.storage import add_task
from <cli_app>.display import display
from <cli_app>.constants import EXIT_INVALID_INPUT

app = typer.Typer()


@app.command()
def add(
    title: Annotated[str, typer.Argument(help="task title")],
    priority: Annotated[str, typer.Option("--priority", "-p", help="priority level")] = "low",
):
    """Add a new task."""
    if not title.strip():
        display.error("Title cannot be empty")
        raise typer.Exit(EXIT_INVALID_INPUT)

    task = add_task(title=title, priority=priority)
    display.success(f"Added '{task.title}'")

Template B: Command Group

For commands with subcommands (<cli_app> db migrate, <cli_app> db status).

import typer

from <cli_app>.storage import storage
from <cli_app>.display import display

app = typer.Typer(help="Database operations.")


@app.command()
def migrate():
    """Run database migrations."""
    storage.migrate()
    display.success("Migrations complete")


@app.command()
def status():
    """Show database status."""
    info = storage.get_status()
    display.info(f"Version: {info.version}")