Skip to main content

CLI reference

broods syncs a local broods/ project to a project and stage, manages stages, environment variables and organizations, and gives you logs and a terminal chat for deployed agents. It runs on Bun 1.2+ or Node 22.15+.

bun add -g broods # or: npm install -g broods
broods # where you are pointed, what to run next, every command
broods <command> -h # one command's flags

Help and output​

broods on its own shows where the next command acts. It reads only .env.local, your shell and the stored login, and makes no network call.

broods v0.26.0

org beeblast
project my-app
stage development
server gateway.broods.app

Next
broods dev sync on save, tail logs
broods run <agent> chat with an agent

Commands
Develop dev diff run logs stream
Ship deploy env stage github
Inspect agent runs trace audit usage whoami
Account login connect disconnect org project
Tools init machine mcp update

Usage: broods <command> [options] -h, --help -v, --version
Run `broods <command> --help` for a command's flags.

Help does not apply defineBroods project or stage settings, because it never loads your broods/ code. broods whoami and the commands themselves do.

Pages of commands that act on a stage start with a target line. It appears on --help pages and on the page a grouped command prints with no subcommand. org, stage, env, agent, project and machine print their page that way. After broods stage use staging, broods deploy -h shows now my-app → production (ignores stage staging). The note only appears when BROODS_STAGE or --stage names another stage.

Options take their value as the next argument or inline, so --stage staging and --stage=staging are the same.

Every command marks its output the same way. ✔ marks a completed change, ! a warning and ✖ an error. Errors go to stderr and exit with code 1.

Where a command acts​

Four settings decide what a command touches.

