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.
brainbase agent create
brainbase agent create --name "Repo Assistant" --tagline "Reviews PRs"
| Flag | Description |
|---|---|
| `--name <name>` | Agent name (otherwise prompted / read from the manifest). |
| `--tagline <text>` | Short tagline for the agent. |
| `--org <id>` / `--team <id>` | Create under a specific org / 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. |
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.
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`). |
brainbase agent push
Send local manifest changes — instructions, entrypoint, playbooks, skills, and MCP servers — to the cloud. Pass --force to overwrite the cloud version.
brainbase agent push
brainbase agent push --force
brainbase agent status
Preview what would push and what would pull, without changing anything.
brainbase agent status
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.
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
Publish the linked agent. Pass --yes to skip confirmation.
brainbase publish --yes