WordloopReference
CLI Reference
Complete reference for every command in the ./dev CLI.
CLI Reference
The Wordloop platform uses the repository-root ./dev CLI for local orchestration, quality checks, generation, documentation maintenance, and bet authoring. Run commands from the monorepo root.
Use the CLI help as the executable source of truth when in doubt:
./dev help
./dev <verb> --helpCommand groups
| Group | Verbs | Purpose |
|---|---|---|
| Lifecycle | start, stop, logs, attach, status | Run local infrastructure and services, inspect state, and connect to service shells. |
| Quality | build, test, lint | Simulate CI builds, run test suites, and run static checks. |
| Utilities | db, dash, gcp, gen, docs, setup, sync | Manage local dependencies, schemas, generated artifacts, docs, and synced resources. |
| Authoring | new, archive | Scaffold and archive bet-design content. |
| System | doctor, completions | Validate the local machine and generate shell completion scripts. |
Lifecycle
| Command | Description |
|---|---|
./dev start all | Start infrastructure plus Core, ML, App, and Docs using the default native-service model. |
./dev start all --docker | Start everything in Docker containers. |
./dev start infra | Start shared infrastructure only: Postgres, Pub/Sub, Storage, OTel, and dashboards. |
./dev start [services...] | Start selected services natively, for example ./dev start core ml. |
./dev start [services...] --docker | Start selected services in Docker containers. |
./dev stop all | Stop all managed Docker and native processes safely. |
./dev stop wipe | Destructive: stop everything and remove local data volumes. |
./dev stop [services...] | Stop selected services or infrastructure targets. |
./dev logs all | Tail logs for all running Docker/native services. |
./dev logs [services...] | Tail selected services, for example ./dev logs core ml. |
./dev attach db | Open an interactive local PostgreSQL shell. |
./dev status | Print local ports, endpoints, and service status. |
Services run natively by default with auto-reload where supported. Use --docker when you need container parity or do not have a native toolchain installed.
Quality
| Command | Description |
|---|---|
./dev build all | Run local CI-style builds for Core, ML, App, and Docs. |
./dev build core | Docker-build wordloop-core. |
./dev build ml | Docker-build wordloop-ml. |
./dev build app | Docker-build wordloop-app with the required public Clerk build arg. |
./dev build docs | Install docs dependencies and run the docs production build. |
./dev test all | Run Core, ML, App, system, smoke, and CLI test suites. |
./dev test core | Run Go tests for wordloop-core. |
./dev test ml | Run Python tests for wordloop-ml. |
./dev test app | Run Vitest tests for wordloop-app. |
./dev test system | Run cross-service system integration tests. |
./dev test bet <slug> | Run the progress suite for an active or archived bet. |
./dev test smoke | Run infrastructure smoke tests. |
./dev test cli | Run pure Bash tests for the CLI. |
./dev lint all | Run static checks across Core, ML, and App. |
./dev lint core | Run go vet for Core. |
./dev lint ml | Run ruff check for ML. |
./dev lint app | Run the App linter. |
Utilities
| Command | Description |
|---|---|
./dev db shell | Open a local PostgreSQL shell. |
./dev db migrate | Diff services/wordloop-core/db/schema.sql against the live database with pg-schema-diff and apply the generated plan. |
./dev db dry-run | Preview the pg-schema-diff plan and hazards without applying changes. |
./dev db drop | Destructive: drop the local schema. |
./dev db dump | Apply schema changes, then export a pg_dump snapshot to .dev/schema.sql. |
./dev db prod-proxy start | Start a background Cloud SQL Auth Proxy to the live production database. |
./dev db prod-proxy stop | Stop the production database proxy process. |
./dev dash obs | Open the observability dashboard. |
./dev dash api | Open the ML API documentation dashboard. |
./dev dash app | Open the Next.js app. |
./dev dash docs | Open the documentation site. |
./dev gcp pubsub | Interact with the local Pub/Sub emulator. |
./dev gcp storage | Query the local Storage emulator. |
./dev gen all | Run API, event, client, and docs generation in order. |
./dev gen api | Compile local OpenAPI JSON specs and stage AsyncAPI specs under specs/. |
./dev gen events | Generate typed AsyncAPI event models for Core, App, and ML. |
./dev gen clients | Rebuild typed service and frontend clients. |
./dev gen docs | Rebuild generated API reference material for the docs site. |
./dev docs health | Check docs freshness, skill-doc references, corpus freshness, and known drift-prone claims. |
./dev setup all | Run environment-file setup and dependency installation. |
./dev setup env | Copy blank .env templates to active local paths. |
./dev setup install | Install/synchronize workspace dependencies. |
./dev sync skills | Sync source skills from tools/skill-factory/skills/ into .agents/skills/. |
Authoring
| Command | Description |
|---|---|
./dev new bet <slug> | Register a new active bet and baseline progress suite. |
./dev new problem-statement <bet-slug> | Add a problem-statement page to a bet. |
./dev new pitch <bet-slug> | Add a pitch page to a bet. |
./dev new tdd <bet-slug> | Add a TDD overview to a bet. |
./dev new milestone <bet-slug> <milestone-slug> | Scaffold a TDD milestone. |
./dev new slice <bet-slug> <milestone-slug> <domain> <slice-slug> | Scaffold a vertical domain slice. |
./dev new contracts <bet-slug> | Scaffold the default contract tree for a bet. |
./dev new contract <bet-slug> <service> <protocol> | Scaffold one API/event contract page. |
./dev new schema <bet-slug> <service> <tech> | Scaffold one database schema page. |
./dev archive bet <slug> | Move a delivered bet and its tests into archive locations. |
System
| Command | Description |
|---|---|
./dev doctor | Validate required dependencies, Docker status, ports, and environment files. |
./dev completions zsh | Print zsh completion setup. |
./dev completions bash | Print bash completion setup. |
Native vs Docker
By default, application services run as native background processes with logs and PIDs under .dev/. Infrastructure runs through Docker Compose. This hybrid model keeps local debugging fast while preserving realistic infrastructure dependencies.
Use --docker on start when you need full containerized behavior, CI parity, or a local run without a native service toolchain.
Maintenance notes
This page summarizes the CLI for humans and agents, but the executable source remains the CLI itself. When changing CLI behavior, update scripts/cli/*.sh, run the relevant ./dev <verb> --help, then update this page and run ./dev docs health.