Command Reference
Command reference
Every command, grouped by area. Run brainbase help to print this same summary in your terminal.
brainbase <command> [options]
Commands
| Group | Commands | Reference |
|---|---|---|
| Auth | login · logout · whoami | auth |
| Teams | team list | team |
| Members | member ls | member |
| Agent | agent list · init · create · pull · push · delete · unpack · status · eval · env · link · unlink · sync · run | agent |
| Connections | agent connections · agent connect · agent disconnect · agent surface | agent |
| Agent versions | agent versions list · show · diff · label · restore · pin · unpin | agent |
| Tasks | task create · list · get · logs · send · update · stop · delete | task |
| Interfaces | interface ls · get · create · access · build · preview · publish · rollback · archive | interface |
| MCP | mcp list · mcp check · mcp connect | mcp |
| Integrations | integrations list · search · actions · add · connect · disconnect · remove · allow · ask · deny | integrations |
| Templates | template pack · publish · search · info · onboard · list · remove | template |
| Skills | skill add · list · update · remove · search · info · publish | skill |
| Orchestrations | orchestration init · create · list · pull · push · status · add-agent · delete | orchestration |
| Sandboxes | machine ls · machine rm | machine |
| Tokens | token create · list · rename · revoke · clear | token |
Global flags
| Flag | Applies to | Description |
|---|---|---|
--yes, -y | most commands | Skip confirmations / auto-overwrite. Required by destructive commands when there is no terminal — see below. |
--harness <id> | onboard, sync, agent init / create / unpack, orchestration pull / add-agent | Force the harness (e.g. claude-code). agent pull ignores it: the harness comes from the cloud agent. |
--scope <s> | onboard, sync, skill, agent pull / unpack | Force install scope: global or project. |
--agent <id> | link, task create / list, interface ls / create, mcp list / connect, integrations, agent connections / connect / disconnect / surface, agent versions | On link, attach this folder to an existing agent non-interactively. On task list and interface ls, filter to that agent. Everywhere else, act on that agent instead of the one linked in this folder. |
--no-tracking | link, agent create, agent pull --link | Skip routing LLM traffic through Brainbase. |
--link | agent pull | Link this folder to the agent first, as brainbase link --agent <id> --yes would, then pull. |
--track | agent create | Route LLM traffic through Brainbase (off without a TTY). |
--shell <sh|fish> | agent env | Output format (auto-detected from $SHELL). |
--all | template list, machine ls | Include more: other folders' installs, or torn-down machines. |
--force | agent init, orchestration init, agent pull, agent push, orchestration push | On init, overwrite an existing manifest (orchestration init still refuses a folder linked to an orchestration); on pull, take cloud runtime/content changes; on push, keep local conflicts — for orchestration push, the graph's schedule triggers and metadata. It cannot change machine_kind. |
--minimal / --full | agent init, orchestration init | Write the starter manifest (the default), or a commented template covering every block. Passing both is an error. |
--run-entrypoint | agent pull | Execute the agent entrypoint after pulling. |
--graph-only | orchestration push | Push members, edges, edge settings, and schedule triggers without pushing member-agent content. |
--no-push | orchestration add-agent | Create / wire locally but skip the push. |
--web <url> | login | Web app URL. |
--org <id-or-slug> | team list, member ls, agent list / create, orchestration create / list | Scope to an organization. Omitted, team list shows every organization you belong to; the others select a lone one automatically and otherwise ask. |
--team <id> | agent list / create, orchestration create / list | Scope to a team. Team ids are unique, so this works without --org. |
--json | whoami, team list, member ls, agent init / list / status / delete / eval / connections / connect / disconnect / surface / versions, orchestration init / list / delete, mcp list / check / connect, integrations, machine ls / rm, task, interface | Machine-readable output, and nothing else on stdout. Never prompts — an ambiguous choice or a missing value errors instead, and a destructive command needs --yes alongside it. On the connection, MCP and integrations commands, failures print {"error": "…"} rather than plain text. |
--wait / --timeout <secs> | task create, agent versions list | On task create, block until the task settles and exit 0 only when it succeeded. On agent versions list, wait until the latest edit is saved as a version. --timeout bounds the wait and needs --wait. See task and agent versions. |
--timeout <secs> | agent connect github / linear, agent surface github / linear connect / reconnect / wait | How long to wait for the provider setup to finish (default 600). |
--no-open | mcp connect, integrations connect, agent connect github / linear, agent surface github / linear connect | Print the link without opening a browser. Implied when there is no terminal. |
--no-wait | mcp connect, integrations connect, agent connect github / linear, agent surface github / linear connect | Print the link and exit instead of waiting for the outcome. |
--account <id> | integrations disconnect | Which connected account to remove, when the app has more than one. |
--limit <n> | task list, task logs, machine ls, agent eval runs | On task list and machine ls, cap the page (1–200). On agent eval runs, how many verdicts to fetch (1–200, default 50). On task logs, stop after <n> events instead of the whole transcript — or, with --follow, size the first page the server sends before it starts tailing. |
--follow, -f | task logs | Stay attached and print events as they land, until the task reaches a terminal state. |
--bot-token <t> | agent connect slack | Slack bot token. Also BRAINBASE_SLACK_BOT_TOKEN, or piped on stdin. |
--signing-secret <s> | agent connect slack | Slack signing secret. Also BRAINBASE_SLACK_SIGNING_SECRET, or piped on stdin. |
--app-id <id> / --app-name <name> | agent connect slack | Slack app metadata, recorded for reference. |
--bot-name <name> | agent connect meeting | Display name the agent joins meetings under. |
--bot-image-url <url> | agent connect meeting | Avatar for the meeting bot. |
--name | agent init / create, orchestration init, skill publish, token create / rename | Name / label (alias -n for token create and token rename). |
--tagline | agent init / create | Agent tagline. |
--from <agent> | orchestration add-agent | Source edge into the new agent (repeatable). |
--to <agent> | orchestration add-agent | Edge out of the new agent (repeatable). |
--description <text> | orchestration add-agent | Description for the new member agent. |
--schema <json> | orchestration add-agent | Edge payload schema. |
--visibility <s> | template publish, skill publish | public, unlisted, or private. |
--category <s> | template search, skill search | Filter by category (ignored by publish). |
--target <id> | template search | Filter search results by target. |
--page <n> | template search, skill search | Page through search results. |
--as <slug> | skill add | Install the skill under a different slug. |
--skill-version <v> | skill publish | Version to publish (MAJOR.MINOR.PATCH). |
Destructive commands
Most confirmation prompts only exist to slow a human down, and with no terminal to ask — a pipe, a CI job, an agent-driven shell — they carry on by themselves.
Commands that destroy something do not. Without a terminal they need an explicit --yes, and exit non-zero naming the flag if it is missing, rather than reading the absent terminal as a "yes".
$ brainbase token revoke tok_abc123 < /dev/null
Revoking ci-runner (tok_abc123) is destructive and needs confirmation, but
there is no interactive terminal to ask. Pass --yes to revoke it without a
prompt.
$ echo $?
1
This covers token revoke, unlink, link (its unlink and re-link paths), agent delete, orchestration delete, task delete, agent disconnect, integrations disconnect, agent versions restore, pin and unpin, interface access, threads, address, archive, unarchive, publish and rollback, template remove, skill remove, and skill add when it would overwrite a skill that already exists. In a real terminal nothing changes — you still get the prompt, and --yes still skips it. Under --json, which never prompts, the delete, integrations, versions and interface commands need --yes as well.
A few never prompt at all and need --yes every time, at a terminal too: agent surface <surface> disconnect — and agent disconnect for chat, github, linear and phone — plus agent surface phone purchase and agent surface phone release, which start and end recurring charges.
`agent disconnect --json` for Slack and meeting is the exception
For those two it still goes ahead on its own. What changed is that an *absent* terminal no longer counts as agreement —
--json is a flag you typed, and it has never prompted in a terminal either, so it keeps authorising the disconnect the way --yes does. The other four surfaces need --yes with --json too.Environment variables
Hosts, the config dir, and PATs are all configurable via environment variables — see Environment variables.