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

> Install the bt CLI and use it to authenticate, trace coding-agent sessions, run evals, query logs, sync data, and manage Braintrust from the terminal.

If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

`bt` is the command-line interface for Braintrust. It lets you authenticate, trace coding-agent sessions, run evals, browse and query logs, sync data, and manage functions without leaving your terminal.

<Accordion title="MCP or CLI?">
  Which one you want depends on what your tool can access and where the work needs to run.

  * **[MCP](/docs/integrations/developer-tools/mcp)**: Best when your AI tool can connect to Braintrust but has no authenticated shell, which is common in chat applications. It also fits when you want an assistant to reason over your Braintrust data and take several connected actions in one conversation, without installing and maintaining a CLI in its execution environment.
  * **[`bt` CLI](/docs/reference/cli/quickstart)**: Best for repeatable work in scripts, CI, local files, and shell pipelines, where you want deterministic commands instead of an assistant's judgment. Coding agents with shell access can call those commands too.

  If your tool supports both, either one works. Pick whichever is more reliable for the task at hand.
</Accordion>

## Install

To install the latest version of `bt`:

<CodeGroup>
  ```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl -fsSL https://bt.dev/cli/install.sh | bash
  ```

  ```powershell Windows (PowerShell) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  powershell -ExecutionPolicy Bypass -c "irm https://github.com/braintrustdata/bt/releases/latest/download/bt-installer.ps1 | iex"
  ```
</CodeGroup>

To install a specific version:

<CodeGroup>
  ```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl -fsSL https://bt.dev/cli/install.sh | bash -s -- --version 0.17.0
  ```

  ```powershell Windows (PowerShell) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  $env:BT_VERSION='0.17.0'; powershell -ExecutionPolicy Bypass -c "irm https://github.com/braintrustdata/bt/releases/latest/download/bt-installer.ps1 | iex"
  ```
</CodeGroup>

To install the canary (pre-release) channel:

<CodeGroup>
  ```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl -fsSL https://bt.dev/cli/install.sh | bash -s -- --canary
  ```

  ```powershell Windows (PowerShell) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  $env:BT_CHANNEL='canary'; powershell -ExecutionPolicy Bypass -c "irm https://github.com/braintrustdata/bt/releases/latest/download/bt-installer.ps1 | iex"
  ```
</CodeGroup>

The installer downloads a pre-built binary to `~/.local/bin/bt` (or `$XDG_BIN_HOME/bt` if set).

