CLI reference

All commands are run from the repository root with pnpm. Each one loads .env automatically if the file exists, so the same command works locally and in CI.

Running watches

Command	What it does	Needs
pnpm run-due	Runs every watch whose schedule is due	Google key, MongoDB_URI
pnpm run-due:force	Runs every enabled watch, ignoring schedules	same
pnpm dev	run-due, re-running on file changes	same
pnpm serve	Starts the API and the in-process scheduler	same, plus AUTH_JWT_SECRET

run-due prints one line per watch and exits non-zero if any watch failed with a real error. A watch whose model could not produce a valid verdict is reported as transient and does not fail the run.

Managing watches

Command	What it does
pnpm watches:import	Upserts every watches/*.yml into the database (idempotent)
pnpm watches:list	Lists stored watches with their thresholds and channels
pnpm watches get <id>	Prints one watch as JSON
pnpm watches enable <id>	Enables a watch
pnpm watches disable <id>	Disables a watch without deleting it
pnpm watches delete <id>	Deletes the watch definition (run history is kept)
pnpm watches history <id> [limit]	Recent run records, newest first (default 20)

Caution

watches:import reads the YAML files; the running system reads the database. Editing a file changes nothing until you import it.

Accounts

Command	What it does
pnpm users:create <email> [--role admin|user] [--id <ownerId>] [--password <pw>]	Creates an account. The first account defaults to admin.
pnpm users:list	Lists accounts (id, email, role). Never prints password hashes.

Prefer the ADMIN_PASSWORD environment variable over --password so the secret stays out of your shell history:

ADMIN_PASSWORD='a-long-random-password' pnpm users:create you@example.com --role admin --id local

--id local makes the account the owner of data created before accounts existed.

Keys

Command	What it does
pnpm keys:migrate	One-time, idempotent migration of older provider-scoped stored keys into per-use-case records. Requires CONFIG_ENCRYPTION_KEY.

Quality gates

Command	What it does
pnpm verify	typecheck + lint + tests + build. The gate to run before committing.
pnpm test	Vitest once. Hermetic: no network, no API keys.
pnpm test:watch	Vitest in watch mode
pnpm test:integration	The one test that needs a real database. Self-skips without MONGO_TEST_URI.
pnpm typecheck	tsc --noEmit
pnpm lint / pnpm lint:fix	Biome check / autofix
pnpm format	Biome formatter
pnpm build	Bundles to dist/

Accuracy harness

Command	What it does
pnpm eval	Runs the golden-set harness against a mocked model — deterministic and CI-safe
pnpm eval:live	The same set against the real model. Self-skips without a key.
pnpm eval:export	Turns labelled feedback into golden-case drafts for review

See The evaluation harness.

Admin panel

Command	What it does
pnpm web:dev	Panel dev server, proxying the API
pnpm web:verify	The panel’s gate: typecheck + tests + build

Documentation site

Command	What it does
pnpm docs:dev	This documentation site, locally
pnpm docs:build	Builds it, then runs the link, structure and content-safety checks
pnpm docs:verify	Type-checks content and builds