Skip to main content

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.

​
bb Is Not Found

Check where the binary was installed: 
ls -l "$HOME/.local/bin/bb"
If the file exists, add ~/.local/bin to your PATH: 
export PATH="$HOME/.local/bin:$PATH"
Then verify: 
command -v bb
bb --version
bb doctor

​
Login Does Not Complete

Run: 
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: 
chmod 600 ~/.bb/config.json

​
The Hook Does Not Upload Sessions

Run the install command again from the repository where you use your provider: 
bb agent-sessions hooks install --codex
bb agent-sessions hooks install --claude
Inspect hook health: 
bb agent-sessions hooks doctor --codex
bb agent-sessions hooks doctor --claude
Repair a managed hook without changing unrelated provider hooks: 
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.: 
ls -t ~/.bb/logs/error-*.log | head -1 | xargs tail -100
Check that you are signed in: 
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: 
bb auth login
If Codex reports that the Stop hook failed, repair the hook so it uses the current quiet JSON output path: 
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: 
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: 
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: 
bb --version
bb auth status
bb update --check
bb doctor --json
command -v bb
When support requests a diagnostic archive: 
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: 
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.