brainbase orchestration
Create, pull, and push multi-agent graphs. See Orchestrations for the concept and the orchestration manifest for the full YAML schema. orch is an alias for orchestration.
brainbase orchestration init
Write a starter brainbase-orchestration.yaml in the current folder and stop. It needs no login and makes no network calls, so it works offline, in CI, and inside a sandbox. The file is valid input to orchestration create as written. It has no members, because create requires a local checkout for every member; add members after creating the orchestration with orchestration add-agent.
brainbase orchestration init --name "Support Flow"
brainbase orchestration create
brainbase orchestration add-agent triage
| Flag | Description |
|---|---|
--name <name> | Orchestration name. Defaults to the folder name. |
--full | Write a commented template documenting every optional block: icon, colour, credit limit, members, edges, and schedule triggers. |
--minimal | Write the starter manifest. This is the default. |
--force | Overwrite an existing brainbase-orchestration.yaml. Without it, init exits 1 and leaves the file alone. A folder linked to an orchestration is always refused: edit its manifest and run orchestration push instead. |
--json | Print { path, created, name, template }, or { path, created: false, reason } when it refuses. |
brainbase orchestration create
Claim a local brainbase-orchestration.yaml and create the orchestration in the cloud. Every declared member must already have a linked checkout under agents/<slug>/. The command validates the graph and schedule triggers, attaches the existing members, creates edges, edge settings, and schedule triggers, then writes gitignored link and sync state.
brainbase orchestration create
brainbase orchestration create --org <org-id-or-slug> --team <team-id> --yes
| Flag | Description |
|---|---|
--org <id-or-slug> | Create in this organization. |
--team <id> | Create in this team. |
--yes, -y | Skip the creation confirmation. |
brainbase orchestration list
List orchestrations under a team. --org accepts an organization ID or slug; --team accepts a team ID. Note the CLI's vocab inversion: --org maps to the DB teams.id and --team maps to the DB groups.id.
brainbase orchestration list
brainbase orchestration list --org <org-id-or-slug> --team <team-id>
brainbase orchestration list --team <team-id> --json | jq -r '.[].id'
| Flag | Description |
|---|---|
--org <id-or-slug> | List within this organization. |
--team <id> | List within this team. |
--json | Print the orchestration array and nothing else. Never prompts; pass --team <id> when the choice is ambiguous. |
brainbase orchestration pull <id>
Recursively fetch an orchestration plus every member agent. Pull preserves edge settings, materializes member runtime configuration, writes schedule triggers in their writable normalized form, and retains non-schedule app triggers as read-only context.
brainbase orchestration pull <orchestration-id>
brainbase orchestration pull <orchestration-id> --harness codex --yes
| Flag | Description |
|---|---|
--harness <id> | Harness for newly-created member folders (default claude-code). |
--yes, -y | Skip confirmation prompts. |
brainbase orchestration push
Recursively push each member agent, then update the graph: membership, edges, edge settings, and schedule triggers. Use --graph-only to update that graph without pushing member-agent content. Non-schedule triggers are preserved in YAML but ignored by push.
brainbase orchestration push
brainbase orchestration push --graph-only
brainbase orchestration push --force
| Flag | Description |
|---|---|
--graph-only | Push members, edges, edge settings, and schedule triggers, but not member-agent content. |
--force | Settle every conflict in the local manifest's favour. See below. |
--yes | Skip confirmation prompts. |
Push refuses, and names each conflict, when the cloud holds schedule triggers this checkout has never pulled or that were edited in the cloud since, or when orchestration metadata — name, description, icon, icon_color, credit_limit — changed both locally and in the cloud. Run orchestration pull to take the cloud's side, or --force to take yours. One flag settles both kinds: the cloud's conflicting schedule triggers are deleted and the metadata fields are overwritten with the file's values. A field only the cloud changed is never reverted. The flag applies to the graph only: member agents are still pushed without it, so a member's own conflict is settled with agent push --force in that member's folder.
brainbase orchestration add-agent <name>
Create a new member agent, wire its edges into the graph, and push. add is an alias for add-agent.
brainbase orchestration add-agent researcher --from planner --to writer
| Flag | Description |
|---|---|
--from <agent> | Source edge into the new agent (repeatable). |
--to <agent> | Edge out of the new agent (repeatable). |
--description <text> | Description for the new member agent. |
--schema <json> | Edge payload schema. |
--harness <id> | Target harness for the new member agent. |
--org <id> | Scope to an org. |
--no-push | Create and wire locally but skip the push. |
--yes | Skip confirmation prompts. |
brainbase orchestration delete <id>
Permanently delete an orchestration graph. Its member agents are kept. The id is required and never taken from the linked folder. Find ids with orchestration list.
brainbase orchestration delete <orchestration-id>
brainbase orchestration delete <orchestration-id> --yes --json
| Flag | Description |
|---|---|
--yes, -y | Delete without the confirmation prompt. Required with no terminal. See destructive commands. |
--json | Print { id, kind, name, deleted } and nothing else. Requires --yes, because --json never prompts. |
If the folder you run it in is linked to the deleted orchestration, the command says so: delete .brainbase/orchestration-link.json before recreating it with orchestration create.
brainbase orchestration status
Preview membership, edge description/payload/settings, and schedule trigger drift. Status also reports missing or stale member checkouts and cloud revision drift since the last pull. Schedule drift compares the UUID node, active state, normalized config, and target edges; non-schedule triggers are not diffed.
brainbase orchestration status