Skip to content

cli-reference.md

Latest commit

 

History

History
132 lines (100 loc) · 3.93 KB

cli-reference.md

File metadata and controls

132 lines (100 loc) · 3.93 KB

CLI Reference

If You Are New

Use this pattern locally inside this repository:

cd backend && uv run <command>

Example:

cd backend && uv run ade --help

uv run ensures commands use the repo's Python environment.

Root CLI: ade

Command What it does
ade start Start API + worker + web
ade dev Start API + worker + web in dev mode
ade test Run API unit + worker unit + web tests (excludes integration suites)
ade reset Reset DB/storage/local state (destructive)
ade api ... Run API subcommands
ade worker ... Run worker subcommands
ade db ... Run DB subcommands
ade storage ... Run storage subcommands
ade web ... Run web/frontend subcommands
ade infra ... Manage local infra stack (Postgres + Azurite)

Key options for ade start/ade dev:

  • --services
  • --migrate / --no-migrate
  • --open (open ADE web in the default browser when the web service is reachable)
  • ADE_API_PROCESSES applies to ade start; ade dev keeps API reload mode (single process)

API CLI: ade-api

Command What it does
ade-api dev Run API in development mode
ade-api start Run API in production-style mode
ade-api test <suite> Run tests (unit, integration, all; default unit)
ade-api lint Run lint/type checks
ade-api routes Print route list
ade-api types Generate OpenAPI + TypeScript types

Common API options:

  • ade-api start --processes N
  • ade-api dev --processes N (disables reload when N > 1)

API docs:

  • API docs are enabled by default. Set ADE_API_DOCS_ENABLED=false to disable:
    • ReDoc at /api
    • Swagger UI at /api/swagger
    • OpenAPI JSON at /api/openapi.json
  • Set ADE_API_DOCS_ACCESS_MODE=authenticated (default) to require sign-in, or public for unauthenticated docs.
  • No CLI "open docs" helper is provided; use the URLs above directly.

Worker CLI: ade-worker

Command What it does
ade-worker start Start worker
ade-worker dev Start worker in dev mode
ade-worker test <suite> Run tests (unit, integration, all; default unit)
ade-worker gc Run one garbage-collection pass

DB CLI: ade-db

Command What it does
ade-db migrate [revision] Apply migrations
ade-db history [range] Show migration history
ade-db current Show current revision
ade-db stamp <revision> Set revision without running migrations
ade-db reset --yes Reset schema and re-migrate (destructive)

Storage CLI: ade-storage

Command What it does
ade-storage check Test storage connection
ade-storage reset --yes --mode <prefix-or-container> Delete blobs (destructive)

Web Commands: ade web

Command What it does
ade web start Serve built frontend via nginx
ade web dev Start Vite dev server
ade web build Build web assets
ade web test Run frontend tests
ade web lint Run frontend lint
ade web typecheck Run frontend typecheck

Quick Recipes

cd backend && uv run ade infra up
cd backend && uv run ade infra info
cd backend && uv run ade infra down -v --rmi all
cd backend && uv run ade dev
cd backend && uv run ade dev --open
cd backend && uv run ade start --services worker --no-migrate
cd backend && uv run ade db migrate
cd backend && uv run ade api types

Integration Test Prerequisites

Integration suites use explicit ADE_TEST_* settings and do not read runtime ADE_* values.

At minimum set:

  • ADE_TEST_DATABASE_URL
  • ADE_TEST_BLOB_CONNECTION_STRING (recommended for API integration coverage)

Example:

cd backend && \
ADE_TEST_DATABASE_URL='postgresql+psycopg://postgres:postgres@127.0.0.1:5432/ade_test?sslmode=disable' \
ADE_TEST_BLOB_CONNECTION_STRING='UseDevelopmentStorage=true' \
uv run ade api test integration