# Typer CLI Documentation

## Core Commands

typer.run(main) - Runs the main function as a Typer CLI application

Basic user management commands:
- create - Create a new user with USERNAME
- delete - Delete a user with USERNAME
- delete_all - Delete ALL users in the database
- init - Initialize the users database
- config - Configure the system
- sync - Synchronize the system
- help - Get help with the system
- report - Report an issue

Advanced user management commands:
- delete (with --force) - Deletes a user with confirmation prompt
- delete-all (with --force) - Deletes all users with confirmation prompt

Command decorators:
- @app.command() - Defines a command that can be executed in the CLI
- @app.callback() - Defines a callback function for the main CLI application

## Code Examples

### Basic CLI Application
```python
import typer

def main(name: str, lastname: str = "", formal: bool = False):
    """
    Say hi to NAME, optionally with a --lastname.

    If --formal is used, say hi very formally.
    """
    if formal:
        print(f"Good day Ms. {name} {lastname}.")
    else:
        print(f"Hello {name} {lastname}")

if __name__ == "__main__":
    typer.run(main)
```

### Using Annotated Type Hints
```python
from typing_extensions import Annotated

def main(name: Annotated[str, typer.Argument(help="The name of the user to greet")]):
    print(f"Hello {name}")
```

### CLI Arguments with Default Values
```python
def main(name: Annotated[str, typer.Argument(help="Who to greet")] = "World"):
    """
    Say hi to NAME very gently, like Dirk.
    """
    print(f"Hello {name}")
```

### Rich Help Panels
```python
def main(
    name: Annotated[str, typer.Argument(help="Who to greet")],
    lastname: Annotated[str, typer.Argument(help="The last name", rich_help_panel="Secondary Arguments")],
):
    print(f"Hello {name}")
```

### User Management Application
```python
app = typer.Typer(help="Awesome CLI user manager.")

@app.command()
def create(username: str):
    """
    Create a new user with USERNAME.
    """
    print(f"Creating user: {username}")
```

### Rich Markup Support
```python
app = typer.Typer(rich_markup_mode="rich")

@app.command()
def create(username: str):
    """
    [green]Create[/green] a new user. :sparkles:
    """
    print(f"Creating user: {username}")
```

### Command Epilog
```python
@app.command(epilog="Made with :heart: in [blue]Venus[/blue]")
def create(username: str):
    print(f"Creating user: {username}")
```

## Key Concepts

CLI Arguments:
- Basic parameters passed to CLI applications
- Can have help text, default values
- Support type hints and validation
- Can be grouped into help panels

CLI Options:
- Modify command behavior
- Support default values and type conversion
- Can be hidden or marked as deprecated
- Allow for rich markup and documentation

Callbacks:
- Execute before commands
- Manage shared state and parameters
- Provide documentation
- Can be overridden

## Best Practices

Documentation:
- Use docstrings for detailed descriptions
- Add help text to arguments and options
- Group related options in help panels
- Consider using rich markup for better readability

Type Safety:
- Use Annotated for clear type hints
- Leverage automatic type conversion
- Add validation where needed
- Consider using default_factory for dynamic defaults

Command Structure:
- Keep commands focused and simple
- Use subcommands for complex applications
- Implement confirmation prompts for destructive actions
- Provide verbose output options

Error Handling:
- Add clear error messages
- Validate input types
- Handle edge cases gracefully
- Provide clear feedback to users
