CLI overview - Braintrust

Complete reference for the bt CLI. For installation and workflow examples, see the CLI quickstart.

Beta — This feature is subject to change.

Commands

Core

Command	Subcommands	Description
`bt init`		Link the current directory to a Braintrust org and project (creates `.bt/config.json`)
`bt auth`	`login`, `refresh`, `profiles`, `logout`	Authenticate with Braintrust and manage saved credential profiles for working with multiple orgs
`bt switch`		Set default org and project context
`bt view`	`logs`, `trace`, `span`, `thread`, `waterfall`	Browse logs, traces, and spans in a terminal UI, or render a trace transcript or waterfall

Projects and resources

Command	Subcommands	Description
`bt projects`	`list`, `create`, `view`, `delete`	Manage projects
`bt prompts`	`list`, `view`, `delete`	Manage prompts
`bt functions`	`list`, `view`, `invoke`, `delete`, `push`, `pull`	Manage functions (tools, scorers, and more)
`bt tools`	`list`, `view`, `invoke`, `delete`	Manage tools (alias for `bt functions --type tool`)
`bt scorers`	`list`, `view`, `invoke`, `delete`	Manage scorers (alias for `bt functions --type scorer`)
`bt experiments`	`list`, `view`, `compare`, `delete`	Manage experiments
`bt datasets`	`list`, `create`, `view`, `update`, `delete`, `pipeline`, `snapshots`	Manage datasets
`bt topics`	`status`, `poke`, `rewind`, `open`, `config`, `report`, `btmap`	Manage Topics automations and real-time message streams

Data and evaluation

Command	Subcommands	Description
`bt eval`		Run JavaScript/TypeScript and Python eval files (macOS and Linux only)
`bt sql`		Run SQL queries against Braintrust
`bt sync`	`pull`, `push`, `status`	Sync project logs, experiments, or datasets to/from local NDJSON files

Additional

Command	Subcommands	Description
`bt docs`	`fetch`	Download workflow docs for coding agents
`bt update`		Update the CLI binary
`bt setup`	`skills`, `instrument`, `mcp`, `doctor`	Configure coding agents and MCP
`bt status`		Show current org, project, and auth source
`bt util`	`xact`	Local utilities (transaction ID conversion)

Global flags

These flags are accepted by every bt command.

Flag	Short	Env var	Description
`--json`			Output as JSON
`--verbose`	`-v`	`BRAINTRUST_VERBOSE`	Increase output verbosity
`--quiet`	`-q`	`BRAINTRUST_QUIET`	Suppress non-essential output
`--no-color`		`BRAINTRUST_NO_COLOR`	Disable ANSI color output
`--profile <NAME>`		`BRAINTRUST_PROFILE`	Use a saved login profile
`--org <NAME>`	`-o`	`BRAINTRUST_ORG_NAME`	Override org
`--project <NAME>`	`-p`	`BRAINTRUST_DEFAULT_PROJECT`	Override project
`--api-key <KEY>`		`BRAINTRUST_API_KEY`	Override API key
`--prefer-profile`			Prefer profile credentials even if `BRAINTRUST_API_KEY` is set
`--no-input`			Disable interactive prompts
`--api-url <URL>`		`BRAINTRUST_API_URL`	Override API URL
`--app-url <URL>`		`BRAINTRUST_APP_URL`	Override app URL
`--env-file <PATH>`		`BRAINTRUST_ENV_FILE`	Load a `.env` file
`--ca-cert <PATH>`		`BRAINTRUST_CA_CERT`	Path to a PEM-encoded CA bundle for HTTPS requests (takes precedence over `SSL_CERT_FILE`)

Environment variables

