CLI

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:

  1. Per-language value checks — framework, orm, migrations, and frontend must belong to the selected language's option set.
  2. 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:

CategoryPythonGoRust
frameworkfastapi, litestar, django, flaskgin, fiber, echo, chi, stdlibaxum, actix-web, rocket, warp, salvo
frontendhtmx, nonehtmx, nonehtmx, none
ormsqlmodel, sqlalchemy, tortoise, nonesqlc, gorm, sqlx, noneseaorm, diesel, sqlx-rust, none
migrationsalembic, nonegoose, golang-migrate, nonenone
databasesqlite, postgres, mysql, nonesamesame
packageManageruv, poetry, pipgocargo
addonsdocker, ruff, mypy, pytest, github-actions, nonedocker, air, golangci-lint, github-actions, nonedocker, cargo-watch, clippy, github-actions, none

Status: Python, Go, and Rust scaffolds are all generated today.

What gets validated today

  • framework not in the language's set → error, e.g. --language python --framework gin
  • frontend not in the language's set → error
  • frontend htmx with framework none → error (HTMX needs a backend to serve the rendered pages)
  • orm not in the language's set → error, e.g. --language python --orm seaorm
  • migrations not in the language's set → error, e.g. --language python --migrations goose
  • orm tortoise with migrations alembic → error (Alembic only supports SQLAlchemy-based ORMs)
  • migrations alembic with orm none → error (Alembic migrates SQLAlchemy models)
  • any orm other than none with database none → error (an ORM needs a database)
  • orm tortoise with framework flask → error (Tortoise needs one long-lived event loop; Flask runs each async view in its own loop — use SQLModel or SQLAlchemy with Flask)
  • addons passed as a list must be valid enum values; none is normalized away
  • database must be one of sqlite, 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 seaorm

Validation order

The CLI validates resolved configs in this order:

  1. Flag input validation: valid enum values, project-name rules (see below)
  2. Per-language value checks: framework/orm/migrations/frontend belong to the language
  3. 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_modules is 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.

On this page