CLI quickstart - Braintrust

bt is the command-line interface for Braintrust. It lets you authenticate, trace coding-agent sessions, run evals, browse and query logs, sync data, and manage functions without leaving your terminal.

MCP or CLI?

Which one you want depends on what your tool can access and where the work needs to run.

MCP: Best when your AI tool can connect to Braintrust but has no authenticated shell, which is common in chat applications. It also fits when you want an assistant to reason over your Braintrust data and take several connected actions in one conversation, without installing and maintaining a CLI in its execution environment.
bt CLI: Best for repeatable work in scripts, CI, local files, and shell pipelines, where you want deterministic commands instead of an assistant’s judgment. Coding agents with shell access can call those commands too.

If your tool supports both, either one works. Pick whichever is more reliable for the task at hand.

Install

Already have bt installed? Follow Migrate bt to update it and complete any required version-specific migration steps.

Choose an installation method:

Standalone
npm
pnpm
mise

Install the latest version of bt:

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

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

Install the Braintrust JavaScript SDK, which includes bt, then verify the installed version:

npm install braintrust@latest
npx bt --version

The braintrust package pins a specific version of bt, which can lag behind standalone releases. Install bt with the standalone installer to manage its version independently.

Install the Braintrust JavaScript SDK, which includes bt, then verify the installed version:

pnpm add braintrust@latest
pnpm exec bt --version

The braintrust package pins a specific version of bt, which can lag behind standalone releases. Install bt with the standalone installer to manage its version independently.

Install and activate the latest stable version of bt with mise:

mise use --global "github:braintrustdata/bt@latest"
bt --version

Authenticate and set context

Choose how to authenticate

bt supports three authentication methods:

Environment API key
Saved OAuth profile
Saved API key profile

BRAINTRUST_API_KEY supplies an API key directly for the current shell session. bt does not save it in a profile, and it overrides any saved profile.Set the environment variable:

export BRAINTRUST_API_KEY="your-api-key"

To create an API key, go to Settings > API keys.

A saved OAuth profile stores reusable credentials from browser-based Braintrust authentication.Authenticate and name the profile:

bt login --oauth --profile <your-profile>

A saved API key profile stores an API key for repeated use, so you do not need to set it in each shell session.Run the interactive login and select API key to save the key in a profile. If BRAINTRUST_API_KEY is set, bt asks whether to save that key instead:

bt login --profile <your-profile>

To create an API key, go to Settings > API keys.

Select an organization and project

Next, select the active profile, organization, and project that bt should use by default:

bt switch

bt switch handles authentication in two ways:

Environment API key: If BRAINTRUST_API_KEY is set, bt switch authenticates with it instead of selecting a saved profile.
Saved profile: If BRAINTRUST_API_KEY is not set, bt switch prompts you to select a saved profile (when there are multiple to choose from), then authenticates with that profile.

It then retrieves the organizations and projects available to those credentials and lets you select from them.

Override organization and project context

You can override the saved context at two scopes:

Single command: Pass --org (-o) or --project (-p). Command-line flags override both environment variables and saved context.
Current environment: Set BRAINTRUST_ORG_NAME or BRAINTRUST_DEFAULT_PROJECT. These variables override saved context for commands run in that environment.

With bt switch, the organization and project overrides are also saved as the new active context (but not BRAINTRUST_API_KEY).

Verify authentication and context

Inspect the completed setup:

bt status --all

Use the output to confirm:

Saved profiles: Each profile you intend to use authenticates successfully.
Active context: The selected profile, organization, and project are correct.

bt status --all reports when BRAINTRUST_API_KEY overrides saved profiles, but it does not validate the key. If you use this variable, a successful bt switch in the previous step confirms that the key can authenticate.

For details about how bt chooses between environment API keys and saved profiles, see Credential precedence.

Trace coding-agent sessions

bt trace enable installs a tracing plugin for your coding agent to trace future sessions to Braintrust, including turns, model calls, and tool use. Use bt v0.19.3 or later for Grok tracing and the v2 OpenCode and pi integrations. Run the command for your agent:

bt trace enable claude --project my-project       # Claude Code
bt trace enable codex --project my-project        # Codex
bt trace enable antigravity --project my-project  # Google Antigravity
bt trace enable grok --project my-project         # Grok
bt trace enable opencode --project my-project     # OpenCode
bt trace enable pi --project my-project           # pi

Follow your agent’s guide to restart the agent or activate its tracing hooks, then run a short session and confirm that its trace appears on the Logs page. See the guides for Claude Code, Codex, Google Antigravity, Grok, OpenCode, and pi.

Instrument your project

In your project directory, run the agent-assisted setup wizard:

curl -fsSL https://braintrust.dev/wizard/setup.sh | sh

The wizard handles authentication, SDK installation, and LLM client instrumentation in one step. You can run it whether or not bt is already installed or authenticated.

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 my-evaluator.eval.ts   # Run a specific eval file

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 --jsonl for non-interactive output:

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

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 --jsonl  # smoke run on PR, non-final
bt eval tests/ --no-input --jsonl             # 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. By default, FROM logs queries the active project in bt’s local or global context. The --project flag or BRAINTRUST_DEFAULT_PROJECT selects a different project for the command. In scripts without saved context, pass --project explicitly:

bt sql "SELECT * FROM logs WHERE created > now() - interval 1 day AND scores.Factuality < 0.5 LIMIT 50"
BRAINTRUST_API_KEY=... bt sql --project my-project "SELECT count(*) FROM logs WHERE created > now() - interval 1 day" --json

See bt view and bt sql for details.

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

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 Filter and search logs for SQL query examples against your logs
See Run evaluations for eval workflow details

​Install

​Authenticate and set context

​Trace coding-agent sessions

​Instrument your project

​Run evals locally

​Run evals in CI

​Browse and query logs

​Sync data

​Manage functions

​Next steps

Install

Authenticate and set context

Trace coding-agent sessions

Instrument your project

Run evals locally

Run evals in CI

Browse and query logs

Sync data

Manage functions

Next steps