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

> Breaking changes and migration steps for major bt CLI releases.

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`](/docs/reference/cli/update).

## v0.16.0

v0.16.0 changes [authentication](#authentication), [renames several commands and flags](#renamed-commands-and-flags), and adds [`bt trace`](/docs/reference/cli/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`](/docs/reference/cli/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](/docs/admin/self-hosting)).

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`](/docs/reference/cli/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`](/docs/reference/cli/switch) or pass `--org`.

**What to do:**

1. Run [`bt switch`](/docs/reference/cli/switch) to select your org and project.
2. Run [`bt status`](/docs/reference/cli/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`](/docs/reference/cli/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`](/docs/reference/cli/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](/docs/reference/cli/overview#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.

| Before v0.16.0     | v0.16.0 and later                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `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) in v0.16.0 or later, or [`bt profiles list`](/docs/reference/cli/profiles) in v0.17.0 or later |
| `bt self update`   | [`bt update`](/docs/reference/cli/update)                                                                                                 |

**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`](/docs/reference/cli/sync) and [`bt datasets pipeline`](/docs/reference/cli/datasets#bt-datasets-pipeline). Behavior is unchanged.
* `bt self update` still runs but is undocumented. Switch to [`bt update`](/docs/reference/cli/update).
* Replace `--api-key` with `BRAINTRUST_API_KEY` or [`bt login`](/docs/reference/cli/login). The flag still works, but it is deprecated, hidden from help output, and will be removed soon.

### Coding-agent tracing

[`bt trace`](/docs/reference/cli/trace) manages tracing for [Claude Code](/docs/integrations/developer-tools/claude-code), [Codex](/docs/integrations/developer-tools/codex), [OpenCode](/docs/integrations/developer-tools/opencode), and [pi](/docs/integrations/developer-tools/pi). Each agent gets a Braintrust plugin that observes sessions and sends trace data through `bt`. Authentication is handled by [`bt login`](/docs/reference/cli/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`](/docs/reference/cli/trace#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`](/docs/reference/cli/quickstart#install) and run [`bt login`](/docs/reference/cli/login).
2. Run [`bt trace setup <agent> --project <name>`](/docs/reference/cli/trace#bt-trace-setup) 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](/docs/integrations/developer-tools/claude-code#upgrade), [Codex](/docs/integrations/developer-tools/codex#upgrade), [OpenCode](/docs/integrations/developer-tools/opencode#upgrade), [pi](/docs/integrations/developer-tools/pi#upgrade).

## 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 complete release notes.