Skip to main content
bt is the command-line interface for Braintrust. Use it to run evals, query logs, manage prompts, sync data, and configure coding agents — all from your terminal.
Beta - This feature is subject to change.

​
Install

curl -fsSL https://github.com/braintrustdata/bt/releases/latest/download/bt-installer.sh | sh
The binary installs to ~/.cargo/bin/bt. Source or open a new shell if bt is not found.
To test the latest features before release, use the canary channel: curl -fsSL https://github.com/braintrustdata/bt/releases/download/canary/bt-installer.sh | sh

​
Getting started

bt auth login      # Log in (opens browser for OAuth)
bt switch          # Pick an org and project
bt prompts list    # List your prompts
bt view logs       # Browse logs interactively

​
Available commands

CommandSubcommandsDescription
bt authlogin, refresh, profiles, logoutAuthenticate with Braintrust
bt switchSwitch org and project context
bt statusShow current org and project context
bt sqlRun SQL queries against Braintrust
bt viewlogs, trace, spanView logs, traces, and spans
bt evalRun eval files (Unix only)
bt experimentslist, view, deleteManage experiments
bt projectslist, create, view, deleteManage projects
bt functionslist, view, invoke, deleteManage and invoke functions
bt scorerslist, view, invoke, deleteManage and invoke scorers
bt toolslist, view, invoke, deleteManage and invoke tools
bt promptslist, view, deleteManage prompts
bt syncpull, push, statusSync project logs to/from local NDJSON files
bt initInitialize .bt/ config in current directory
bt setupskills, mcp, doctorConfigure coding agents and MCP
bt docsManage workflow docs for coding agents
bt selfupdateSelf-update the CLI binary

​
Global flags

FlagShortEnv varDescription
--jsonOutput as JSON
--profile <NAME>BRAINTRUST_PROFILEUse a saved login profile
--org <NAME>-oBRAINTRUST_ORG_NAMEOverride org
--project <NAME>-pBRAINTRUST_DEFAULT_PROJECTOverride project
--api-key <KEY>BRAINTRUST_API_KEYOverride API key
--prefer-profilePrefer profile even if API key env is set
--no-inputDisable interactive prompts
--api-url <URL>BRAINTRUST_API_URLOverride API URL
--app-url <URL>BRAINTRUST_APP_URLOverride app URL
--env-file <PATH>BRAINTRUST_ENV_FILELoad a .env file

​
Environment variables

For CI/CD environments, use the BRAINTRUST_API_KEY environment variable instead of OAuth login.
VariablePurpose
BRAINTRUST_API_KEYAPI key (skips OAuth; use for CI)
BRAINTRUST_PROFILEProfile selection
BRAINTRUST_ORG_NAMEOrg override
BRAINTRUST_DEFAULT_PROJECTProject override
BRAINTRUST_API_URLAPI endpoint (default: https://api.braintrust.dev)
BRAINTRUST_APP_URLApp endpoint (default: https://www.braintrust.dev)
BRAINTRUST_ENV_FILE.env file path
BT_EVAL_RUNNEREval runner binary
BT_EVAL_LANGUAGEForce eval language (js / py)
BT_EVAL_LOCALRun evals locally (same as --no-send-logs)
BT_EVAL_PYTHON_RUNNEROverride Python runner binary
NO_COLORDisable colored output
PAGERCustom pager (default: less -R)
GITHUB_TOKENGitHub API auth for bt self update in CI
bt automatically loads .env files from the current directory: .env → .env.{NODE_ENV} → .env.local → .env.{NODE_ENV}.local. Existing env vars are not overwritten.

​
Troubleshooting

Open a new shell. Ensure ~/.cargo/bin is in your PATH.
On SSH, bt auto-detects and prints the URL. Use --no-browser to force this. 5-minute callback timeout.
Run bt auth profiles --verbose to check. Specify with --profile or BRAINTRUST_PROFILE.
Run bt status --verbose to see where each value comes from.
Run bt auth refresh, or bt auth login to re-authenticate.
Only works for installer-managed installs. Use your package manager otherwise.