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 is the exception — it reads a whole team rather than the current folder. 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 --json
216 agents in Acme → Core
Release Bot release-bot
cuts releases and files the changelog
claude-code · daytona · anthropic/claude-sonnet-4
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 the team is listed, however many there are — there is no page size to raise and no flag to pass. --json emits that same complete array, so brainbase agent list --json | jq length is the team's real size.
| Flag | Description |
|---|---|
--org <id-or-slug> | Organization to look in. |
--team <id> | Team to look in. Team ids are unique, so this works without --org. |
--json | Emit the raw agent array and nothing else. |
A lone organization or team is selected automatically rather than prompted, which is what makes the command safe to run from CI or an agent sandbox. When the choice is ambiguous you get a picker in a terminal, and an error naming the flag to pass when there is no TTY. --json never prompts — a picker would write into the same stdout the JSON has to own — so pass --team <id> instead.
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.
agent init performs no authentication, no API calls, and no cloud writes, so it works offline, in CI, and inside a sandbox. It also never prompts: the same flags in the same folder always write the same file.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.
| Flag | Description |
|---|---|
--name <name> | Agent name. Defaults to the folder name. |
--tagline <text> | Short tagline for the agent. |
--harness <id> | Target harness instead of detecting one. |
--minimal | Write the starter manifest above. This is the default. |
--full | Write a commented template covering every block the CLI syncs, with the optional ones commented out. |
--force | Overwrite an existing manifest. |
--json | Emit the resulting path and nothing else on stdout. |
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.
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
| Flag | Description |
|---|---|
--name <name> | Agent name (otherwise prompted / read from the manifest). |
--tagline <text> | Short tagline for the agent. |
--org <id-or-slug> / --team <id> | Create under a specific organization / team. |
--harness <id> | Target harness (e.g. claude-code). |
--track | Enable tracking non-interactively (off without a TTY). |
--no-tracking | Opt out of routing LLM traffic through Brainbase. |
--yes, -y | Skip prompts. It no longer decides whether a manifest gets written. |
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 --run-entrypoint
| Flag | Description |
|---|---|
--force | Overwrite local changes with the cloud version. |
--run-entrypoint | Run the agent entrypoint after pulling (also via BRAINBASE_RUN_ENTRYPOINT=1). |
--harness <id> | Override the harness used to install a fresh pull. |
--yes, -y | Skip confirmation prompts. |
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
| Flag | Description |
|---|---|
--force | Overwrite cloud-side content and default_model conflicts with local values, and archive cloud evals missing from the manifest even when they have not been pulled; never overrides machine_kind immutability. |
--yes, -y | Skip confirmation prompts. |
brainbase agent pull first, or --force to make your local list win. See the agent manifest reference.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
| Flag | Description |
|---|---|
--json | Machine-readable report. evals.archive lists what a push would archive and evals.pushBlocked is true when a push would be refused, so a pipeline can gate on either. |
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
| Flag | Description |
|---|---|
--archived | list only. Also show evals a push has archived; they are marked (archived) and carry a status of archived in --json. |
--task-id <id> | runs only. Narrow to one task. |
--limit <n> | runs only. How many verdicts to fetch (1–200, default 50). |
--json | Machine-readable output. |
--json, status reports whether the judge ran, not what it decided. A binary eval the agent failed comes back as status: "passed" with passed: false; status: "errored" means the judge itself failed and the verdict fields are empty.brainbase agent connections
Show which integrations the agent is wired to. Read-only. Whether Slack, meeting and GitHub 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 --json
✓ slack Acme Corp
brainbase agent disconnect slack
· github not connected
GitHub renders the App-manifest confirmation page itself, so connecting it needs a browser. Use the web app.
· meeting not connected
brainbase agent connect meeting
· phone not connected
Connecting phone means buying a Twilio number, which is a purchase rather than an authorization. Use the web app.
| Flag | Description |
|---|---|
--json | Emit { linked, agent_id, integrations[] } and nothing else. An unlinked folder emits { linked: false, integrations: [] } — no agent_id, and no error — and exits non-zero. |
Each integration carries manageable_from_cli, which is false for the ones that still need a browser. An unlinked folder exits non-zero and still prints valid JSON, so a jq pipeline does not choke on empty input.
brainbase agent connect <slack|meeting>
Connect an integration. 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"
| Flag | Applies to | Description |
|---|---|---|
--bot-token <t> | slack | Bot token (xoxb-…). Also BRAINBASE_SLACK_BOT_TOKEN, or stdin. |
--signing-secret <s> | slack | Signing secret. Also BRAINBASE_SLACK_SIGNING_SECRET, or stdin. |
--app-id <id> | slack | Slack app id, recorded for reference. |
--app-name <name> | slack | Slack app name, recorded for reference. |
--bot-name <name> | meeting | Display name the agent joins meetings under. |
--bot-image-url <url> | meeting | Avatar for the meeting bot. |
--json | both | Emit the resulting integration state and nothing else. |
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 <slack|meeting>
Revoke an install. Removes the same record the web app's disconnect removes, and is idempotent, so disconnecting something that was never connected still succeeds.
brainbase agent disconnect slack
brainbase agent disconnect meeting --yes
| Flag | Description |
|---|---|
--yes, -y | Confirm the disconnect. At a terminal it skips the prompt; with no terminal it is required — without it the command exits non-zero naming the flag and leaves the install alone. See destructive commands. |
--json | Emit the resulting integration state and nothing else. Also authorises the disconnect on its own, terminal or not. |
After connecting or disconnecting, run agent pull to pick up or drop the matching built-in MCP server locally.
Runtime configuration
schema: 1
machine_kind: daytona
default_model: openai/gpt-5.6-terra
agent:
name: Repo Assistant
Both fields are optional. Omit default_model to leave it unmanaged, 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
| Flag | Description |
|---|---|
--harness <id> | Target harness (e.g. claude-code, codex, kafka). |
--scope <s> | global or 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
| Flag | Description |
|---|---|
--shell <sh\|fish> | Output format. Auto-detected from $SHELL when omitted. |
brainbase link / unlink / status
link attaches the current folder to an existing cloud agent; status shows what it's linked to; unlink disconnects it. Run agent list to find the id --agent takes.
brainbase link --agent <id> --no-tracking
brainbase status
brainbase unlink
| Flag | Applies to | Description |
|---|---|---|
--agent <id> | link | Attach to this agent non-interactively. |
--no-tracking | link | Don't route LLM traffic through Brainbase. |
--yes, -y | link, unlink | Skip confirmations. |
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.