> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Troubleshooting

> Fix common BuildBetter CLI install, auth, update, and hook issues

## `bb` Is Not Found

Check where the binary was installed:

```bash theme={null}
ls -l "$HOME/.local/bin/bb"
```

If the file exists, add `~/.local/bin` to your `PATH`:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

Then verify:

```bash theme={null}
command -v bb
bb --version
bb doctor
```

## Login Does Not Complete

Run:

```bash theme={null}
bb auth status
bb auth login
```

If the browser flow cannot open, copy the printed login URL into your browser. If login succeeds but commands still fail, confirm that `bb auth status` shows the expected environment, email, organization key, and API base URL.

If `bb auth status` warns that `~/.bb/config.json` is group/world-readable, run:

```bash theme={null}
chmod 600 ~/.bb/config.json
```

## The Hook Does Not Upload Sessions

Run the install command again from the repository where you use your provider:

```bash theme={null}
bb agent-sessions hooks install --codex
bb agent-sessions hooks install --claude
```

Inspect hook health:

```bash theme={null}
bb agent-sessions hooks doctor --codex
bb agent-sessions hooks doctor --claude
```

Repair a managed hook without changing unrelated provider hooks:

```bash theme={null}
bb agent-sessions hooks repair --codex
bb agent-sessions hooks repair --claude
```

Hook stderr is written to timestamped files under `~/.bb/logs/`. Check the latest file when Codex shows `BuildBetter hook failed.`:

```bash theme={null}
ls -t ~/.bb/logs/error-*.log | head -1 | xargs tail -100
```

Check that you are signed in:

```bash theme={null}
bb auth status
```

Provider hooks only upload when local CLI auth configuration exists. If `~/.bb/config.json` is missing or empty, the Codex hook returns a short authentication warning.

Codex may show `BuildBetter CLI is not authenticated. Run bb auth login.` from the hook. Sign in with:

```bash theme={null}
bb auth login
```

If Codex reports that the Stop hook failed, repair the hook so it uses the current quiet JSON output path:

```bash theme={null}
bb agent-sessions hooks repair --codex
```

If your provider runs from a shared user profile rather than the repository's config layer, inspect and repair the global hook target:

```bash theme={null}
bb agent-sessions hooks doctor --codex --global
bb agent-sessions hooks repair --codex --global
```

## Updates Fail

Check whether BuildBetter can return the latest release metadata:

```bash theme={null}
bb update --check
```

If your network uses a proxy, VPN, or custom certificate inspection, make sure the machine can reach:

* `https://api.buildbetter.app`
* your BuildBetter auth domain

`api.buildbetter.app` returns manifests, installers, hook bootstrap scripts, and
the binary artifact streams under `/v3/rest/cli/bb/releases/<version>/...`. The
API reads private GitHub Release assets server-side, so customers do not need
direct network access to private BuildBetter GitHub repositories.

If `bb` was installed through Homebrew or npm after those channels become available, use the package-manager upgrade command shown by `bb update --check` instead of forcing an in-place update.

## Collect Diagnostics for Support

Share command output only after checking it for sensitive values:

```bash theme={null}
bb --version
bb auth status
bb update --check
bb doctor --json
command -v bb
```

When support requests a diagnostic archive:

```bash theme={null}
bb support bundle --output /tmp/bb-support.zip
```

Do not share `~/.bb/config.json`, bearer tokens, refresh tokens, native session files, or full AI transcript payloads unless BuildBetter support gives you a secure upload path.

## Send Feedback From the CLI

If the issue is a product or workflow problem rather than a support archive request, send it directly:

```bash theme={null}
bb feedback --agent --provider codex --message "The hook summary is missing the uploaded session ID."
bb feedback --human --message "The install docs need fish shell PATH instructions." --email user@example.com
```

Use `--category`, `--severity`, and `--agent-session-id` when an agent can provide structured context. Use `--dry-run --json` first if you need to inspect the payload.