> ## 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.
# Migrate bt
> Upgrade bt across releases with breaking changes while preserving authentication, project context, and coding-agent tracing settings
This page describes steps to follow when upgrading `bt` across versions with breaking changes.
## Command syntax
How you invoke `bt` depends on how it is installed:
* For the standalone installer, mise, and global npm or pnpm installations, use the commands as written.
* For a project-local npm installation, run commands from the project and replace `bt` with `npx bt`.
* For a project-local pnpm installation, run commands from the project and replace `bt` with `pnpm exec bt`.
The commands in this guide use `bt`. Substitute the project-local invocation above when applicable.
## Before you update
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt --version
```
Record the version so you can identify the migration instructions that apply after updating.
Complete this step only if your installed version is older than v0.16.0. Otherwise, continue to [Update bt](#update-bt).
Record three parts of your current setup before updating:
* **Saved profiles:** Run `bt auth profiles`. For each profile you still use, record its name, whether it uses OAuth or an API key, its authentication status, and any associated organization shown.
* **Environment API key:** Check whether `BRAINTRUST_API_KEY` is set where you run `bt`, such as your shell, an environment file, CI/CD settings, or a secret manager. Record only whether it is set, not its value.
* **Selected context:** Run [`bt status`](/docs/reference/cli/status) and record the selected profile, organization, and project so you can restore them after updating.
## Update bt
Update `bt` using the method that matches how you installed it, then check the installed version:
Run these commands:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt update
bt --version
```
If your installed version does not recognize [`bt update`](/docs/reference/cli/update), run this command instead:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt self update
bt --version
```
If `braintrust` is installed in a project, run these commands from that project:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
npm install braintrust@latest
npx bt --version
```
If you installed `braintrust` globally, update the global package instead:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
npm install --global braintrust@latest
bt --version
```
The `braintrust` package pins a specific version of `bt`, which can lag behind standalone releases. If the package does not yet include the `bt` release whose migration steps you need, use the standalone installer.
If `braintrust` is installed in a project, run these commands from that project:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pnpm add braintrust@latest
pnpm exec bt --version
```
If you installed `braintrust` globally, update the global package instead:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pnpm add --global braintrust@latest
bt --version
```
The `braintrust` package pins a specific version of `bt`, which can lag behind standalone releases. If the package does not yet include the `bt` release whose migration steps you need, use the standalone installer.
Update `bt`, then verify the installed version:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
mise upgrade "github:braintrustdata/bt" --bump
bt --version
```
For a standalone Windows installation running `bt` v0.17.0 or later, run:
```powershell theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt update
bt --version
```
For v0.16.x or earlier, rerun the PowerShell installer instead. [`bt update`](/docs/reference/cli/update) did not work on Windows in those versions.
```powershell theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
powershell -ExecutionPolicy Bypass -c "irm https://github.com/braintrustdata/bt/releases/latest/download/bt-installer.ps1 | iex"
bt --version
```
## Version-specific migrations
Only releases with migration steps appear below. Complete each applicable section newer than the version you recorded before updating, through the version you installed, in ascending version order.
### v0.16.0
For the full list of changes, see the [v0.16.0 changelog entry](/docs/changelog#bt-cli-releases-2).
v0.16.0 changes authentication context, command names, and tracing setup:
* Saved profiles no longer select the active organization. You can use one profile with every organization its credentials can access. Project selection remains separate.
* Top-level commands replace the previous `bt auth` commands.
* Coding-agent tracing setup moves to [`bt trace`](/docs/reference/cli/trace).
The update preserves saved profiles and credentials, but an organization stored only in a legacy profile is no longer selected as active context.
Verify each credential source you plan to keep using:
* **Saved profiles:** Run [`bt status --all`](/docs/reference/cli/status). This command checks every saved OAuth and API key profile. Confirm that each profile you still use can authenticate successfully.
* **Environment API key:** [`bt status --all`](/docs/reference/cli/status) reports when `BRAINTRUST_API_KEY` overrides saved profiles, but it does not validate the key. To verify the environment key, use it for an authenticated request such as [`bt projects list --org "your-org"`](/docs/reference/cli/projects). Replace `your-org` with the organization you recorded before updating. If the command returns the organization's projects, the key works.
Repair each credential source you plan to keep using that could not authenticate. If multiple saved profiles need repair, repeat the applicable commands for each profile.
If `BRAINTRUST_API_KEY` is missing or invalid, replace it with a valid Braintrust API key in the environment where you run `bt`.
For a custom or self-hosted deployment, also set `BRAINTRUST_API_URL` and `BRAINTRUST_APP_URL` in the environment where you run `bt`.
If the profile reports `token expired`, refresh it:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt login --refresh --profile your-profile
```
If the refresh fails or the profile reports `credential missing`, log in again:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt login --oauth --profile your-profile
```
For a custom or self-hosted deployment, add its `--api-url` and `--app-url` to the login command.
If the profile reports `credential missing` or `invalid API key`, log in again:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt login --profile your-profile
```
Choose API key and enter it when prompted.
For a custom or self-hosted deployment, add its `--api-url` and `--app-url` to the login command.
Choose the credentials, organization, and project that `bt` should use for subsequent commands.
To save your selection globally, use [`bt switch --global`](/docs/reference/cli/switch) as shown below. For a project-specific selection, use `bt switch --local` (which writes to the nearest `.bt/config.json`, which you can create with [`bt init`](/docs/reference/cli/init)).
1. Leave `BRAINTRUST_API_KEY` set.
2. Check `BRAINTRUST_ORG_NAME` and `BRAINTRUST_DEFAULT_PROJECT`. Keep values accessible to the API key, or unset them to choose interactively.
3. Run [`bt switch --global`](/docs/reference/cli/switch) and select an organization and project accessible to your API key. If only one organization is available, `bt` selects it automatically.
1. Unset `BRAINTRUST_API_KEY`, since it overrides credentials from saved profiles.
2. Check `BRAINTRUST_PROFILE`, `BRAINTRUST_ORG_NAME`, and `BRAINTRUST_DEFAULT_PROJECT`. Keep the intended profile and values accessible to it, or unset them to choose interactively.
3. Run [`bt switch --global`](/docs/reference/cli/switch). If prompted, select the saved profile. Then select an organization and project accessible with that profile. If only one organization is available, `bt` selects it automatically.
Run [`bt status --all`](/docs/reference/cli/status) and confirm that the saved profiles, selected profile, organization, and project are correct.
Skip this step if you do not have scripts or saved commands that use `bt`.
Existing scripts may require two types of changes:
v0.16.0 changes several commands and flags, including replacing the `bt auth` command group with top-level commands. Update existing scripts as follows:
| Before v0.16.0 | Replacement |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bt auth login` | [`bt login`](/docs/reference/cli/login) |
| `bt auth logout` | [`bt logout`](/docs/reference/cli/logout) |
| `bt auth refresh` | [`bt login --refresh`](/docs/reference/cli/login) |
| `bt auth profiles` | [`bt status --all`](/docs/reference/cli/status) to verify saved credentials. [`bt profiles list`](/docs/reference/cli/profiles) lists local profiles and is available in v0.17.0 or later |
| `bt self update` | [`bt update`](/docs/reference/cli/update). Use the old command once if the installed version does not recognize `bt update` |
| `--fresh` on [`bt sync`](/docs/reference/cli/sync) or [`bt datasets pipeline`](/docs/reference/cli/datasets#bt-datasets-pipeline) | `--force`. The behavior is unchanged |
| `--api-key ` | The `BRAINTRUST_API_KEY` environment variable or a saved OAuth or API key profile created with [`bt login`](/docs/reference/cli/login). The flag is deprecated and hidden from help output in v0.16.0 and v0.17.x, then removed in v0.18.0 |
Starting in v0.16.0, a saved profile no longer provides an organization. Update affected scripts based on how they authenticate:
* If the script uses a saved profile, add `--profile --org `. An explicit `--profile` flag takes precedence over `BRAINTRUST_API_KEY`, so you do not need to unset the variable.
* If the script uses `BRAINTRUST_API_KEY`, leave it set and add `--org `. Do not pass `--profile`.
For commands scoped to a project, also add `--project `.
If you have an older tracing setup for [Claude Code](/docs/integrations/developer-tools/claude-code#migrate-from-an-older-plugin-version), [Codex](/docs/integrations/developer-tools/codex#upgrade), [OpenCode](/docs/integrations/developer-tools/opencode#upgrade), or [pi](/docs/integrations/developer-tools/pi#upgrade), follow its migration guide to preserve your settings when moving to `bt`-managed tracing. Grok and Antigravity use `bt`-managed tracing from their first release and do not require this migration.
### v0.18.0
For the full list of changes, see the [v0.18.0 changelog entry](/docs/changelog#bt-cli-releases-2).
Before v0.18.0, scripts and saved commands could pass an API key with the `--api-key` flag. Starting in v0.18.0, this flag is no longer supported. Update affected commands to use one of these authentication methods:
* **Environment API key:** Set `BRAINTRUST_API_KEY` in the command's environment, then remove the `--api-key` flag. For example, change:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt projects list --api-key "$BT_API_KEY" --org ""
```
to:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY="$BT_API_KEY" bt projects list --org ""
```
* **Saved profile:** Create or repair the profile with [`bt login`](/docs/reference/cli/login), then pass `--profile ` to commands that should use it. An explicit `--profile` flag takes precedence over `BRAINTRUST_API_KEY`.
Run one affected command after the change to confirm that it authenticates successfully.
### v0.19.0
For the full list of changes, see the [v0.19.0 changelog entry](/docs/changelog#bt-cli-releases).
This step applies only if your scripts or CI workflows run `bt login` with `BRAINTRUST_API_KEY` set. Other commands can continue using `BRAINTRUST_API_KEY` without changes.
Before v0.19.0, when [`bt login`](/docs/reference/cli/login) authenticated with an API key supplied through `BRAINTRUST_API_KEY`, it saved the key as a profile without asking for confirmation. Starting in v0.19.0, it requires confirmation before saving the environment key.
After upgrading, choose one of these options for each affected `bt login` flow:
* **Interactive login:** Leave `BRAINTRUST_API_KEY` set, run `bt login`, and confirm the prompt to save the key.
* **Non-interactive login:** Leave `BRAINTRUST_API_KEY` set and pass `--save-env-api-key`:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY="$BT_API_KEY" bt login --profile --save-env-api-key
```
Starting in `bt` v0.19.0, Claude Code and Codex no longer use `TRACE_TO_BRAINTRUST` to enable tracing. This applies even if you don't update the tracing plugin.
* If your tracing configuration already sets `trace_to_braintrust` to `true`, you don't need to change it.
* If you relied on `TRACE_TO_BRAINTRUST`, follow the [Claude Code migration](/docs/integrations/developer-tools/claude-code#migrate-from-an-older-plugin-version) or [Codex migration](/docs/integrations/developer-tools/codex#migrate-from-an-older-plugin-version) to enable tracing in the configuration file while preserving your settings.
If you use an OpenCode or pi tracing integration configured by a version of `bt` earlier than v0.19.0, its configuration may contain obsolete top-level destination and authentication fields. These can override settings written by newer versions of `bt` in the [`route` object](/docs/reference/cli/trace#tracing-configuration).
Starting in v0.19.0, [`bt trace enable`](/docs/reference/cli/trace#bt-trace-enable) removes those obsolete fields and updates the saved tracing settings in the global file. It does not migrate project-local files.
Follow the [OpenCode migration instructions](/docs/integrations/developer-tools/opencode#migrate-from-an-older-plugin-version) or [pi migration instructions](/docs/integrations/developer-tools/pi#migrate-from-an-older-extension-version) to preserve your settings and migrate both global and project-local files.
If a script or saved command passes `--dangerously-bypass-hook-trust` to `bt trace run codex`, update it before running it with v0.19.0 or higher. Before v0.19.0, `bt` could forward this option even though it conflicts with the managed hook and can produce duplicate Braintrust hook output. Starting in v0.19.0, `bt` rejects the combination before launching Codex.
Remove `--dangerously-bypass-hook-trust` from commands launched through [`bt trace run codex`](/docs/reference/cli/trace#bt-trace-run). If the Codex invocation requires that option, run Codex directly instead of through `bt trace run`.
With `bt` v0.19.0 or higher, [`bt trace enable claude`](/docs/reference/cli/trace#bt-trace-enable) warns if Claude's `settings.json` contains obsolete Braintrust tracing environment variables, but it does not remove them.
Follow the [Claude Code plugin migration](/docs/integrations/developer-tools/claude-code#migrate-from-an-older-plugin-version) to preserve your tracing destination and remove obsolete settings after verifying tracing.
### v0.19.2
For the full list of changes, see the [v0.19.2 changelog entry](/docs/changelog#bt-cli-releases).
Before v0.19.2, [`bt sync pull`](/docs/reference/cli/sync) used a three-day time window when `--window` and `BT_SYNC_WINDOW` were omitted. Starting in v0.19.2, project log pulls retain that default, but experiment and dataset pulls are unbounded.
Find scripts and saved commands that use `bt sync pull` with an `experiment` or `dataset` object reference and do not set `--window` or `BT_SYNC_WINDOW`.
To preserve the previous behavior, add `--window 3d` to each affected command or set `BT_SYNC_WINDOW=3d` in its environment. Leave the window unset only when you intend to pull all matching history.
For example:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt sync pull "experiment:" --window 3d
bt sync pull "dataset:" --window 3d
```
### v0.19.3
For the full list of changes, see the [v0.19.3 changelog entry](/docs/changelog#bt-cli-releases).
Starting in v0.19.3, `bt trace enable opencode` and `bt trace enable pi` install v2 of their tracing integrations instead of v1. Updating `bt` alone does not update an installed plugin or extension.
For an existing v1 installation, follow the [OpenCode migration instructions](/docs/integrations/developer-tools/opencode#migrate-from-an-older-plugin-version) or [pi migration instructions](/docs/integrations/developer-tools/pi#migrate-from-an-older-extension-version) before updating the integration. The guides explain how to preserve settings that v1 read from environment variables and how to migrate global and project-local configuration files.
For routine updates after completing the applicable migrations, use [`bt trace update`](/docs/reference/cli/trace#bt-trace-update) to preserve your tracing settings.
## Troubleshooting
Start by inspecting the saved profiles and selected context:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt status --all
```
This command verifies each saved profile, reports missing, expired, or invalid credentials, and shows the selected profile, organization, project, and configuration source.
Use the output to choose a troubleshooting path:
If the output is not what you expect, check the following:
* If you intend to use a saved profile, unset `BRAINTRUST_API_KEY` or pass `--profile `. [`bt status --all`](/docs/reference/cli/status) reports when the environment API key is overriding saved profiles.
* If `BRAINTRUST_PROFILE` is set, unset it or make sure it names the intended profile. It takes precedence over the profile saved by [`bt switch`](/docs/reference/cli/switch) unless you pass `--profile` explicitly.
To correct problems:
* Repair a saved profile with the applicable [`bt login`](/docs/reference/cli/login) command from the migration steps. The command updates the existing profile, so you do not need to delete and recreate it first.
* Correct organization and project context with [`bt switch`](/docs/reference/cli/switch) instead of editing the files directly.
* Check command-line flags and environment variables that can override saved values. See [Credential precedence](/docs/reference/cli/overview#credential-precedence) for authentication details.
If the environment variables are correct, inspect the following locations:
| Data | Default location | What to check |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Saved profile metadata | - macOS and Linux: `~/.config/bt/auth.json`
- Windows: `%APPDATA%\bt\auth.json`
| Confirm that the expected profile exists and uses the expected `auth_kind`. This file stores metadata, not credentials. Starting in v0.16.0, `bt` does not treat a legacy `org_name` value as active context. Starting in v0.19.0, `bt` automatically adds a stable ID for each profile under `profile_ids` |
| Saved credentials | The system credential store. If secure storage is unavailable:- macOS and Linux: `~/.config/bt/secrets.json`
- Windows: `%APPDATA%\bt\secrets.json`
| Do not copy, share, or edit stored credentials. Use [`bt status --all`](/docs/reference/cli/status) to check them and [`bt login`](/docs/reference/cli/login) to repair them |
| Global context | - macOS and Linux: `~/.config/bt/config.json`
- Windows: `%USERPROFILE%\.config\bt\config.json`
| Check the `profile`, `org`, `project`, and `project_id` values written by [`bt switch --global`](/docs/reference/cli/switch) |
| Project context | The nearest `.bt/config.json` found by searching upward from the current directory. `bt` stops after checking the Git repository root or your home directory | Check the `profile`, `org`, `project`, and `project_id` values. These values override the corresponding global values |
On macOS and Linux, `XDG_CONFIG_HOME` is an optional environment variable that changes where applications store configuration files. If it is set, `bt` uses `$XDG_CONFIG_HOME/bt/` instead of `~/.config/bt/`.
## Next steps
* [CLI overview](/docs/reference/cli/overview) for the full command reference and auth precedence.
* [bt releases](https://github.com/braintrustdata/bt/releases) for release artifacts and version history.