Compatibility Rules
Understanding compatibility rules and restrictions between different CLI options
Overview
The CLI validates option combinations to ensure generated projects are coherent. Validation happens in two places:
- Per-language value checks —
framework,orm,migrations, andfrontendmust belong to the selected language's option set. - Resolved-config checks — after prompts (or with
--yes), the fully-resolved stack is validated again.
--yolo skips the compatibility checks entirely.
Per-language option sets
Each language has its own option sets (packages/types), so a Go/Rust value can never leak into a Python stack:
| Category | Python | Go | Rust |
|---|---|---|---|
framework | fastapi, litestar, django, flask | gin, fiber, echo, chi, stdlib | axum, actix-web, rocket, warp, salvo |
frontend | htmx, none | htmx, none | htmx, none |
orm | sqlmodel, sqlalchemy, tortoise, none | sqlc, gorm, sqlx, none | seaorm, diesel, sqlx-rust, none |
migrations | alembic, none | goose, golang-migrate, none | none |
database | sqlite, postgres, mysql, none | same | same |
packageManager | uv, poetry, pip | go | cargo |
addons | docker, ruff, mypy, pytest, github-actions, none | docker, air, golangci-lint, github-actions, none | docker, cargo-watch, clippy, github-actions, none |
Status: Python, Go, and Rust scaffolds are all generated today.
What gets validated today
frameworknot in the language's set → error, e.g.--language python --framework ginfrontendnot in the language's set → errorfrontend htmxwithframework none→ error (HTMX needs a backend to serve the rendered pages)ormnot in the language's set → error, e.g.--language python --orm seaormmigrationsnot in the language's set → error, e.g.--language python --migrations gooseorm tortoisewithmigrations alembic→ error (Alembic only supports SQLAlchemy-based ORMs)migrations alembicwithorm none→ error (Alembic migrates SQLAlchemy models)- any
ormother thannonewithdatabase none→ error (an ORM needs a database) orm tortoisewithframework flask→ error (Tortoise needs one long-lived event loop; Flask runs each async view in its own loop — use SQLModel or SQLAlchemy with Flask)addonspassed as a list must be valid enum values;noneis normalized awaydatabasemust be one ofsqlite,postgres,mysql,none
# ❌ Invalid - Gin is not a Python framework
uvx tristack --language python --framework gin
# ✅ Valid
uvx tristack --language python --framework fastapi
# ❌ Invalid - SeaORM is a Rust ORM
uvx tristack --language python --orm seaorm
# ✅ Valid
uvx tristack --language python --orm sqlmodel
# ✅ Valid - Rust stack (standalone binary)
tristack my-api --language rust --framework axum --orm seaormValidation order
The CLI validates resolved configs in this order:
- Flag input validation: valid enum values, project-name rules (see below)
- Per-language value checks: framework/orm/migrations/frontend belong to the language
- Path checks: target directory must be within the current directory and not a symlink (unless
--directory-conflict increment)
Project name rules
- Cannot be empty or longer than 255 characters
- Cannot start with
.(except.itself) or- - Cannot contain
<,>,:,",|,?,* node_modulesis reserved
Roadmap
Cross-option rules ship with each language and are enforced today — for example Django bundles its own ORM and migrations (hiding those prompts), Alembic only supports SQLAlchemy-based ORMs, and an ORM requires a database. Future dimensions (new frontends, auth, observability) will follow the same pattern: declared in the shared type layer, enforced by the CLI, prompts, and Stack Builder together.
Understanding these rules helps you create valid configurations and troubleshoot issues when the CLI reports compatibility errors.
