bt setup

bt setup is deprecated. For new project instrumentation, use the standalone setup wizard: curl -fsSL https://braintrust.dev/wizard/setup.sh | sh.

bt setup is a deprecated command that configures Braintrust integrations for coding agents (Claude, Copilot, Cursor, Codex, Gemini, Opencode, Qwen). For existing automation, it can give your agent access to Braintrust skills, workflow documentation, and MCP tools.

bt setup and bt trace setup do different jobs. bt setup gives your agent tools to work with Braintrust, such as skills and MCP access. bt trace setup makes Braintrust observe your agent by tracing its sessions.

On first run, bt setup opens a browser to sign in or sign up, then prompts in the terminal to select an organization and project. No manual API key setup is required beforehand. The created API key is exported to the setup process (so sub-commands like bt setup instrument work immediately) and printed with a ready-to-copy export BRAINTRUST_API_KEY=<key> command. Run it to make the key available in your current terminal session. After a successful run, bt setup displays a verification prompt.

The browser-based flow requires a desktop environment. On headless servers, authenticate with bt login --no-browser or set BRAINTRUST_API_KEY directly.

bt setup --agent cursor --workflow observe
bt setup skills --agent codex --global
bt setup mcp --agent codex

By default, bt setup authenticates, creates an API key, and runs instrumentation (detecting your project language, installing the SDK, and instrumenting LLM clients). Pass --no-instrument to skip instrumentation. Skills and MCP config are not installed unless you pass --skills or --mcp. To install only skills after initial setup, run bt setup skills.

For CI or non-interactive environments, pass --no-input. This requires --project <NAME>, BRAINTRUST_API_KEY, and --agent <AGENT> unless exactly one supported agent is on PATH. The --api-key <KEY> flag still works for compatibility, but it is deprecated.

bt setup skills

Writes agent-specific skill files so your agent knows how to use Braintrust. Also prefetches workflow docs. Install locations by agent: Claude (.claude/skills/braintrust/SKILL.md), Copilot (.copilot/skills/braintrust/SKILL.md), Cursor (.cursor/skills/braintrust/SKILL.md), Gemini (.gemini/skills/braintrust/SKILL.md), Qwen (.qwen/skills/braintrust/SKILL.md).

bt setup skills --local --agent claude --workflow evaluate
bt setup skills --global --agent codex --agent cursor

bt setup instrument

Runs a coding agent against your repo to automatically add Braintrust SDK instrumentation (tracing, logging). The agent detects your project language, installs the exact SDK version, instruments your LLM clients, runs the app to verify the integration, and outputs a Braintrust permalink to the emitted trace.

bt setup instrument --agent codex
bt setup instrument --agent claude
bt setup instrument --agent claude --language typescript

What the agent does:

Verifies that BRAINTRUST_API_KEY is set — aborts if missing
Detects the project language from build files: package.json → TypeScript, requirements.txt/pyproject.toml → Python, pom.xml/build.gradle → Java, go.mod → Go, Gemfile → Ruby, .csproj → C#
Looks up and installs the latest exact SDK version (never uses latest)
Instruments LLM clients in the app entry point
Runs the app to verify traces are emitted
Outputs a Braintrust permalink to the captured trace

What the agent does NOT do: refactor unrelated code, add eval code, or add manual flush/shutdown logic. The app is required to run correctly without BRAINTRUST_API_KEY set. Supported languages: Python, TypeScript/JavaScript, Go, Java, Ruby, C# Instrumentation approach by language:

Language	SDK package	Instrumentation
Python	`braintrust`	`braintrust.init_logger()` + `braintrust.auto_instrument()` or manual wrappers
TypeScript	`braintrust`	`initLogger()` + `wrapOpenAI()` / framework wrappers
Go	`github.com/braintrustdata/braintrust-sdk-go`	`braintrust.New()` + Orchestrion compile-time instrumentation
Java	`dev.braintrust:braintrust-sdk-java`	`Braintrust.get()` + `BraintrustOpenAI.wrapOpenAI()`
Ruby	`braintrust` gem	`require "braintrust/setup"` or `braintrust exec` wrapper
C#	`Braintrust.Sdk` NuGet	`Braintrust.Get(config)` + `BraintrustOpenAI.WrapOpenAI()`

Instrument-specific flags:

Flag	Description
`--language <LANG>`	Force language (repeatable): `python`, `typescript`, `javascript`, `go`, `java`, `ruby`, `csharp`
`--agent-cmd <CMD>`	Override agent command (replaces the built-in default)
`--workflow <WORKFLOW>`	Latest workflow docs to provide to the instrumentation agent: `instrument`, `observe`, `annotate`, `evaluate`, `deploy`, or `all`. Always includes `instrument`
`--no-workflow`	Do not provide additional workflow docs
`--workers <WORKERS>`	Number of concurrent workers for docs download [default: 12]
`--tui`	Run the agent in interactive TUI mode [default]
`--background`	Run the agent in background mode. Use `--verbose` to see the agent output
`--yolo`	Grant full permissions by bypassing permission prompts

bt setup mcp

Adds the Braintrust MCP server to your agent’s config so it can query Braintrust data directly.

bt setup mcp --local --agent claude
bt setup mcp --global --agent codex

bt setup doctor

Diagnoses your coding agent setup and reports what is and isn’t configured.

bt setup doctor --local
bt setup doctor --global

Common flags

Flag	Description
`--agent <AGENT>`	Agent to configure: `claude`, `codex`, `copilot`, `cursor`, `gemini`, `opencode`, `qwen` (repeatable; auto-detected if omitted)
`--local`	Configure for the current git repo
`--global`	Configure user-wide [default]
`--skills`	Also install reusable coding-agent skills
`--no-skills`	Do not install reusable coding-agent skills. Alias: `--no-skill`
`--mcp`	Set up the MCP server
`--no-mcp`	Do not set up the MCP server [default]
`--instrument`	Run the instrumentation agent [default]
`--no-instrument`	Do not run the instrumentation agent. Skills and MCP configuration can still run
`--tui`	Run the agent in interactive TUI mode [default]
`--background`	Run the agent in background mode. Use `--verbose` to see the agent output
`--language <LANG>`	Force language detection for instrumentation: `python`, `typescript`, `javascript`, `go`, `csharp`, `java`, or `ruby`
`--interactive`, `-i`	Run the interactive setup wizard
`--workflow <WORKFLOW>`	Prefetch docs for a workflow: `instrument`, `observe`, `annotate`, `evaluate`, `deploy`, or `all` (repeatable) [default: all]
`--no-workflow`	Do not fetch workflow docs during setup
`--no-input`	Non-interactive mode for CI; requires `--project`, credentials, and `--agent` unless one agent is auto-detected
`--refresh-docs`	Clear and re-fetch any previously downloaded docs
`--workers <WORKERS>`	Number of concurrent workers for docs prefetch/download [default: 12]
`--yolo`	Grant the agent full permissions by bypassing permission prompts

API

CLI

SQL

bt setup skills

bt setup instrument

bt setup mcp

bt setup doctor

Common flags

​bt setup skills

​bt setup instrument

​bt setup mcp

​bt setup doctor

​Common flags

bt setup skills

bt setup instrument

bt setup mcp

bt setup doctor

Common flags