CLI overview - Braintrust

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

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 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 profiles`	`list`, `delete`, `rename`	Manage saved Braintrust login profiles
`bt projects`	`list`, `create`, `view`, `delete`	Manage projects
`bt prompts`	`list`, `view`, `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`	`setup`, `run`, `import`	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

Authentication and profiles

A profile is a saved login containing credentials and connection details for one Braintrust app URL. One profile can be used 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. Organization and project selection is separate from the profile. bt switch saves both as your active context, bt status shows what’s active, and you can override either one per command with --org and --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. If you’re moving from a version with bt auth commands, see Migrate bt.

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.

The hidden --api-key <KEY> flag is deprecated and will be removed. While it is still available, it takes precedence over other credential sources.

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.

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
`--api-key <KEY>`		`BRAINTRUST_API_KEY`	Deprecated. Use `BRAINTRUST_API_KEY` or `bt login` instead
`--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
`--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

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_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_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_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_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`	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`
`BRAINTRUST_SQL_FORCE_IGNORE_LINTER`	Run `bt sql` even when the SQL linter reports failures
`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_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 --verbose to see the active organization and project and where that context was set.

bt is using the wrong credentials

Run bt status --verbose to inspect the saved profile and context. If BRAINTRUST_API_KEY is set in your shell, it takes precedence over a saved login. Unset it or pass --prefer-profile to use your profile instead. See Credential precedence for the full order.

Token expired

Run bt login --refresh to force-refresh your OAuth token, or bt login to re-authenticate. If these commands are unfamiliar, they 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

bt update works for installs made with the standalone shell or PowerShell installer. If you installed with mise or npm, update through that 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

​Authentication and profiles

​Credential precedence

​Global flags

​Environment variables

​Troubleshooting

Commands

Authentication and profiles

Credential precedence

Global flags

Environment variables

Troubleshooting