Command Reference

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. See Agents & linking for the lifecycle.

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.

bash

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; also scaffold a minimal manifest when none exists.

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.

bash

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, 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.

bash

brainbase agent push
brainbase agent push --force

Flag	Description
`--force`	Overwrite cloud-side content and `default_model` conflicts with local values; never overrides `machine_kind` immutability.
`--yes`, `-y`	Skip confirmation prompts.

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.

bash

brainbase agent status

Runtime configuration

brainbase.agent.yamlyaml

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.

bash

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.

bash

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.

bash

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.

bash

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.

bash

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

brainbase publish

Publish the linked agent. Pass --yes to skip confirmation.

bash

brainbase publish --yes