Skip to main content

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.

bt setup configures Braintrust integrations for coding agents (Claude, Copilot, Cursor, Codex, Gemini, Opencode, Qwen). Run it once to give your agent access to Braintrust skills, workflow documentation, and MCP tools (optional). On first run, bt setup walks you through authentication and API key creation interactively. 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. 
bt setup                                  # Interactive wizard (handles auth + API key creation)
bt setup --local --agent claude           # Configure Claude for current repo
bt setup --global --agent codex           # Configure Codex user-wide
Running bt setup without --skills or --mcp is ephemeral. It authenticates and creates an API key but does not install persistent agent skills or MCP config. Pass --skills to install skills or --mcp to configure 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>, either --api-key <KEY> or BRAINTRUST_API_KEY, and --agent <AGENT> unless exactly one supported agent is on PATH.

​
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/rules/braintrust.mdc), 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:
  1. Verifies that BRAINTRUST_API_KEY is set — aborts if missing
  2. 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#
  3. Looks up and installs the latest exact SDK version (never uses latest)
  4. Instruments LLM clients in the app entry point
  5. Runs the app to verify traces are emitted
  6. 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:
LanguageSDK packageInstrumentation
Pythonbraintrustbraintrust.init_logger() + braintrust.auto_instrument() or manual wrappers
TypeScriptbraintrustinitLogger() + wrapOpenAI() / framework wrappers
Gogithub.com/braintrustdata/braintrust-sdk-gobraintrust.New() + Orchestrion compile-time instrumentation
Javadev.braintrust:braintrust-sdk-javaBraintrust.get() + BraintrustOpenAI.wrapOpenAI()
Rubybraintrust gemrequire "braintrust/setup" or braintrust exec wrapper
C#Braintrust.Sdk NuGetBraintrust.Get(config) + BraintrustOpenAI.WrapOpenAI()
Instrument-specific flags:
FlagDescription
--language <LANG>Force language (repeatable): python, typescript, javascript, go, java, ruby, csharp
--agent-cmd <CMD>Override agent command (replaces the built-in default)
--quiet / -qSuppress streaming agent output
--interactive / -iRun agent in interactive mode
--yoloGrant full permissions and run in background without prompting

​
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

FlagDescription
--agent <AGENT>Agent to configure: claude, codex, copilot, cursor, gemini, opencode, qwen (repeatable; auto-detected if omitted)
--localConfigure for the current git repo
--globalConfigure user-wide
--workflow <WORKFLOW>Prefetch docs for a workflow: instrument, observe, annotate, evaluate, deploy (repeatable)
--no-inputNon-interactive mode for CI; requires --project, credentials, and --agent unless one agent is auto-detected
--refresh-docsClear and re-fetch any previously downloaded docs