Skip to main content
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

Record the version so you can identify the migration instructions that apply after updating.
2

Record authentication and context

Complete this step only if your installed version is older than v0.16.0. Otherwise, continue to 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 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:
If your installed version does not recognize bt update, run this command instead:

​
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.
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.
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. 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 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". 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.
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.
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 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).
  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 and select an organization and project accessible to your API key. If only one organization is available, bt selects it automatically.
4

Verify the migrated setup

Run bt status --all and confirm that the saved profiles, selected profile, organization, and project are correct.
5

Update scripts and automation if needed

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:
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 <PROFILE> --org <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 <ORG>. Do not pass --profile.
For commands scoped to a project, also add --project <PROJECT>.
6

Identify coding-agent migrations

If you have an older tracing setup for Claude Code, Codex, OpenCode, or pi, 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.
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:
    to:
  • Saved profile: Create or repair the profile with bt login, then pass --profile <your-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.
1

Update scripts that run bt login

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 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:
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 or Codex migration 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.Starting in v0.19.0, 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 or pi migration instructions 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. 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 warns if Claude’s settings.json contains obsolete Braintrust tracing environment variables, but it does not remove them.Follow the Claude Code plugin migration 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.
Before v0.19.2, bt sync pull 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:

​
v0.19.3

For the full list of changes, see the v0.19.3 changelog entry.
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 or pi migration instructions 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 to preserve your tracing settings.

​
Troubleshooting

Start by inspecting the saved profiles and selected context:
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 <PROFILE>. bt status --all 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 unless you pass --profile explicitly.
To correct problems:
  • Repair a saved profile with the applicable bt 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 instead of editing the files directly.
  • Check command-line flags and environment variables that can override saved values. See Credential precedence for authentication details.
If the environment variables are correct, inspect the following locations:
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 for the full command reference and auth precedence.
  • bt releases for release artifacts and version history.