Development
bb-cli
Use this when controlling bb. The bb CLI lets you inspect, create, and orchestrate bb threads, automations, projects, providers, and environments.
davidondrej · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add davidondrej/skills --skill bb-cliAbout this skill
name: bb-cli description: Use this when controlling bb. The bb CLI lets you inspect, create, and orchestrate bb threads, automations, projects, providers, and environments.
bb CLI
Use bb when controlling bb itself: inspect current context, coordinate threads,
message agents, or inspect projects, providers, and environments.
Start With Context
- Use
bb statusto identify the current project, thread, and environment. - Prefer
--jsonwhen command output will drive follow-up work. - Run
bb guidefor the system overview andbb guide <chapter>for full command reference. - A standalone
bbCLI with no connection env targets the default local server athttp://127.0.0.1:38886and host daemon port38887. SetBB_SERVER_URLandBB_HOST_DAEMON_PORTonly for remote or non-default targets. The Add machine installer injects its enrolled daemon's selected local API port automatically and atomically reserves it across default and custom machine data directories. - The main server and source Vite app bind to loopback by default. Use bb
connect or a private Tailscale Serve URL for remote browsers and execution
machines.
--server-bind-host 0.0.0.0is a compatibility escape hatch only: the public API is unauthenticated and permits command execution and file reads, so wildcard binding requires a trusted network boundary. The startup listener andapprows then showhttp://0.0.0.0:<port>; health checks and the colocated daemon still use loopback. This opt-in is IPv4-only. Containers must also publish the port to the host.
Environment Setup Script
- To make a repo work with bb worktrees, run
bb guide environments. It documents the repo-level.bb-env-setup.shsetup hook and the.worktreeincludefile. - A new worktree checks out tracked files only. Commit a
.worktreeincludefile at the repo root to list untracked files, such as.env, that bb must copy from the source checkout. It uses gitignore pattern syntax. bb copies the matches before it runs.bb-env-setup.sh.
Remote Client
bb-app client ssh-target set <server-origin> <ssh-target>configures the local helper to open files from a remote bb server in local editors. The SSH target is the value that works afterssh, such asdevboxoruser@devbox.- These mappings live on the client machine in
<dataDir>/client.json; the CLI resolves the server's host ID when writing the mapping, and the remote server does not read the file. - Use
bb-app client ssh-target list --jsonto inspect mappings.
App Settings
BB_INFERENCEselects the shared model for server-side helper completions, including thread titles and commit subjects. It defaults tocodex/gpt-5.6-luna; set an override withbb-app config set BB_INFERENCE <provider/model>.BB_INFERENCE_FALLBACKselects the helper model used after a transient primary timeout, rate limit, or service-unavailable failure. It defaults tocodex/gpt-5.4-mini; set it withbb-app config set BB_INFERENCE_FALLBACK <provider/model>.BB_TRANSCRIPTIONselects the voice transcription model. It defaults tocodex/gpt-transcribe; set an override withbb-app config set BB_TRANSCRIPTION <provider/model>.bb-app configandbb-app envreload runtime settings in a running server, but the CLI identifies server and launcher settings that are startup-only, including binding/ports, data and the dev-app port, telemetry, inherited skill roots, andBB_FF_*flags.BB_LOG_LEVELis also startup-only. Usebb-app config, notbb-app env, to changeBB_APP_URL,BB_INFERENCE,BB_INFERENCE_FALLBACK, orBB_TRANSCRIPTIONlive. After a startup-only change, runbb-app stop && bb-app startor restart the desktop app. Until then, a server previously bound to0.0.0.0remains exposed even ifBB_SERVER_BIND_HOSTwas changed or unset.- Settings → General holds server-backed app-wide preferences. For details, read
references/app-settings.md(in this skill's directory). - Keep Awake is a standalone builtin plugin. Use
bb keep-awake enableandbb keep-awake disableto configure its macOS idle-sleep assertion. Inspect it withbb keep-awake status [--json]. Target hosts withbb keep-awake hosts allorbb keep-awake hosts <host-id>.... - The
showUnhandledProviderEventsGeneral preference defaults to false and exposes raw provider events that bb does not yet understand in packaged builds. Development builds always show those diagnostic rows. Update it withbb settings general showUnhandledProviderEvents <true|false>. - The
steerActiveThreadOnEnterGeneral preference defaults to false. Outside an open composer typeahead menu, enable it to make Enter steer a running thread and Command+Enter queue a follow-up; when disabled, those actions are reversed. Shift+Enter inserts a newline, while zen mode also makes unmodified Enter insert one. On coarse-pointer touch devices, the software keyboard keeps Return as a newline; iPadOS WebKit preserves the Enter shortcuts for a connected Magic Keyboard. Update the preference withbb settings general steerActiveThreadOnEnter <true|false>. - Settings → Keyboard records server-backed per-command shortcut overrides.
The
showKeyboardHintspreference controls the delayed badges shown while holding Command or Control and defaults to true; update it withbb settings keyboard hints <true|false>. Reset returns to bb's current default; Clear disables the command. Non-native actions apply in browser and desktop clients, and desktop menu accelerators use the same resolved bindings. For details, readreferences/app-settings.md. - Use
bb settings show,bb settings general,bb settings experiment,bb settings keyboard,bb settings usage, andbb settings versionto inspect or change these server-backed values from agents. Passbb settings usage --machine <id-or-name>to read p