CLI Design

import click
from typing import Optional
 
@click.group()
@click.version_option()
@click.option('--verbose', '-v', is_flag=True, help='Enable verbose output')
@click.pass_context
def cli(ctx: click.Context, verbose: bool) -> None:
    """Modern CLI tool for project management."""
    ctx.ensure_object(dict)
    ctx.obj['verbose'] = verbose
 
@cli.command()
@click.argument('name')
@click.option('--template', '-t', 
              type=click.Choice(['basic', 'advanced']), 
              default='basic',
              help='Project template to use')
@click.option('--force', is_flag=True, 
              help='Overwrite existing project')
@click.pass_context
def create(ctx: click.Context, name: str, template: str, force: bool) -> None:
    """Create a new project."""
    if ctx.obj['verbose']:
        click.echo(f"Creating project '{name}' with template '{template}'")
    
    # Validation with clear messages
    if not force and project_exists(name):
        click.echo(f"Error: Project '{name}' already exists. Use --force to overwrite.", err=True)
        ctx.exit(1)
    
    # Progress feedback
    with click.progressbar(range(100), label='Setting up project') as bar:
        for i in bar:
            setup_step(i)
    
    click.echo(f"✅ Project '{name}' created successfully!")
 
@cli.command()
@click.option('--format', type=click.Choice(['table', 'json']), 
              default='table', help='Output format')
def list(format: str) -> None:
    """List all projects."""
    projects = get_projects()
    
    if format == 'json':
        click.echo(json.dumps(projects))
    else:
        # Formatted table for humans
        for project in projects:
            click.echo(f"{project['name']:<20} {project['status']}")
 
if __name__ == '__main__':
    cli()

# General help
$ myapp --help
 
# Subcommand-specific help
$ myapp create --help
 
# Error suggestions
$ myapp creat project1
Error: No such command 'creat'. Did you mean 'create'?

@cli.command()
def setup() -> None:
    """Interactive setup wizard."""
    # Prompt with validation
    name = click.prompt('Project name', 
                       type=str,
                       value_proc=lambda x: x.strip().lower())
    
    # Confirmation with default
    use_git = click.confirm('Initialize git repository?', default=True)
    
    # Multiple choice
    template = click.prompt(
        'Choose template',
        type=click.Choice(['basic', 'web', 'api']),
        show_choices=True
    )
    
    # Hidden password
    if click.confirm('Set up authentication?'):
        token = click.prompt('API token', hide_input=True)
    
    click.echo(f"Setting up '{name}' with {template} template...")

# Bash completion
eval "$(_MYAPP_COMPLETE=bash_source myapp)"
 
# Zsh completion  
eval "$(_MYAPP_COMPLETE=zsh_source myapp)"
 
# Fish completion
eval (env _MYAPP_COMPLETE=fish_source myapp)

# Custom autocompletion
def complete_projects(ctx, param, incomplete):
    """Autocomplete existing project names."""
    projects = get_projects()
    return [p['name'] for p in projects if p['name'].startswith(incomplete)]
 
@click.argument('project', autocompletion=complete_projects)
def deploy(project: str) -> None:
    """Deploy project."""
    pass

# ❌ Inconsistent flags
myapp --verbose create
myapp deploy -v  # Should be --verbose too
 
# ❌ Unparseable output
myapp list
Project: web-app (status: running, created: yesterday)
 
# ✅ Structured output
myapp list --json
{"projects": [{"name": "web-app", "status": "running", "created": "2026-03-18"}]}
 
# ❌ Vague error messages
Error: Something went wrong
 
# ✅ Actionable error messages
Error: Project 'web-app' not found. Run 'myapp list' to see available projects.