CLI fails with plain click or rich-click < 1.9.0 due to aliases parameter

[cofin]

Description

The FastAPI extension CLI uses the aliases parameter on groups, but this feature:

1. Does NOT exist in standard click at all
2. Was only added to rich-click in version 1.9.0 (September 2025)

Users encounter TypeError in two scenarios:

Scenario A: Plain click (no rich-click)

TypeError: __init__() got an unexpected keyword argument 'aliases'

Scenario B: Old rich-click (< 1.9.0)

TypeError: __init__() got an unexpected keyword argument 'aliases'

Root Cause

In advanced_alchemy/extensions/fastapi/cli.py:38:

@click.group(name="database", aliases=["db"])

The import pattern falls back to plain click:

try:
    import rich_click as click
except ImportError:
    import click  # <-- Plain click doesn't support aliases!

This pattern doesn't account for:

1. Users who have plain click but not rich-click
2. Users with old rich-click versions (< 1.9.0) that lack alias support

Affected Users

• FastAPI users who install advanced-alchemy[fastapi] but not advanced-alchemy[cli]
• Users who have plain click from other dependencies (Flask, Typer, etc.)
• Users with rich-click < 1.9.0 installed
• CI/CD environments with pinned/cached dependencies

Suggested Fix

Create a compatibility utility in advanced_alchemy/utils/click.py that:

1. Detects whether rich-click is installed AND supports aliases (1.9.0+)
2. Provides an AliasedGroup class for plain click / old rich-click
3. Exports a group() wrapper that auto-selects the right class

# Detection logic
try:
    import rich_click as click
    from rich_click import RichGroup
    import inspect
    
    _params = inspect.signature(RichGroup.__init__).parameters
    RICH_CLICK_ALIASES_SUPPORTED = "aliases" in _params
except ImportError:
    import click
    RICH_CLICK_ALIASES_SUPPORTED = False

# Usage in CLI modules
from advanced_alchemy.utils.click import click, group

@group(name="database", aliases=["db"])  # Works with all scenarios
def database_group():
    pass

Files to Modify

File	Change
advanced_alchemy/utils/click.py	NEW - Compatibility utilities
advanced_alchemy/extensions/fastapi/cli.py	Update imports
advanced_alchemy/cli.py	Update imports for consistency
advanced_alchemy/extensions/flask/cli.py	Update imports for consistency
advanced_alchemy/extensions/litestar/cli.py	Update imports for consistency

Related

• sqlspec has a similar issue: CLI fails with rich-click < 1.9.0 due to aliases parameter sqlspec#292