Commands
Common Bun workspace commands.
Run these commands from the repository root unless noted otherwise.
Tip
Use the filtered @orcai/web commands when you only need to validate documentation changes.
Development stack
Each checkout owns an isolated Docker Compose project with per-worktree ports stored in a gitignored .env. bun run stack starts the backing services from docker-compose.yaml with the docker-compose.infra.yaml override, which publishes them on loopback ports. The app, workers and docs site run on the host.
Overrides shared by every worktree on the machine go in ~/.config/orcai/dev.env or the file ORCAI_DEV_ENV_FILE names. They are merged on top of the generated defaults whenever .env is created or regenerated.
bun run stack up and bun run stack reset seed a placeholder embedding setting (http://127.0.0.1:11434/v1, model baai/bge-m3, 1024 dimensions) unless one is stored. Change it to a real endpoint on the instance Settings page.
Inside the devcontainer, ORCAI_ENV_FILE points the runner at .devcontainer/.env. Only dev, workers, web, exec and migrate apply there.
| Command | Purpose |
|---|---|
bun run stack up | Start infrastructure, write .env, apply migrations and the SpiceDB schema. Reuses an existing .env. |
bun run stack up --reset | Regenerate .env with new ports and secrets, then start as up does. |
bun run stack status | Show container state and probe every service. |
bun run stack reset | Empty every store of the stack, leaving containers and .env in place. Asks first. |
bun run stack e2e | Install the pinned Chromium, build the production images, reset the stack, then run the end-to-end suite against the images and the integration tier. |
bun run stack build | Build the app, docs, and workers production images for this stack. Arguments after -- reach docker buildx bake. |
bun run stack dev | Start the app development server with the stack environment. |
bun run stack dev --all | Start the app, workers, and documentation site together. |
bun run stack workers | Start workers with the stack environment. |
bun run stack web | Start the documentation site with the stack environment. |
bun run stack migrate | Reapply migrations and the SpiceDB schema. |
bun run stack exec -- <command> | Run any command with .env loaded. |
bun run stack logs [service] | Follow infrastructure logs. |
bun run stack env | Print the path and content of .env, writing it first when it is missing. |
bun run stack env --reset | Regenerate .env with new ports and secrets. |
bun run stack down --volumes | Stop the stack and delete its data. Asks first. |
These options apply to every command and can stand anywhere before --:
| Option | Purpose |
|---|---|
--name <stack> | Compose project name. Defaults to ORCAI_STACK_NAME, or else orcai-<checkout folder>. |
--env-file <path> | Env file to read and write. Defaults to ORCAI_ENV_FILE, or else .env at the repository root. |
--yes | Answer the confirmation of a destructive command up front. A caller without a terminal has to pass it. |
bun run stack --name <name>-e2e --env-file .env.e2e up starts a second, independent stack, for example to run the end-to-end suite without touching your development data. An unknown option before -- fails with an error, and everything after -- reaches the command unchanged.
Application
| Command | Purpose |
|---|---|
bun run dev:all | Alias for bun run stack dev --all. |
bun run dev | Alias for bun run stack dev. |
bun run build | Build the main app, the docs site, and the workers. |
bun run start | Run the built main app. |
bun run workers:dev | Alias for bun run stack workers. |
bun run workers:start | Run the built workers. |
Quality checks
| Command | Purpose |
|---|---|
bun run verify | Run Biome, TypeScript checks, the migration check, and unit tests. |
bun run test:integration | Run the integration tier against the stack. |
bun run e2e | Alias for bun run stack e2e. |
bun run lint | Run Biome, TypeScript checks, and the migration check. |
bun run lint-full | Run Biome, TypeScript checks, the migration check, and ESLint. |
bun run knip | Find unused dependencies and exports. |
bun run prepush | Run the full pre-push check. |
bun run prompt-evals | Run the prompt evals against real models through OpenRouter or PROMPT_EVALS_ENDPOINT. Costs money and never runs in CI, see Contributing. |
The TypeScript check passes --force to tsgo --build, so stale build info
cannot hide an error that a fresh CI checkout reports.
The migration check is drizzle-kit check on packages/db/migrations. It
needs no database and fails when two migrations branch from the same parent
and change the same table, column, or other entity. That happens when a branch
with a new migration is rebased onto a main that gained one. Regenerate the
branch's migration on top.
lint:eslint, which lint-full runs, enumerates the workspaces
(apps/app, apps/web, then apps/e2e and apps/workers) because
each carries its own ESLint project settings.
End-to-end tests
Everything after -- is passed to Playwright. End-to-end tests has the full workflow.
| Command | Purpose |
|---|---|
bun run stack e2e | Reset the stack, then run the whole suite. |
bun run stack e2e -- --grep auth | Run one spec area. |
bun run stack e2e -- --ui | Open Playwright UI mode. |
bun run stack e2e --no-reset -- --grep smoke | Reuse existing data for fast iteration. |
bun run stack e2e --no-integration | Run Playwright without the integration tier. |
Database and authorisation
Package scripts do not see the root .env on their own, so wrap them in bun run stack exec --.
| Command | Purpose |
|---|---|
bun run stack migrate | Apply SQL migrations and the SpiceDB schema. |
bun run stack exec -- bun run --filter @orcai/db generate | Generate a new Drizzle migration. |
bun run stack exec -- bun run --filter @orcai/db studio | Open Drizzle Studio. |
bun run stack exec -- bun run --filter @orcai/spice-db status | Inspect SpiceDB schema migration status. |
bun run stack exec -- bun run --filter @orcai/spice-db reset | Delete every relationship, keeping the schema. Asks first, and names the endpoint it would wipe. bun run stack reset calls this with --yes. |
Documentation web service
Run the docs service directly with:
bun run stack webCheck MDX generation and TypeScript types with:
bun run --filter @orcai/web types:checkBuild the docs service with:
bun run --filter @orcai/web buildThe build prerenders on a free preview port when port 3001, the docs site's own port, is occupied, so another local server does not block bun run ci.
Maintenance
| Command | Purpose |
|---|---|
bun run clean | Remove dependencies, build outputs, generated TanStack artifacts, devtools folders, and TypeScript build info. |
bun run machine-translate | Run the app machine-translation workflow. |