brainbase agent

Manage the agent bound to the current folder. The committed brainbase.agent.yaml is the source of truth; these commands create it in the cloud and keep the two in sync. agent list and agent delete are the exceptions — one reads a whole team, the other names its agent by id. The connection commands and agent surface take --agent <id> to act on another agent. See Agents & linking for the lifecycle.

brainbase agent list

List the agents in a team, including the ids that link takes. Read-only. Use team list first if you don't know the team id.

brainbase agent list
brainbase agent list --team <team-id>
brainbase agent list --org <org-id-or-slug> --team <team-id>
brainbase agent list --all-teams
brainbase agent list --json

216 agents in Acme → Core

Release Bot  release-bot
  cuts releases and files the changelog
  claude-code · daytona · claude-sonnet-5
  11111111-2222-4333-8444-555555555555

The first line is the count. Each entry then shows the agent name and slug, its tagline, then its harness, sandbox provider, and default_model where those are set, and finally the id. The listing is ordered by when each agent was granted to the team, newest first.

Every agent in each selected team is listed. With --team, --json emits that team's complete array. Each JSON row includes its team_id, whether listing one team or several.

Without --team, --all-teams lists every team in the selected organization. This is also the default with --json or no interactive terminal, including piped output. An interactive run otherwise selects the only team automatically or offers a picker when there are several. If the organization is ambiguous, pass --org <id-or-slug>.

brainbase agent init

Write a starter brainbase.agent.yaml into the current folder and stop. The manifest is unclaimed — it has no id — so nothing exists in the cloud until you run agent create. This is the way to author a manifest, review it in a pull request, and create the cloud agent later, possibly from CI.

brainbase agent init
brainbase agent init --name "Repo Assistant" --harness codex
brainbase agent init --full          # commented template, every block
brainbase agent init --json          # print the path and nothing else

schema: 1
harness: claude-code
agent:
  name: hello-world
  tagline: A starter agent.
instructions:
  text: You are a helpful Claude Code agent.

The name defaults to the folder name. The harness is detected from the folder first (a .claude directory here, say), then from what's installed on this machine, and falls back to claude-code — the command tells you which of the three it used, and --harness overrides it.

Without --force the command refuses to touch an existing manifest — including a legacy brainbase.yaml — and exits non-zero, so it is safe to run twice or from a script. An unknown --harness is rejected here rather than by the control plane.

brainbase agent create

Claim an unclaimed brainbase.agent.yaml (one with no id), create the cloud agent, and stamp the id back into the file. Top-level machine_kind and default_model values are applied during creation. machine_kind is immutable after the agent is created. The CLI verifies that the control plane applied both fields; if it did not, the new id is still written to prevent a duplicate retry and the command exits non-zero with recovery guidance.

When the manifest has no default_model, the control plane gives the agent the platform default model for its harness, the same one the web console picks, and the result card shows it. Cursor, Factory, and Qoder agents get none, because those harnesses always run their vendor's own model. The manifest is not rewritten, so default_model stays unmanaged until you add it.

If the folder has no manifest, agent create scaffolds the same starter file agent init writes and carries on. In a terminal it confirms first; without a TTY it goes ahead, because there is nobody to ask and an empty folder should not be a dead end for CI.

brainbase agent create
brainbase agent create --name "Repo Assistant" --tagline "Reviews PRs"
brainbase agent create --org <org-id-or-slug> --team <team-id> --yes

brainbase agent pull [<id>]

Bring cloud changes into this folder. Pass an <id> to pull a specific agent into an empty folder; omit it to pull the folder's claimed agent. Pull materializes the reported cloud machine_kind and non-null default_model; an authored default_model: null remains explicit when the cloud model is unset. Older control planes that do not expose these fields do not erase authored values. Pull refuses to overwrite locally edited runtime config unless --force is passed.

brainbase agent pull
brainbase agent pull <agent-id> --force
brainbase agent pull <agent-id> --link --no-tracking
brainbase agent pull --run-entrypoint

The harness comes from the cloud agent, so pull ignores --harness: the manifest's harness is rewritten to match the cloud on every pull.

brainbase agent push

Send local manifest changes — instructions, entrypoint, playbooks, skills, MCP servers, evals, and default_model — to the cloud. Set default_model: null to clear the override. A changed machine_kind is always blocked because providers cannot be changed on an existing agent. Pass --force to keep the local side of content or default_model conflicts. Push also stops if the active control plane does not expose an authored runtime field.

brainbase agent push
brainbase agent push --force

brainbase agent delete <id>

