--- name: Bb Cli slug: bb-cli category: Automation description: Bb Cli controls bb itself to inspect status, manage threads and automations, and work with projects, providers, and environments. Use it when an agent needs to coordinate or configure a bb workspace. github: "https://github.com/get-bb/bb/tree/main/apps/server/src/services/skills/builtin-skills/bb-cli" language: TypeScript stars: 2274 forks: 253 install: "npx degit https://github.com/get-bb/bb/tree/main/apps/server/src/services/skills/builtin-skills/bb-cli ~/.claude/skills/bb-cli" installs_to: ~/.claude/skills/bb-cli source_path: apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md collection_size: 14 category_size: 1523 collection_url: "https://dirskills.com/collections/get-bb/bb" added: 2026-08-18T06:58:22.575Z last_synced: 2026-08-18T06:58:22.575Z canonical_url: "https://dirskills.com/skills/bb-cli" --- # Bb Cli Bb Cli controls bb itself to inspect status, manage threads and automations, and work with projects, providers, and environments. Use it when an agent needs to coordinate or configure a bb workspace. **Install:** ```bash npx degit https://github.com/get-bb/bb/tree/main/apps/server/src/services/skills/builtin-skills/bb-cli ~/.claude/skills/bb-cli ``` ## README # 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 ` 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. 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.0` is 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 and `app` rows then show `http://0.0.0.0:`; 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.sh` setup hook and the `.worktreeinclude` file. - A new worktree checks out tracked files only. Commit a `.worktreeinclude` file 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 ` 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 `/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 - `BB_INFERENCE` selects the shared model for server-side helper completions, including thread titles and commit subjects. It defaults to `codex/gpt-5.6-luna`; set an override with `bb-app config set BB_INFERENCE `. - `BB_INFERENCE_FALLBACK` selects the helper model used after a transient primary timeout, rate limit, or service-unavailable failure. It defaults to `codex/gpt-5.4-mini`; set it with `bb-app config set BB_INFERENCE_FALLBACK `. - `BB_TRANSCRIPTION` selects the voice transcription model. It defaults to `codex/gpt-transcribe`; set an override with `bb-app config set BB_TRANSCRIPTION `. - `bb-app config` and `bb-app env` reload 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, and `BB_FF_*` flags. `BB_LOG_LEVEL` is also startup-only. Use `bb-app config`, not `bb-app env`, to change `BB_APP_URL`, `BB_INFERENCE`, `BB_INFERENCE_FALLBACK`, or `BB_TRANSCRIPTION` live. After a startup-only change, run `bb-app stop && bb-app start` or restart the desktop app. Until then, a server previously bound to `0.0.0.0` remains exposed even if `BB_SERVER_BIND_HOST` was 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 enable` and `bb keep-awake disable` to configure its macOS idle-sleep assertion. Inspect it with `bb keep-awake status [--json]`. Target hosts with `bb keep-awake hosts all` or `bb keep-awake hosts ...`. - 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 `. - The `steerActiveThreadOnEnter` General 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 with `bb settings general steerActiveThreadOnEnter `. - 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 `. 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 ` to read provider limits from a specific connected machine instead of the primary machine. - Extensions provides the unified Skills and Plugins management UI, while Automations stays in the Plugins section beside threads. - The default-off `newOnboarding` experiment exposes the first-run agent and project setup guide. Change it with `bb settings experiment newOnboarding `. Use `bb settings replay-onboarding` to enable it and show the guide again. - The default-on `editMessages` experiment allows accepted root user messages in Codex, Claude Code, and Pi threads to be replaced and rerun, including failed or incomplete turns. Submitting an edit to a running thread stops and settles the current turn first. Change it with: `bb settings experiment editMessages `. - 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 ` or `bb skill files ` to read that exact skill. - `bb skill show --json` returns the revision. Pass that revision, plus `--file`, to `bb skill update `. Use update or delete only when the list says editable. - Use `bb skill search [query]` for live skills.sh results. With no query it lists what is trending; `ranking` in the response says which leaderboard you got. Install counts match the Skills browse page — lifetime totals, resolved per skill on the trending ranking, where the leaderboard's own number counts only a 24h window. Resolution is capped at 48 rows per page and a detail page can fail to fetch, so read the two surfaces differently: the `INSTALLS` column prints `—` for a row it could not resolve, while `--json` lists those ids in `unresolvedInstallIds` and leaves their `installs` holding the 24h figure. Every other row's `installs` is the lifetime total. Use `--per-page 48` or less to avoid unresolved rows. Inspect metadata and the bounded file preview with `bb skill registry detail `. Install with `bb skill install `; 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 `, 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 --prompt "..."` to create another thread. Pass the intended project explicitly; the CLI does not infer it from context variables. Omitted execution flags use remembered project defaults; without a remembered model, bb uses the explicitly requested provider or Codex and resolves its provider-reported default model on the target machine. - Add repeatable `--file ` / `--image ` flags for structured prompt attachments, and `--section ` 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 ` 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 --visibility visible|hidden`. - Stop a finished hidden worker with `bb thread stop ` to release its agent runtime promptly. Archive it first when it no longer belongs in active thread lists. Stop preserves the thread and supports a later resume. - `bb connect --code --server https://.getbb.app` pairs this bb server for browser access at `.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. In a source checkout, `pnpm dev` automatically sets `BB_DEV_CONNECT_BASE_URL` to the worktree's local Cloud origin. Connect uses it only as the unpaired default; explicit `--server` and `--base-url` values still win, including when pairing the dev bb with getbb.app. `bb connect status` / `bb connect off` report and clear the pairing. Port sharing works from a thread on any enrolled host. `bb connect expose ` resolves that thread's environment host and returns its public URL; outside a thread it defaults to the server host. Pass `--host ` 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 and uses the npm registry only on a 404. It installs under the enrollment's bb data directory, without `sudo` or a global npm configuration, and enables daemon `--auto-update`. Newer protocol mismatches update that private install with a persisted exponential retry backoff from 5 seconds to 5 minutes, then let launchd/systemd restart the daemon. Auto-update never downgrades. To bypass a transient backoff, use `bb machine retry-update `. 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 ` (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 ]` 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 --root --machine ` 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 --machine --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 ` (`--host` alias) or `--environment `, 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 --client-file ` 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 --client-file ` 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 ` and `bb environment pull-request show `. 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. The parent's mode is a hard ceiling: an explicit flag can lower it but never exceed it. - 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. - Subagents inherit the parent's permission mode by default; `--permission-mode full` only takes effect when the parent itself runs full. - Use `--parent-self` inside a thread to parent the new thread to the current thread. - Use `--parent-thread ` to choose another specific parent. - If provider or model choice matters, inspect options with `bb provider list` and `bb provider models `. Both accept `--machine ` (alias `--host`) or `--environment ` to inspect the