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

> Deprecated reference for configuring Braintrust coding-agent skills, workflow docs, MCP access, and instrumentation with bt setup.

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

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

<Note>
  `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`](/docs/reference/cli/trace) makes Braintrust **observe** your agent by tracing its sessions.
</Note>

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 login --no-browser` or set `BRAINTRUST_API_KEY` directly.
</Note>

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt setup --agent cursor --workflow observe
bt setup skills --agent codex --global
bt setup mcp --agent codex
```

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

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

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

```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 \[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                                                                |