Permanently delete a cloud agent and every task it has run. It cannot be undone. The id is required and never taken from the linked folder, so a stray --yes in the wrong directory cannot pick the target. Find ids with agent list.

brainbase agent delete <agent-id>
brainbase agent delete <agent-id> --yes
brainbase agent delete <agent-id> --yes --json

If the folder you run it in is linked to the deleted agent, the command says so: run brainbase unlink, after which brainbase agent create can recreate the agent from brainbase.agent.yaml.

brainbase agent status

Preview what would push and what would pull, without changing anything. Runtime output distinguishes a blocked machine_kind mismatch, cloud provider drift, local or cloud default_model drift, and a two-sided model conflict. It also lists the evals a push would archive, and whether a push would be refused because the cloud holds eval changes this folder has never pulled.

brainbase agent status
brainbase agent status --json

brainbase agent eval

Read the agent's evals and the judge's verdicts. list shows the eval definitions the cloud currently holds; runs shows verdicts newest first, with the judge's reasoning, any quotes it cited, and the task each verdict came from.

Both subcommands are read-only. Eval definitions are declarative — edit the `evals` block in brainbase.agent.yaml and run brainbase agent push. There is no run command: the platform scores each turn as it finishes.

brainbase agent eval list
brainbase agent eval list --archived
brainbase agent eval runs --limit 20
brainbase agent eval runs --task-id 6f1d9c2a-... --json

brainbase agent connections

Show which of the six surfaces — chat, Slack, meeting, GitHub, Linear and phone — the agent is wired to. Read-only. Whether Slack, meeting, GitHub and Linear are connected decides which built-in MCP servers unpack installs, so this is what explains an agent that came up unable to reach Slack. It reads the installs directly rather than the *_connected flags on the agent payload — the two agree, but only this one can say *which* workspace or account is behind a true. See Connecting integrations for the walkthrough.

brainbase agent connections
brainbase agent connections --agent <agent-id>
brainbase agent connections --json

✓ chat  connected
    brainbase agent disconnect chat
✓ slack  Acme Corp
    brainbase agent disconnect slack
· meeting  not connected
    brainbase agent connect meeting
· github  not connected
    brainbase agent connect github
· linear  not connected
    brainbase agent connect linear
· phone  not connected
    brainbase agent surface phone search; then brainbase agent surface phone purchase <number> --yes

Each integration carries name, connected, detail (the workspace, account, bot name or number behind it) and manageable_from_cli, which is true for all six. An older control plane may still send false with an unmanageable_reason, and the human output prints that reason in place of a command. An unlinked folder exits non-zero and still prints valid JSON, so a jq pipeline does not choke on empty input. For one surface's full settings, use agent surface.

brainbase agent connect <surface>

Connect one of the six surfaces: chat, slack, meeting, github, linear or phone. Slack and meeting are handled here as below. The other four are shorthand for brainbase agent surface <surface> connect and take its flags — see agent surface: chat turns chat on, github and linear open the provider's setup in a browser and wait for it, and phone buys a number, so it needs --number <number> --yes.

For Slack and meeting the command is idempotent — re-running rotates the stored values, which is also how you refresh a Slack token. Slack credentials are validated against Slack before anything is stored, and values you do not pass are preserved, so rotating a token will not blank an app_id or app_name the web app set.

Prefer stdin for the Slack credentials: a command line is readable by any process through ps. Pipe them in to keep them out of shell history too — a here-string is recorded verbatim, same as a flag. See Connecting integrations for the history-safe forms.

vault kv get -format=json -field=data secret/slack | brainbase agent connect slack
brainbase agent connect slack --bot-token xoxb-… --signing-secret …
brainbase agent connect meeting --bot-name "Notetaker"
brainbase agent connect github
brainbase agent connect linear --client-id <client-id>
brainbase agent connect phone --number +14155550123 --yes

Credentials resolve flag → environment variable → piped stdin → prompt. Piping {"bot_token":"…","signing_secret":"…"} keeps both out of argv, where ps can read them; a bare value on stdin fills the single field still missing. With no terminal to prompt on, the command exits non-zero naming all three of the other ways, without writing anything.

connect reads connections first, to check the control plane allows the change, so it can fail on an unreachable control plane even when every credential was supplied locally.

brainbase agent disconnect <surface>

Revoke an install, or for chat, turn chat off. Removes the same record the web app's disconnect removes, and is idempotent, so disconnecting something that was never connected still succeeds. For chat, github, linear and phone it is shorthand for brainbase agent surface <surface> disconnect. Disconnecting phone releases the agent's number.

brainbase agent disconnect slack
brainbase agent disconnect meeting --yes
brainbase agent disconnect linear --yes
brainbase agent disconnect phone --yes --agent <agent-id>

