CLI overview - Braintrust

bt is Braintrust’s command-line interface for working from the terminal. Use it to authenticate, select projects, manage Braintrust resources, run evaluations, query logs, and configure coding-agent tracing. Commands support both interactive use and automated workflows in scripts or CI.

To get started with the bt CLI, follow the CLI quickstart. If you’re moving from a version with bt auth commands, follow Migrate bt.

Authentication and profiles

bt can authenticate in three ways:

Environment API key: BRAINTRUST_API_KEY supplies an API key directly from the environment.
Saved OAuth profile: A reusable login created through browser-based Braintrust authentication.
Saved API key profile: An API key stored by bt for repeated use.

The CLI quickstart walks through configuring each authentication method and selecting an active organization and project. A profile is a saved login containing credentials and connection details for one Braintrust app URL. You can use one profile with every organization its credentials can access. Most people need only one profile. Add another when you sign in with different credentials or connect to a different Braintrust app URL. Run bt login to save a profile, bt profiles to list, rename, or delete profiles, and bt status --all to verify saved credentials. bt switch selects the active organization and project. When it authenticates with a saved profile, it also makes that profile active. Later commands use this context by default. Run bt status to see what’s active, or override the organization or project for one command with --org or --project. bt stores profile metadata locally and credentials in your system’s secure credential store when available. If secure storage is unavailable, it uses a local credentials file.

Credential precedence

When more than one credential source is present, bt makes two decisions in turn. First, whether to use an API key or a saved profile:

Passing --profile or --prefer-profile on the command line makes bt use a saved profile and ignore BRAINTRUST_API_KEY.
Otherwise, BRAINTRUST_API_KEY from the environment wins.
Otherwise, bt uses a saved profile, selected by the rules below.

Then, when using a saved profile, which one:

The --profile NAME flag.
The BRAINTRUST_PROFILE environment variable.
The profile saved by bt switch, if it matches the requested app URL.
The only compatible profile for the app URL and organization, if exactly one is saved.
An interactive picker, if several profiles are compatible and bt is running in an interactive terminal. In CI or other non-interactive environments, set BRAINTRUST_PROFILE or pass --profile to avoid an ambiguous-profile error.

Run bt status to see the active organization, project, and selected profile. Run bt status --all to verify saved profiles and report missing, expired, or invalid credentials.

Having a saved login is not the same as selecting one. Only the --profile or --prefer-profile flag suppresses BRAINTRUST_API_KEY. Setting BRAINTRUST_PROFILE does not, so an API key in the environment still wins over it.

Commands

Command	Subcommands	Description
`bt datasets`	`list`, `create`, `view`, `update`, `delete`, `pipeline`, `snapshots`	Manage datasets
`bt docs`	`fetch`	Download Braintrust documentation for coding agents
`bt environments`	`list`, `view`, `create`, `update`, `delete`	Manage deployment environments
`bt eval`		Run JavaScript/TypeScript and Python eval files (macOS and Linux only)
`bt experiments`	`list`, `view`, `compare`, `delete`	Manage experiments
`bt functions`	`list`, `view`, `invoke`, `delete`, `push`, `pull`	Manage functions (tools, scorers, and more)
`bt init`		Link the current directory to a Braintrust org and project (creates `.bt/config.json`)
`bt login`		Log in to Braintrust, or refresh an OAuth login with `--refresh`
`bt logout`		Remove a saved Braintrust login and its local credentials
`bt observability`	`template pull`, `template push`	Export and apply portable JSON configuration for facets and Loop automations
`bt profiles`	`list`, `doctor`, `repair`, `delete`, `rename`	Manage saved Braintrust login profiles and diagnose orphaned credentials
`bt projects`	`list`, `create`, `view`, `delete`	Manage projects
`bt prompts`	`list`, `view`, `versions`, `assign`, `unassign`, `delete`	Manage prompts
`bt scorers`	`list`, `create`, `view`, `invoke`, `delete`	Manage scorers and classifiers
`bt setup`	`skills`, `instrument`, `mcp`, `doctor`	Configure Braintrust setup flows. Deprecated; use the standalone setup wizard
`bt sql`		Run SQL queries against Braintrust
`bt status`		Show current identity, org, and project context
`bt switch`		Switch org and project context
`bt sync`	`pull`, `push`, `status`	Sync project logs, experiments, or datasets to/from local NDJSON files
`bt tools`	`list`, `view`, `invoke`, `delete`	Manage tools (alias for `bt functions --type tool`)
`bt topics`	`status`, `poke`, `rewind`, `open`, `config`, `report`, `btmap`	Inspect and control Topics automation
`bt trace`	`enable`, `disable`, `run`, `import`, `doctor`, `update`	Manage coding-agent tracing
`bt update`		Update the CLI binary
`bt view`	`logs`, `trace`, `span`, `thread`, `waterfall`	Browse logs, traces, and spans in a terminal UI, or render a trace transcript or waterfall

