Headless

bro run sends one prompt to an ACP agent without opening the TUI. Use it in scripts or automation when you need streamed updates or an assistant reply.

Send a prompt

Choose an ACP server from the bundled catalog or your agents: configuration. Supply the prompt as an argument, through stdin, or from a file:

bro run codex "Summarize this repository"
printf 'Review this diff' | bro run claude -
bro run codex --prompt-file task.md --format quiet

Use --cwd <PATH> to set the working directory supplied to the agent session.

Choose the output

bro run codex "Summarize this repository" --format ndjson
bro run codex --prompt-file task.md --format text

Use --result-schema @schema.json when the final reply must satisfy a JSON Schema, or supply the schema as inline JSON. Set --turn-timeout <SECS> to bound the turn. The generated CLI reference lists the complete options.

Permissions

bro run denies permission requests by default. Choose the policy required by the task:

For an inspection task:

bro run codex "Review this repository" --approve-reads

For rules stored in a file:

{
  "autoApprove": ["read", "search"],
  "autoDeny": ["edit", "execute"],
  "defaultAction": "deny"
}

bro run codex "Review this repository" --permission-policy @permissions.json

Entries match the ACP tool kind, the tool-call title, or its first word. autoDeny wins over autoApprove. Unmatched requests use defaultAction, or the selected mode flag when no default action is supplied. See the generated CLI reference for the complete contract.

Routing and sessions

Supported adapters attempt to route model traffic through the local daemon by default. Use --model to pin a model, --base-url to select an explicit gateway, or --direct to use the harness's own provider authentication. --no-start fails when the local daemon is unavailable instead of starting it.

When the adapter supports native session persistence, --load <id> replays a harness-native session and --resume <id> continues one without replaying history. The harness owns the session identity and history.

Execution boundaries

These options govern permission requests made by an ACP harness. Native harness launch uses the harness's own permission configuration. They do not define an execution sandbox or grant upstream credentials.

Server tools have a separate activation contract: the deployment enables the implementation and the request opts into it. Caller access policy, upstream credentials, and the tool's own approval rules still apply.