After connecting or disconnecting, run agent pull to pick up or drop the matching built-in MCP server locally.

brainbase agent surface <surface> <action>

Read and change every setting of one surface — chat, slack, meeting, github, linear or phone — and run its provider setup. The action defaults to status. Each action prints the surface's resulting state as JSON: agent_id, surface, connected, installation_id, config, capabilities and details. Run brainbase agent surface --help for the full grammar.

brainbase agent surface slack                     # status
brainbase agent surface github configure --auto-review false --allow-push true
brainbase agent surface meeting image upload avatar.png
brainbase agent surface phone whitelist add +14155550199 --label "On-call"
brainbase agent surface linear status --agent <agent-id>

Slack and Linear secrets resolve flag, then environment variable (BRAINBASE_SLACK_BOT_TOKEN, BRAINBASE_SLACK_SIGNING_SECRET, BRAINBASE_LINEAR_CLIENT_SECRET, BRAINBASE_LINEAR_WEBHOOK_SIGNING_SECRET), then JSON on stdin, then a masked prompt. Under --json there is no prompt, and a secret the command saw is redacted from any error it prints.

GitHub and Linear setup

github connect, linear connect and linear reconnect print a setup link and a resume command, open the link in your browser, and wait until the installation is live, then print its state. Under --json they print { agent_id, surface, connected: false, pending: true, installation_id, url, next_command } and exit without waiting; run the next_command — brainbase agent surface <surface> wait --installation <id> — to pick the wait up again, here or on another machine.

A timed-out wait exits 1 and Ctrl-C exits 130; both print the resume command, and the browser setup can still finish in the meantime. A wait also ends with exit 1 if the installation is revoked, disconnected or failed.

Destructive actions and provider operations

disconnect, phone release and phone purchase need --yes every time — at a terminal, with no terminal, and with --json alike. They never prompt. phone whitelist remove is a single step, as it is in the web app, and accepts --yes without requiring it.

Provider operations go through the web app rather than the control plane: github connect, linear manifest, linear connect, linear reconnect, linear disconnect, and phone search, purchase and release. They need a brainbase login session and refuse a personal access token, so unset BRAINBASE_TOKEN for them. BRAINBASE_WEB_URL picks the web app they use.

Failures print a message on stderr, or { "error": "…", "code": "…" } on stdout under --json, and exit 1 — 130 for an interrupted wait.

brainbase agent versions

Brainbase saves a version of an agent a few seconds after each change to it, whether the change came from the web app, agent push or the API. These commands list those versions, compare them, name them, roll the agent back to one, and pin new tasks to one, with the same meaning as the version history in the web app. They act on the agent linked in this folder unless --agent <id> names another, and they act as you: a sandbox or agent credential is refused.

brainbase agent versions list
brainbase agent versions show v12
brainbase agent versions diff v12
brainbase agent versions diff v11 v12
brainbase agent versions label v12 "baseline" --description "Before the escalation rewrite"
brainbase agent versions restore v12 --dry-run
brainbase agent versions restore v12 --yes
brainbase agent versions pin v12 --yes
brainbase agent versions unpin --yes

A version is named by its number (12 or v12) or by its id. Every subcommand takes --json, which prints only JSON on stdout and never prompts; guidance a person would read in the terminal goes into a notes array. Under --json a failure prints {"error": {code, reason, message, details}}, where details holds status and retry_after and, for a restore that stopped partway, its sections and warnings. A refusal the CLI makes before calling Brainbase has code invalid_input and a reason such as confirmation_required, agent_not_specified or invalid_version_ref.

brainbase agent versions list

agent       13dadac5-37fb-48d4-8e10-bb8c5e77bf69
pinned      none, new tasks run the current configuration

   v4  rollback            1h ago   Instructions
   v3  auto                1h ago   Instructions
   v2  auto                1h ago   Instructions
   v1  auto      baseline  1h ago   Initial version

Every version, newest first, with its number, kind (auto, or rollback for one made by a restore), label, age and summary. The header names the pinned version, and the pinned row is marked *. ls, and brainbase agent versions on its own, do the same. There is no page size to raise: the whole history is listed, and --json emits it as one object with items, pin and capture_pending.

A version is saved once an edit settles: a few seconds, or up to a minute when playbooks change. Until then the list says an edit is still being saved, and the newest number may be about to change. label, restore and pin say so too. After a push, run list --wait before pinning the version you just made.

agent versions show <version> prints one version: its number, id, kind, label, description, summary, when it was made and by whom (user, agent or service, and the id), where the change came from, and whether it is pinned.

