The dev CLI

python dev.py <command>

Colon-separated commands work, and so does the plain form: migrate:status and migrate status are the same command.

Migrations

Safety Notice: Craft Engine enforces Absolute Data Persistence. Destructive commands (migrate:fresh, migrate:reset, migrate:refresh, db wipe) are strictly prohibited in production, test, and automated agent environments. See Database Safety.

Database

db wipe exits 1 without --force, and with it the migrator refuses the operation (DATABASE_DESTRUCTIVE_OPERATION_REFUSED) in every environment. No database name, _test suffix or in-memory database authorizes a wipe, and config/database.py carries no allowlist key for it.

Generators

Names are normalised: service_order, service-order and ServiceOrder all produce ServiceOrder. Suffixes are added once — make controller Product and make controller ProductController both give ProductController.

Generators refuse to overwrite. Pass --force when you mean it.

Migration names drive the stub: create_*_table produces a create migration and add_*_to_*_table produces an alter migration, with the table inferred.

Extensions

Updating requires deploying files and restarting workers before reactivation. See extensions.md for the ordered procedure and architecture.md for kind selection.

Routes

python dev.py route list
python dev.py route list --method POST
python dev.py route list --path /api
python dev.py route list --json

The table shows the ordered global middleware stack plus each route's declared middleware. --json returns global_middleware and a routes array with method, uri, name, and middleware fields for tooling and agents.

python dev.py route check
python dev.py route check --json

route:check resolves every route's middleware aliases and action, and exits 1 when one is broken, so it composes in a CI job:

The command takes the kernel from the container (app.make("kernel"), bound in bootstrap/app.py). A project that does not bind it still gets the action and name checks, but its middleware aliases are not resolved. python dev.py doctor runs the same route checks along with the rest of the project's wiring.

Data

python dev.py data audit
python dev.py data audit --json

data:audit reads the live database and reports rows that already break the schema's own promises: a foreign key that points at a parent row which is not there, and a row in a table that carries tenant_id with none set. It is read-only — nothing is repaired, because what to do with customer data is the owner's call — and it exits 1 when it finds an error, so it composes in a CI job. When multi-tenancy is on, a NULL tenant_id is an error rather than a warning.

Queue

python dev.py queue work
python dev.py queue work --queue emails
python dev.py queue work --once

See Queues and events.

Outbox

python dev.py outbox relay
python dev.py outbox relay --limit 500

Publishes the messages committed to the transactional outbox. Run it from a worker or a schedule; see Transactional Outbox.

Cache

python dev.py cache clear

Firewall (WAF) & Security Audit

python dev.py firewall list
python dev.py firewall allow 192.168.1.100
python dev.py firewall block 203.0.113.55 -r "Port scanner detected"
python dev.py security audit --limit 50

AI Coding Agents & Discovery

Craft Engine is optimized for autonomous AI coding agents (Cursor, Claude Code, Windsurf, AGY):

python dev.py agent:scaffold
python dev.py agent:list --kind agent
python dev.py agent:install code-reviewer test-driven-development ship

Installs refuse to overwrite an existing entry without --force, and check every conflict before writing anything. Both commands write to .agents/ and keep .claude a symlink to it; a project that still has a physical .claude/ directory is refused (AGENT_LEGACY_DIRECTORY) until its contents are moved. See AI Agents.

Release

See Release synchronization.

Application

tinker gives you app, db and the facades:

>>> from app.Models.User import User
>>> User.query().count()
3

Exit codes

Commands exit non-zero on failure, so they compose in scripts and CI:

python dev.py db ping && python dev.py migrate

Adding a command

dev is built with Typer. Add commands in engine/cli/app.py:

@cli.command("stats")
def stats():
    """Show application statistics."""
    app = get_app()
    total = app.make("db").statement("SELECT COUNT(*) AS n FROM users").fetchone()
    echo(f"Users: {total['n']}")

Use get_app() to boot the application lazily — importing it at module level would slow down every command, including --help.