WordloopCLI 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, Docs (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 wipe | Destructive: stop everything and destroy all data volumes |
./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 — supports multi-tail (e.g. ./dev logs core ml) |
./dev attach db | Drop into an interactive psql shell |
./dev status | Print local environment ports and endpoints |
Services run natively by default with auto-reload (Air for Go, uvicorn for Python, HMR for Next.js). Use --docker to 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 smoke | Run infrastructure health smoke tests |
./dev test core | Run Go test suites |
./dev test ml | Run Python Pytest suites |
./dev test app | Run TS Vitest suites |
./dev lint all | Run static analysis across all services |
./dev lint core | Run go vet on Core |
./dev lint ml | Run ruff check on ML |
./dev lint app | Run eslint on App |
Utilities
| Command | Description |
|---|---|
./dev db migrate | Apply all pending Core DB migrations |
./dev db rollback | Revert the single most recently applied migration |
./dev db drop | Destructive: completely drop the schema |
./dev db shell | Drop securely into the local PostgreSQL console |
./dev dash obs | Open the .NET Aspire Observability UI Dashboard |
./dev dash api | Open the ML API Swagger docs |
./dev dash app | Open the Next.js App |
./dev dash docs | Open the Fumadocs Documentation UI |
./dev gcp pubsub | Interact with local Pub/Sub emulator via gcloud |
./dev gcp storage | Query the local Storage emulator REST API |
./dev gen api | Generate OpenAPI schemas |
./dev gen events | Generate AsyncAPI structs across all services |
./dev gen clients | Rebuild typed API clients (Orval + Go + Python) |
./dev gen docs | Recompile OpenAPI metadata for docs UI |
./dev setup env | Copy environment baseline configurations |
./dev setup install | Install workspace-wide package dependencies |
System
| Command | Description |
|---|---|
./dev doctor | Validate all system dependencies, Docker status, port availability, and env files |
./dev completions zsh | Output zsh auto-completion script |
./dev completions bash | Output bash auto-completion script |
First time? Run ./dev doctor immediately after cloning to verify your machine has everything needed.
Enabling auto-completion
# Zsh — add to ~/.zshrc for permanent access
eval "$(./dev completions zsh)"
# Bash — add to ~/.bashrc
eval "$(./dev completions bash)"After sourcing, typing ./dev then pressing Tab will suggest available commands and sub-targets.
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.
Resilience Model
The CLI is designed for safety and resilience:
- Graceful shutdown:
./dev stopsendsSIGTERMfirst, allowing services to flush connections and clean up. Only falls back toSIGKILLafter a 3-second grace period. - Subshell isolation: All commands run in isolated subshells, preventing
cdside-effects from corrupting your terminal's working directory. - Port conflict detection:
./dev doctorand./dev startboth check for port conflicts before launching services. - No external dependencies: Port checking uses native bash
/dev/tcpinstead of requiringncornetcat.