SettingStored inChanged by
ServerBROODS_BASE_URL in .env.localbroods login, --base-url
Organizationthe CLI login token, server-sidebroods org use
ProjectBROODS_PROJECT in .env.localbroods dev prompt, --project
StageBROODS_STAGE in .env.localbroods stage use, --stage
  • The organization lives on the login token, so every project directory on the machine shares it. Run broods whoami before syncing somewhere shared.
  • deploy targets production, or the stages.deploy stage set with defineBroods, and ignores BROODS_STAGE. Pass --stage <name> to deploy elsewhere. Every other command follows BROODS_STAGE.
  • A variable exported in your shell wins over .env.local. The CLI warns when an export shadows a value it just wrote. unset BROODS_API_KEY to let the file take effect.
  • ~/.broods/config.json keeps one login per server, so a dev dashboard login never replaces a production one. A command uses the login for the server BROODS_BASE_URL names and stops with Not logged in to <server> when there is none.
  • The CLI writes ~/.broods/config.json and .env.local with mode 0600, and ~/.broods with 0700. The CLI adds .env*.local to .gitignore when nothing ignores .env.local yet.
  • The CLI loads broods/*.ts as ESM itself and never edits a package.json, so a CommonJS app keeps its module type.
  • The dashboard tracks its own active organization. After broods org use, switch the dashboard too, or a ?project=…&stage=… deep link resolves against the old one.

Global options​

Every command except mcp and update accepts these:

FlagDescription
--project <name>Project override. Default: package name or folder name
--stage <name>Stage override. Default: BROODS_STAGE
--base-url <url>Broods API base URL for sync and env calls. Default: set at login
--dashboard-url <url>Dashboard URL for login and deep links. Default: https://dashboard.broods.app
-h, --helpShow the command's help

broods -v prints the CLI version. org, stage, env, agent, project and machine print their help page when run without a subcommand.

Subcommands accept short aliases. ls means list, select means use, new means create, rm means project delete, and remove means env rm.

init​

Creates the broods/ project shell with a starter agent and sandbox, plus .env.local defaults.

broods init [--region <region>] [--force]
FlagDescription
--region <region>Service region preference, eu-west-1, us-east-1 or ap-southeast-1
--forceOverwrite existing starter files

In a repo that has CLAUDE.md, AGENTS.md, .claude/, .agent/ or .agents/, init and dev also write the broods skill to .agents/skills/broods/. It is written once and your edits survive. Only --force rewrites it.

login​

Authenticates through the dashboard in your browser and stores the token in ~/.broods/config.json.

broods login [--region <region>]

The browser hand-off uses PKCE, so only the CLI that started the login can exchange the code. The token belongs to an org owner or admin and is re-checked on every request. Demote or remove the user and it stops working.

login does not choose a project. It writes BROODS_PROJECT, BROODS_STAGE and BROODS_REGION to .env.local only when passed --project, --stage or --region. It records BROODS_BASE_URL so SDK clients in the project reach the same deployment.

Self-hosted:

export BROODS_BASE_URL="https://gateway.your-domain.example"
broods login --dashboard-url https://your-dashboard.example.com

logout​

Revokes the stored login on its server and removes it from ~/.broods/config.json. Logins for other servers stay.

broods logout [--base-url <url>]

A revoked token stops working at once, so run it on a machine you no longer trust with the login, or after a token leaked. A token the server does not revoke (already invalid, or lent to an agent) is removed locally all the same, with a warning instead of Logged out. A BROODS_TOKEN in the environment is left alone, and logout says so: the CLI cannot unset it, so remove it from your shell or CI settings.

connect​

Signs an external account in through the browser and keeps it on your deployment, so agents act through it. There is nothing to pass. Without a type, lists the account's connections. See Connections.

broods connect [chatgpt]

It uses the account key in BROODS_ACCOUNT_SECRET when set, otherwise your broods login. chatgpt works on self-hosted deployments, and on the managed service when the deployment enables it.

disconnect​

broods disconnect <chatgpt>

Forgets the connection and revokes its refresh token at the provider.

whoami​

Shows the login, server, organization, plan, project and stage the next command will use. Exits 1 when no login is saved for the server, so broods whoami && broods deploy stops early.

broods whoami
broods v0.26.0
Dashboard: https://dashboard.broods.app
Project: my-agent-project
Stage: development
Server: https://gateway.broods.app
User: you@example.com
Org: my-team (my-team, owner, free plan)
Account: my-team (active)
Runtime key: bsk_…vK8s (matches this org and stage)

It also checks the local BROODS_API_KEY against the key that org and stage serve and warns when they differ, which happens after switching organizations without resyncing. Before a project exists it prints Project: none and the folder name dev would suggest.

dev​

Watches broods/, syncs the current stage on every change, and live-tails agent logs.

broods dev [--once] [--level <lvl>] [--all] [--region <region>]
FlagDescription
--onceSync once and exit. No watch, no log tail
--level <lvl>Minimum tail level, DEBUG, INFO, WARN or ERROR. Default WARN
--allTail INFO and up. DEBUG lines are only in the dashboard
--region <region>Region preference used when dev onboards a new project

The first run in an empty folder does the setup. It opens the browser like login, asks for an organization, project, stage and service region, creates broods/ like init, asks for each env("NAME") value that neither .env.local nor the stage holds yet (the starter's OPENAI_API_KEY, typed hidden and saved to .env.local), pushes referenced secrets from .env.local, syncs, and writes BROODS_API_KEY and BROODS_USER_TOKEN_SECRET to .env.local. Only a terminal is asked; a piped or CI run fails the sync and names the missing variables.

On every sync dev:

  • pushes each env("NAME") value from .env.local that the stage does not already hold, like env sync
  • asks about each remote resource you removed from code and deletes only the ones you confirm
  • sends the stage revision it read, so a sync from another session in between refuses the write instead of overwriting it; dev then reads the stage again, reprints the diff and tries again, three attempts in all, and asks again before any delete
  • uploads each skill too large to send inline when anything in its definition changed since this stage last synced it, its files or a moved skill folder alike, or when the account no longer holds exactly those files (another stage or the dashboard may have replaced them); when the server names skills it does not hold, dev uploads only those and sends the manifest once more
  • regenerates broods/_generated/
  • writes a new user token signing secret to .env.local as BROODS_USER_TOKEN_SECRET when the stage has none yet, and warns when the stage has one this checkout does not hold (see Signing secret)
  • prints each channel's webhook URL

A sync that references an env("NAME") with no stored value fails before anything is written and names the missing variables. dev checks npm for a newer CLI at most once a day and prints a one-line notice.

A manifest conflict causes up to three sync attempts. If another sync still holds the stage, dev reports the failure and keeps watching; save again or rerun after that sync finishes. It does not queue unchanged source for automatic retry.

diff​

Shows local desired state against the current stage, without writing anything.

broods diff

Markers are [+] create, [~] rename, [*] update and [-] delete. It also warns when the stage's value for a referenced env("NAME") no longer matches .env.local:

! .env.local and demo-app/development disagree on 1 variable(s): ZALO_WEBHOOK_SECRET. Run `broods env sync` to push the local values.

deploy​

Syncs the production stage once, or the stages.deploy stage set with defineBroods, and writes its runtime key to .env.local.

It also stores the stage's source (broods/ text files, package.json, bun.lock); see Stored source. In GitHub Actions it records GITHUB_SHA with it.

broods deploy [--prune] [--rotate-key] [--region <region>] [--stage <name>]
FlagDescription
--pruneDelete remote resources the project no longer declares
--rotate-keyMint a fresh runtime key and write it to .env.local. The old key stops working
--regionProduction's region, pinned by its first deploy. Defaults to eu-west-1

Production region​

The first deploy to production that syncs its manifest pins its region, so data stays where you chose for GDPR. It takes --region, else eu-west-1, the only region live today; BROODS_REGION in .env.local is not read. A region Initialize Production set in the dashboard counts the same. A later deploy that names another region is refused with 409 and Production stays put; one that names none keeps the pinned region. --region on any other stage is an error. SDK callers set region on the manifest they pass to BroodsSyncClient.putManifest. A Production stage made this way opens directly in the dashboard, with no Initialize Production step.

Like dev, it writes the stage's user token signing secret as BROODS_USER_TOKEN_SECRET when the stage has none yet, and never rotates an existing one. See Signing secret. With CI set, as in GitHub Actions, it writes neither the runtime key nor the signing secret, since the checkout is thrown away; the next local dev or deploy mints the secret where you can read it.

deploy ignores BROODS_STAGE. Unlike dev, it never pushes secrets from .env.local. Set production values with broods env set or broods env sync --stage production, so a stale local value cannot ride a deploy. It warns when an agent lists a policy the deploy does not declare. --prune fails when an agent or channel record still references a policy it would remove, and names them. It removes skills, hooks and MCP servers only when this stage created them, never ones another stage manages or you made on the dashboard, and only after the rest of the deploy is accepted, so a manifest rejected before synchronization removes nothing. A later failure can leave committed changes; the deploy is not rolled back. A removed agent takes its cron jobs with it. A cron job is removed only when code declared it: one an agent scheduled at runtime, or you made on the dashboard, survives every prune. deploy sends no stage revision, so it can replace the last completed sync. An overlapping manifest PUT receives 409 manifest_conflict; retry after the active sync finishes. SDK callers pass prune: true to BroodsSyncClient.putManifest to remove every undeclared resource, or a list of { kind, name } to remove only those, as broods dev does after asking.

Signing secret​

A new agent refuses the runtime key without a signed user token, and signUserToken signs one with the stage's bsig_ signing secret from BROODS_USER_TOKEN_SECRET. The stage shows the secret only once, so after each sync dev and deploy compare the stage's hint with the secret in .env.local (or your shell) and act:

StageLocal secretWhat the CLI does
Has noneanyMints one and writes it to .env.local
Has onematchesNothing
Has onemissing or another oneWarns and keeps it. Copy it from where your backend has it, or rotate it on the dashboard

The CLI never rotates a secret the stage already has, so a CI deploy or a teammate's dev on a fresh checkout cannot void the secret a running backend signs with.

The CLI prints only that it wrote the secret, never the secret. Rotating takes keys:write on the stage: the account key and a project key hold it, a broods login token holds it while you do. The route is POST /v1/account/projects/{project}/stages/{stage}/user-token-secret.

env​

Manages encrypted environment variables in the current stage. Resources read them through env("NAME").

broods env <set|get|list|rm|sync> [name]
SubcommandDescription
set <name>Store a value, read from a prompt or stdin
get <name>Reveal a value. Audited. Needs a login token or the account key
listList names. Values stay hidden
rm <name>Remove a variable
syncPush every env("NAME") the project references from .env.local
echo "$VALUE" | broods env set SOME_NAME
  • Names are uppercase letters, digits and _, start with a letter, and are at most 64 characters. env("NAME") refs follow the same rule.
  • rm refuses while a synced agent or sandbox still references the name, and says which. Remove the reference and sync first. To rotate a secret, run set again instead.
  • sync only touches names the project references. It skips values the stage already holds, never deletes, and never touches BROODS_* variables. It reports names that exist only on the stage.
▌ ↑ Synced 1 env var(s) from .env.local: ZALO_WEBHOOK_SECRET
3 other referenced variable(s) already in step with demo-app/production.
1 referenced variable(s) live only on demo-app/production: SLACK_SIGNING_SECRET

The stage answers a SHA-256 of each value on request, so sync and diff compare without the CLI reading secrets. A project key can set and list variables but not read them.

run​

Opens a terminal chat with a deployed agent.

broods run <agent> [prompt]
broods run my-agent "Summarize the open issues"
broods run my-agent "ping" > answer.txt # plain text, no UI
  • The session streams reasoning, shows tool calls as cards with input and output, and stops for y/n on tools that need approval. It stays open for follow-ups.
  • Enter sends, arrows or PgUp and PgDn scroll, and Ctrl+L repaints. Esc while the agent answers stops that answer on screen and keeps the chat open (the run already sent still finishes on the server); Esc when idle, or Ctrl+C, leaves.
  • When stdin or stdout is not a terminal, run prints the answer as plain text. A prompt is then required.
  • run reaches the agent with your 15-minute stage session ticket, the credential logs uses, not the runtime key. So it runs private agents and agents that require a user token, and a long chat gets a fresh ticket before the old one ends.
  • Each turn is a normal run on one conversation. Tools, sandboxes and policies behave as in production.

agent​

Inspects the agents in the current project and stage.

broods agent list # name, public or private, model, deploy status
broods agent get my-agent # model, sandboxes, workspaces, tools, channels, webhooks

logs​

Backfills recent logs, then live-tails. Needs a broods login token and a deployed stage.

broods logs [-n <n>] [--level <lvl>] [--all] [--json] [--sandbox <id>]
FlagDescription
-n, --limitBackfill line count. Default 100
--level <lvl>Minimum level, DEBUG, INFO, WARN or ERROR. Default WARN
--allEvery level. DEBUG comes from the backfill only
--jsonPrint each log line as JSON
--sandbox <id>Tail one sandbox instance's guest output instead. The id is the UUID in the dashboard Instances sheet

The CLI trades your login token for a 15-minute stage session ticket and refreshes it on reconnect. The runtime key in BROODS_API_KEY cannot open logs, because logs carry every end user's chats. Code hook console.* lines appear here too, tagged source: "user-code".

trace​

Prints one run's trace by id and exits: every model step and tool call with its status, duration and error. Needs a broods login token and a deployed stage, like logs.

broods trace <trace-id> [--json]
FlagDescription
--jsonPrint every span as a JSON array, with its full attributes: system prompt, model input, reasoning, response, tool input and output, and the error

The trace id is the 32-character id on the run in the dashboard Tracing tab. Its Copy prompt for agent button copies the ids plus this command, so a coding agent can read the run and fix or audit it. Traces are kept 30 days, so one older than the seven-day search window still opens by id until then.

runs​

Prints the stage's recent runs, newest first, with the trace id broods trace takes. Needs a broods login token and a deployed stage. --agent asks the gateway for that agent's runs only. --status filters the newest 500 runs. Both search the last seven days.

broods runs [--limit <n>] [--agent <id>] [--status <status>] [--json]

audit​

Prints the account's audit events, newest first, without the hash chain. It reads the newest 500 and says so when older ones exist.

broods audit [--limit <n>] [--agent <id>] [--action <name>] [--json]

usage​

Prints the stage's tokens, invocations, model calls and run time.

broods usage [--range <1h|3h|1d|7d|30d|1y>] [--json]

stream​

Live-tails logs for the whole project and stage until Ctrl+C. No backfill.

broods stream [--level <lvl>] [--all]

--level works as in logs. --all streams INFO and up. Authentication is the same as logs.

org​

Lists, switches and creates organizations.

broods org list # current org marked with *
broods org use beeblast # slug, name or id
broods org create "New Org"

On the managed service creating an organization needs Pro: past your own Hobby workspace, create is refused with payment_required until you are on Pro. Upgrade in the dashboard's Billing tab first; Pro covers every organization you own, and each new one starts on it. Only organizations where you are owner or admin, with a provisioned API account, can be selected. use and create store the choice and rewrite BROODS_API_KEY for the current project and stage in the new organization. If the project does not exist there yet, the CLI warns and keeps the old key. Run broods dev to create the project and mint a key.

project​

Lists projects in the organization, or deletes one.

broods project list
broods project delete abandoned-e2e [--yes]
Projects:
support: 1 stage(s), 1 agent(s), 7 env var(s), 1 deployment(s), 0 workspace file(s)
abandoned-e2e: empty

delete removes the project on every stage, including agent configs, canvas, environment variables, project keys, cron schedules, and workspace files with their stored blobs. It needs the org admin role. There is no undo. The prompt shows the counts first. --yes skips it. Without a TTY the prompt answers no, so a CI run without --yes deletes nothing.

github​

Links the project to a GitHub repo, so a push deploys its stage from your own GitHub Actions. See GitHub.

broods github status # the link, latest deploy per branch, connected accounts
broods github repos # repos the org's connected accounts let you link
broods github link acme/web # main deploys Development, or Production when the project has it
broods github link acme/web --production-branch main --development-branch dev
broods github unlink [--yes]
broods github connect # install the Broods GitHub App on another account
FlagDescription
--folder <path>The folder holding broods/, when the repo has several
--production-branch <name|none>Branch Production deploys from. Default: the repo's default branch when the project has a Production stage, else none
--development-branch <name|none>Branch Development deploys from, created when missing. Default: dev beside Production, else the default branch
--jsonPrint the result as JSON

none leaves that stage out: no key for it, and no push deploys it. Linking the project's repo again changes its branches in place: new keys, the old ones revoked. Naming a Production branch adds the Production stage when the project has none. The two branches must differ. unlink on a project with no linked repo fails with a not-found error. Linking and unlinking need keys:write on the project, connect an org admin. The commands use your broods login and act in its organization.

stage​

Lists, switches and creates stages in the current project.

broods stage list
broods stage create staging --from development [--use]
broods stage use staging
FlagDescription
--from <stage>Deep-copy agent configs, MCP servers, canvas and every env var from that stage
--useSwitch to the new stage right away
  • Without --from the new stage is empty. Cloned secrets live in both stages, so removing one later means removing it twice.
  • use writes BROODS_STAGE and refreshes BROODS_API_KEY, since the runtime key is per stage. Run broods dev afterwards to sync your resources there.
  • development and production are reserved names. Other names must be lowercase letters, digits and dashes, such as staging or qa-2, because they appear in URLs and log labels.

machine​

Connects this computer to a machine sandbox, so agents on it run bash here as you. See Machine.

broods machine <sandbox> [--cwd <dir>] [--computer] [--mcp <file>] [--force]
broods machine --doctor [--request]
FlagDescription
--cwd <dir>Working directory for commands. Default: current directory
--computerAlso serve the computer tool for screenshots, mouse and keyboard. macOS only
--mcp <file>Run the stdio MCP servers in this .mcp.json for MCP rows on this sandbox
--forceTake the record over from another daemon
--doctor [--request]Check the Screen Recording and Accessibility grants --computer needs. --request shows the macOS prompts
  • Needs a broods login token and a deployed stage. The daemon uses a 15-minute stage ticket and sends core a fresh one on the open socket before it expires, so a running command is not interrupted. Each reconnect mints a fresh ticket too.
  • It reconnects after a network drop. Another daemon on any computer is refused while this one holds the record, and the refusal names the host. --force is only needed after a daemon died while offline.
  • Agent commands and --mcp servers never see BROODS_* variables.

mcp​

Serves the account config plane to a coding agent over MCP on stdio. Start it from an MCP client, not a terminal. It speaks MCP 2026-07-28 only, so the client must too: a 2025-era initialize gets error -32022.

claude mcp add broods -- broods mcp

Tools are few on purpose, since each one costs the agent context on every session. list-resources, get-resource, create-resource, update-resource and delete-resource take a resource: agent, cron, sandbox, workspace, policy, role, channel, skill or mcp. A list returns only the fields that pick a record, and get-resource returns the rest. sandbox-action suspends, resumes, terminates, snapshots or opens a terminal on a reservation. The others are list-cron-runs, upload-skill, list-env-vars, set-env-var, delete-env-var, get-account, update-account, rotate-secret and assume-role. An mcp record takes project and stage, defaulted from BROODS_PROJECT and BROODS_STAGE.

With a stored broods login, it also registers list-orgs, create-org, select-org, list-projects, list-stages and create-stage. Creating a stage under a new project name creates the project.

The server reads credentials from the environment once, at startup.

CredentialWhat the agent can reach
BROODS_SESSION_TOKEN, a role sessionWhat the role's policy allows. Preferred
BROODS_ACCOUNT_SECRET, the account keyThe whole account
Stored broods login onlyOrg, project and stage tools only

The server enforces these guards itself.

  • A delete needs confirm: true and takes one id.
  • There is no tool that reads env values.
  • list-runs and read-logs default to the last hour. Supply epoch-millisecond from and to for an older range; follow nextTo with the same from to continue. Empty pages may have older results. incomplete means retry the same page.
  • list-runs, read-trace and read-logs need a broods login, and open a read-only ticket for that one stage. With a stored login they register even with no account credential in the environment. read-audit and read-usage use the account credential in the environment when there is one, so a role's policy still bounds them, and the stored login otherwise.
  • A stage-scoped resource refuses a call with no scope.
  • rotate-secret and delete-project stay unregistered unless BROODS_MCP_ALLOW_DESTRUCTIVE=1 is exported in the shell that starts the server. A value in .env or .env.local is ignored, since the agent can write those files.

See Security for minting a role session.

update​

Installs the newest release of the major you run, with the package manager that installed the CLI.

broods update

A global bun or npm install is replaced in place. Inside a project, the dependency is upgraded with the manager its lockfile names: bun, pnpm, yarn, or npm when there is none. A new major is only announced. Install it yourself, for example npm install -g broods@1.

Upgrading from older versions​

OldNow
broods statusbroods whoami
--env <name>--stage <name>
BROODS_ENVIRONMENT in .env.localBROODS_STAGE
BROODS_CONTROL_URL, --control-urlRemoved. BROODS_BASE_URL serves both the CLI and the SDK
/api/cli/* routes/v1/account/*

status, --env and BROODS_ENVIRONMENT fail with an error that names the replacement. BROODS_CONTROL_URL, --control-url and the /api/cli/* routes no longer exist, so they do nothing. Environment-based auth needs both BROODS_TOKEN and BROODS_BASE_URL. Logins from before the base URL change need broods login again.