How-To Guides

Scaffold a Full-Stack Project

quadkit new project my-app --template full -d ./workspace
cd ./workspace/my-app
ls src/my_app/

The full template includes application.yaml, app.py, modules structure, tests, and pyproject.toml.

Create a New Extension Package

quadkit new package my-feature -d ./extensions
cd ./extensions/quadkit-my-feature
uv sync
uv run pytest

Scaffolds quadkit-my-feature/ with pyproject.toml, src/quadkit/my_feature/, di/provider.py, and a unit test scaffold.

List All Available Generators

quadkit gen list

Generators are contributed by installed packages. Each entry shows the generator name and description.

Generate a Domain, Service, and Controller

quadkit gen domain Product
quadkit gen service ProductService
quadkit gen repository ProductRepository
quadkit gen controller ProductController

Generated files are placed in the project’s src/ tree, following framework conventions.

Run Database Migrations

quadkit db init          # create initial migration
quadkit db migrate -m "add email field"
quadkit db upgrade       # apply pending
quadkit db rollback      # revert last
quadkit db status        # check state
quadkit db list          # show history

Requires the package that provides the database provider.

Inspect the Runtime

quadkit inspect providers    # list DI providers
quadkit inspect routes       # show HTTP routes
quadkit inspect health       # run health checks
quadkit inspect container    # show container bindings

Start an Interactive Shell

quadkit shell                # REPL with app context
quadkit shell --ipython      # use IPython if available
quadkit shell --no-app       # plain Python REPL

The context-loaded shell provides app, container, config, db, cache, and events.

Run Project Checks as a Pre-Commit Gate

quadkit test                 # run pytest
quadkit lint                 # run ruff
quadkit project typecheck    # run mypy
quadkit project run-all      # all checks

Notes

• Use --json flag on any command for machine-readable output
• Generators create files relative to the project root; run from the project directory
• Migration files are timestamped and stored in the project’s migrations directory
• The dev server and run command auto-discover create_app(); use module:attr syntax to override