bluefox-cli 0.3.0

Scaffolding tool for the Bluefox Stack — one command to generate a complete FastAPI project with auth, Postgres, and Redis.

bluefox-cli

Scaffolding tool for the Bluefox Stack — one command to generate a complete, ready-to-run FastAPI project with auth, Postgres, and Redis.

Part of the Bluefox Stack.

Documentation · PyPI

---

Install

uv tool install bluefox-cli

This makes bluefox (and the bfx alias) available globally.

---

Quick start

bluefox init myapp
cd myapp
bfx db migrate initial
bfx dev

bfx dev starts Postgres, Redis, runs migrations, and launches the app with hot reload. Visit http://localhost:8000 to see the welcome page with a message playground and auth panel.

---

What it generates

myapp/
  main.py                     # App factory with BluefoxAuth
  models.py                   # Root-level models (auto-discovered)
  items/                      # Example module (auto-discovered)
    api.py                    # Router → auto-mounted at /items
    models.py                 # Item model → auto-discovered
  Makefile                    # dev, test, migrate, run
  Dockerfile                  # Multi-stage uv build
  docker-compose.yml          # Production on dokploy-network
  docker-compose.dev.yml      # Local Postgres + Redis + hot reload
  alembic.ini                 # Migration config
  migrations/                 # Alembic migrations
  tests/                      # bluefox-test fixtures + smoke test

---

CLI commands

Command	Description
bluefox init <name>	Scaffold a new project
bfx dev	Start Postgres + Redis + app with hot reload
bfx db migrate <name>	Generate a migration (spins up temp Postgres)

---

What you get

• FastAPI app with bluefox-core settings and app factory
• Authentication via bluefox-auth — JWT tokens, cookie sessions, user management
• SQLAlchemy models with auto-discovery — just add models.py in any directory
• Alembic migrations configured with one line via configure_alembic()
• Docker Compose for production (dokploy-network) and dev (local Postgres + Redis)
• Multi-stage Dockerfile with uv — small production images
• Test suite with bluefox-test — real Postgres via testcontainers, SAVEPOINT isolation
• Auto-discovery — routers in */api.py and models in */models.py are found automatically

---

Documentation

Full docs at bluefox-cli.bluefox.software/docs/

• Getting started — walkthrough of your first project
• Generated files — what each file does
• CLI commands — bfx dev, bfx db migrate
• Adding models — auto-discovery convention
• Deployment — deploying with Dokploy