CLI Reference

alpha (0.0.x) — Apache 2.0 licensed. Commands and flags may change before 1.0.

Overview

The quadkit CLI is the primary developer tool for scaffolding, running, and managing Quadkit projects. Commands are organised into categories.

Built-in commands

quadkit new

Scaffold a new project or package.

quadkit new project <name> [--template web-api] [--directory .]
quadkit new module <name> [--directory .]
quadkit new package <name> [--output-dir packages/]

Flag	Default	Description
--template, -t	web-api	Project template (minimal, api, web-api, graphql, worker, full, fullstack)
--directory, -d	.	Output directory

Examples:

quadkit new project my-api --template web-api
quadkit new project my-app --template api
quadkit new project my-platform --template full

quadkit new module <name> adds a bounded context to a project (src/<app>/modules/<name>/ with a @module boundary, protocols.py, provider.py and services.py, registered in modules/__init__.py).

quadkit gen <generator> <name> --module <feature> writes module-local components into the matching bounded context; cross-cutting generators (errors, filters, health, schema, …) write into shared/.

quadkit run

Smart runner — auto-detects create_app() factory and starts the ASGI server.

quadkit run [target] [--host 0.0.0.0] [--port 8000] [--server uvicorn]

Flag	Default	Description
target	Auto-detected	module:attr factory path
--host, -h	0.0.0.0	Bind address
--port, -p	8000	Port
--server	Auto-detected	Server backend (uvicorn, hypercorn, granian)

Example: quadkit run my_app.app:create_app --port 8080

quadkit dev

Development server with hot reload.

quadkit dev [--entry src/main.py] [--host 127.0.0.1] [--port 8000] [--reload] [--env development]

Flag	Default	Description
--entry	Auto-detected	Entry point file
--reload/--no-reload	True	Hot reload on file changes
--env	development	Environment profile

Example: quadkit dev --entry app.py --port 9000 --no-reload

quadkit db

Database management commands.

quadkit db init [--reset] [--seed]
quadkit db migrate [--name <migration>] [--auto]
quadkit db seed [--file seeds.py]     # src/<app>/shared/seeders, else ./seeds
quadkit db shell

quadkit gen

Code generation commands.

quadkit gen provider <name> [--output src/di/]
quadkit gen module <name> [--output src/modules/]
quadkit gen migration [--auto-detect]

quadkit inspect

Inspect runtime state of a running application or configuration.

quadkit inspect providers [--json]
quadkit inspect config [--section <section>]
quadkit inspect routes
quadkit inspect health

Flag	Description
--json	Output as JSON
--section	Filter config to a specific section

quadkit shell

Open an interactive Python REPL with the Quadkit application loaded.

quadkit shell [target]

quadkit init

Initialize Quadkit in an existing project.

quadkit init [--force]

Creates application.yaml, project scaffold, and optional pyproject.toml updates.

quadkit add

Add a provider or extension to the project.

quadkit add <package> [--version <version>]
quadkit add provider <name>

quadkit config

Configuration management.

quadkit config view [--section <section>]
quadkit config validate [--file application.yaml]

quadkit contrib

Discover and inspect installed contributors (plugins).

quadkit contrib list [--json]
quadkit contrib info <name>

Flag	Description
--json	Machine-readable output

quadkit project

Project management utilities.

quadkit project test [path] [--coverage] [--verbose] [--runner pytest]
quadkit project lint [path] [--fix] [--check]
quadkit project routes

quadkit system

System information and diagnostics.

quadkit system info
quadkit system diagnostics
quadkit system check

quadkit version

Show framework and package versions.

quadkit version [--all]

Flag	Description
--all	List versions of all installed Quadkit packages

quadkit list

List all available commands.

quadkit list [--group <group>] [--json]

Flag	Description
--group, -g	Filter by category
--json	Machine-readable output

quadkit completion

Generate shell completion script.

quadkit completion --shell <bash|zsh|fish|powershell>

Install with: eval "$(quadkit completion --shell bash)"

quadkit test

Run project tests (delegates to quadkit project test).

quadkit test [path] [--coverage] [--verbose]

quadkit lint

Run project linting (delegates to quadkit project lint).

quadkit lint [path] [--fix]

quadkit events

Event schema management.

quadkit events schema validate
quadkit events schema migrate

Plugin/contributor commands

Packages can register commands via the quadkit.cli.commands entry point. Contributor commands appear under their own category in quadkit list. Register in pyproject.toml:

[project.entry-points."quadkit.cli.commands"]
my_contrib = "my_package.cli:app"

See also

• CLIModule — DI integration for CLI commands
• CommandRegistry — programmatic command registration
• ContributorRuntime — plugin discovery at runtime
• PUBLIC_PACKAGE_CLI_MATRIX.md — per-package command ownership