CLI overview

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`	Browse logs, traces, and spans in a terminal UI

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`, `delete`	Manage experiments

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 self`	`update`	Self-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
`--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

Environment variables

Variable	Purpose
`BRAINTRUST_API_KEY`	API key (skips OAuth; use for CI)
`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_PYTHON_RUNNER`	Override Python runner binary
`BT_SYNC_WINDOW`	Default time window for `bt sync pull`
`BT_SYNC_VERBOSE`	Print BTQL queries and timing during sync
`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_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 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

bt not found after install

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

OAuth login fails

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 or BRAINTRUST_API_KEY (unless --prefer-profile is set)
--profile or BRAINTRUST_PROFILE
A saved profile whose org matches the active org
Auto-select if only one profile exists

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)

Self-update fails

bt self 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

SDKs

API

CLI

Other

Commands

Core

Projects and resources

Data and evaluation

Additional

Global flags

Environment variables

Troubleshooting

SDKs

API

CLI

Other

​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