bb-cli

# 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 status` to identify the current project, thread, and environment. - Prefer `--json` when command output will drive follow-up work. - Run `bb guide` for the system overview and `bb guide <chapter>` for full command reference. - A standalone `bb` CLI with no connection env targets the default local server at `http://127.0.0.1:38886` and host daemon port `38887`. Set `BB_SERVER_URL` and `BB_HOST_DAEMON_PORT` only for remote or non-default targets. ## Environment Setup Script - To make a repo work with bb worktrees, run `bb guide environments`. It documents the repo-level `.bb-env-setup.sh` setup hook. ## 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 after `ssh`, such as `devbox` or `user@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 --json` to inspect mappings. ## App Settings - Settings → General holds server-backed app-wide preferences, such as the macOS-only "Caffeinate" toggle. For details, read `references/app-settings.md` (in this skill's directory). - The `showUnhandledProviderEvents` General 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 with `bb settings general showUnhandledProviderEvents <true|false>`. - The `steerActiveThreadOnEnter` General preference defaults to false. Enable it to make Enter steer a running thread and Command+Enter queue a follow-up; when disabled, those actions are reversed. Update it with `bb settings general steerActiveThreadOnEnter <true|false>`. - Settings → Keyboard records server-backed per-command shortcut overrides. The `showKeyboardHints` preference controls the delayed badges shown while holding Command or Control and defaults to true; update it with `bb 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, read `references/app-settings.md`. - Use `bb settings show`, `bb settings general`, `bb settings experiment`, `bb settings keyboard`, `bb settings usage`, and `bb settings version` to inspect or change these server-backed values from agents. Pass `bb settings usage --machine <id-or-name>` to read provider limits from a specific connected machine instead of the primary machine. - The default-off `toolsHub` experiment exposes the unified Skills, Plugins, and Automations management UI. Change it with `bb settings experiment toolsHub <true|false>`. It does not load or unload tools. - Thread timeline windows are capped by event count as well as by user-message count (`BB_FF_TIMELINE_WINDOW_EVENT_BUDGET`, default 1500), because a thread with few user messages but many events would otherwise reproject its whole history on every timeline request, blocking the server event loop and delaying the daemon endpoints the agent awaits between tool calls. A turn still running is cut at the budget as well, so a very long turn costs the budget per update rather than growing without limit; a finished turn is rendered whole. Older activity loads automatically as you scroll toward the top; nothing becomes unreachable. ## Agent Instructions - Add `AGENTS.md` to the bb data dir (usually `~/.bb/AGENTS.md`) to inject user-level default instructions for every provider-backed thread across all projects. - Add `.bb/AGENTS.md` at a workspace root to inject repo-specific instructions into every thread that runs there. Track the workspace file with git so fresh managed worktrees include it. - bb appends data-dir instructions first, then workspace instructions, to the thread system prompt for all providers when a provider session starts. - Only the plural `AGENTS.md` is read, only from those exact locations (no parent-directory walk); an empty file is ignored. Run `bb guide agent-configuration` for details (it also covers project `.bb/skills/`). ## Skills - Use `bb skill list` to inspect installed and discovered skills. It defaults to `BB_PROJECT_ID`, then the personal project; pass `--project` or `--environment` to select another workspace. - Copy the opaque ID from `bb skill list`, then use `bb skill show <skill-id>` or `bb skill files <skill-id>` to read that exact skill. - `bb skill show <skill-id> --json` returns the revision. Pass that revision, plus `--file`, to `bb skill update <skill-id>`. Use update or delete only when the list says editable. - Use `bb skill search [query]` for live skills.sh results. Inspect metadata and the bounded file preview with `bb skill registry detail <registry-skill-id>`. Install with `bb skill install <registry-skill-id>`; never infer an install source from a display name. - `bb skill install-cli-skills` copies bb's built-in CLI skills into a machine's global agent skill roots (`~/.agents/skills` and `~/.claude/skills`) so agents outside bb can drive bb. It targets every connected machine unless you pass the repeatable `--machine <id-or-name>`, and reports each machine's outcome. Settings → Skills has the same action; it confirms first, and asks which machines only when more than one is enrolled. - `bb skill cli-skills-status` reports per machine whether the installed copy is `installed`, `outdated`, `missing`, or `unknown` (disconnected or unreachable). ## Spawning Threads - Use `bb thread spawn --project <project-id> --prompt "..."` to create another thread. Pass the intended project explicitly; the CLI does not infer it from context variables. - Add repeatable `--file <path>` / `--image <path>` flags for structured prompt attachments, and `--section <id>` to add the new thread to a section. These flags pass host-readable absolute paths (or relative server-upload tokens) through to the runtime; they do not read files on the CLI machine. - Spawn creates a root thread unless you pass `--parent-thread`. - Use `bb thread fork <source-thread-id>` to clone a provider session. It creates an idle fork by default; add `--prompt`, select `--workspace isolated|reuse`, or anchor with `--source-seq-end`. Permission mode inherits the source thread unless explicitly overridden. - Pass `--visibility hidden` for background/plugin workers that should remain out of sidebar organization without contributing unread/pending favicon attention. `bb thread list` excludes them by default; pass `--include-hidden` when a hidden worker must be discovered. Direct-ID lifecycle and messaging operations remain available. A root thread is visible by default; a child thread inherits its parent's visibility, so a hidden thread's subagents are hidden too. Pass `--visibility` to override the inherited value. A hidden child still reports its turns and blockers to its parent thread; only forks and side chats stay silent. Promote or hide an existing thread with `bb thread update <id> --visibility visible|hidden`. - `bb connect --code <code> --server https://<handle>.getbb.app` pairs this bb server for browser access at `<handle>.getbb.app` (get the code from https://getbb.app). Pairing returns immediately — the server itself holds the tunnel and reconnects on restart, so there is no foreground process. `bb connect status` / `bb connect off` report and clear the pairing. Port sharing works from a thread on any enrolled host. `bb connect expose <port>` resolves that thread's environment host and returns its public URL; outside a thread it defaults to the server host. Pass `--host <name-or-id>` to override expose, unexpose, or shares. Server-host URLs use the server label; machine-host URLs use the machine label and proxy directly through its daemon. Shares are owner-session-gated, not public. `bb connect status` shows every share's host and URL; `shares --json` includes the resolved host plus `hostId`, `hostName`, `port`, and `url` per row. `bb connect servers` lists every bb on the paired account (handle, name, url, live) so callers can discover siblings; `--json` includes `selfHandle` for deduping this server. When you start a local server the user should open remotely, expose the port and give them the share URL. Remote access is owned by the builtin `connect` plugin: `bb plugin disable connect` cuts it off entirely; with bb connect still enabled, `bb plugin enable connect` restores the command. Plugins → Connect shows the current URL, QR code, shared ports, re-pair form, and disconnect control. - Add remote execution machines from Settings → Machines. Its one-line installer stores the bb connect machine credential locally and configures both the daemon protocol and agent-launched `bb` CLI to traverse the account gate; revoke a lost machine from the getbb.app dashboard. The installer uses the server's exact `/install/bb-app.tgz` artifact (npm only on a 404) and enables daemon `--auto-update`; newer protocol mismatches update from that artifact with a persisted exponential retry backoff from 5 seconds to 5 minutes, then let launchd/systemd restart the daemon. Auto-update never downgrades. Use `bb machine retry-update <id-or-name>` to bypass the current backoff after a transient failure. Remove `--auto-update` from the service definition and reload it to opt out. - Run `bb machine list` to see machine names, IDs, connection status, and last seen time (`--json` returns the raw host list). Use `--machine <id-or-name>` (alias `--host`) on `bb thread spawn` to run in a personal or unmanaged workspace, or combine it with `--new-environment worktree`. Do not combine a machine selector with an existing environment ID, which already owns its machine. - Each machine carries a permission limit (`maxPermissionMode`, default `full`): the highest permission mode a thread on that machine may run with. The server resolves any higher request down to it, and refuses a provider that supports no mode under it. Only the owner can change it, on the machine page at Settings → Machines → the machine — there is no CLI, SDK, or API surface that sets it, and machine credentials are refused — so read it from `bb machine list --json` or `bb machine show` and ask the user to change it in the app. - `bb machine show`, `join-code`, `rename`, `retry-update`, and `remove` cover the Settings → Machines lifecycle. Use `bb machine provider-cli status|install` to inspect or install provider CLIs on a selected machine. - `bb updates` (alias for `bb updates status`) aggregates bb-app and provider CLI update state across every machine — the CLI counterpart of Settings → Updates. `bb updates apply [--machine <id-or-name>]` runs every available provider CLI install/update sequentially; update bb-app itself with the printed upgrade command or the desktop relaunch. - Use `bb project create --name <name> --root <path> --machine <id-or-name>` to bind a new project's local path to a connected enrolled machine. Use `--host` as an alias. Omitting both selectors preserves the existing local CLI machine fallback (normally the primary machine). - `bb project list` preserves the ordinary-project-only default. Pass `--include-personal` when the singleton personal project must be discoverable. - Use `bb project source add <project-id> --machine <id-or-name> --path <path>` to register a path on another connected machine. It uses the same selector resolution and fallback as project create. Use `--clone` instead of `--path` to clone the project's remote there; `--remote-url` and `--target-path` are optional clone overrides. - `bb project paths|files|content|commands` accept `--machine <id-or-name>` (`--host` alias) or `--environment <id>`, but not both. An environment uses its owning machine and workspace; an explicit machine uses that machine's project source; omitting both intentionally uses the primary machine source. `bb project content --json` returns UTF-8 text or base64 binary content with an explicit `contentEncoding`. - Use `bb project attachment upload <project-id> --client-file <path>` when the bytes live on the CLI machine, including when the CLI and bb server are on different hosts. It reads locally and sends multipart bytes through the configured `BB_SERVER_URL` (and its enrolled-machine authentication proxy), returning the stable server attachment DTO. Optional `--filename` and `--mime-type` override inferred metadata. Pass the returned relative `path` to thread `--file` or `--image`; image MIME types are capped at 10MB and other files at 25MB. `bb project attachment download <project-id> <attachment-path> --client-file <path>` writes existing attachment bytes on the CLI machine. There is no project-attachment list or per-file remove API. - `bb project history|reorder` exposes project prompt recall and sidebar order. - Direct environment inspection accepts any environment ID: use `bb environment status|branches|paths|diff|diff-files|diff-file|diff-patch <id>` and `bb environment pull-request show <id>`. Diff commands require an explicit target and the matching merge-base or commit flags; all support `--json`. - `bb environment pull-request ready|draft|merge` manages pull-request state; `bb environment archive-threads` bulk-archives an environment's threads. - Spawned child threads inherit permission from explicit flags, then the parent thread's last execution, then project defaults. - Public permission modes are `accept-edits`, `auto`, and `full`. `accept-edits` keeps workspace sandboxing and asks the user to review escalations. `auto` keeps the same workspace sandbox while using the provider's automatic reviewer. `full` explicitly bypasses sandbox and approval protections. Plan mode remains separate. The product default is `auto` when no inherited or project default applies. - When spawning a subagent, pass `--permission-mode full` unless the user or task explicitly requests restricted access. - Use `--parent-self` inside a thread to parent the new thread to the current thread. - Use `--parent-thread <thread-id>` to choose another specific parent. - If provider or model choice matters, inspect options with `bb provider list` and `bb provider models <provider-id>`. Both accept `--machine <id-or-name>` (alias `--host`) or `--environment <id>` to inspect the machine where work will run; the selectors cannot be combined. With neither selector they intentionally inspect the primary machine. - Known ACP agents can appear automatically when their CLI is installed on the host; for example `opencode`, `omp`, Grok Build's `grok` CLI, or Hermes' `hermes` CLI on PATH appears as provider `acp-opencode`, `acp-omp`, `acp-grok`, or `acp-hermes-agent`. - Custom ACP agents can be registered in the app data-dir `config.json` under `customAcpAgents`. The user supplies a slug `id`; bb exposes it as provider id `acp-<id>`. Custom config wins if it uses the same provider id as a known ACP agent, so overriding `acp-opencode` uses `"id": "opencode"`. This list has no set/unset CLI surface, so edit the JSON and run `bb-app config refresh` or restart bb. The configured command is local code execution and only works with a co-located daemon. Optional `logo` accepts an SVG, PNG, or WebP path; relative paths resolve from the bb data dir. Custom ACP agents can use `modelCli` for CLI model listing/selection, `reasoningCli` for launch-time reasoning flags, and `nativeReasoning` for ACP `session/set_config_option` reasoning. Give spawned threads clear prompts: objective, constraints, expected deliverable, validation to perform, and what to report back. Ask for outcome, changed files or artifacts, validation performed, and blockers. ## Coordinating Work - Use one clear owner per task. - Spawn independent tasks separately when parallel work is useful. - Let threads work after spawning. Do not poll with shell sleeps, repeated log reads, or repeated status reads. - Use `bb thread wait <thread-id>` when you explicitly need to block until a thread finishes. It defaults to waiting for `idle` for up to 20 minutes; pass `--status` or `--event` for a different target, and `--timeout <seconds>` when you need a shorter or longer budget. - Use `bb thread tell <thread-id> "..."` when requirements change, a blocker needs clarification, or follow-up work is needed. - `bb thread tell` steers by default, delivering the message immediately into the active turn. Use `--mode queue` when the message is non-urgent and the agent can finish its current work first. Steer is especially important for a wrong direction, hard stop, or critical clarification. Example: `bb thread tell <thread-id> "Stop and use approach B" --mode steer`. ## Inspecting Results - Use `bb thread search`, `history`, `read|unread`, and `section` for the same organization and recall features as the sidebar. `bb thread queue` exposes queued-message list/create/update/send/reorder/group/delete operations. Queue updates use the listed message version to prevent overwriting a concurrent edit and accept repeatable `--file` and `--image` attachment options. - Use `bb thread show <thread-id>` for status, parent, environment, pull request status, and result. - Use `bb thread show <thread-id> --git-diff` to review file changes. - Use `bb thread log <thread-id>` to inspect the conversation. - Use `bb thread output <thread-id>` to read the latest final output, or `bb thread output --self` for the current thread. For review or fix pipelines, get the environment ID from `bb thread show <thread-id> --json`, then spawn the follow-up with `--environment <environment-id>` so it sees the same files. ## Opening Threads And Files In The App - Use `bb thread open <path>` inside a BB thread to open a Markdown, HTML, or other workspace file for the user in the BB IDE's thread panel. - Use `bb thread open <thread-id> --split right|down|left|top|replace` to open or focus a thread in the current app split layout. `replace` is the default; an already-open thread is focused. Edge splits create panes through the eighth pane; at eight panes, they replace the focused pane. - A file path is optional when a thread ID is explicit: `bb thread open <thread-id> [path] [--split <placement>]`. - Paths can be thread-relative workspace paths, or absolute paths inside the target thread workspace. - Absolute paths under `BB_THREAD_STORAGE` open as thread-storage files for the current thread. - Use `bb thread pane maximize|restore|toggle [thread-id]` to change a matching already-open pane in every connected BB app window. Inside a BB thread, omit the id to use `BB_THREAD_ID`. The command reports how many connected clients received the ephemeral action. The SDK equivalent is `sdk.threads.paneAction({ threadId, action })`. - Users can also toggle the focused pane from its header or with the configurable `pane.maximize.toggle` app command (default `Mod+Shift+E`). ## Files And Voice - Use `bb file read|write|list|paths|mkdir|move|remove` for SDK-equivalent host file access. `--host` targets another machine; `--root` confines mutations. - Use `bb voice transcribe <file>` to invoke the configured voice transcription service without the app composer. ## Long-Running Commands - Use `bb terminal ...` for long-running commands the user may need to inspect or stop later: dev servers, watch tasks, REPLs, database consoles, and similar processes. The terminal is a real persistent PTY shown in the bb UI. - `list` and `create` require exactly one explicit scope: `--thread <id>`, `--environment <id>`, or `--machine <id-or-name>` (`--host` is an alias). Add `--cwd <path>` only to a machine scope. Machine targets resolve to an explicit host ID; terminal commands never silently fall back to primary. - Start a server with `bb terminal create --thread <thread-id> --title "pnpm dev" --command "pnpm dev"`. - All existing-session operations need only the terminal ID. Use `bb terminal wait <terminal-id> --contains "Local:" --timeout 120` to wait for readiness from new output. Pass `--from-start` only when matching existing scrollback is intentional. - Use `bb terminal output <terminal-id> --json` to read bounded output, then