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

`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

<Tip>
  Already have `bt` installed? Follow [Migrate bt](/docs/reference/cli/migrate) to update it and complete any required version-specific migration steps.
</Tip>

Choose an installation method:

<Tabs>
  <Tab title="Standalone">
    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
      bt --version
      ```

      ```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"
      bt --version
      ```
    </CodeGroup>
  </Tab>

  <Tab title="npm">
    Install the [Braintrust JavaScript SDK](/docs/sdks/typescript/quickstart), which includes `bt`, then verify the installed version:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    npm install braintrust@latest
    npx bt --version
    ```

    <Note>
      The `braintrust` package pins a specific version of `bt`, which can lag behind standalone releases. Install `bt` with the standalone installer to manage its version independently.
    </Note>
  </Tab>

  <Tab title="pnpm">
    Install the [Braintrust JavaScript SDK](/docs/sdks/typescript/quickstart), which includes `bt`, then verify the installed version:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    pnpm add braintrust@latest
    pnpm exec bt --version
    ```

    <Note>
      The `braintrust` package pins a specific version of `bt`, which can lag behind standalone releases. Install `bt` with the standalone installer to manage its version independently.
    </Note>
  </Tab>

  <Tab title="mise">
    Install and activate the latest stable version of `bt` with [mise](https://mise.jdx.dev):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    mise use --global "github:braintrustdata/bt@latest"
    bt --version
    ```
  </Tab>
</Tabs>

## Authenticate and set context

<Steps>
  <Step title="Choose how to authenticate">
    `bt` supports three authentication methods:

    <Tabs>
      <Tab title="Environment API key">
        `BRAINTRUST_API_KEY` supplies an API key directly for the current shell session. `bt` does not save it in a profile, and it overrides any saved profile.

        Set the environment variable:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        export BRAINTRUST_API_KEY="your-api-key"
        ```

        <Tip>
          To create an API key, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="key-square" /> API keys**](https://www.braintrust.dev/app/~/configuration/org/api-keys).
        </Tip>
      </Tab>

      <Tab title="Saved OAuth profile">
        A saved OAuth profile stores reusable credentials from browser-based Braintrust authentication.

        Authenticate and name the profile:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        bt login --oauth --profile <your-profile>
        ```
      </Tab>

      <Tab title="Saved API key profile">
        A saved API key profile stores an API key for repeated use, so you do not need to set it in each shell session.

        Run the interactive login and select **API key** to save the key in a profile. If `BRAINTRUST_API_KEY` is set, `bt` asks whether to save that key instead:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        bt login --profile <your-profile>
        ```

        <Tip>
          To create an API key, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="key-square" /> API keys**](https://www.braintrust.dev/app/~/configuration/org/api-keys).
        </Tip>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Select an organization and project">
    Next, select the active profile, organization, and project that `bt` should use by default:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt switch
    ```

    [`bt switch`](/docs/reference/cli/switch) handles authentication in two ways:

    * **Environment API key:** If `BRAINTRUST_API_KEY` is set, `bt switch` authenticates with it instead of selecting a saved profile.
    * **Saved profile:** If `BRAINTRUST_API_KEY` is not set, `bt switch` prompts you to select a saved profile (when there are multiple to choose from), then authenticates with that profile.

    It then retrieves the organizations and projects available to those credentials and lets you select from them.

    <Accordion title="Override organization and project context">
      You can override the saved context at two scopes:

      * **Single command:** Pass `--org` (`-o`) or `--project` (`-p`). Command-line flags override both environment variables and saved context.
      * **Current environment:** Set `BRAINTRUST_ORG_NAME` or `BRAINTRUST_DEFAULT_PROJECT`. These variables override saved context for commands run in that environment.

      With `bt switch`, the organization and project overrides are also saved as the new active context (but not `BRAINTRUST_API_KEY`).
    </Accordion>
  </Step>

  <Step title="Verify authentication and context">
    Inspect the completed setup:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt status --all
    ```

    Use the output to confirm:

    * **Saved profiles:** Each profile you intend to use authenticates successfully.
    * **Active context:** The selected profile, organization, and project are correct.

    [`bt status --all`](/docs/reference/cli/status) reports when `BRAINTRUST_API_KEY` overrides saved profiles, but it does not validate the key. If you use this variable, a successful `bt switch` in the previous step confirms that the key can authenticate.
  </Step>
</Steps>

<Note>
  For details about how `bt` chooses between environment API keys and saved profiles, see [Credential precedence](/docs/reference/cli/overview#credential-precedence).
</Note>

## Trace coding-agent sessions

[`bt trace enable`](/docs/reference/cli/trace#bt-trace-enable) installs a tracing plugin for your coding agent to trace future sessions to Braintrust, including turns, model calls, and tool use. Use `bt` v0.19.3 or later for Grok tracing and the v2 OpenCode and pi integrations. Run the command for your agent:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable claude --project my-project       # Claude Code
bt trace enable codex --project my-project        # Codex
bt trace enable antigravity --project my-project  # Google Antigravity
bt trace enable grok --project my-project         # Grok
bt trace enable opencode --project my-project     # OpenCode
bt trace enable pi --project my-project           # pi
```

Follow your agent's guide to restart the agent or activate its tracing hooks, then run a short session and confirm that its trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page. See the guides for [Claude Code](/docs/integrations/developer-tools/claude-code), [Codex](/docs/integrations/developer-tools/codex), [Google Antigravity](/docs/integrations/developer-tools/antigravity), [Grok](/docs/integrations/developer-tools/grok), [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`](/docs/reference/cli/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`](/docs/reference/cli/sql) runs [SQL queries](/docs/reference/sql) against your logs from the terminal or in scripts.

By default, `FROM logs` queries the active project in `bt`'s local or global context. The `--project` flag or `BRAINTRUST_DEFAULT_PROJECT` selects a different project for the command. In scripts without saved context, pass `--project` explicitly:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt sql "SELECT * FROM logs WHERE created > now() - interval 1 day AND scores.Factuality < 0.5 LIMIT 50"
BRAINTRUST_API_KEY=... bt sql --project my-project "SELECT count(*) FROM logs 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`](/docs/reference/cli/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`](/docs/reference/cli/functions) uploads local TypeScript or Python [function definitions](/docs/deploy/functions) (tools, scorers, and LLM functions) to Braintrust. [`bt functions pull`](/docs/reference/cli/functions) 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