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

> Complete reference for every bt command, global flag, and environment variable, with examples for scripting and automation.

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

<Warning>
  **Beta** — This feature is subject to change.
</Warning>

## 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`](/reference/cli/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`](/reference/cli/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                                      |
| [`bt datasets`](/reference/cli/datasets)   | `list`, `create`, `view`, `update`, `delete`, `pipeline`, `snapshots` | Manage datasets                                         |
| [`bt topics`](/reference/cli/topics)       | `status`, `poke`, `rewind`, `open`, `config`, `report`, `btmap`       | Manage Topics automations and real-time message streams |

### Data and evaluation

| Command                          | Subcommands              | Description                                                            |
| -------------------------------- | ------------------------ | ---------------------------------------------------------------------- |
| [`bt eval`](/reference/cli/eval) |                          | Run JavaScript/TypeScript and Python eval files (macOS and Linux only) |
| [`bt sql`](/reference/cli/sql)   |                          | Run SQL queries against Braintrust                                     |
| [`bt sync`](/reference/cli/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`](/reference/cli/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                                                                         |
| `--ca-cert <PATH>`  |       | `BRAINTRUST_CA_CERT`         | Path to a PEM-encoded CA bundle for HTTPS requests (takes precedence over `SSL_CERT_FILE`) |

## Environment variables

| Variable                                    | Purpose                                                                    |
| ------------------------------------------- | -------------------------------------------------------------------------- |
| `BRAINTRUST_API_KEY`                        | API key (skips OAuth; use for CI)                                          |
| `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 (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_EVAL_PARAMS_JSON`                       | JSON object of parameter values passed to evaluators via `--param`         |
| `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                                 |

<Warning>
  As of v0.6.0, `bt` no longer automatically loads `.env` files. Set environment variables explicitly in your shell (e.g., via `export`, `--env-file <PATH>`, or 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 auth profiles --verbose` to list saved profiles. Specify one with `--profile` or `BRAINTRUST_PROFILE`.
  </Accordion>

  <Accordion title="Wrong org or project">
    Run `bt status --verbose` to see where each value comes from (flag, env var, local config, or global config).
  </Accordion>

  <Accordion title="Auth precedence">
    When multiple credential sources are present, `bt` resolves them in this order:

    1. `--api-key <KEY>` flag (always wins)
    2. `BRAINTRUST_API_KEY` env var (wins unless `--profile` CLI flag or `--prefer-profile` is also set)
    3. `--profile <NAME>` or `BRAINTRUST_PROFILE`
    4. A saved profile whose org matches the active org
    5. Auto-select if only one profile is saved
    6. Interactive picker if multiple profiles remain and `bt` is running in an interactive terminal

    <Note>
      The interactive picker only runs in interactive terminals. In CI or other non-interactive environments with multiple saved profiles, set `BRAINTRUST_PROFILE` or pass `--profile` to avoid an ambiguous-profile error.
    </Note>
  </Accordion>

  <Accordion title="Token expired">
    Run `bt auth refresh` to force-refresh your OAuth token, or `bt auth login` to re-authenticate.
  </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**: `0600`-permission file (keychain integration not yet implemented)
  </Accordion>

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