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.

Complete reference for the bt CLI. For installation and workflow examples, see the CLI quickstart.
Beta — This feature is subject to change.

​
Commands

​
Core

CommandSubcommandsDescription
bt initLink the current directory to a Braintrust org and project (creates .bt/config.json)
bt authlogin, refresh, profiles, logoutAuthenticate with Braintrust and manage saved credential profiles for working with multiple orgs
bt switchSet default org and project context
bt viewlogs, trace, spanBrowse logs, traces, and spans in a terminal UI

​
Projects and resources

CommandSubcommandsDescription
bt projectslist, create, view, deleteManage projects
bt promptslist, view, deleteManage prompts
bt functionslist, view, invoke, delete, push, pullManage functions (tools, scorers, and more)
bt toolslist, view, invoke, deleteManage tools (alias for bt functions --type tool)
bt scorerslist, view, invoke, deleteManage scorers (alias for bt functions --type scorer)
bt experimentslist, view, deleteManage experiments
bt topicsstatus, poke, rewind, open, configManage Topics automations and real-time message streams

​
Data and evaluation

CommandSubcommandsDescription
bt evalRun JavaScript/TypeScript and Python eval files (macOS and Linux only)
bt sqlRun SQL queries against Braintrust
bt syncpull, push, statusSync project logs, experiments, or datasets to/from local NDJSON files

​
Additional

CommandSubcommandsDescription
bt docsfetchDownload workflow docs for coding agents
bt selfupdateSelf-update the CLI binary
bt setupskills, instrument, mcp, doctorConfigure coding agents and MCP
bt statusShow current org, project, and auth source
bt utilxactLocal utilities (transaction ID conversion)

​
Global flags

These flags are accepted by every bt command.
FlagShortEnv varDescription
--jsonOutput as JSON
--quiet-qBRAINTRUST_QUIETSuppress non-essential output
--no-colorBRAINTRUST_NO_COLORDisable ANSI color output
--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 credentials even if BRAINTRUST_API_KEY 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
--ca-cert <PATH>BRAINTRUST_CA_CERTPath to a PEM-encoded CA bundle for HTTPS requests (takes precedence over SSL_CERT_FILE)

​
Environment variables

VariablePurpose
BRAINTRUST_API_KEYAPI key (skips OAuth; use for CI)
BRAINTRUST_CA_CERTPath to a PEM-encoded CA bundle (overrides SSL_CERT_FILE)
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
BRAINTRUST_QUIETSuppress non-essential output
BRAINTRUST_NO_COLORDisable colored output
BT_EVAL_RUNNEREval runner binary
BT_EVAL_LANGUAGEForce eval language (js or py)
BT_EVAL_LOCALRun evals without sending logs to Braintrust
BT_EVAL_WATCHRe-run evals on file change
BT_EVAL_PYTHON_RUNNEROverride Python runner binary
BT_SYNC_WINDOWDefault time window for bt sync pull
BT_SYNC_VERBOSEPrint BTQL queries and timing during sync
BT_FUNCTIONS_PUSH_FILESFile or directory path(s) to scan for bt functions push
BT_FUNCTIONS_PUSH_IF_EXISTSConflict behavior for bt functions push: error, replace, or ignore
BT_FUNCTIONS_PUSH_LANGUAGEForce language for bt functions push: auto, javascript, or python
BT_FUNCTIONS_PUSH_EXTERNAL_PACKAGESAdditional packages to exclude from JS bundling during push
BT_EVAL_PARAMS_JSONJSON object of parameter values passed to evaluators via --param
BT_FUNCTIONS_PUSH_RUNNEROverride runner binary for bt functions push
BT_FUNCTIONS_PUSH_TSCONFIGtsconfig path for the JS runner and bundler
BT_FUNCTIONS_PUSH_REQUIREMENTSPython requirements file for bt functions push
BT_FUNCTIONS_PUSH_CREATE_MISSING_PROJECTSCreate referenced projects when they do not exist (default: true)
BT_FUNCTIONS_PUSH_TERMINATE_ON_FAILUREStop after first failure during push (default: false)
BT_FUNCTIONS_PULL_SLUGFunction slug(s) to pull
BT_FUNCTIONS_PULL_IDFunction ID selector for bt functions pull
BT_FUNCTIONS_PULL_LANGUAGEOutput language for bt functions pull: typescript or python
BT_FUNCTIONS_PULL_OUTPUT_DIRDestination directory for bt functions pull (default: ./braintrust)
BT_FUNCTIONS_PULL_PROJECT_IDProject ID filter for bt functions pull
BT_FUNCTIONS_PULL_VERSIONVersion selector for bt functions pull
BT_FUNCTIONS_PULL_FORCEOverwrite local files during pull (default: false)
NO_COLORDisable colored output (standard convention)
PAGERCustom pager (default: less -R)
GITHUB_TOKENGitHub API auth for bt self update in CI
As of v0.6.0, bt no longer automatically loads .env files. Set environment variables explicitly in your shell (e.g., via export, --env-file <PATH>, or a tool like direnv) before running bt commands.

​
Troubleshooting

Open a new shell. Ensure ~/.local/bin (or $XDG_BIN_HOME if set) is in your PATH.
On SSH, bt auto-detects and prints the auth URL instead of opening a browser. Use --no-browser to force this behavior. The OAuth callback times out after 5 minutes. On remote hosts, paste the final callback URL from your local browser if the localhost callback can’t be delivered.
Run bt auth profiles --verbose to list saved profiles. Specify one with --profile or BRAINTRUST_PROFILE.
Run bt status --verbose to see where each value comes from (flag, env var, local config, or global config).
When multiple credential sources are present, bt resolves them in this order:
  1. --api-key <KEY> flag (always wins)
  2. BRAINTRUST_API_KEY env var (wins unless --profile CLI flag or --prefer-profile is also set)
  3. --profile <NAME> or BRAINTRUST_PROFILE
  4. A saved profile whose org matches the active org
  5. Auto-select if only one profile is saved
Run bt auth refresh to force-refresh your OAuth token, or bt auth login to re-authenticate.
bt stores credentials in your system’s secure credential store:
  • macOS: system keychain (via security)
  • Linux: libsecret / secret-tool if available; otherwise a 0600-permission plaintext file
  • Windows: 0600-permission file (keychain integration not yet implemented)
bt self update only works for installs made via the official installer. If you installed another way, update through your package manager.
macOS and Linux:
rm -f "${XDG_BIN_HOME:-${XDG_DATA_HOME:-$HOME/.local}/bin}/bt"
rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/bt"
Windows (PowerShell):
$cargoHome = if ($env:CARGO_HOME) { $env:CARGO_HOME } else { Join-Path $HOME ".cargo" }
Remove-Item -Force (Join-Path $cargoHome "bin\bt.exe") -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force (Join-Path $env:APPDATA "bt") -ErrorAction SilentlyContinue