> ## 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.

Reference for the `bt` CLI. For installation and workflow examples, see the [CLI quickstart](/docs/reference/cli/quickstart).

## 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 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 profiles`](/docs/reference/cli/profiles)       | `list`, `delete`, `rename`                                            | Manage saved Braintrust login profiles                                                     |
| [`bt projects`](/docs/reference/cli/projects)       | `list`, `create`, `view`, `delete`                                    | Manage projects                                                                            |
| [`bt prompts`](/docs/reference/cli/prompts)         | `list`, `view`, `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)             | `setup`, `run`, `import`                                              | 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 |

## 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`](/docs/reference/cli/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](/docs/reference/cli/migrate).

### 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.

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

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.

<Note>
  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.
</Note>

## 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`                                                               |

<Warning>
  `bt` does not automatically load `.env` files. Set environment variables explicitly in your shell, through `--env-file <PATH>`, or with a tool like [direnv](https://direnv.net) before running `bt` commands.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="bt not found after install">
    Open a new shell. Ensure `~/.local/bin` (or `$XDG_BIN_HOME` if set) is in your `PATH`.
  </Accordion>

  <Accordion title="OAuth login fails">
    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.
  </Accordion>

  <Accordion title="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](/docs/reference/cli/migrate).
  </Accordion>

  <Accordion title="Wrong org or project">
    Run `bt status --verbose` to see the active organization and project and where that context was set.
  </Accordion>

  <Accordion title="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](#credential-precedence) for the full order.
  </Accordion>

  <Accordion title="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](/docs/reference/cli/migrate).
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Uninstall">
    **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
    ```
  </Accordion>
</AccordionGroup>