Skip to main content

Documentation Index

Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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: 
curl -fsSL https://bt.dev/cli/install.sh | bash
The installer downloads a pre-built binary to ~/.local/bin/bt (or $XDG_BIN_HOME/bt if set). After installing, the installer prompts you to run bt setup. This handles authentication and API key creation. 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 | bash -s -- --version 0.2.0
To install the canary (pre-release) channel: 
curl -fsSL https://bt.dev/cli/install.sh | bash -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
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
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 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.

​
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