## TL;DR

A dead Braintrust CLI is almost always one of three things: the API key is missing or expired, the CLI is stale, or the command ran outside a Braintrust-initialized project. Check `braintrust --version`, re-run `braintrust login` with a fresh key, and confirm you are in the right project directory. Nine times out of ten one of those fixes it.

## The query

```text
braintrust cli not working
```

## Use this when

- `braintrust` commands error, hang, or print auth failures.
- `braintrust login` does not stick between sessions.
- Eval runs from the CLI never reach the Braintrust dashboard.

## Not for

- Problems inside the Braintrust web UI itself (login there is a separate auth).
- SDK-side failures in Python/TS eval code; this is about the CLI tool.
- Self-hosted Braintrust proxy networking; check the proxy first.

## Steps

1. Confirm the CLI is installed and current: run `braintrust --version` and compare against the latest release. Expected output: a version number at or near the latest; if the command is not found, reinstall per the official install docs.
2. Re-authenticate: run `braintrust login` and paste a fresh API key from your Braintrust org settings. Expected output: a success message and the org name; if it fails, the key is wrong or revoked, so generate a new one.
3. Check the key is visible to the shell: run `env | grep -i braintrust` to confirm `BRAINTRUST_API_KEY` is set. Expected output: the variable listed; if absent, export it in your shell profile so it survives new sessions.
4. Run from the right directory: many commands need the project config. Run `pwd` and confirm you are inside the project that was initialized with `braintrust init`. Expected output: the project directory; move there and retry.
5. Re-run the failing command with verbose output (`--verbose` or the debug flag the CLI offers) and read the first error line, not the last. Expected output: the root cause surfaces, usually auth, network, or a bad project slug.

## Provenance

(appended by publisher)

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cyR8raZmHOPZTihNEzwd7Q