Reviewing CLI Commands

Checklist for reviewing Typer CLI command implementations.

Review Process

1. Read the command file
2. Check each section below
3. Report findings using output format at bottom

Structure

• File in src/<cli_app>/commands/
• Has app = typer.Typer() and @app.command()
• Command groups use @app.command() for each subcommand
• Registered in commands/__init__.py with add_typer()
• Single commands: add_typer(app) without name
• Command groups: add_typer(app, name="group")

Arguments & Options

• Uses Annotated syntax
• Arguments for required positional input
• Options for optional named parameters
• Short flags where appropriate (-f, -q)
• Help text: lowercase, no period, brief

# GOOD:
name: Annotated[str, typer.Argument(help="item name")]
force: Annotated[bool, typer.Option("--force", "-f", help="skip confirmation")] = False

# BAD:
name: str = typer.Argument(..., help="The name of the item.")

Error Handling

• Validates input before processing
• Exit codes: 0=success, 1=error, 2=invalid input
• Errors via display.error()
• Uses raise typer.Exit(code) after errors
• Uses raise typer.Abort() for cancellation

# GOOD:
if id < 1:
    display.error("ID must be positive")
    raise typer.Exit(EXIT_INVALID_INPUT)

# BAD:
if id < 1:
    print("Error: ID must be positive")
    return

Output

• All output through display module
• No print(), typer.echo(), or console.print()

# GOOD:
display.success(f"Added '{task.title}'")

# BAD:
print(f"Added '{task.title}'")

Destructive Actions

• Has --force / -f flag
• typer.confirm() with default=False
• Shows "Cancelled" on abort

# GOOD:
if not force:
    confirm = typer.confirm(f"Delete '{task.title}'?", default=False)
    if not confirm:
        display.info("Cancelled")
        raise typer.Abort()

# BAD: defaults to Yes
confirm = typer.confirm(f"Delete?", default=True)

Help Text

• Docstring exists
• Imperative mood ("Add a task" not "Adds a task")
• First line < 60 characters

Common Mistakes

Review Output Format

## Review: <command_name>

[OK] Uses Annotated syntax
[OK] Has docstring in imperative mood
[X] Missing --force flag on destructive command
[X] Uses print() instead of display module
[!] Help text could be shorter

### Summary
<brief summary of issues found>

### Suggested Fixes
<code suggestions if needed>