> ## 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, the recommended way for you and your coding agents to run evals, instrument code, query logs, and sync data from the terminal.

`bt` is the command-line interface for Braintrust. It lets you run evals, instrument your code, browse and query logs, sync data, manage functions, and configure coding agents without leaving your terminal.

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

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

  ```powershell Windows (PowerShell) theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  $env:BT_VERSION='0.2.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).

After installing, the installer suggests running [`bt setup`](#set-up-coding-agents) to connect your project to Braintrust. You can do this now or come back later.

### Install with npm

If you already use the [Braintrust JavaScript SDK](/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.

## Set up coding agents

`bt setup` handles authentication and API key creation for your project. Optionally, it installs Braintrust skill files, workflow docs, and MCP server config into your coding agent's config directory (Claude, Copilot, Cursor, Codex, Gemini, Opencode, Qwen).
It also detects your project language, installs the exact SDK version, instruments your LLM clients, verifies the app still runs, and outputs a Braintrust permalink to the captured trace:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt setup                           # Interactive wizard with the minimal amount of questions
bt setup -i                        # Interactive wizard with all the options

# Directly starts codex to instrument the code since all questions are answered
bt setup --project 'project-name' --api-key BRAINTRUST_API_KEY --agent codex
```

If `bt setup` creates a new API key, it prints an `export BRAINTRUST_API_KEY=<key>` command. Run it to make the key available in your current terminal session.

See [`bt setup`](/reference/cli/setup) for supported languages and all subcommands.

## Authenticate and set context

`bt` supports two authentication methods:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt auth login                        # OAuth: opens a browser login flow, saves credentials to your keychain
export BRAINTRUST_API_KEY=<your-key> # API key: good for CI, scripts, or if you prefer not to use OAuth
```

To use an API key, create one under <Icon icon="settings-2" /> **Settings** > <Icon icon="key-square" /> **API keys** in the Braintrust app. If you haven't set up the CLI yet, `bt setup` creates an API key for you interactively. See [Set up coding agents](#set-up-coding-agents) below.

After authenticating, set a default org and project:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt switch    # Pick a default org and project
bt status    # Confirm what's active
```

`bt` saves a **context** (a default org) so you don't need to specify it on every command. The project must be set on each command with `-p`. You can always override the org with `-o` or environment variables.

## Run evals locally

Run your [evaluation](/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 --filter my-evaluator  # Run a specific evaluator by name
```

`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`](/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](/evaluate/run-evaluations#run-in-ci-cd) 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 `--json` for non-interactive output:

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

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 --json   # smoke run on PR, non-final
bt eval tests/ --no-input --json              # full run on merge, final
```

## Browse and query logs

[`bt view logs`](/reference/cli/view) opens an interactive terminal UI for [browsing your project's logs](/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](/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 scores.Factuality < 0.5 LIMIT 50"
BRAINTRUST_API_KEY=... bt sql "SELECT count(*) FROM project_logs('my-project')" --json
```

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

## 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`](/reference/cli/sync) for the full flag reference.

## Manage functions

`bt functions push` uploads local TypeScript or Python [function definitions](/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`](/reference/cli/functions) for bundling behavior, language options, and all flags.

## Next steps

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