<AccordionGroup>
  <Accordion title="Install with npm">
    If you already use the [Braintrust JavaScript SDK](/docs/sdks/typescript/quickstart), `bt` is available as an optional dependency of the `braintrust` npm package (`braintrust` v3.17.0 or later).

    After installing `braintrust`, run `bt` through your package manager:

    <CodeGroup>
      ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      pnpm exec bt --version
      ```

      ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      npx bt --version
      ```
    </CodeGroup>

    To run `bt` once without adding it to a project, use `npx -p braintrust bt`.

    <Note>
      Use the standalone installer above if you want to update `bt` independently of the SDK, or if you need the canary channel, which isn't published to npm. The npm package always matches your installed `braintrust` version.
    </Note>

    Platform-specific binaries are delivered through optional dependencies, with a postinstall download as a fallback when optional dependencies are skipped, such as with `--omit=optional` or in airgapped installs. Two environment variables control binary resolution:

    * **`BT_BINARY_PATH`**: Path to a `bt` binary to use instead of the resolved one.
    * **`BT_SKIP_DOWNLOAD`**: Set to `1` to skip the postinstall fallback download.
  </Accordion>

  <Accordion title="Install with mise">
    If you use [mise](https://mise.jdx.dev) as a version manager, add `bt` to your `mise.toml`:

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    [tools."github:braintrustdata/bt"]
    version = "latest"
    ```

    To pin a specific version with SHA256 verification:

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    [tools."github:braintrustdata/bt"]
    version = "0.17.0"
    [tools."github:braintrustdata/bt".platforms]
    macos-arm64.checksum = "sha256:<checksum-for-macos-arm64>"
    linux-x64.checksum = "sha256:<checksum-for-linux-x64>"
    # Add other platforms as needed: macos-x64, linux-arm64, linux-x64-musl, windows-arm64, windows-x64
    ```

    Checksums are available in the release's `.sha256` files on the [GitHub releases page](https://github.com/braintrustdata/bt/releases). Supported platforms: `macos-arm64`, `macos-x64`, `linux-arm64`, `linux-x64`, `linux-x64-musl`, `windows-arm64`, `windows-x64`.

    The `version` field accepts `"latest"` for the latest stable release, a specific version string (e.g., `"0.17.0"`), `"canary"` for the latest pre-release build, or a 12-character canary commit SHA (e.g., `"canary-7129692509ab"`). Do not combine `"latest"` or `"canary"` with pinned SHA256 checksums, since those version strings resolve to different binaries on each release.
  </Accordion>
</AccordionGroup>

## Authenticate and set context

Authenticate with OAuth or an API key:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt login --oauth                     # Open a browser and save an OAuth profile
export BRAINTRUST_API_KEY=<your-key> # Use an API key from the environment
```

<Tip>
  To create an API key, go to <Icon icon="settings-2" /> **Settings** > <Icon icon="key-square" /> **API keys** in the Braintrust app.
</Tip>

After authenticating, select an organization and project:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt switch    # Select an organization and project
bt status    # Confirm the active context
```

`bt switch` saves the selected organization and project as your active context, so you don't need to specify them on every command. Override them for one command with `-o` and `-p`.

OAuth login is saved as a profile that you can reuse across the organizations and projects your account can access. See [Authentication and profiles](/docs/reference/cli/overview#authentication-and-profiles) for details.

## Trace coding-agent sessions

[`bt trace setup`](/docs/reference/cli/trace#bt-trace-setup) installs a tracing plugin for your coding agent so every session is traced to Braintrust: turns, model calls, tool use, and more.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace setup claude --project my-project    # Claude Code
bt trace setup codex --project my-project     # Codex
bt trace setup opencode --project my-project  # OpenCode
bt trace setup pi --project my-project        # pi
```

After setup, traces appear automatically in your project's logs. For agent-specific instructions, see the guides for [Claude Code](/docs/integrations/developer-tools/claude-code), [Codex](/docs/integrations/developer-tools/codex), [OpenCode](/docs/integrations/developer-tools/opencode), and [pi](/docs/integrations/developer-tools/pi).

## Instrument your project

In your project directory, run the agent-assisted setup wizard:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl -fsSL https://braintrust.dev/wizard/setup.sh | sh
```

The wizard handles authentication, SDK installation, and LLM client instrumentation in one step. You can run it whether or not `bt` is already installed or authenticated.

## Run evals locally

Run your [evaluation](/docs/evaluate/run-evaluations) files directly without `npx` or SDK runner setup:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt eval                        # Discover and run all eval files in the current directory
bt eval tests/                 # Run eval files under a specific directory
bt eval --watch                # Re-run on file changes during development
bt eval my-evaluator.eval.ts   # Run a specific eval file
```

`bt eval` auto-detects your JavaScript runner (`tsx`, `vite-node`, `ts-node`) and supports Python eval files too. For other languages, run your eval file directly with your language's toolchain. See [`bt eval`](/docs/reference/cli/eval) for the full list of flags.

### Run evals in CI

For CI pipelines, set `BRAINTRUST_API_KEY` instead of using OAuth login. See [Run in CI/CD](/docs/evaluate/run-in-ci) for the full workflow.

```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# GitHub Actions example
- name: Run evals
  env:
    BRAINTRUST_API_KEY: ${{ secrets.BRAINTRUST_API_KEY }}
  run: bt eval tests/
```

Create an API key in the Braintrust app under <Icon icon="settings-2" /> **Settings** > <Icon icon="key-square" /> **API keys**. Use `--no-input` and `--jsonl` for non-interactive output:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=... bt eval tests/ --no-input --jsonl
```

Use `--first N` or `--sample N` to run a subset of your data as a non-final smoke run on pull requests, then run the full suite on merge:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt eval --first 20 tests/ --no-input --jsonl  # smoke run on PR, non-final
bt eval tests/ --no-input --jsonl             # full run on merge, final
```

## Browse and query logs

[`bt view logs`](/docs/reference/cli/view) opens an interactive terminal UI for [browsing your project's logs](/docs/observe/view-logs), useful for checking on production traffic or debugging during an incident:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt view logs                                    # Browse logs for the active project
bt view logs --search "error"                   # Search by keyword
bt view logs --filter "metrics.duration > 5.0"  # Filter by expression
bt view logs --url <braintrust-url>             # Open a Braintrust URL in the terminal
```

For programmatic access, `bt sql` runs [SQL queries](/docs/reference/sql) against your logs from the terminal or in scripts:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt sql "SELECT * FROM project_logs('my-project') WHERE created > now() - interval 1 day AND scores.Factuality < 0.5 LIMIT 50"
BRAINTRUST_API_KEY=... bt sql "SELECT count(*) FROM project_logs('my-project') WHERE created > now() - interval 1 day" --json
```

See [`bt view`](/docs/reference/cli/view) and [`bt sql`](/docs/reference/cli/sql) for details.

<Tip>
  Most SQL data-source functions also accept an object name in place of its ID. See [Querying by name](/docs/reference/sql/query-structure#querying-by-name).
</Tip>

## Sync data

`bt sync` downloads Braintrust data to local NDJSON files for offline analysis, backup, or migration:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt sync pull project_logs:my-project --window 24h   # Pull the last 24 hours of logs
bt sync pull experiment:my-experiment               # Pull a specific experiment
bt sync push project_logs:my-project                # Push local data back to Braintrust
```

See [`bt sync`](/docs/reference/cli/sync) for the full flag reference.

## Manage functions

`bt functions push` uploads local TypeScript or Python [function definitions](/docs/deploy/functions) (tools, scorers, and LLM functions) to Braintrust. `bt functions pull` downloads them back to local files.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt functions push my_tools.ts              # Upload a TypeScript function file
bt functions push src/scorers.py           # Upload a Python function file
bt functions pull --slug my-scorer         # Download a function by slug
```

See [`bt functions`](/docs/reference/cli/functions) for bundling behavior, language options, and all flags.

## Next steps

* Read the [CLI overview](/docs/reference/cli/overview) for the complete command list, global flags, and environment variables
* See [Filter and search logs](/docs/observe/filter) for SQL query examples against your logs
* See [Run evaluations](/docs/evaluate/run-evaluations) for eval workflow details