Variable	Purpose
`BRAINTRUST_API_KEY`	API key (skips OAuth; use for CI)
`BRAINTRUST_CA_CERT`	Path to a PEM-encoded CA bundle (overrides `SSL_CERT_FILE`)
`BRAINTRUST_PROFILE`	Profile selection
`BRAINTRUST_ORG_NAME`	Org override
`BRAINTRUST_DEFAULT_PROJECT`	Project override
`BRAINTRUST_API_URL`	API endpoint (default: `https://api.braintrust.dev`)
`BRAINTRUST_APP_URL`	App endpoint (default: `https://www.braintrust.dev`)
`BRAINTRUST_ENV_FILE`	`.env` file path
`BRAINTRUST_QUIET`	Suppress non-essential output
`BRAINTRUST_NO_COLOR`	Disable colored output
`BT_EVAL_RUNNER`	Eval runner binary
`BT_EVAL_LANGUAGE`	Force eval language (`js` or `py`)
`BT_EVAL_LOCAL`	Run evals without sending logs to Braintrust
`BT_EVAL_WATCH`	Re-run evals on file change
`BT_EVAL_NUM_WORKERS`	Worker threads for Python eval execution
`BT_EVAL_PYTHON_RUNNER`	Override Python runner binary
`BT_EVAL_DEV`	Start the eval dev server
`BT_EVAL_DEV_HOST`	Host interface for the eval dev server (default: `localhost`)
`BT_EVAL_DEV_PORT`	Port for the eval dev server (default: `8300`)
`BT_EVAL_DEV_ORG_NAME`	Restrict eval dev server to a specific org
`BT_EVAL_DEV_ALLOWED_ORIGIN`	Additional allowed CORS origin(s) for the eval dev server (comma-separated)
`BT_SYNC_WINDOW`	Default time window for `bt sync pull`
`BT_SYNC_PUSH_MAX_BATCH_BYTES`	Maximum input bytes per upload batch for `bt sync push`
`BT_SYNC_PUSH_MAX_IN_FLIGHT_BYTES`	Maximum in-flight input bytes for `bt sync push`
`BT_FUNCTIONS_PUSH_FILES`	File or directory path(s) to scan for `bt functions push`
`BT_FUNCTIONS_PUSH_IF_EXISTS`	Conflict behavior for `bt functions push`: `error`, `replace`, or `ignore`
`BT_FUNCTIONS_PUSH_LANGUAGE`	Force language for `bt functions push`: `auto`, `javascript`, or `python`
`BT_FUNCTIONS_PUSH_EXTERNAL_PACKAGES`	Additional packages to exclude from JS bundling during push
`BT_EVAL_PARAMS_JSON`	JSON object of parameter values passed to evaluators via `--param`
`BT_FUNCTIONS_PUSH_RUNNER`	Override runner binary for `bt functions push`
`BT_FUNCTIONS_PUSH_TSCONFIG`	tsconfig path for the JS runner and bundler
`BT_FUNCTIONS_PUSH_REQUIREMENTS`	Python requirements file for `bt functions push`
`BT_FUNCTIONS_PUSH_CREATE_MISSING_PROJECTS`	Create referenced projects when they do not exist (default: `true`)
`BT_FUNCTIONS_PUSH_TERMINATE_ON_FAILURE`	Stop after first failure during push (default: `false`)
`BT_FUNCTIONS_PULL_SLUG`	Function slug(s) to pull
`BT_FUNCTIONS_PULL_ID`	Function ID selector for `bt functions pull`
`BT_FUNCTIONS_PULL_LANGUAGE`	Output language for `bt functions pull`: `typescript` or `python`
`BT_FUNCTIONS_PULL_OUTPUT_DIR`	Destination directory for `bt functions pull` (default: `./braintrust`)
`BT_FUNCTIONS_PULL_PROJECT_ID`	Project ID filter for `bt functions pull`
`BT_FUNCTIONS_PULL_VERSION`	Version selector for `bt functions pull`
`BT_FUNCTIONS_PULL_FORCE`	Overwrite local files during pull (default: `false`)
`NO_COLOR`	Disable colored output (standard convention)
`PAGER`	Custom pager (default: `less -R`)
`GITHUB_TOKEN`	GitHub API auth for `bt 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

bt not found after install

Open a new shell. Ensure ~/.local/bin (or $XDG_BIN_HOME if set) is in your PATH.

No profile found

Run bt auth profiles --verbose to list saved profiles. Specify one with --profile or BRAINTRUST_PROFILE.

Wrong org or project

Run bt status --verbose to see where each value comes from (flag, env var, local config, or global config).

Auth precedence

When multiple credential sources are present, bt resolves them in this order:

--api-key <KEY> flag (always wins)
BRAINTRUST_API_KEY env var (wins unless --profile CLI flag or --prefer-profile is also set)
--profile <NAME> or BRAINTRUST_PROFILE
A saved profile whose org matches the active org
Auto-select if only one profile is saved
Interactive picker if multiple profiles remain and bt is running in an interactive terminal

The interactive picker only runs in interactive terminals. In CI or other non-interactive environments with multiple saved profiles, set BRAINTRUST_PROFILE or pass --profile to avoid an ambiguous-profile error.

Token expired

Run bt auth refresh to force-refresh your OAuth token, or bt auth login to re-authenticate.

Where are credentials stored?

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)

Update fails

bt update only works for installs made via the official installer. If you installed another way, update through your package manager.

Uninstall

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

​Commands

​Core

​Projects and resources

​Data and evaluation

​Additional

​Global flags

​Environment variables

​Troubleshooting

Commands

Core

Projects and resources

Data and evaluation

Additional

Global flags

Environment variables

Troubleshooting