Bb CLI

BB CLI

Use bb for BB state and actions. Inspect context when the target project, host, workspace, or execution selection is not already established.

Start with context

bb status --json

Use JSON when command output controls later work. Use human output for quick inspection.

Run bb --version for the CLI version. Use bb --help or bb help [command] for help. Run bb guide for the system overview. Run bb guide <chapter> for one area. Use bb <group> --help for current flags and defaults, or bb guide commands <group> for every command in a group with its options on one page.

Errors and JSON

• Read the whole error before you run --help. A failed invocation prints the nearest command or option, the usage line, the valid options, and, for a missing project, thread, machine, or environment, the exact flag to add with the current ID filled in.
• With --json, a failure prints {"ok": false, "error": {"code", "message", "hint"}} on stdout and the readable message on stderr, and exits non-zero. Parse stdout only; 2>&1 mixes the message into the JSON.
• Output shapes differ by command: bb thread list --json is a bare array, bb thread show --json nests under .thread, bb terminal list --json wraps in .sessions. bb guide json lists each shape, and the help of the most-parsed commands ends with its JSON shape.
• Pass long or multi-line text from a file: bb thread tell <id> --message-file <path>, bb thread spawn --prompt-file <path>, with - for stdin. Inside double quotes the shell runs backticks and $(...) before bb sees the text, which silently corrupts Markdown and can execute commands.
• Timeouts take seconds or a duration with a unit (90s, 20m, 4h).
• Examples here use POSIX shell syntax. On a Windows machine the agent shell is usually PowerShell: read an environment variable as $env:NAME ("$env:BB_THREAD_ID"), separate commands with ; instead of &&, and continue a line with a backtick instead of a backslash.

A standalone CLI targets http://127.0.0.1:38886. Use BB_SERVER_URL and BB_HOST_DAEMON_PORT only for an intentional non-default target.

Read only the relevant reference

• Read references/command-index.md to find the exact core command path. Use live help for current flags and defaults.
• Read references/configuration.md for settings, agent instructions, skills, remote clients, and environment setup scripts.
• Read references/thread-creation.md before you spawn or fork threads, create projects, select machines, move the server, or create environments.
• Read references/thread-operation.md for messages, queues, interactions, panes, terminals, inspection, and long-running commands.
• Read references/failure-recovery.md when a thread fails, stops, or needs plan or goal recovery.
• Read references/theme-commands.md for palette and favicon commands. Read references/theming.md before you create or edit theme CSS.
• Read references/plugins.md for plugin discovery, install, build, update, configuration, runtime, and contributed commands.
• Read references/app-settings.md for complete app setting keys and effects.

Command habits

• Resolve names and IDs with a list or show command before mutation.

• Pass an explicit project when a command can act across projects.

• Pass an environment or machine selector when the default host is uncertain.

• Spawn onto a plugin-provisioned environment with bb thread spawn --environment-provider <id> (list them with bb environment providers). Read the provider's requires (projectCheckout, gitCheckout, gitRemote, projectless): these facts decide where the provider is offered. A provider whose inputs schema does not accept an empty object needs --environment-inputs <json> matching that JSON Schema; providers that accept {} use it when the flag is omitted (bb environment providers --json prints both facts). --base-branch belongs to --new-environment worktree only.

• Enroll an existing machine with bb machine create --provider manual; run the printed command on the target. --no-wait returns its host ID. Cancel with bb machine remove <host-id>. Removal revokes access; use the original install-machine.sh --uninstall --host-id <host-id> on that box.

• Create a standalone machine with bb machine create --provider <id>; use --inputs <JSON> for non-secret provider inputs and --key for retry identity.

• List plugin-provisioned machine choices with bb machine providers. Create a machine and an explicit environment with bb thread spawn --new-machine <provider-id> --environment-provider <id>; add --machine-inputs <json> when its schema requires inputs. Machine inputs are persisted and non-secret; credentials belong in plugin settings. Composed environments choose their own machine: use --environment-provider modal-sandbox without machine selectors and pass --machine-inputs <json> when configuring the composition's machine provider.

• Use bb machine enroll for a private core-prepared bundle. Local lifecycle is handled by install-machine.sh --start|--stop|--uninstall --host-id <id>; see references/thread-creation.md for ownership checks.

• Moving the bb server to another machine is experimental (the serverMove experiment). Never move a server, abandon a move, or unlock an old copy without the user's explicit confirmation in this conversation: run bb server move --to <machine> --check, show them the checklist, and run the same command without --check only after they confirm. A move stops all running work. bb server export --out <file> backs up a running server. bb server import, unlock, allow-connect, and delete-old-copy act on this computer's data directory without calling a server. An imported server keeps its connect tunnel and bb account off until bb server allow-connect. On the computer a server moved away from, bb server install-machine-service installs the persistent, self-updating machine service (macOS and Linux only; needs Node.js 22.19+ on the PATH).

• Use bb machine suspend|resume <id-or-name> only for providers that expose suspend and resume. Resume waits for pending suspension and is a no-op when already active. Use bb machine retry-cleanup <id-or-name> to retry a failed provider teardown immediately.

• Use bb machine reconnect <id-or-name> when a disconnected machine's server access or host key is rejected but its BB host ID must remain. Run the printed short-lived command on that machine as is; it reuses the machine's recorded data directory, refreshes access, and re-enrolls under the same host ID. Connected machines are refused, and --json returns without waiting.

• bb environment providers lists Project checkout, Worktree, then other installed providers by display name. With --project <id> --machine <id> it also prints that machine's availability (available, setup-required, unavailable, or unknown until the background probe answers). Read or set managedBranchPrefix through bb settings show and bb settings general <key> <value>.

• The server keeps a registry of sidebar layout preferences (organization mode, section order, collapsed rows, navigation entries): bb settings ui list, get, set, and reset.

• Query provider models on the machine that will run the thread.

• Prefer non-interactive commands and machine-readable output for automation.

• Pass --yes for a confirmed destructive command in a non-interactive shell.

• Treat plugin commands as normal top-level commands after installation.

• Inspect real status, logs, API results, or diffs instead of assumptions.

• For launcher startup errors and console output, read logs/server-stdio.log or logs/host-daemon-stdio.log under the selected bb data directory. These append across restarts; bb-app, bb-server, and bb-host-daemon capture service output there instead of forwarding it to their terminal.

• Keep file paths on the machine that owns the selected workspace.