/bb-cli

name: bb-cli
description: "Inspect or manage BB state with the bb CLI; use for BB commands and configuration."

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 tun