fastapi-spawn 0.3.0

A powerful CLI tool to scaffold production-ready FastAPI projects with flexible database, auth, broker, and deployment options.

⚡ fastapi-spawn

The most complete FastAPI project scaffolding CLI — built for modern Python development.

Generate production-ready FastAPI projects in seconds — with exactly the stack you need.

---

Installation

pip install fastapi-spawn
# or
uv pip install fastapi-spawn

---

Quick Start

# Interactive TUI — guided step-by-step
fastapi-spawn new my-api

# One-liner with all flags
fastapi-spawn new my-api \
  --db postgresql \
  --orm sqlalchemy \
  --migration alembic \
  --auth jwt \
  --broker redis \
  --storage s3 \
  --ai openai \
  --monitoring sentry \
  --email sendgrid \
  --log-dest cloudwatch \
  --vector-db qdrant \
  --stack full \
  --ci github

# Preview file tree without writing
fastapi-spawn new my-api --dry-run

# Add a feature to an existing project
fastapi-spawn add openai
fastapi-spawn add alembic
fastapi-spawn add sentry

---

What Gets Generated

my-api/
├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── health.py        # GET /health  /readiness  /liveness
│   │       └── auth.py          # POST /auth/login  /auth/refresh
│   ├── core/
│   │   ├── config.py            # Pydantic Settings v2 — individual env fields + @property URLs
│   │   ├── logger.py            # Context-var logger — request ID, client IP, dual-timezone
│   │   ├── exceptions.py        # Custom exception hierarchy + handlers
│   │   ├── security.py          # JWT / bcrypt
│   │   ├── storage.py           # AWS S3 / MinIO helpers
│   │   ├── ai.py                # OpenAI / Anthropic / Gemini / Ollama async client
│   │   ├── email.py             # SendGrid / SMTP / SES
│   │   └── monitoring.py        # Sentry init / Prometheus metrics
│   ├── middleware/
│   │   ├── request_logger.py    # X-Request-ID, response time, structured logs
│   │   └── rate_limit.py        # slowapi — 429 with Retry-After
│   ├── db/
│   │   └── session.py           # Async SQLAlchemy / Tortoise / Beanie
│   ├── models/
│   ├── schemas/
│   ├── services/
│   └── repositories/
├── tasks/                       # Celery workers (root-level)
│   ├── celery_app.py
│   └── sample_tasks.py
├── migrations/                  # Alembic (async-compatible)
│   ├── env.py
│   └── versions/
├── infra/
│   ├── docker/
│   ├── helm/
│   └── terraform/
├── tests/
├── logs/                        # Local log rotation directory
├── main.py                      # uv run main.py
├── alembic.ini
├── Dockerfile                   # Uses uv for fast layer-cached builds
├── docker-compose.yml           # All selected services pre-configured
├── .env                         # gitignored
├── .env.example
├── .gitignore
├── .pre-commit-config.yaml
├── Makefile
└── pyproject.toml               # uv-compatible with [tool.uv.scripts]

---

All Options

fastapi-spawn new [OPTIONS] PROJECT_NAME

Database & ORM
  --db           postgresql | mysql | mongodb | sqlite | none
  --orm          sqlalchemy | tortoise | beanie | none
  --migration    alembic | aerich | none

Auth & Security
  --auth         jwt | oauth2 | api-key | none

Messaging & Cache
  --broker       redis | rabbitmq | kafka | none
  --cache        redis | memcached | none

Storage
  --storage      s3 | local | none          (s3 = AWS S3 or MinIO)

AI / LLM
  --ai           openai | anthropic | gemini | ollama | none

Monitoring
  --monitoring   sentry | prometheus | both | none

Email
  --email        sendgrid | smtp | ses | none

Notifications
  --notify       slack | discord | none

Logging
  --log-lib      loguru | structlog | standard
  --log-dest     local | cloudwatch | datadog | none

Vector Database
  --vector-db    qdrant | pinecone | elasticsearch | none

Deployment
  --stack        minimal | standard | full
  --ci           github | gitlab | both | none

Flags
  --no-docker    Skip Docker files
  --no-tests     Skip test suite
  --dry-run      Preview file tree without writing
  --force / -f   Overwrite existing directory
  --output / -o  Output directory

---

uv run Scripts

Every generated project has [tool.uv.scripts] pre-wired:

uv run dev        # uvicorn --reload
uv run start      # python main.py
uv run test       # pytest --cov
uv run lint       # ruff check
uv run format     # ruff format
uv run typecheck  # mypy
uv run migrate    # alembic upgrade head  (if alembic)
uv run rollback   # alembic downgrade -1  (if alembic)
uv run makemig    # alembic revision --autogenerate  (if alembic)
uv run worker     # celery worker  (if broker)
uv run beat       # celery beat    (if broker)

---

Environment Variables

Individual fields per service — no URL strings. URLs are assembled via @property:

ENVIRONMENT=dev
SECRET_KEY=super-secret-change-in-production

# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=my_api_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# AWS S3 (or MinIO — set ENDPOINT_URL for local)
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG
AWS_REGION=us-east-1
AWS_S3_BUCKET=my-api-bucket
AWS_S3_ENDPOINT_URL=http://localhost:9000   # MinIO local

# OpenAI (supports custom base URL for Azure / LM Studio)
OPENAI_API_KEY=sk-placeholder
OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=

# Sentry
SENTRY_DSN=https://[e-mail]/yyy

# Logging
LOG_LEVEL=INFO
LOG_DIR=logs
LOG_BACKUP_DAYS=30

---

Add Features to Existing Projects

fastapi-spawn add sentry      # Sentry error tracking setup
fastapi-spawn add openai      # OpenAI async client + env vars
fastapi-spawn add alembic     # Alembic async migrations
fastapi-spawn add s3          # AWS S3 / MinIO storage utils
fastapi-spawn add celery      # Celery worker + tasks/
fastapi-spawn add helm        # Helm chart in infra/helm/
fastapi-spawn add terraform   # Terraform scaffold in infra/terraform/

---

ORM ↔ Database Compatibility

ORM	Compatible Databases
sqlalchemy	postgresql, mysql, sqlite
tortoise	postgresql, mysql, sqlite
beanie	mongodb
none	any

---

Middleware Stack (always included)

Middleware	What it does
RequestLoggingMiddleware	Logs → METHOD /path + ✓ status duration with request ID
RateLimitMiddleware	200 req/min default via slowapi, returns 429 + Retry-After
CORSMiddleware	Configurable via CORS_ORIGINS env var

Every response includes X-Request-ID and X-Response-Time headers.

---

Contributing

git clone https://github.com/Bishwajitgarai/fastapi-spawn
cd fastapi-spawn
uv sync --all-extras
uv run pytest

---

License

MIT © Bishwajit Garai