Development Commands and Scripts: Complete Reference

The Financial Analytics Agent’s development workflow revolves around a small set of pnpm scripts that cover everything from spinning up the local dev server and the eve agent, to migrating and seeding the Postgres database, to running type checks, unit tests, and the deterministic eval suite. All commands below are run from the repo root and require pnpm — the project uses a pnpm-lock.yaml and pnpm-workspace.yaml, so npm and yarn are not supported.

This project uses pnpm exclusively. Do not run npm install, yarn add, or any other package manager command — only pnpm install, pnpm add, and pnpm <script> are supported.

Development

Command	What it does
`pnpm dev`	Starts the Next.js development server at http://localhost:3000. The eve agent is mounted automatically via `withEve()` in `next.config.ts`, so this single command runs the full stack — web chat UI, Finance REST API, and the agent channel — together.
`pnpm dev:eve`	Runs `eve dev` directly (with the eve UI). Use this when you want to iterate on the agent using the built-in eve interface rather than the custom Next.js chat UI.
`pnpm exec eve dev --no-ui`	Starts eve in headless mode without launching a Next.js process. Use this to verify that the agent and its authored tools work correctly in isolation. Because `agent/lib/finance.ts` connects to Postgres directly (no HTTP boundary), the agent is fully functional with no Next.js server running.

The --no-ui flag is particularly useful when iterating on tool logic or instructions, since it skips the full Next.js build and starts the agent loop immediately.

Database

Command	What it does
`pnpm db:migrate`	Runs `tsx db/migrate.ts`, which applies `db/schema.sql` to the Postgres database pointed to by `DATABASE_URL` in `.env.local`. Run this once on a fresh database and again whenever the schema changes.
`pnpm db:seed`	Runs `tsx db/seed.ts`, which generates approximately three years of deterministic synthetic transaction and budget data using a fixed RNG seed. The seed is authored with real financial stories (seasonality, growth trends, anomalies) so that every chart type has something meaningful to display. Re-running produces identical data.

If you regenerate the seed data, run pnpm db:migrate first, then pnpm db:seed, and finally pnpm test to confirm the shared finance library still returns expected values.

Build and Production

Command	What it does
`pnpm build`	Runs the standard Next.js production build.
`pnpm build:eve`	Compiles the eve agent manifest.
`pnpm start`	Starts the Next.js production server after a completed `pnpm build`.
`pnpm start:eve`	Starts eve in production mode after a completed `pnpm build:eve`.

Quality Checks

Command	What it does
`pnpm typecheck`	Runs `tsc` with no emit to check the entire project for TypeScript errors. Run this before committing any changes — it catches type mismatches between finance function signatures, tool input schemas, and REST route handlers that tests may not cover.
`pnpm test`	Runs `vitest run` across the unit and DB-gated integration test suite. Integration tests (such as those in `agent/lib/finance.test.ts`) require `DATABASE_URL` to be set in `.env.local`. The vitest config excludes the `.eve/` snapshot directory to prevent duplicate test runs.
`pnpm eval`	Runs `eve eval` against every eval file in the `evals/` directory. The eval suite is deterministic — all assertions are made against tool inputs, tool outputs, and reply substrings, with no LLM-as-judge grading required.

Get Started

Core Features

Data Layer

Configuration & Deployment

Development

Development Commands and Scripts: Complete Reference

Development

Database

Build and Production

Quality Checks

​Development

​Database

​Build and Production

​Quality Checks

Development

Database

Build and Production

Quality Checks