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

> Connect coding agents like Claude, Cursor, and Copilot to Braintrust with a single bt setup command, no manual API key required.

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

<Note>
  The browser-based flow requires a desktop environment. On headless servers, authenticate with `bt auth login --no-browser` or set `BRAINTRUST_API_KEY` directly.
</Note>

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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
```

<Note>
  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`.
</Note>

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`).

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:**

| 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)                                            |
| `--quiet` / `-q`       | Suppress streaming agent output                                                                   |
| `--interactive` / `-i` | Run agent in interactive mode                                                                     |
| `--yolo`               | Grant 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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                                                                                                             |
| `--workflow <WORKFLOW>` | Prefetch docs for a workflow: `instrument`, `observe`, `annotate`, `evaluate`, `deploy` (repeatable)                            |
| `--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                                                                               |