Global flags

Most bt commands accept these global flags. Commands that only manage login state, such as bt login, accept the credential-related flags but not organization or project selection flags.

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
`--prefer-profile`			Prefer profile credentials even if `BRAINTRUST_API_KEY` is set
`--no-input`		`BRAINTRUST_NO_INPUT`	Disable interactive prompts
`--api-url <URL>`		`BRAINTRUST_API_URL`	Override API URL
`--app-url <URL>`		`BRAINTRUST_APP_URL`	Override app URL
`--app-public-url <URL>`		`BRAINTRUST_APP_PUBLIC_URL`	Override the public app URL used for browser links
`--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`)

After argument parsing, errors from commands run with --json use an error.message field. If the server returns structured details, they appear under error.details. By default, bt uses the authentication app URL for browser links, such as when opening a project. If your deployment uses a different address to access Braintrust in a browser, set --app-public-url so those links point to that address. This option requires bt v0.19.3 or later and does not change authentication or API requests.

Environment variables

These variables configure common CLI behavior and selected commands. Run bt <command> --help for that command’s complete flag and environment-variable mappings.

Variable	Purpose
`BRAINTRUST_ADDITIONAL_METADATA`	JSON object merged into root-span metadata by supported `bt trace` commands
`BRAINTRUST_TAGS`	Comma-separated session tags for supported `bt trace enable`, `bt trace run`, and `bt trace import` commands
`BRAINTRUST_API_KEY`	Use API key credentials instead of a saved profile, unless profile credentials are explicitly preferred
`BRAINTRUST_CA_CERT`	Path to a PEM-encoded CA bundle (overrides `SSL_CERT_FILE`)
`BRAINTRUST_CUSTOM_CA_BUNDLE`	Additional trusted CA certificates for SDK-backed tracing and data uploads. Supply PEM contents, not a file path. Requires `bt` v0.19.3 or later
`BRAINTRUST_PROFILE`	Profile selection
`BRAINTRUST_ORG_NAME`	Org override
`BRAINTRUST_DEFAULT_PROJECT`	Project override
`BRAINTRUST_API_URL`	API endpoint override
`BRAINTRUST_APP_URL`	App endpoint (default: `https://www.braintrust.dev`)
`BRAINTRUST_APP_PUBLIC_URL`	Public app URL for browser links (defaults to the app URL used for authentication)
`BRAINTRUST_ENV_FILE`	`.env` file path
`BRAINTRUST_VERBOSE`	Increase output verbosity
`BRAINTRUST_QUIET`	Suppress non-essential output
`BRAINTRUST_NO_COLOR`	Disable colored output
`BRAINTRUST_NO_INPUT`	Disable all interactive prompts
`BT_EVAL_RUNNER`	Eval runner binary
`BT_EVAL_LANGUAGE`	Force eval language (`java-script` or `python`)
`BT_EVAL_FILTER`	Filter expression for evaluator selection
`BT_EVAL_FIRST`	Run only the first N dataset records
`BT_EVAL_SAMPLE`	Run a deterministic random sample of N dataset records
`BT_EVAL_SAMPLE_SEED`	Seed used with `--sample`
`BT_EVAL_LOCAL`	Run evals without sending logs to Braintrust
`BT_EVAL_WATCH`	Re-run evals on file change
`BT_EVAL_MAX_CONCURRENCY`	Maximum number of evaluators to run concurrently
`BT_EVAL_NUM_WORKERS`	Worker threads for Python eval execution
`BT_EVAL_LIST`	List evaluators without executing them
`BT_EVAL_JSONL`	Emit eval results as JSONL
`BT_EVAL_TERMINATE_ON_FAILURE`	Stop after the first hard eval failure
`BT_EVAL_NO_AUTO_INSTRUMENTATION`	Disable automatic instrumentation for JavaScript and TypeScript evals
`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`	Relative 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`
`BRAINTRUST_SQL_FORCE_IGNORE_LINTER`	Run `bt sql` even when the SQL linter reports failures
`BT_OBSERVABILITY_TEMPLATE_PULL_OUTPUT`	Output file path for `bt observability template pull`
`BT_OBSERVABILITY_TEMPLATE_PULL_FORCE`	Overwrite an existing output file for `bt observability template pull`
`BT_OBSERVABILITY_TEMPLATE_PUSH_FILE`	Template source for `bt observability template push`
`BT_OBSERVABILITY_TEMPLATE_PUSH_TOPICS_AUTOMATION`	Topics automation name or ID for `bt observability template push`
`BT_OBSERVABILITY_TEMPLATE_PUSH_FORCE`	Replace matching resources for `bt observability template push`
`BT_OBSERVABILITY_TEMPLATE_PUSH_YES`	Skip the confirmation prompt for `bt observability template push`
`BT_TOPICS_STATUS_PROGRESS_WINDOW`	Window for `bt topics status` progress counts
`BT_TOPICS_REPORT_FUNCTION_ID`	Topic map function ID for `bt topics report`
`BT_TOPICS_REPORT_VERSION`	Topic map version for `bt topics report`
`BT_TOPICS_REPORT_OUTPUT`	Output file path for `bt topics report`
`BT_TOPICS_BTMAP_FUNCTION_ID`	Topic map function ID for `bt topics btmap`
`BT_TOPICS_BTMAP_VERSION`	Topic map version for `bt topics btmap`
`BT_TOPICS_BTMAP_OUTPUT`	Output file path for `bt topics btmap`
`BT_FUNCTIONS_VIEW_ID`	Function ID for `bt functions view`
`BT_FUNCTIONS_VIEW_VERSION`	Version selector for `bt functions view`
`BT_FUNCTIONS_VIEW_ENVIRONMENT`	Environment selector for `bt functions view`
`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
`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 authentication for `bt update`

bt does not automatically load .env files. Set environment variables explicitly in your shell, through --env-file <PATH>, or with 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 profiles list to list saved profiles, or bt status --all to verify their credentials. Specify one with --profile or BRAINTRUST_PROFILE. If you recently migrated from a version with bt auth commands, see the CLI migration guide.

Wrong org or project

Run bt status to see the active organization and project and where that context was set.

bt is using the wrong credentials

Run bt status --all to verify saved profiles, inspect the configured context, and check whether BRAINTRUST_API_KEY is overriding saved profiles. The command reports the override but does not validate the environment API key. Unset it, pass --profile <NAME>, or pass --prefer-profile to use a saved profile instead. See Credential precedence for the full order.

Token expired

Run bt login --refresh --profile <name> to refresh the expired OAuth profile. If refresh fails, run bt login --oauth --profile <name> to authenticate that profile again. These commands replaced bt auth refresh and bt auth login in v0.16.0. See the CLI migration guide.

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: local credentials file (keychain integration not yet implemented)

Update fails

If your installed version does not recognize bt update, run bt self update once. Versions before v0.16.0 used the older command. See bt update for package-manager installs and Windows upgrades.

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

​Authentication and profiles

​Credential precedence

​Commands

​Global flags

​Environment variables

​Troubleshooting

Authentication and profiles

Credential precedence

Commands

Global flags

Environment variables

Troubleshooting