Skip to main content

​
bb Is Not Found

Check where the binary was installed:
If the file exists, add ~/.local/bin to your PATH:
Then verify:

​
Login Does Not Complete

Run:
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:

​
The Hook Does Not Upload Sessions

Run the install command again from the repository where you use your provider:
Inspect hook health:
Repair a managed hook without changing unrelated provider hooks:
Hook stderr is written to timestamped files under ~/.bb/logs/. Check the latest file when Codex shows BuildBetter hook failed.:
Check that you are signed in:
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:
If Codex reports that the Stop hook failed, repair the hook so it uses the current quiet JSON output path:
If your provider runs from a shared user profile rather than the repository’s config layer, inspect and repair the global hook target:

​
Updates Fail

Check whether BuildBetter can return the latest release metadata:
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:
When support requests a diagnostic archive:
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:
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.