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. Keys depend on which provider adapter you use (see Configuration):

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

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

# 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).
• Provider API keys stay in your environment or .env; they are not needed by the web app. BLXBENCH_API_KEY is only for uploading reports to BLXBench.

Next Steps

• Quick Start Guide — Run your first benchmark
• blxbench Reference — Full command documentation