> ## Documentation Index > Fetch the complete documentation index at: https://docs.braintrust.dev/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 **1. Check the installed version of bt** ```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. **2. Record authentication and context** > [!NOTE] > > 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`](https://docs.braintrust.dev/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: > [tab] Standalone > > 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`](https://docs.braintrust.dev/reference/cli/update), run this command instead: > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > bt self update > bt --version > ``` > [tab] npm > > 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 > ``` > > > [!NOTE] > > > > 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. > [tab] pnpm > > 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 > ``` > > > [!NOTE] > > > > 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. > [tab] mise > > 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 > ``` > [tab] Windows > > 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`](https://docs.braintrust.dev/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 > [!NOTE] > > For the full list of changes, see the [v0.16.0 changelog entry](https://docs.braintrust.dev/changelog.md#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`](https://docs.braintrust.dev/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. **1. Verify authentication** Verify each credential source you plan to keep using: * **Saved profiles:** Run [`bt status --all`](https://docs.braintrust.dev/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`](https://docs.braintrust.dev/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"`](https://docs.braintrust.dev/reference/cli/projects). Replace `your-org` with the organization you recorded before updating. If the command returns the organization's projects, the key works. **2. Repair authentication if needed** 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. > [tab] Environment API key > > If `BRAINTRUST_API_KEY` is missing or invalid, replace it with a valid Braintrust API key in the environment where you run `bt`. > > > [!TIP] > > > > For a custom or self-hosted deployment, also set `BRAINTRUST_API_URL` and `BRAINTRUST_APP_URL` in the environment where you run `bt`. > [tab] Saved OAuth profile > > 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 > ``` > > > [!TIP] > > > > For a custom or self-hosted deployment, add its `--api-url` and `--app-url` to the login command. > [tab] Saved API key profile > > 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. > > > [!TIP] > > > > For a custom or self-hosted deployment, add its `--api-url` and `--app-url` to the login command. **3. Choose credentials, organization, and project** Choose the credentials, organization, and project that `bt` should use for subsequent commands. To save your selection globally, use [`bt switch --global`](https://docs.braintrust.dev/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`](https://docs.braintrust.dev/reference/cli/init)). > [tab] Environment API key > > 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`](https://docs.braintrust.dev/reference/cli/switch) and select an organization and project accessible to your API key. If only one organization is available, `bt` selects it automatically. > [tab] Saved profile > > 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`](https://docs.braintrust.dev/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. **4. Verify the migrated setup** Run [`bt status --all`](https://docs.braintrust.dev/reference/cli/status) and confirm that the saved profiles, selected profile, organization, and project are correct. **5. Update scripts and automation if needed** > [!NOTE] > > Skip this step if you do not have scripts or saved commands that use `bt`. Existing scripts may require two types of changes: > [accordion] Replace old commands and flags > > 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`](https://docs.braintrust.dev/reference/cli/login) | > | `bt auth logout` | [`bt logout`](https://docs.braintrust.dev/reference/cli/logout) | > | `bt auth refresh` | [`bt login --refresh`](https://docs.braintrust.dev/reference/cli/login) | > | `bt auth profiles` | [`bt status --all`](https://docs.braintrust.dev/reference/cli/status) to verify saved credentials. [`bt profiles list`](https://docs.braintrust.dev/reference/cli/profiles) lists local profiles and is available in v0.17.0 or later | > | `bt self update` | [`bt update`](https://docs.braintrust.dev/reference/cli/update). Use the old command once if the installed version does not recognize `bt update` | > | `--fresh` on [`bt sync`](https://docs.braintrust.dev/reference/cli/sync) or [`bt datasets pipeline`](https://docs.braintrust.dev/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`](https://docs.braintrust.dev/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 | > [accordion] Specify credentials, organization, and project > > 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 `. **6. Identify coding-agent migrations** If you have an older tracing setup for [Claude Code](https://docs.braintrust.dev/integrations/developer-tools/claude-code.md#migrate-from-an-older-plugin-version), [Codex](https://docs.braintrust.dev/integrations/developer-tools/codex.md#upgrade), [OpenCode](https://docs.braintrust.dev/integrations/developer-tools/opencode.md#upgrade), or [pi](https://docs.braintrust.dev/integrations/developer-tools/pi.md#upgrade), follow its migration guide to preserve your settings when moving to `bt`-managed tracing. Cursor, Grok, Antigravity, and Muse Code use `bt`-managed tracing from their first release and do not require this migration. ### v0.18.0 > [!NOTE] > > For the full list of changes, see the [v0.18.0 changelog entry](https://docs.braintrust.dev/changelog.md#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`](https://docs.braintrust.dev/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 > [!NOTE] > > For the full list of changes, see the [v0.19.0 changelog entry](https://docs.braintrust.dev/changelog.md#bt-cli-releases). **1. Update scripts that run bt login** > [!NOTE] > > 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`](https://docs.braintrust.dev/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 ``` **2. Enable tracing in the configuration file** 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](https://docs.braintrust.dev/integrations/developer-tools/claude-code.md#migrate-from-an-older-plugin-version) or [Codex migration](https://docs.braintrust.dev/integrations/developer-tools/codex.md#migrate-from-an-older-plugin-version) to enable tracing in the configuration file while preserving your settings. **3. Refresh existing OpenCode and pi tracing configuration** 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](https://docs.braintrust.dev/reference/cli/trace#tracing-configuration). Starting in v0.19.0, [`bt trace enable`](https://docs.braintrust.dev/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](https://docs.braintrust.dev/integrations/developer-tools/opencode.md#migrate-from-an-older-plugin-version) or [pi migration instructions](https://docs.braintrust.dev/integrations/developer-tools/pi.md#migrate-from-an-older-extension-version) to preserve your settings and migrate both global and project-local files. **4. Update affected Codex tracing commands** 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`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-run). If the Codex invocation requires that option, run Codex directly instead of through `bt trace run`. **5. Address Claude Code tracing warnings** With `bt` v0.19.0 or higher, [`bt trace enable claude`](https://docs.braintrust.dev/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](https://docs.braintrust.dev/integrations/developer-tools/claude-code.md#migrate-from-an-older-plugin-version) to preserve your tracing destination and remove obsolete settings after verifying tracing. ### v0.19.2 > [!NOTE] > > For the full list of changes, see the [v0.19.2 changelog entry](https://docs.braintrust.dev/changelog.md#bt-cli-releases). Before v0.19.2, [`bt sync pull`](https://docs.braintrust.dev/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. **1. Review experiment and dataset pull commands** 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`. **2. Choose a time 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 > [!NOTE] > > For the full list of changes, see the [v0.19.3 changelog entry](https://docs.braintrust.dev/changelog.md#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](https://docs.braintrust.dev/integrations/developer-tools/opencode.md#migrate-from-an-older-plugin-version) or [pi migration instructions](https://docs.braintrust.dev/integrations/developer-tools/pi.md#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`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-update) to preserve your tracing settings. ### v0.20.0 > [!NOTE] > > For the full list of changes, see the [v0.20.0 changelog entry](https://docs.braintrust.dev/changelog.md#bt-cli-releases). Before v0.20.0, `bt topics config enable` and `bt topics config set` accepted a `--relabel-overlap` flag. Starting in v0.20.0, passing `--relabel-overlap` produces an error. The flag was deprecated and ignored since data plane v2.15.0. Remove `--relabel-overlap` from any scripts or saved commands that pass it to `bt topics config enable` or `bt topics config set`. > [!NOTE] > > For self-hosted deployments on data plane before v2.15.0, Topics still honors the relabel overlap and defaults an omitted value to one hour. If your scripts pass a non-default overlap, removing the flag reverts Topics to the one-hour default. To keep a custom overlap, upgrade your data plane to v2.15.0 or later, which ignores the setting, before removing the flag, or set **Relabel overlap (seconds)** in the Topics automation settings. Data plane v2.15.0 and later ignore the setting, so removing the flag is safe there. ### v0.26.0 > [!NOTE] > > For the full list of changes, see the [v0.26.0 changelog entry](https://docs.braintrust.dev/changelog.md#bt-cli-releases). Starting in v0.26.0, `bt` reads its command-specific environment variables with the `BRAINTRUST_` prefix instead of `BT_`, matching the Braintrust SDKs. For example, `BT_EVAL_WATCH` is now `BRAINTRUST_EVAL_WATCH`, and `BT_FUNCTIONS_PUSH_IF_EXISTS` is now `BRAINTRUST_FUNCTIONS_PUSH_IF_EXISTS`. The earlier `BT_` names still work as deprecated aliases, so no immediate change is required. If both names are set, `bt` uses the `BRAINTRUST_` value and ignores the `BT_` value. Coding-agent tracing follows the same rule. For example, `BT_DAEMON_CONFIG` is now `BRAINTRUST_DAEMON_CONFIG`. To update, replace the `BT_` prefix with `BRAINTRUST_` for these variables in your shell profiles, `.env` files, and CI/CD settings. Run `bt --help` to see the variable names a command reads. Don't rename `BT_BINARY_PATH` or `BT_SKIP_DOWNLOAD`. The `bt` launcher in the `braintrust` npm package reads them, and they keep the `BT_` prefix. ## 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: > [accordion] Fix authentication or context > > 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`](https://docs.braintrust.dev/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`](https://docs.braintrust.dev/reference/cli/switch) unless you pass `--profile` explicitly. > > To correct problems: > > * Repair a saved profile with the applicable [`bt login`](https://docs.braintrust.dev/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`](https://docs.braintrust.dev/reference/cli/switch) instead of editing the files directly. > * Check command-line flags and environment variables that can override saved values. See [Credential precedence](https://docs.braintrust.dev/reference/cli/overview.md#credential-precedence) for authentication details. > [accordion] Inspect configuration files > > 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, v0.22.2 or later: `%USERPROFILE%\.braintrust\auth\credentials.dpapi`, encrypted together with credentials
  • Windows, earlier versions: `%APPDATA%\bt\auth.json`
| Confirm that the expected profile exists and uses the expected `auth_kind`. This file stores metadata, not credentials, except on Windows with v0.22.2 or later. 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 |
  • macOS and Linux: the system credential store, or `~/.config/bt/secrets.json` if secure storage is unavailable
  • Windows, v0.22.2 or later: `%USERPROFILE%\.braintrust\auth\credentials.dpapi`, with no plaintext fallback
  • Windows, earlier versions: `%APPDATA%\bt\secrets.json`
| Do not copy, share, or edit stored credentials. Use [`bt status --all`](https://docs.braintrust.dev/reference/cli/status) to check them and [`bt login`](https://docs.braintrust.dev/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`](https://docs.braintrust.dev/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 | > > > [!NOTE] > > > > 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](https://docs.braintrust.dev/reference/cli/overview.md) for the full command reference and auth precedence. * [bt releases](https://github.com/braintrustdata/bt/releases) for release artifacts and version history. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.