> ## 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.
# CLI overview
> Use the bt CLI to manage Braintrust resources, run evaluations, query data, and trace coding-agent sessions.
`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](/docs/reference/cli/quickstart). If you're moving from a version with `bt auth` commands, follow [Migrate bt](/docs/reference/cli/migrate).
## 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](/docs/reference/cli/quickstart#authenticate-and-set-context) 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`](/docs/reference/cli/login) to save a profile, [`bt profiles`](/docs/reference/cli/profiles) to list, rename, or delete profiles, and [`bt status --all`](/docs/reference/cli/status) to verify saved credentials.
[`bt switch`](/docs/reference/cli/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`](/docs/reference/cli/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:
1. Passing `--profile` or `--prefer-profile` on the command line makes `bt` use a saved profile and ignore `BRAINTRUST_API_KEY`.
2. Otherwise, `BRAINTRUST_API_KEY` from the environment wins.
3. Otherwise, `bt` uses a saved profile, selected by the rules below.
Then, when using a saved profile, which one:
1. The `--profile NAME` flag.
2. The `BRAINTRUST_PROFILE` environment variable.
3. The profile saved by `bt switch`, if it matches the requested app URL.
4. The only compatible profile for the app URL and organization, if exactly one is saved.
5. 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`](/docs/reference/cli/datasets) | `list`, `create`, `view`, `update`, `delete`, `pipeline`, `snapshots` | Manage datasets |
| [`bt docs`](/docs/reference/cli/docs) | `fetch` | Download Braintrust documentation for coding agents |
| [`bt environments`](/docs/reference/cli/environments) | `list`, `view`, `create`, `update`, `delete` | Manage deployment environments |
| [`bt eval`](/docs/reference/cli/eval) | | Run JavaScript/TypeScript and Python eval files (macOS and Linux only) |
| [`bt experiments`](/docs/reference/cli/experiments) | `list`, `view`, `compare`, `delete` | Manage experiments |
| [`bt functions`](/docs/reference/cli/functions) | `list`, `view`, `invoke`, `delete`, `push`, `pull` | Manage functions (tools, scorers, and more) |
| [`bt init`](/docs/reference/cli/init) | | Link the current directory to a Braintrust org and project (creates `.bt/config.json`) |
| [`bt login`](/docs/reference/cli/login) | | Log in to Braintrust, or refresh an OAuth login with `--refresh` |
| [`bt logout`](/docs/reference/cli/logout) | | Remove a saved Braintrust login and its local credentials |
| [`bt observability`](/docs/reference/cli/observability) | `template pull`, `template push` | Export and apply portable JSON configuration for facets and Loop automations |
| [`bt profiles`](/docs/reference/cli/profiles) | `list`, `doctor`, `repair`, `delete`, `rename` | Manage saved Braintrust login profiles and diagnose orphaned credentials |
| [`bt projects`](/docs/reference/cli/projects) | `list`, `create`, `view`, `delete` | Manage projects |
| [`bt prompts`](/docs/reference/cli/prompts) | `list`, `view`, `versions`, `assign`, `unassign`, `delete` | Manage prompts |
| [`bt scorers`](/docs/reference/cli/scorers) | `list`, `create`, `view`, `invoke`, `delete` | Manage scorers and classifiers |
| [`bt setup`](/docs/reference/cli/setup) | `skills`, `instrument`, `mcp`, `doctor` | Configure Braintrust setup flows. Deprecated; use the standalone setup wizard |
| [`bt sql`](/docs/reference/cli/sql) | | Run SQL queries against Braintrust |
| [`bt status`](/docs/reference/cli/status) | | Show current identity, org, and project context |
| [`bt switch`](/docs/reference/cli/switch) | | Switch org and project context |
| [`bt sync`](/docs/reference/cli/sync) | `pull`, `push`, `status` | Sync project logs, experiments, or datasets to/from local NDJSON files |
| [`bt tools`](/docs/reference/cli/tools) | `list`, `view`, `invoke`, `delete` | Manage tools (alias for `bt functions --type tool`) |
| [`bt topics`](/docs/reference/cli/topics) | `status`, `poke`, `rewind`, `open`, `config`, `report`, `btmap` | Inspect and control Topics automation |
| [`bt trace`](/docs/reference/cli/trace) | `enable`, `disable`, `run`, `import`, `doctor`, `update` | Manage coding-agent tracing |
| [`bt update`](/docs/reference/cli/update) | | Update the CLI binary |
| [`bt view`](/docs/reference/cli/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 ` | | `BRAINTRUST_API_URL` | Override API URL |
| `--app-url ` | | `BRAINTRUST_APP_URL` | Override app URL |
| `--app-public-url ` | | `BRAINTRUST_APP_PUBLIC_URL` | Override the public app URL used for browser links |
| `--env-file ` | | `BRAINTRUST_ENV_FILE` | Load a `.env` file |
| `--ca-cert ` | | `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 --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](/docs/reference/cli/trace#tag-traces) 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 `, or with a tool like [direnv](https://direnv.net) 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 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](/docs/reference/cli/migrate).
Run `bt status` to see the active organization and project and where that context was set.
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 `, or pass `--prefer-profile` to use a saved profile instead. See [Credential precedence](#credential-precedence) for the full order.
Run `bt login --refresh --profile ` to refresh the expired OAuth profile. If refresh fails, run `bt login --oauth --profile ` to authenticate that profile again. These commands replaced `bt auth refresh` and `bt auth login` in v0.16.0. See the [CLI migration guide](/docs/reference/cli/migrate).
`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)
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`](/docs/reference/cli/update) for package-manager installs and Windows upgrades.
**macOS and Linux:**
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
rm -f "${XDG_BIN_HOME:-${XDG_DATA_HOME:-$HOME/.local}/bin}/bt"
rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/bt"
```
**Windows (PowerShell):**
```powershell theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
$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
```