Skip to main content

Installation

Prerequisites​

  • Node.js 20 or higher
  • pnpm (recommended) or npm

Install from npm​

# Install the CLI globally
npm install -g @evalstudio/cli

# Or use npx
npx @evalstudio/cli status

Install for Development​

Clone the repository and install dependencies:

git clone https://github.com/Treatwell-AI/evalstudio.git
cd evalstudio
pnpm install
pnpm build

Configuration​

Workspace & Projects​

EvalStudio uses a workspace model: a directory containing evalstudio.config.json with a project registry. Projects are stored under projects/{uuid}/data/.

EvalStudio resolves the workspace by walking up from cwd looking for evalstudio.config.json. You can override with the EVALSTUDIO_PROJECT_DIR environment variable.

To create a new workspace:

evalstudio init my-evals
cd my-evals

To override with an environment variable:

export EVALSTUDIO_PROJECT_DIR=/path/to/workspace
evalstudio status

PostgreSQL Storage (Optional)​

By default, EvalStudio stores data as JSON files on disk. For team environments or production use, you can use PostgreSQL instead.

# Install the PostgreSQL storage package
npm install @evalstudio/postgres

Add storage configuration to your evalstudio.config.json:

{
  "storage": {
    "type": "postgres",
    "connectionString": "postgresql://user:pass@localhost:5432/evalstudio"
  }
}

Then initialize the database schema:

evalstudio db init

See the Projects documentation for details on connection string resolution and environment variable support.

Verify Installation​

Check that everything is working:

evalstudio status

You should see output like:

EvalStudio Status
-----------------
Name:      evalstudio
Version:   0.0.1
Status:    ok
Node:      v20.x.x
Timestamp: 2026-01-26T12:00:00.000Z