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.

​
Local Credentials

bb auth login stores CLI configuration under ~/.bb/config.json. The file includes the selected BuildBetter environment, API URL, OIDC client ID, and local tokens. Keep this file private to your user account. Do not paste it into support tickets, chat messages, logs, or agent prompts. bb auth status prints the config path and warns if an older config file is group/world-readable. If you see a permission warning, run: 
chmod 600 ~/.bb/config.json

​
Update Checks

Check for a newer CLI release: 
bb update --check
Install the latest release over the current executable: 
bb update
Direct installs auto-update by default for normal user-facing commands. To opt out of startup auto-update, set: 
export BB_AUTO_UPDATE=0
When auto-update is enabled, the current invocation continues running on the old process image. The next bb invocation uses the updated binary.
Package-manager installs are expected to use package-manager update commands once Homebrew and npm distribution are ready. A Homebrew-managed or npm-managed bb refuses in-place self-update and directs you to the package-manager upgrade command instead.
Run a local health report when update behavior looks wrong: 
bb doctor
bb doctor --json
The doctor report includes the detected install source, current executable path, auth status, release-manifest reachability, hook health, and local error-log status.

​
Release Download Hosts

The BuildBetter API owns release manifests, installer scripts, and hook bootstrap scripts under: 
https://api.buildbetter.app/v3/rest/cli/bb
Immutable CLI binaries are private GitHub Release assets streamed by the API from: 
https://api.buildbetter.app/v3/rest/cli/bb/releases/<version>/artifacts/<target>/download
For example, a macOS Apple Silicon release artifact is fetched from a versioned path such as https://api.buildbetter.app/v3/rest/cli/bb/releases/0.1.0/artifacts/aarch64-apple-darwin/download. The API uses BuildBetter’s server GitHub App to read the private release asset, so customers never need GitHub credentials. Installers and updaters should follow the manifest and verify the published checksum before replacing a local binary.

​
Hook Bootstrap Behavior

Provider hooks are designed to avoid noisy output at the end of AI coding turns. The default installed hook fetches BuildBetter’s hook bootstrap script with curl, checks for a local CLI install, attempts a quiet update, and then runs: 
bb hook stop --provider <provider> --cwd "$PWD" --quiet
Codex Stop hooks require JSON on stdout. In quiet Codex mode, bb returns {"continue":true,"suppressOutput":true} after a successful upload attempt. If hook sync fails or the remote bootstrap cannot run, it returns a short systemMessage such as BuildBetter hook failed. or BuildBetter CLI is not authenticated. Run bb auth login. without breaking the provider transcript. Hook stderr is written to ~/.bb/logs/error-<timestamp>.log. If you install hooks with --global, bb writes user-level provider config and adds a repo-root guard. If you install with --direct-bb, the hook invokes the local bb binary directly instead of fetching the remote bootstrap script.

​
Feedback Submissions

bb feedback sends CLI feedback through BuildBetter’s feedback API. It targets the staging feedback endpoint for the production CLI release because BuildBetter dogfoods the full application in staging, and it includes only the message plus structured context such as reporter type, provider, CLI version, OS/architecture, git repository, branch, commit, and pull-request metadata when available. Do not include secrets, customer data, bearer tokens, or full private transcript payloads in the feedback message. Use --dry-run --json to inspect the payload before sending.

​
Release Integrity Roadmap

Before general availability, BuildBetter is hardening CLI releases with:
  • Multi-platform release artifacts.
  • SHA-256 checksums in release manifests.
  • Signed and notarized macOS artifacts.
  • Build provenance attestations.
  • Manifest-driven update channels and rollback policy.
  • Installer and updater verification before replacing local binaries.
Until that work is complete, use only install and update commands provided by your BuildBetter team.

​
Support Bundles

When support asks for diagnostics, create a local redacted bundle: 
bb support bundle --output /tmp/bb-support.zip
The archive includes a redacted doctor report, metadata, a redacted auth config summary, and recent local agent-session submission errors when present. Review the archive before sharing it outside your machine.