CLI quickstart

bt login --oauth                     # Open a browser and save an OAuth profile
export BRAINTRUST_API_KEY=<your-key> # Use an API key from the environment

bt switch    # Select an organization and project
bt status    # Confirm the active context

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

curl -fsSL https://braintrust.dev/wizard/setup.sh | sh

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

# GitHub Actions example
- name: Run evals
  env:
    BRAINTRUST_API_KEY: ${{ secrets.BRAINTRUST_API_KEY }}
  run: bt eval tests/

BRAINTRUST_API_KEY=... bt eval tests/ --no-input --jsonl

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

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

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

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

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