Python Quick Start

Overview

This guide walks through the default TriStack flow: scaffold a FastAPI + SQLModel + Alembic + SQLite project, run it, and verify the health endpoint.

Install the CLI

Python projects run the CLI as uvx tristack. If you don't use uv, install the standalone binary instead:

# run on demand — no install needed
uvx tristack

# or install once with uv
uv tool install tristack

1. Scaffold

uvx tristack my-api

Follow the prompts, or skip them and take the defaults completely non-interactively:

uvx tristack my-api --yes

After scaffolding you'll see the reproducible command, which is also saved to tristack.jsonc inside the project.

2. Run it

cd my-api
cp .env.example .env
uv sync
uv run uvicorn src.main:app --reload

Open http://localhost:8000/health — you should see {"status":"ok"}.

3. Common commands

uv sync                # install dependencies (default package manager)
uv add <package>       # add a dependency
uv run pytest          # run the test suite (pytest addon)
uv run ruff check .    # lint (ruff addon)
uv run ruff format .   # format (ruff addon)
uv run mypy .          # type-check (mypy addon)

Database migrations

With Alembic, migrations live in migrations/:

uv run alembic revision --autogenerate -m "create users"
uv run alembic upgrade head

Docker

With the docker addon, run the whole stack in containers:

docker compose up --build

4. Other frameworks

The stack varies by framework — same flow, different runner:

5. Reproduce the same stack

Every scaffold prints a reproducible command and stores it in tristack.jsonc:

uvx tristack my-api \
  --language python \
  --framework fastapi \
  --orm sqlmodel \
  --migrations alembic \
  --database sqlite \
  --package-manager uv \
  --addons docker ruff pytest

Or validate it without writing anything:

uvx tristack my-api --yes --dry-run

Next steps

• Project Structure — exactly what gets generated
• CLI Options — every flag
• Compatibility — valid combinations