connectionsphere-fastapi-cli 0.3.3

CLI to scaffold production-ready FastAPI projects with UV, Docker, and GitHub Actions

connectionsphere-fastapi-cli

A command-line tool for scaffolding production-ready FastAPI projects. Generates a complete project structure with UV dependency management, GitHub Actions CI/CD, Docker, pre-commit hooks, Ruff, and MyPy — ready to run on first install.

---

Installation

pip install connectionsphere-fastapi-cli

Requires Python 3.10 or later.

---

Commands

fastapi-scaffold

Scaffold a production-ready FastAPI project.

fastapi-cli fastapi-scaffold <project-name> [OPTIONS]

Options

Flag	Description
--postgres	Add PostgreSQL integration (SQLModel, Alembic, psycopg2)
--redis	Add Redis integration

Examples

# Minimal project
fastapi-cli fastapi-scaffold my-api

# With Postgres and Redis
fastapi-cli fastapi-scaffold my-api --postgres --redis

Generated structure

my-api/
├── app/
│   ├── api/
│   │   └── v1/
│   │       └── endpoints.py
│   ├── core/
│   │   ├── config.py          # Pydantic Settings, injected via Depends
│   │   └── security.py        # JWT + bcrypt, env-validated secret key
│   ├── models/
│   ├── schemas/
│   ├── services/
│   └── main.py                # App factory + lifespan context manager
├── tests/
│   ├── conftest.py            # TestClient fixture, function scope
│   └── test_main.py
├── .github/
│   └── workflows/
│       └── ci.yml             # uv, Ruff, MyPy, pytest
├── alembic/                   # If --postgres
├── docker-compose.yml
├── pyproject.toml             # uv-compatible, Ruff + MyPy configured
└── .env                       # Placeholder values, gitignored

---

init

Initialise a plain UV Python project with a virtual environment, core dependencies, pre-commit hooks, and a GitHub Actions workflow.

fastapi-cli init <project-name>

Requires uv to be installed. Install with:

curl -LsSf https://astral.sh/uv/install.sh | sh

---

create-github

Create a GitHub repository from a local project directory and push all files.

fastapi-cli create-github <project-dir> [OPTIONS]

Options

Flag	Description
--repo-name TEXT	Repository name (defaults to directory name)
--private	Create a private repository (default: public)

Requires the GitHub CLI (gh) to be installed and authenticated.

---

Reference guides

Built-in terminal reference guides — no internet connection required.

Command	Description
fastapi-cli git-cheat-sheet	Git commands reference
fastapi-cli git-refactor-workflow	Git workflow for refactoring legacy projects
fastapi-cli pseudocode-guide	Pseudocode conventions for DSA problems

---

What the scaffold enforces

Security — SECRET_KEY is loaded from the environment. The application raises RuntimeError at startup if the variable is unset or holds the default placeholder. No secrets are hardcoded in generated source files.

Settings — pydantic-settings with BaseSettings. Settings are injected via Depends(get_settings), never imported as a module-level singleton. The @lru_cache factory ensures one Settings instance per process; tests call get_settings.cache_clear() and use dependency_overrides.

App factory — main.py uses a create_app() factory and a lifespan context manager rather than a bare module-level FastAPI() instance. Startup and shutdown logic has a defined home.

Testing — conftest.py uses scope="function" for the TestClient fixture. Mutable state is never shared across tests. The fixture includes a commented scaffold for SQLite in-memory dependency_overrides for integration tests.

CI — GitHub Actions workflow uses uv throughout. Steps: install, Ruff lint, Ruff format check, MyPy type check, pytest. Postgres and Redis service containers are included automatically when the corresponding flags were passed at scaffold time.

Tooling — Ruff handles both linting and formatting. MyPy runs in strict mode. Black is not included; Ruff's formatter covers the same ground without the dependency.

---

Requirements

Tool	Required	Purpose
Python	3.10+	Runtime
uv	Optional	Used by init command and generated projects
gh (GitHub CLI)	Optional	Used by create-github command

---

Development

git clone https://github.com/ConnectSphere/connectionsphere-fastapi-cli
cd connectionsphere-fastapi-cli
uv sync --all-extras
uv run pytest
uv run ruff check .
uv run mypy src/

---

Changelog

0.3.0

• First release of the real implementation
• fastapi-scaffold command with Jinja2 template engine
• --postgres and --redis flags
• App factory pattern, lifespan context manager
• Environment-validated secret key, no hardcoded credentials
• init and create-github commands
• Built-in terminal reference guides

---

License

MIT