Skip to main content
This page covers breaking changes between bt versions. Find each version newer than your installed version and follow its migration steps in order. To update the CLI itself, run bt update.

​
v0.16.0

v0.16.0 changes authentication, renames several commands and flags, and adds bt trace for coding-agent tracing.

​
Authentication

In bt, a profile is a saved login. Previously, each profile was tied to one organization, so multi-org users needed a separate login per org. v0.16.0 decouples profiles from organizations. A profile now stores your credentials and app URL, and one login works across every org the account can access. Organization and project are selected separately with bt switch (which also prompts for a profile in interactive mode), or overridden per command with --org and --project. Most people need only one profile; add another when you sign in as a different user or work against a different deployment (e.g. self-hosted). Your saved credentials carry over automatically and do not need to be migrated. The --api-key flag is deprecated, hidden from help output, and will be removed soon; use BRAINTRUST_API_KEY or bt login instead. Breaking change: Your saved logins carry over, but the org that was saved with each login does not. Commands that previously inferred an org from the profile may prompt or fail until you run bt switch or pass --org. What to do:
  1. Run bt switch to select your org and project.
  2. Run bt status to verify the active profile, org, and credential source are correct.
  3. If you had separate profiles for each org under one account, you only need one now. Remove the extras with bt logout --profile <name>.
  4. In scripts, pass --org explicitly instead of relying on a profile to imply it. If profile auto-selection is ambiguous, set BRAINTRUST_PROFILE or pass --profile.
  5. If BRAINTRUST_API_KEY is set in your shell, bt uses it instead of your saved profile. This is fine if intentional (e.g. CI). If not, check for leftover exports and unset the variable, or pass --prefer-profile to use your saved login.
  6. If you pass --api-key on the command line, switch to BRAINTRUST_API_KEY or bt login. The flag still works, but it is deprecated, hidden from help output, and will be removed soon.
For the full credential resolution order, see Credential precedence.

​
Renamed commands and flags

The bt auth command group is replaced by top-level commands, --fresh is renamed to --force on sync and pipeline commands, and --api-key is deprecated, hidden from help output, and will be removed soon. Breaking changes:
  • bt auth no longer exists. Scripts that call it fail.
  • --fresh is gone on bt sync pull, bt sync push, and bt datasets pipeline push.
What to do:
  • Replace bt auth calls with the new spellings above.
  • Replace --fresh with --force on bt sync and bt datasets pipeline. Behavior is unchanged.
  • bt self update still runs but is undocumented. Switch to bt update.
  • Replace --api-key with BRAINTRUST_API_KEY or bt login. The flag still works, but it is deprecated, hidden from help output, and will be removed soon.

​
Coding-agent tracing

bt trace manages tracing for Claude Code, Codex, OpenCode, and pi. Each agent gets a Braintrust plugin that observes sessions and sends trace data through bt. Authentication is handled by bt login or BRAINTRUST_API_KEY, the same as any other bt command, so there is nothing separate to configure for credentials. Breaking change: The new plugins replace the earlier tracing plugins. Settings move from environment variables to a config file managed by bt trace setup, and credentials are handled by bt instead of the plugin. If you use the old versions of the plugins, follow the steps below to upgrade. What to do:
  1. Install bt and run bt login.
  2. Run bt trace setup <agent> --project <name> to install the new plugin and configure tracing.
  3. Follow the upgrade section in your agent’s guide for details on migrating from the old plugin: Claude Code, Codex, OpenCode, pi.

​
Next steps