typer-cli

Typer CLI

context7: If documentation tools are available, resolve and load the full typer documentation before making any changes to the CLI system:

context7_resolve-library-id: "typer"
context7_query-docs: <resolved-id> "your query here"

Any command or script that must be accessible to users must be exposed through the Typer library.

For full developer documentation see docs/dev/cli.md.

---

CLI Structure

The CLI is registered in pyproject.toml as a project script pointing to {{cookiecutter.__package_slug}}.cli:app.

The main app is defined in {{cookiecutter.__package_slug}}/cli.py. Domain-specific subcommand groups live in separate {{cookiecutter.__package_slug}}/cli_<domain>.py files and are mounted onto the main app.

---

Async Commands — @syncify

Typer runs commands synchronously, but this project uses async throughout (database access, HTTP calls, etc.). Use the @syncify decorator from {{cookiecutter.__package_slug}}/cli.py to bridge them:

from {{cookiecutter.__package_slug}}.cli import syncify

@app.command()
@syncify
async def my_command(name: str) -> None:
    """This async function will run correctly from the CLI."""
    result = await some_async_operation(name)
    typer.echo(result)

Critical: @app.command() must appear before @syncify in decorator order. Do not use asyncio.run() directly — syncify handles the event loop correctly.

---

{%- if cookiecutter.include_sqlalchemy == "y" %}

Database Access in CLI Commands

Use get_session from {{cookiecutter.__package_slug}}.services.db for database-backed commands. Always use it as an async context manager:

from {{cookiecutter.__package_slug}}.services.db import get_session

@app.command()
@syncify
async def my_db_command() -> None:
    """Example command using database access."""
    async with get_session() as session:
        result = await session.execute(select(MyModel))
        items = result.scalars().all()
        for item in items:
            typer.echo(item.name)