> ## 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 Security and Updates

> Understand how bb stores credentials, checks for updates, and uses provider hooks

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

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

## Update Checks

Check for a newer CLI release:

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

Install the latest release over the current executable:

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

Direct installs auto-update by default for normal user-facing commands. To opt
out of startup auto-update, set:

```bash theme={null}
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.

<Info>
  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.
</Info>

Run a local health report when update behavior looks wrong:

```bash theme={null}
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:

```text theme={null}
https://api.buildbetter.app/v3/rest/cli/bb
```

Immutable CLI binaries are private GitHub Release assets streamed by the API from:

```text theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.