Guide

Requirements

Package	Required	Purpose
quadkit	Yes	Core framework
quadkit-contracts	Yes	Protocol definitions
quadkit-web	Yes	Web UI support

The Problem quadkit-cli Solves

Building a Quadkit application involves repeated setup: project scaffolding, code generation, database migrations, and runtime inspection. quadkit-cli automates these tasks through a single quadkit command, using a contributor-based plugin system where packages extend the CLI via quadkit.cli.contributors entry points.

Mental model: Think of quadkit-cli as the framework’s toolbox — one command to create, build, run, and introspect your application.

---

Core Concepts

• Command groups — commands are organized as sub-Typer apps (new, run, dev, db, gen, inspect, shell, etc.)
• Contributors — packages advertise commands, generators, health checks, shell context, and hooks via quadkit.cli.contributors; discovered at import with automatic conflict resolution
• CLIContext — per-invocation shared state holding config, output mode (Rich/JSON/Quiet), and flags
• OutputManager — centralized output with support for Rich formatting, JSON serialization, and debug modes

---

Full Command Walkthrough

Scaffolding (new, add)

# Create a new project from a template
quadkit new project my-app --template web-api -d ./projects

# Create a project interactively
quadkit new project my-app -i

# Scaffold a new quadkit-* extension package
quadkit new package my-feature

# Add a provider to an existing project
quadkit add web
quadkit add sql

Available templates: web-api, full, api.

Dev Server (run, dev)

# Auto-detect create_app() and start the server
quadkit run

# Explicit entry point
quadkit run my_app.app:create_app --port 9000 --no-reload

# Development server with hot-reload
quadkit dev --entry src/main.py --port 8000 --env development

# Use a specific server backend
quadkit run --server granian

# Run with an MCP SSE server alongside
quadkit run --mcp-port 8080

The CLI auto-detects the server backend, preferring Granian → Uvicorn → Hypercorn based on availability.

Database Management (db)

# Create/upgrade a database and generate an initial migration
quadkit db init

# Auto-generate a migration from schema changes
quadkit db migrate -m "add email to users"

# Apply pending migrations
quadkit db upgrade

# Rollback the last migration
quadkit db rollback

# View migration status
quadkit db status

# Seed test data
quadkit db seed

# View migration history
quadkit db list

Database commands need the package that provides the database provider. No public package ships one yet, so db reports ProviderNotInstalledError.

Code Generation (gen)

# List all available generators
quadkit gen list

# Generate code
quadkit gen domain User
quadkit gen service UserService
quadkit gen repository UserRepository
quadkit gen controller UserController

Generators are contributed by installed packages. Each generator creates files in the current project’s source tree.

Runtime Inspection (inspect)

# List registered container providers
quadkit inspect providers

# Show HTTP routes
quadkit inspect routes

# Display container bindings
quadkit inspect container

# Run health checks
quadkit inspect health

# View service list
quadkit inspect services

Interactive Shell (shell)

# Start a REPL with the application context pre-loaded
quadkit shell

# Plain Python REPL without app bootstrap
quadkit shell --no-app

# Use IPython if available
quadkit shell --ipython

The shell provides app, container, config, db, cache, and events as pre-loaded objects.

Other Commands

# System information
quadkit system info
quadkit version

# Configuration management
quadkit config show
quadkit config schema
quadkit config init --output application.yaml

# Contributor discovery
quadkit contrib check
quadkit contrib list

# Meta commands
quadkit list         # list all commands
quadkit completion   # generate shell completion
quadkit test         # run project tests
quadkit lint         # run project linters

---

Integration with the DI Container

from quadkit import Application
from quadkit.cli import CLIModule, CLIConfig
from quadkit.cli.di.provider import CLIProvider

# Via module (recommended)
app = Application(name="my-app")
app.add_module(CLIModule.configure(CLIConfig(color=False)))

# Via provider directly
provider = CLIProvider(config=CLIConfig(color=False))
app.add_provider(provider)

The CLIProvider has priority APPLICATION (40) — it boots after infrastructure but before domain services.

---

Best Practices

• ✅ Run quadkit gen list to see all available generators from installed packages
• ✅ Use quadkit project test/lint as a pre-commit gate
• ✅ Run quadkit contrib check to verify contributors load cleanly after adding packages
• ✅ Use --json flag for machine-readable output (useful in CI scripts)
• ❌ Don’t manually edit generated file headers — re-run the generator instead
• ❌ Don’t use quadkit run in production — deploy through your ASGI server directly