Proposal: Plugin System for fastapi-cli Using Entry Point

[grandimam]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched in the documentation/README.
• I already searched in Google "How to do X" and didn't find any information.
• I already read and followed all the tutorial in the docs/README and didn't find an answer.

Commit to Help

• I commit to help with one of those options 👆

Example Code

N/A

Description

I would like to propose adding a plugin system to fastapi-cli using Python entry points. This would allow third-party packages to register commands that appear in the fastapi CLI automatically.

Target Repository: fastapi/fastapi-cli

Motivation

Several discussions have requested CLI extensibility:

• [Feature Request] Support custom command #82
• Feature Request: Add CLI Commands for FastAPI Similar to `rails generate` and `rails routes` #142
• `fastapi new my-app` #170
• How to Create FastAPI Project Structure via CLI? #130

Currently, the answer to these is "use external tools". But there is a real gap: we developers want commands that integrate with their FastAPI app context - database sessions, settings, dependencies and not just random scripts that happen to live nearby.

A plugin system would:

1. Keep fastapi-cli core minimal
2. Let the community build and share extensions
3. Provide a blessed path for app-aware tooling

Proposed Design

Following is a high-level design on how this can be achieved. Plugin authors will register commands via entry points in pyproject.toml:

[project.entry-points."fastapi_cli.plugins"]
shell = "my_plugin.commands:shell_command"
routes = "my_plugin.commands:routes_command"

That is it. When users pip install my-plugin, the commands appear in fastapi --help automatically.

Implementation

File: fastapi_cli/plugins.py

import importlib.metadata
import logging
import sys
import typer

logger = logging.getLogger("fastapi_cli.plugins")

def load_plugins(app: typer.Typer) -> None:
    eps = importlib.metadata.entry_points()
    entry_points = eps.get("fastapi_cli.plugins", [])
    
    registered_commands = {cmd.name for cmd in app.registered_commands}
    
    for ep in entry_points:
        if ep.name in registered_commands:
            logger.warning(
                f"Plugin command '{ep.name}' conflicts with existing command, skipping"
            )
            continue
            
        try:
            command_func = ep.load()
            app.command(name=ep.name)(command_func)
            logger.debug(f"Loaded plugin command: {ep.name} from {ep.value}")
        except Exception as e:
            logger.warning(f"Failed to load plugin '{ep.name}': {e}")

File: fastapi_cli/cli.py

from fastapi_cli.plugins import load_plugins

app = typer.Typer()

# ... existing dev, run commands ...

# Load third-party plugins
load_plugins(app)

How Plugins Access App Context

This is where the magic happens. Plugins are not just random scripts - they can load and interact with your FastAPI app:

# my_plugin/commands.py
import typer

def routes_command(
    app: str = typer.Argument("main:app", help="Import string for FastAPI app"),
    verbose: bool = typer.Option(False, "--verbose", "-v"),
):
    # Use fastapi-cli's existing discovery utilities
    from fastapi_cli.discover import import_app
    
    fastapi_app = import_app(app)
    
    for route in fastapi_app.routes:
        if hasattr(route, "methods"):
            methods = ",".join(route.methods - {"HEAD", "OPTIONS"})
            typer.echo(f"{methods:10} {route.path}")

This gives plugin authors access to:

• The full FastAPI app instance
• All registered routes and dependencies
• App state (app.state)
• Startup/shutdown lifespan context

User Experience

$ pip install fastapi-cli
$ pip install fastapi-shell fastapi-routes

$ fastapi --help

Commands:
  dev       Run development server
  run       Run production server
  shell     Interactive shell [plugin: fastapi-shell]
  routes    List routes [plugin: fastapi-routes]

Plugin Introspection

A built-in command to see what's loaded:

$ fastapi plugins

Installed Plugins:
  fastapi-shell    v0.2.1   shell    Interactive Python shell with app context
  fastapi-routes   v1.0.0   routes   List all registered routes

Reference Plugin Implementation

A minimal example showing the complete plugin structure:

fastapi-routes/pyproject.toml:

[project]
name = "fastapi-routes"
version = "0.1.0"
description = "List routes in your FastAPI app"
dependencies = ["fastapi-cli>=0.0.8", "typer>=0.9.0"]

[project.entry-points."fastapi_cli.plugins"]
routes = "fastapi_routes.cli:routes_command"

fastapi_routes/cli.py:

import typer
from rich.console import Console
from rich.table import Table

console = Console()

def routes_command(
    app: str = typer.Argument("main:app", help="Import string for FastAPI app"),
):
    from fastapi_cli.discover import import_app
    
    fastapi_app = import_app(app)
    
    table = Table(title="Routes")
    table.add_column("Methods", style="cyan")
    table.add_column("Path", style="green")
    table.add_column("Name")
    
    for route in fastapi_app.routes:
        if hasattr(route, "methods"):
            methods = ", ".join(sorted(route.methods - {"HEAD", "OPTIONS"}))
            table.add_row(methods, route.path, route.name or "")
    
    console.print(table)

What I'm Offering

If there's interest, I will submit a PR that:

1. Adds plugin discovery (~50-80 lines of code)
2. Adds fastapi plugins introspection command
3. Documents the plugin interface for authors
4. Includes comprehensive tests

I am also building a management commands package that would use this system, which could serve as a reference implementation for the community.

Open Questions

1. Is a plugin system something maintainers would consider?
2. Any concerns about the entry points approach?
3. Preferred entry point group name? (fastapi_cli.plugins vs fastapi.cli vs other)
4. Should plugins have access to the app instance directly, or just the app import string?
5. Would a [tool.fastapi-cli.plugins] table in pyproject.toml be preferred over entry points? (for future uv/PDM native support)

Operating System

macOS

Operating System Details

MacOs 14

Python Version

3.10

Additional Context

No response