CLI Reference
Complete reference for every command in the ./dev CLI.
CLI Reference
The WordLoop platform has fully deprecated legacy Makefiles in favor of a bespoke, shell-native ./dev interface that powers all local execution logic safely and predictively.
All targets are run from the monorepo root. Run ./dev help for a formatted list.
Lifecycle
| Command | Description |
|---|---|
./dev start all | Start infra (Docker) + Core, ML, App (native) |
./dev start all --docker | Start everything in Docker containers |
./dev start infra | Start shared infra only (Postgres, Pub/Sub, Storage, OTel) |
./dev start [services...] | Start specific services natively (e.g. ./dev start core ml) |
./dev start [services...] --docker | Start specific services in Docker containers |
./dev stop all | Stop everything safely (Docker + native processes) |
./dev stop [services...] | Stop specific services (auto-detects native vs Docker) |
./dev logs all | Tail logs for all running services |
./dev logs [services...] | Tail logs for specific services (native or Docker) |
./dev status | Print local environment ports and endpoints |
[!NOTE] Services run natively by default with auto-reload (Air for Go, uvicorn for Python, HMR for Next.js). Use
--dockerto opt into Docker containers when needed.
Quality
| Command | Description |
|---|---|
./dev test all | Execute all testing suites across all packages |
./dev test system | Execute strictly end-to-end integration boundaries via Pytest |
./dev test core | Run Go test suites |
./dev test ml | Run Python Pytest suites |
./dev test app | Run TS Vitest suites |
./dev lint | Run static analysis and formatters (Go vet, Ruff, ESLint) |
Utilities
| Command | Description |
|---|---|
./dev db migrate | Apply all pending Core DB migrations |
./dev db shell | Drop securely into the local PostgreSQL console |
./dev dash obs | Open the .NET Aspire Observability UI Dashboard |
./dev dash docs | Open the Fumadocs Documentation UI |
./dev gcp | Interact with local Pub/Sub and Storage emulators |
./dev gen api | Generate OpenAPI schemas and clients |
./dev gen events | Generate AsyncAPI structs |
./dev gen docs | Recompile OpenAPI metadata for UI |
./dev setup | Copy environment baseline configurations |
./dev setup install | Install workspace-wide package dependencies |
Native vs Docker
By default, ./dev start core runs the Go service natively using Air for auto-reload. This means:
- File changes are detected automatically — Air watches
.gofiles and rebuilds in ~1 second - Migrations run on every restart — database schema is always current
- Logs go to
.dev/logs/— tail them with./dev logs core - IDE debugging works — you can also run Core from your IDE's debugger instead
Use --docker when you need full containerized behavior (e.g., testing Dockerfiles, CI parity, or running without Go installed locally).
Debug Environments
By running selectively (e.g., ./dev start infra core), you intentionally leave services like wordloop-ml turned off. This allows you to run those specific services through your IDE (like VSCode Launch actions) so you get full debugging breakpoint control while depending on a containerized or native backend.