// Complete reference for all make targets in the project. Use when: looking up the right make command for any task — setup, testing, linting, formatting, database, packaging, or cleanup.
| name | makefile |
| description | Complete reference for all make targets in the project. Use when: looking up the right make command for any task — setup, testing, linting, formatting, database, packaging, or cleanup. |
All developer tasks are exposed as make targets. Run from the project root.
| Target | What it does |
|---|---|
make install | Install Python deps, create .venv (first-time setup) |
make sync | Sync Python deps with uv.lock (after pulling changes) |
make pre-commit | Install pre-commit hooks |
make lock | Upgrade and relock all dependencies |
make lock-check | Verify lock file is up to date without changing it |
| Target | What it does |
|---|---|
| {%- if cookiecutter.include_sqlalchemy == "y" %} | |
make tests | Run everything: pytest, ruff, black, mypy, prettier, TOML, paracelsus |
| {%- else %} | |
make tests | Run everything: pytest, ruff, black, mypy, prettier, TOML formatting |
| {%- endif %} | |
make pytest | Run pytest with coverage report |
make pytest_loud | Run pytest with DEBUG log output enabled |
These check only — they do not auto-fix.
| Target | What it checks |
|---|---|
make ruff_check | Ruff linter |
make black_check | Ruff formatter (black style) |
make mypy_check | Type checking (mypy) |
make prettier_check | Markdown, JSON, YAML, TOML formatting (prettier) |
make tomlsort_check | TOML file formatting (tombi) |
{%- if cookiecutter.include_sqlalchemy == "y" %}
| make paracelsus_check | Database schema docs are up to date |
| make check_ungenerated_migrations | No pending Alembic migration changes |
{%- endif %}
| Target | What it fixes |
|---|---|
| {%- if cookiecutter.include_sqlalchemy == "y" %} | |
make chores | Run all auto-fixes: ruff, format, prettier, TOML, schema docs |
| {%- else %} | |
make chores | Run all auto-fixes: ruff, format, prettier, TOML |
| {%- endif %} | |
make ruff_fixes | Auto-fix ruff lint issues |
make black_fixes | Auto-format Python code (black style via ruff) |
make prettier_fixes | Auto-format markdown/JSON/YAML/TOML |
make tomlsort_fixes | Auto-format TOML files (tombi) |
Typical workflow before committing: make chores && make tests
{%- if cookiecutter.include_sqlalchemy == "y" %}
| Target | What it does |
|---|---|
make create_migration MESSAGE="description" | Generate a new Alembic migration from model changes |
make check_ungenerated_migrations | Fail if there are model changes without a migration |
make run_migrations | Apply all pending migrations (alembic upgrade head) |
make document_schema | Regenerate docs/dev/database.md from current models |
make paracelsus_check | Verify schema docs are current (read-only check) |
make reset_db | Wipe local SQLite test DB and reapply all migrations |
create_migration requires a MESSAGE argument:
make create_migration MESSAGE="add email_verified column to users"
{%- endif %}
{%- if cookiecutter.publish_to_pypi == "y" %}
| Target | What it does |
|---|---|
make build | Build Python package distribution (sdist + wheel) |
{%- endif %}
| I want to… | Run |
|---|---|
| Set up for the first time | make install |
| Run all tests before a PR | make tests |
| Fix all formatting issues | make chores |
| Check types only | make mypy_check |
| {%- if cookiecutter.include_sqlalchemy == "y" %} | |
| Add a database migration | make create_migration MESSAGE="..." |
| Regenerate DB docs after model changes | make document_schema |
| {%- endif %} | |
| Run only Python tests with verbose output | make pytest_loud |
| Update dependencies | make lock && make sync |
Configure or use the aiocache caching layer. Use when: adding cache reads/writes, configuring cache backends, working with TTLs, enabling/disabling caching, or understanding the NoOpCache fallback pattern.
Create or modify Celery tasks and periodic task configuration. Use when: adding new background tasks, setting up periodic/scheduled tasks, configuring Celery workers, or understanding the Celery app setup.
Work with the Docker Compose development environment. Use when: starting or stopping services, inspecting logs, opening a shell in a container, resetting the database, or understanding the service topology.
Create or modify FastAPI routes. Use when: adding new API endpoints, creating Pydantic request/response models, registering routers, designing REST APIs, or following route conventions for this project.
Create or modify Jinja2 templates. Use when: adding new HTML templates, configuring the Jinja2 environment, adding custom filters or globals, rendering templates outside FastAPI, or working with template inheritance.
Add or modify application configuration settings. Use when: adding new environment variables, settings fields, understanding settings conventions, working with secrets, or configuring optional vs required settings.