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 |
| Agent | agent list · init · create · pull · push · unpack · status · env · link · unlink · sync · run | agent |
| Connections | agent connections · agent connect · agent disconnect | agent |
| Tasks | task create · list · get · logs | task |
| MCP | mcp list · mcp check | mcp |
| Templates | template pack · publish · search · info · onboard · list · remove | template |
| Skills | skill add · list · update · remove · search · info · publish | skill |
| Orchestrations | orchestration create · list · pull · push · status · add-agent | orchestration |
| Sandboxes | machine ls · machine rm | machine |
| Tokens | token create · list · 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 / pull / unpack, orchestration pull / add-agent | Force the harness (e.g. claude-code). |
--scope <s> | onboard, sync, agent | Force install scope: global or project. |
--agent <id> | link | Attach this folder to an existing agent non-interactively. |
--no-tracking | link, agent create | Skip routing LLM traffic through Brainbase. |
--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, agent pull, agent push | On init, overwrite an existing manifest; on pull, take cloud runtime/content changes; on push, keep local conflicts. It cannot change machine_kind. |
--minimal / --full | agent 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, 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 | team list, agent init / list / connections / connect / disconnect, mcp list / check, task create / list / get / logs | Machine-readable output, and nothing else on stdout. Never prompts — an ambiguous choice or a missing value errors instead. On the connection commands, failures print {"error": "…"} rather than plain text. |
--wait / --timeout <secs> | task create | Block until the task settles and exit 0 only when it succeeded; --timeout bounds the wait and needs --wait. See task. |
--limit <n> | task list, task logs, machine ls | On task list and machine ls, cap the page (1–200). 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, skill publish, token create | Name / label (alias -n for token create). |
--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 disconnect, 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.
`agent disconnect --json` is the exception
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.Environment variables
Hosts, the config dir, and PATs are all configurable via environment variables — see Environment variables.