Commands cheatsheet

CLI commands for development, testing, and infrastructure control. Full script catalogues live in each app’s package.json and the infra folder’s compose/ directory.

Where scripts live

• Repository root: package.json (monorepo tasks: bun run regen, bun run check)
• apps/api: package.json (API dev, build, test, database)
• apps/ui: package.json (UI dev, build, test, components)
• infra/compose/scripts/: shell helpers (compose-up.sh, compose-down.sh, backup-wrapper.sh)

For every command below, see the source package.json for the full list and options.

First-week commands

Setup (first time)

./setup.sh        # seed compose/.env, optional --up to boot the stack

Dev stack control

./scripts/compose-up.sh       # start (from infra/compose/compose/)
./scripts/compose-down.sh     # stop, keep data
./scripts/compose-down-clean.sh   # stop and wipe

Regeneration and checks (repo root)

bun run regen     # ACL types, OpenAPI schema, lint-meta, docs JSON
bun run check     # drift checks (API must be running on :7330)
bun run agent:quality  # strict tooling types, lint and formatting

Structured verification (repo root)

bun run agent:inspect -- account-resource --json
bun run sandbox:up -- --json
bun run agent:verify -- --profile=release-local --sandbox=<id> --json
bun run sandbox:down -- --id=<id>

Use the returned sandbox ID. See verified workflow for profiles, explicit contract synchronization, inventory updates and failure/blocked results. Root check is not the full release gate.

API app (from apps/api)

bun run dev       # watch mode
bun run validate  # typecheck + lint + tests
bun run db:migrate    # apply migrations
bun run db:seed   # seed superuser (if vars set)

UI app (from apps/ui)

bun run dev       # dev server on :7331
bun run validate  # typecheck + lint + tests
bun run generate:api  # sync OpenAPI schema

Environment modulation (infra commands from infra/compose/compose/)

STACK=prod ./scripts/compose-up.sh              # prod profile
WITH_OBSERVABILITY=0 ./scripts/compose-up.sh    # skip observability
WITH_GLITCHTIP=0 ./scripts/compose-up.sh        # skip error tracking
WITH_MAILPIT=1 ./scripts/compose-up.sh          # add local email catcher
WITH_BULLMQ=1 ./scripts/compose-up.sh           # add queue dashboard (dev only)

Minimal: WITH_OBSERVABILITY=0 WITH_GLITCHTIP=0 ./scripts/compose-up.sh boots Postgres + Valkey + apps only.

Status and debugging

./scripts/compose-up.sh ps          # service status
docker compose logs -f api-dev      # stream logs
docker stats                        # live resource usage

Related

• Scripts & tooling; full command catalogues from each app
• Environment variables; every knob you can set
• Profiles & overlays; what the WITH_* flags control
• Deployment; production command sequences

Push-hook service targets

The API pre-push gate probes the host and port from the selected test database URL and VALKEY_HOST / VALKEY_PORT. TEST_DATABASE_URL takes precedence over DATABASE_URL; migrations and tests use that same target. Without an explicit URL, local defaults honor POSTGRES_HOST_PORT; Valkey defaults honor VALKEY_HOST_PORT. Use disposable test data because the suite can delete rows.

For unavailable local endpoints the hook can start Compose data services on those host ports. Unavailable remote endpoints fail instead of starting unrelated local services. Migrations complete synchronously before tests. The smoke hook cleans up its own stack even if startup fails; Compose configuration validation uses a temporary environment file and preserves the developer’s .env.