brainbase agent versions diff <version> [<version>]

What changed, section by section, as the version page in the web app shows it: instructions and other text line by line, configuration field by field, and playbooks, MCP servers, skills and the other lists entry by entry. diff v12 shows what v12 changed compared with the version before it; for the first version everything reads as added. diff v11 v14 shows the changes from v11 to v14. diff v11 --current shows the changes from v11 to the newest version, like "Compare to current" in the web app.

agent       13dadac5-37fb-48d4-8e10-bb8c5e77bf69
from        v1
to          v3
changes     +2 -1 lines in 4 sections

Instructions .brainbase/instructions.md  +1 -1
    You are a test agent.
  - When asked for your codeword, reply with exactly the single word ALPHA and nothing else.
  + When asked for your codeword, reply with exactly the single word BETA and nothing else.

Configuration  1 field
  Tagline: "Support agent" -> "Support agent, v2"

MCP servers  1 added
  + docs

Secret keys .brainbase/secrets.keys  +1 -0
  + ESCALATION_TOKEN

Unchanged text is folded to three lines around each change. Two versions with the same configuration print none: a version saved only because a secret value changed looks like this, since secret values are never part of a version. A text too long to compare prints its line counts instead. --json prints the comparison Brainbase computed, with from, to and a diff of sections, totals (line counts), identical and initial; the versions themselves never leave Brainbase.

brainbase agent versions label <version> [<label>]

Name or describe a version. Whatever you leave out stays as it is. Never asks for confirmation. A label is 1 to 120 characters, and a description at most 500.

brainbase agent versions restore <version>

Put the agent back the way it was in a version, for everyone using it. The restore is itself saved as a new rollback version, so restoring the version that was newest before undoes it. The command first previews the restore and prints its warnings, such as secrets added since or MCP server credentials that will need setting again, then asks.

Restoring to v1 "baseline" would change the agent for everyone using it.

Warnings
! secret_keys_added_since (my_kafka_secrets) keys: ENG1941_FIXTURE_KEY

The result lists each section applied and how many rows it created, updated, deleted or skipped. If the restore stops partway, the command prints the sections that were applied and exits 1; running it again finishes the job. If Brainbase asks to retry later, the command prints how long to wait and does not retry on its own. If no answer arrives in time, the outcome is unknown: run agent versions list and look for a new rollback version before trying again.

brainbase agent versions pin <version>

Make new tasks run this version until you unpin. A pin freezes the version's instructions, entrypoint, installed skills, tools, playbooks, harness and default model. Secrets, credentials, machine settings, permission rules, connections and skill contents always stay current. Tasks already running keep the version they started with. agent versions unpin makes new tasks run the current configuration again. Both ask first, and need --yes with no terminal or with --json. Both name the current pin, if any, when they ask, and change the pin only while it is still that version: if someone moves it in the meantime, nothing changes and the command exits 1. Unpinning an agent that is not pinned changes nothing and exits 0; with --json the result carries changed: false.

Runtime configuration

schema: 1
machine_kind: daytona
default_model: gpt-5.6-terra
agent:
  name: Repo Assistant

Both fields are optional. Omit default_model to leave it unmanaged (a new agent then starts on the platform default for its harness), set a model ID to manage the override, or set it to null to explicitly clear the override. Schedules are not agent-level configuration; declare them as schedule triggers in brainbase-orchestration.yaml.

brainbase agent unpack

Install the claimed agent into a harness layout — writing CLAUDE.md, .claude/, playbooks, and the rest into the paths the harness reads at runtime.

brainbase agent unpack --harness claude-code
brainbase agent unpack --scope project

brainbase agent env

Print shell export lines for the agent's secrets. The output format is auto-detected from $SHELL; override with --shell.

eval $(brainbase agent env)
brainbase agent env --shell fish

brainbase link / unlink / status

link attaches the current folder to an existing cloud agent; status shows what it's linked to, and says when the cloud has changed since your last sync; unlink disconnects it. Both link and status print the agent's console link, <console>/agents/<agent>. Run agent list to find the id --agent takes.

brainbase link --agent <id> --no-tracking
brainbase status
brainbase unlink

brainbase sync

Reconcile a linked folder with the cloud — see Syncing & tracking.

brainbase sync --harness claude-code --scope project

brainbase run

Run a child command with secrets.env loaded into its environment. All arguments after the command are passed through verbatim, and run does not require Brainbase auth.

brainbase run npm test
brainbase run -- python main.py --verbose

brainbase publish (removed)

Removed. Use brainbase agent push to send local changes to the cloud agent — see agent push. The name still resolves so it can point you there, and exits non-zero.