The quadkit CLI

quadkit-cli ships the quadkit command — the day-to-day driver for every QuadKit project. It scaffolds new apps, runs the development server, drives database migrations when a provider is installed, manages configuration, and exposes a plugin surface that lets installed extensions contribute their own subcommands.

For the full command reference, see the quadkit-cli package docs and the CLI reference.

---

1. Install & Verify

uv add quadkit-cli            # recommended
# or: pip install quadkit-cli
quadkit --version             # → quadkit <version>
quadkit --help                # full command list

The CLI is also pulled in transitively by most projects, so uv sync from a generated project is usually enough.

Global flags work on every subcommand:

Flag	Effect
--json	machine-readable output where supported
--quiet, -q	suppress non-essential output
--debug	print tracebacks on error
--no-color	disable ANSI colour
--config, -c	path to application.yaml

---

2. Scaffolding a New Project

quadkit new project renders one project tree. Templates pick packages and application.yaml sections — not a different shape:

quadkit new project my-app                          # default template: web-api
quadkit new project my-app --template api           # JSON API only
quadkit new project my-app --template minimal       # core only
quadkit new project my-app --interactive            # prompt for template
quadkit new module auth                             # bounded context, same tree

Flag	Default	Notes
--template, -t	web-api	one of minimal, api, web-api (richer templates appear when their providers are installed)
--directory, -d	.	parent directory for the new project
--interactive, -i	false	prompts for template

To scaffold a reusable extension package instead of an application:

quadkit new package my-feature        # → quadkit-my-feature/ with src/ + provider stub

quadkit init writes a minimal application.yaml into an existing directory — useful when adopting QuadKit in a project that already has a pyproject.toml:

quadkit init --full          # full config (web/db/auth/cache/monitor sections)
quadkit init --minimal       # just project + logging (default)
quadkit init --force         # overwrite an existing application.yaml

See Project Structure for what the templates lay down. Feature types land in domains/ (not models/). App providers land in src/<app>/di/ (*_provider.py). If the generator inventory still says quadkit gen model, the file still belongs in domains/ — this site wins.

---

3. Running Locally

Two commands launch your app — pick by intent:

quadkit run                  # production-shaped: --host 127.0.0.1, --reload on
quadkit dev                  # development server, --reload on, QK_ENV=development

Both auto-detect your entry point (src/main.py, create_app, etc.) using discover_entry_point and pick the best available server backend (prefers granian → uvicorn, falls back to hypercorn).

quadkit run flags:

Flag	Default	Notes
target (positional)	auto-detected	module:attr, e.g. my_app.app:create_app
--host, -h	127.0.0.1	bind address
--port, -p	8000	bind port
--reload/--no-reload	true	hot reload
--workers, -w	1	worker processes
--profile	none	sets QK_PROFILE for the run
--server	auto	uvicorn, granian, or hypercorn
--mcp-port	none	also serve MCP (SSE) on this port

quadkit dev accepts --entry, --host, --port, --reload/--no-reload, --env, --server. For production, use quadkit dev start (binds 0.0.0.0, no reload, takes --workers) or invoke an ASGI server directly — see Deployment.

Note

The reloader watches .py files. Changes to application.yaml require a manual restart.

---

4. Database Migrations

quadkit db drives migrations through a database provider. The command surface is always present; the provider is not — no persistence package is published yet, so the commands below report the provider as missing until one is installed. The most common flow, once it is:

quadkit db init migrations              # create migrations/ directory
quadkit db create add_users_table       # new empty migration file
quadkit db upgrade                      # apply pending migrations
quadkit db status                       # show current version + pending
quadkit db history --limit 20           # last N applied migrations
quadkit db downgrade                    # roll back the most recent
quadkit db downgrade 0003_seed          # roll back to a specific version

Inspection and maintenance:

quadkit db inspect                      # list tables + columns
quadkit db inspect --table users        # one table's columns + types
quadkit db shell                        # open psql / mysql / sqlite3 client
quadkit db validate                     # check applied migrations have files
quadkit db reset --force                # drop & re-migrate (SQLite-optimized)
quadkit db backup --output dump.sql
quadkit db restore dump.sql --force

Seed scripts in seeds/*.py (each exposing a run(provider) function) are applied by quadkit db seed or as part of quadkit db reset --seed.

All db commands read DATABASE_URL from the environment. When a database provider is installed, the runner is resolved through the DI container so connection pooling and observability hooks are active.

---

5. Inspecting & Diagnosing

quadkit list                            # all available commands, grouped
quadkit list --group Database
quadkit version --all                   # versions of every installed quadkit-* package
quadkit system info                     # Python version, platform, config path
quadkit system health                   # project + contributor health checks
quadkit system doctor --fix             # diagnostics with auto-fix hints
quadkit system providers                # provider sections in application.yaml

Installed extensions register CLI contributors — discover them with:

quadkit contrib list                    # all contributors + their contributions
quadkit contrib inspect sql             # generators/commands/health checks for one
quadkit contrib check                   # verify every contributor loads

Code generation routes through contributors as well:

quadkit gen list                        # all discovered generators
quadkit gen controller users            # src/<app>/controllers/…
quadkit gen service greetings           # src/<app>/services/…
quadkit gen provider billing            # src/<app>/di/billing_provider.py
quadkit gen error not_found             # src/<app>/shared/errors/…  (always shared)

---

6. Configuration

The CLI looks for application.yaml in the current directory (and walks up to find one). Override with --config /path/to/app.yaml.

Profiles are environment-driven — set QK_PROFILE=production and a matching application.production.yaml is overlaid on the base config. Any value can be overridden by a QK_-prefixed env var with __ for nesting:

export QK_PROFILE=staging
export QK_SQL__BACKEND__URL=postgresql+asyncpg://...

Useful config commands:

quadkit config show                     # current resolved config (secrets masked)
quadkit config show --reveal-secrets    # unmasked
quadkit config validate                 # schema + cross-field validation
quadkit config doctor --env production  # environment-specific diagnostics
quadkit config env                      # ${VAR} references and whether they're set
quadkit config env --missing            # exit 1 if any are unset
quadkit config env-example              # generate .env.example from config
quadkit config diff -c application.production.yaml
quadkit config schema                   # dump the JSON schema

See Configuration and YAML Configuration for the full layering rules.

---

7. Adding Providers & Shell Completion

quadkit add web                         # add quadkit-web + web: section to YAML
quadkit add testing                     # add quadkit-testing

The add command edits pyproject.toml (via uv add when available) and patches application.yaml with the provider’s default config block.

Generate shell completion:

quadkit completion --shell bash         # also: zsh, fish, powershell
eval "$(quadkit completion --shell zsh)"

---

Next Steps

• Your First App — the 60-second walkthrough using quadkit new and quadkit run
• Project Structure — where gen and new module write files
• Deployment & Infrastructure — running quadkit in production
• CLI reference — command tree dump
• quadkit-cli package — README, quickstart, and architecture notes