Installation

The published npm package is @bitslix/blxbench (Bitslix org on npm). After a global install, the command on your PATH is blxbench.

The package installs a small Node launcher plus one platform-specific native binary through optional dependencies (@bitslix/blxbench-linux-x64, @bitslix/blxbench-darwin-arm64, @bitslix/blxbench-darwin-x64, or @bitslix/blxbench-win32-x64). The provider adapters and official tests are bundled into that binary.

Prerequisites

• Bun (v1.3.11+ recommended) — Default for bun install -g. Install via:

  curl -fsSL https://bun.sh/install | bash

• Node.js (v20+) — Used by the global installer’s small launcher when you use npm / pnpm; the app itself runs as a bundled native binary.
• Playwright Chromium — Required for render validation in UI/coding tests. Install it with blxbench --headless --install-chromium or /playwright install in the TUI.

Install blxbench

# Using bun (recommended)
bun install -g @bitslix/blxbench

# Or using pnpm/npm
pnpm add -g @bitslix/blxbench
npm install -g @bitslix/blxbench

# Or clone and build from source (monorepo)
git clone https://github.com/iptoux/blxbench.git
cd blxbench
pnpm install
pnpm --filter @bitslix/blxbench build

Environment Variables

Create a .env file in your project or working directory, or use the first-run setup in the TUI when OPENROUTER_API_KEY is missing: the CLI can save it to ~/.blxbench/config.json (env map) so you are not limited to a per-project file. Merge rules and fields like preferStoredEnv / BLXBENCH_PREFER_STORED_ENV are documented under Configuration — App config file.

Keys depend on which provider adapter you use:

# Example: OpenRouter (default provider alias `opr`)
OPENROUTER_API_KEY=sk-or-...

# Example: direct OpenAI adapter (`oai`)
# OPENAI_API_KEY=sk-...

# Example: Ollama (`oll`); optional locally
# OLLAMA_API_KEY=

# Optional: BLXBench API key for headless leaderboard uploads
BLXBENCH_API_KEY=your-api-key

Verify Installation

blxbench --version
# or: blxbench -V

The TUI footer also shows v<version> when you run blxbench interactively.

Where Local Data Goes

• Reports and ranking files are written to ~/.blxbench/reports/ on Linux/macOS and %USERPROFILE%\.blxbench\reports\ on Windows.
• Playwright browser binaries are stored in Playwright's cache (~/.cache/ms-playwright on Linux, ~/Library/Caches/ms-playwright on macOS, %LOCALAPPDATA%\ms-playwright on Windows).
• ~/.blxbench/config.json can hold env (including OPENROUTER_API_KEY), desktopNotify, and flags for .env precedence — see Configuration.
• Provider API keys stay in your environment, .env, or config.json → env; they are not sent to the web app except through provider APIs. BLXBENCH_API_KEY is only for BLXBench uploads and authenticated CLI requests.

Next Steps

• Quick Start Guide — Run your first benchmark
• Updating blxbench — Upgrade with npm, pnpm, or Bun; read about the in-app “newer on npm” notice
• blxbench Reference — Full command documentation