CLI Reference

CLI Reference

Every pnpm command in the repository, grouped by what it is for. Run them from the repository root, where .env lives.

---

Setup and configuration

Command	What it does
pnpm setup	Interactive setup: how to run it, who can reach it, which services, the AI provider and model, the limits, and whether to keep existing secrets. Writes .env (backing up the old one) and can run the next steps for you. See Getting Started.
pnpm setup --local / --demo	Choose the fully local or the demo-compatible services without being asked.
pnpm setup --private / --public	Just you (no quotas) or a shared instance (strict limits).
pnpm setup --defaults	Skip the limit questions and take the profile's defaults.
pnpm setup --yes (-y)	Answer every question with its default. Stays offline for AI: no discovery, no billable probe.
pnpm setup --force	Overwrite an existing .env without asking.
pnpm setup --no-color · --help
pnpm rate-limit show	The rate limits in force and where each came from (profile, environment or CLI).
pnpm rate-limit set --requests N --window S	Set every limit, written to the database. Takes effect without a restart.
pnpm rate-limit set <name> --requests N --window S	One limit: upload, processing, export, read, search.
pnpm rate-limit reset	Remove CLI overrides.

---

AI provider

Command	What it does
pnpm ai status	Provider and model in force, whether verified, calls and tokens this instance has sent; for a ChatGPT sign-in, the account, plan and the plan's usage limits.
pnpm ai verify	Setup's probe on its own: two synthetic requests (structured output, image), then writes AI_PROVIDER, AI_MODEL and AI_MODEL_CAPABILITIES into .env, leaving the rest untouched. With a terminal and no model, shows the picker.
pnpm ai verify --provider P --model M	Verify a specific model, e.g. --provider ollama --model qwen3-vl:4b-instruct.
pnpm ai verify --text-only	Accept a model that cannot read images (image-region analysis will be skipped, and said so).
pnpm ai verify --input-price X --output-price Y	Record USD per 1M tokens in AI_MODEL_PRICES.
pnpm ai verify --print	Print the settings instead of writing .env.
pnpm ai login --provider openai	Sign in with a ChatGPT subscription (PKCE, loopback on localhost:1455), then pick, verify and price a model. The token is sealed in the database, never in .env. Read the caveat in AI Providers §6. --provider anthropic explains why it is not offered and exits.
pnpm ai logout --provider openai	Delete the stored sign-in. (It lapses at OpenAI when it expires.)
pnpm models:warm	Refresh the cached model lists and list prices that setup shows, for providers with credentials in .env.
pnpm models:warm --provider P · --all · --force · --offline	One provider (repeatable) · every provider (Gateway, DeepInfra and OpenRouter need no key) · refetch even when fresh · report the cache without the network.

---

Running

Command	What it does
pnpm dev	Development server on http://localhost:3000.
pnpm build · pnpm start	Production build and server. NEXT_OUTPUT=standalone produces the standalone output the container uses.
pnpm ocr:warm	Download (and verify) the configured Tesseract model now, instead of during somebody's first scanned page.
pnpm cleanup	Run the expiry sweep once, directly against the database: mark expired, purge, prune global rules and rate-limit buckets. No server or secret needed, so it suits cron, systemd timers or Task Scheduler. Exits non-zero if a document could not be fully purged. It does not run the stalled-queue admission backstop; only the HTTP endpoint /api/cron/cleanup does that (see Deployment §3).

---

Database

Command	What it does
pnpm db:migrate	Create and apply a migration (development).
pnpm db:migrate:deploy	Apply existing migrations (CI, production, every upgrade that needs one). The container's migrate service runs this for you.
pnpm db:push	Push the schema straight to the database. Scratch work only.
pnpm db:generate	Regenerate the Prisma client (also run on postinstall).
pnpm workflow:bootstrap	Create the @workflow/world-postgres tables (the container's migrate service does this).

---

Quality

Command	What it does
pnpm lint	ESLint.
pnpm typecheck	next typegen && tsc --noEmit. The typegen step generates RouteContext / PageProps so a fresh clone type-checks without a build.
pnpm test	Unit, adversarial and security suites. The OCR suites run once the pinned model is cached (pnpm ocr:warm), and skip otherwise.
pnpm test:watch	Vitest in watch mode.
pnpm test:db	Postgres-backed integration suites. Needs TEST_DATABASE_URL pointing at a throwaway database.
pnpm format	Prettier over **/*.{ts,tsx}.

---

End-to-end and performance

Command	What it does
pnpm smoke [url]	Drives a running instance over HTTP: uploads a synthetic document of every supported format, waits, accepts every suggestion, exports, downloads, and opens the result the way an adversary would. Fails if an accepted value, or anything in the report, survives. Default URL http://127.0.0.1:3000.
pnpm smoke --only=eml,pptx	Only those cases.
pnpm smoke --ai	The model pass too, against an instance with a verified model: asserts that calls were made and accounted for, none failed, and every suggestion quotes the document.
pnpm smoke:storage [endpoint]	Upload, range-read, list, presign and delete through S3/RustFS.
pnpm smoke:blob	Asks a real Vercel Blob store for a range, and fails on anything but 206.
pnpm bench	Times extraction and export over deliberately large documents (20,000 CSV rows, a 4 MB text file, a 2,000-reply thread, a 200-slide deck) to catch quadratic curves.

---

Benchmarks and corpus

See Testing and Benchmarks for what each measures.

Command	What it does
pnpm corpus:generate	Generate the synthetic labelled PII corpus through the Claude Code or Codex CLI you are signed in to. --dry-run, --ids, --limit, --backend claude|codex|command, --model, --effort, --thinking, --concurrency, --attempts, --seed, --rebuild, --force, --deny. Seeded and resumable.
pnpm corpus:validate	A model from another family reviews the labels; disagreements are queued for a person.
pnpm corpus:check	Fail if a committed corpus file holds a value outside the reserved fictional ranges (runs in CI).
pnpm corpus:render	Render corpus documents to txt, eml, pdf, docx, csv or xlsx for inspection.
pnpm corpus:pack · corpus:unpack · corpus:status	Manage the committed synthetic-v1.tar.gz archive.
pnpm corpus:score	Precision, covered recall, weighted cost and agreement, with --detector patterns|pipeline, --split, --limit, --format, --rescore, --compare.
pnpm bench:models	Benchmark models (.env or BENCH_MODELS) through three phases: deterministic-first, model-only, throughput. Checkpointed and resumable; --limit, --phases, --sweep, --concurrency, --format, --replace, --fresh. Calls real APIs and costs money.
pnpm bench:charts	Draw light and dark charts from committed results into the READMEs. --check fails if they are stale.

---

Release helpers (maintainers)

scripts/release-labels.mjs (the label → version-bump table) and scripts/changelog.mjs (assembling changelog.d/) are run by .github/workflows/release.yml. Never edit CHANGELOG.md or the package.json version by hand. See Contributing.

---

See also

• Getting Started · Configuration · AI Providers · Testing and Benchmarks