CLI quickstart - Braintrust

bt is the command-line interface for Braintrust. It lets you run evals, instrument your code, browse and query logs, sync data, manage functions, and configure coding agents without leaving your terminal.

Beta — This feature is subject to change.

Install

To install the latest version of bt:

curl -fsSL https://bt.dev/cli/install.sh | bash

powershell -ExecutionPolicy Bypass -c "irm https://github.com/braintrustdata/bt/releases/latest/download/bt-installer.ps1 | iex"

To install a specific version:

curl -fsSL https://bt.dev/cli/install.sh | bash -s -- --version 0.2.0

$env:BT_VERSION='0.2.0'; powershell -ExecutionPolicy Bypass -c "irm https://github.com/braintrustdata/bt/releases/latest/download/bt-installer.ps1 | iex"

To install the canary (pre-release) channel:

curl -fsSL https://bt.dev/cli/install.sh | bash -s -- --canary

$env:BT_CHANNEL='canary'; powershell -ExecutionPolicy Bypass -c "irm https://github.com/braintrustdata/bt/releases/latest/download/bt-installer.ps1 | iex"

The installer downloads a pre-built binary to ~/.local/bin/bt (or $XDG_BIN_HOME/bt if set). After installing, the installer suggests running bt setup to connect your project to Braintrust. You can do this now or come back later.

Install with npm

If you already use the Braintrust JavaScript SDK, bt is available as an optional dependency of the braintrust npm package (braintrust v3.17.0 or later). After installing braintrust, run bt through your package manager:

pnpm exec bt --version

npx bt --version

To run bt once without adding it to a project, use npx -p braintrust bt.

Use the standalone installer above if you want to update bt independently of the SDK, or if you need the canary channel, which isn’t published to npm. The npm package always matches your installed braintrust version.

Platform-specific binaries are delivered through optional dependencies, with a postinstall download as a fallback when optional dependencies are skipped, such as with --omit=optional or in airgapped installs. Two environment variables control binary resolution:

BT_BINARY_PATH: Path to a bt binary to use instead of the resolved one.
BT_SKIP_DOWNLOAD: Set to 1 to skip the postinstall fallback download.

Set up coding agents

bt setup handles authentication and API key creation for your project. Optionally, it installs Braintrust skill files, workflow docs, and MCP server config into your coding agent’s config directory (Claude, Copilot, Cursor, Codex, Gemini, Opencode, Qwen). It also detects your project language, installs the exact SDK version, instruments your LLM clients, verifies the app still runs, and outputs a Braintrust permalink to the captured trace:

bt setup                           # Interactive wizard with the minimal amount of questions
bt setup -i                        # Interactive wizard with all the options

# Directly starts codex to instrument the code since all questions are answered
bt setup --project 'project-name' --api-key BRAINTRUST_API_KEY --agent codex

If bt setup creates a new API key, it prints an export BRAINTRUST_API_KEY=<key> command. Run it to make the key available in your current terminal session. See bt setup for supported languages and all subcommands.

Authenticate and set context

bt supports two authentication methods:

bt auth login                        # OAuth: opens a browser login flow, saves credentials to your keychain
export BRAINTRUST_API_KEY=<your-key> # API key: good for CI, scripts, or if you prefer not to use OAuth

To use an API key, create one under Settings > API keys in the Braintrust app. If you haven’t set up the CLI yet, bt setup creates an API key for you interactively. See Set up coding agents below. After authenticating, set a default org and project:

bt switch    # Pick a default org and project
bt status    # Confirm what's active

bt saves a context (a default org) so you don’t need to specify it on every command. The project must be set on each command with -p. You can always override the org with -o or environment variables.

Run evals locally

Run your evaluation files directly without npx or SDK runner setup:

bt eval                        # Discover and run all eval files in the current directory
bt eval tests/                 # Run eval files under a specific directory
bt eval --watch                # Re-run on file changes during development
bt eval --filter my-evaluator  # Run a specific evaluator by name

bt eval auto-detects your JavaScript runner (tsx, vite-node, ts-node) and supports Python eval files too. For other languages, run your eval file directly with your language’s toolchain. See bt eval for the full list of flags.

Run evals in CI

For CI pipelines, set BRAINTRUST_API_KEY instead of using OAuth login. See Run in CI/CD for the full workflow.

# GitHub Actions example
- name: Run evals
  env:
    BRAINTRUST_API_KEY: ${{ secrets.BRAINTRUST_API_KEY }}
  run: bt eval tests/

Create an API key in the Braintrust app under Settings > API keys. Use --no-input and --json for non-interactive output:

BRAINTRUST_API_KEY=... bt eval tests/ --no-input --json

Use --first N or --sample N to run a subset of your data as a non-final smoke run on pull requests, then run the full suite on merge:

bt eval --first 20 tests/ --no-input --json   # smoke run on PR, non-final
bt eval tests/ --no-input --json              # full run on merge, final

Browse and query logs

bt view logs opens an interactive terminal UI for browsing your project’s logs, useful for checking on production traffic or debugging during an incident:

bt view logs                                    # Browse logs for the active project
bt view logs --search "error"                   # Search by keyword
bt view logs --filter "metrics.duration > 5.0"  # Filter by expression
bt view logs --url <braintrust-url>             # Open a Braintrust URL in the terminal

For programmatic access, bt sql runs SQL queries against your logs from the terminal or in scripts:

bt sql "SELECT * FROM project_logs('my-project') WHERE scores.Factuality < 0.5 LIMIT 50"
BRAINTRUST_API_KEY=... bt sql "SELECT count(*) FROM project_logs('my-project')" --json

Most SQL data-source functions also accept an object name in place of its ID. See Querying by name.

See bt view and bt sql for details.

Sync data

bt sync downloads Braintrust data to local NDJSON files for offline analysis, backup, or migration:

bt sync pull project_logs:my-project --window 24h   # Pull the last 24 hours of logs
bt sync pull experiment:my-experiment               # Pull a specific experiment
bt sync push project_logs:my-project                # Push local data back to Braintrust

See bt sync for the full flag reference.

Manage functions

bt functions push uploads local TypeScript or Python function definitions (tools, scorers, and LLM functions) to Braintrust. bt functions pull downloads them back to local files.

bt functions push my_tools.ts              # Upload a TypeScript function file
bt functions push src/scorers.py           # Upload a Python function file
bt functions pull --slug my-scorer         # Download a function by slug

See bt functions for bundling behavior, language options, and all flags.

Next steps

Read the CLI overview for the complete command list, global flags, and environment variables
See bt functions for uploading and downloading function definitions
See Filter and search logs for SQL query examples against your logs
See Run evaluations for eval workflow details

​Install

​Install with npm

​Set up coding agents

​Authenticate and set context

​Run evals locally

​Run evals in CI

​Browse and query logs

​Sync data

​Manage functions

​Next steps

Install

Install with npm

Set up coding agents

Authenticate and set context

Run evals locally

Run evals in CI

Browse and query logs

Sync data

Manage functions

Next steps