Core Commands — Aquilia Documentation
Comprehensive guide and documentation for Core Commands in the Aquilia framework. View API reference, examples, and implementation patterns.
CLI / Core Commands Core Commands Core lifecycle commands handle workspace bootstrap, module configurations, manifest validations, asset compilation, and server execution. aq init workspace Creates a new workspace structure. Generates the base workspace.py, the entrypoint module, and configuration folders. # Initialize standard API project aq init workspace billing-api --template=api # Initialize minimal workspace without examples aq init workspace core-service --minimal --yes Options Option Description ))} aq add module Generates a new self-contained module directory inside modules/, creating a default manifest.py, controller, models, and tests files. # Standard module scaffold aq add module auth # Custom route prefix and module dependency declarations aq add module payments --depends-on=users --depends-on=auth --route-prefix=/v2/pay Options Option Description ))} aq validate Parses workspace manifests statically, checking that dependency graphs are clear of cycles and routes do not overlap. # Validate entire workspace aq validate # Run validation and output details in JSON format aq validate --strict --json Changed in 1.4.0b3 — exit codes are now enforced Before this release, aq validate and aq doctor printed error banners and still exited 0, so a broken workspace passed CI. Both now run through the unified health-checks engine and exit via exit_code_for(). 0 — passed, or only INFO/WARN findings 1 — at least one ERROR or FATAL finding 2 — bad invocation or arguments 3 — workspace or config could not be loaded 4 — unhandled internal CLI exception A pipeline that previously appeared green may now fail. That is the fix, not a regression — check the reported findings. aq compile Compiles modular controllers, routers, contracts, and translations into a compiled directory of static `.json` files. This is recommended before deploying to production. # Run compilation aq compile # Watch the workspace for edits and automatically recompile files aq compile --watch --output=dist/ aq run Starts the development server. By default, it auto-detects ports from workspace.py, enabling hot reloading. # Start server on local defaults aq run # Bind custom host/port and disable pre-flight checks aq run --port=8080 --host=0.0.0.0 --skip-checks # Native C++ engine toggles (fail-soft fallback to pure-Python) aq run # uses workspace.py accelerator config aq run --no-engine # disable C++ router, use pure-Python aq run --no-dataengine # disable C++ ORM compiler, use pure-Python aq run --no-engine --no-dataengine # full pure-Python mode Configuration Priority for Engine Flags (highest wins): CLI flag (e.g., aq run --no-engine) Process environment (e.g., AQUILIA_ENGINE=0) workspace.py AquilaConfig.Accelerator settings Framework default (enabled) Options Option Description ))} aq serve Starts the production ASGI server. Recommended to wrap in Gunicorn using Uvicorn worker threads to manage concurrency. # Simple serve aq serve # Production gunicorn setup with 4 workers and custom bindings aq serve --use-gunicorn --workers=4 --bind=127.0.0.1:9000 --timeout=60 aq manifest update Synchronizes a module manifest by searching the folder structure for untracked controller classes or model definitions. # Sync payments module manifest aq manifest update payments # Perform dry-run sync check (useful in CI scripts) aq manifest update orders --check aq doctor Performs deep diagnostics on your active workspace setup. It validates imports, database adapters, cache connections, and environment files, reporting details in clean stdout or JSON format. # Run diagnostic check aq doctor # Export diagnostic logs as JSON aq doctor --json Changed in 1.4.0b3. aq doctor runs the same registry of checks as aq validate, plus environment-level probes, and obeys the same exit-code contract described above. Every finding carries a stable code (for example AQ_DB_MISSING), a location, and a concrete remedy. Config-driven subsystem probes stay silent for subsystems a workspace does not declare, so a minimal app produces a short report rather than a wall of noise. Among them is vectordb.driver, which reports AQ_VECTORDB_DRIVER_MISSING when a workspace declares vector stores on an install without the optional elips driver — see Vector Database. )
Go to Homepage