Skip to main content
bt is the command-line interface for Braintrust. It lets you run evals, 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: 
curl -fsSL https://bt.dev/cli/install.sh | sh
The installer downloads a pre-built binary to ~/.local/bin/bt (or $XDG_BIN_HOME/bt if set). Open a new shell if bt is not found after install. After installing, the installer prompts you to run bt setup. This writes Braintrust skill files and MCP config for your coding agent. You can run it now or skip it and come back later — see Set up coding agents below. To install a specific version: 
curl -fsSL https://bt.dev/cli/install.sh | sh -s -- --version 0.2.0
To install the canary (pre-release) channel: 
curl -fsSL https://bt.dev/cli/install.sh | sh -s -- --canary

​
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
Create an API key under Settings > API keys in the Braintrust app. 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 and project — so you don’t need to specify them on every command. You can always override with -o/-p flags 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

​
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
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.

​
Set up coding agents

bt setup writes Braintrust skill files, MCP server config, and workflow docs into your agent’s config directory — giving your coding agent (Claude, Cursor, Codex, Opencode) the context it needs to work with Braintrust: 
bt setup                           # Interactive wizard
bt setup --local --agent claude    # Write Braintrust skills and MCP config for Claude into this repo
bt setup --global --agent codex    # Configure Codex user-wide
To automatically instrument your repo with Braintrust tracing, use bt setup instrument. It 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 instrument --agent codex
bt setup instrument --agent claude --language typescript
See bt setup for supported languages and all subcommands.

​
Manage functions

bt functions push uploads local TypeScript or Python function definitions (tools, scorers, 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