ba run

ba run <agent> [options] executes exactly one hosted Turn without a TUI or interactive prompt. Complete CLI setup and authentication first; the command never retries automatically, making it the CLI interface for scripts and CI.

Choose one input

Provide exactly one non-empty source:

--prompt <text> for a literal prompt;
non-TTY stdin, including a pipe or redirected file; or
--prompt-id <id> for a stored Prompt, with each value supplied once as --var key=value.

--prompt conflicts with --prompt-id. --var requires --prompt-id; missing, unknown, duplicate, or malformed variables fail before the Turn. Empty literal or stdin input also fails.

ba run 'Release Agent' \
  --prompt-id prompt_0123456789abcdef \
  --var version=1.2.3 --var environment=production

Run stateless or resume a Session

The default is stateless generation and creates no Session. --session <id> first verifies an existing Session owned by the selected Agent, then appends one Turn; a missing or foreign Session fails with no stateless or new-Session fallback.

--user-id and JSON-object --metadata attribute the Turn and its usage. For an existing Session, these inputs do not change the Session's immutable Attribution.

Choose an output mode

Plain mode streams only assistant text to stdout, with no label or added newline. For an explicit Session Turn, diagnostics and bounded, recursively secret-redacted Tool summaries go to stderr. --tool-output summary is the default; --tool-output off suppresses successful Tool summaries but retains warnings, denials, and failures.

--json buffers a successful result and writes exactly one document containing agent, output, and sessionId only for an explicit Session Turn:

ba run 'Release Agent' --prompt 'Give the status' --json \
  | jq -r '.output'

--schema <file> reads JSON Schema, performs stateless object generation, validates the final value locally, and implies buffered JSON output. It conflicts with --session.

Buffered JSON and schema failures or cancellations leave stdout empty. Plain streaming can retain assistant text written before a later failure.

Handle Tool approval

For a Session Turn, ba run reports each durable approval request and its Session ID on stderr, then exits with an operational failure. It never approves or denies on behalf of a human.

ba assist cannot recover an ordinary Agent Session: it always selects the Tenant's Admin Agent and accepts only that Agent's Sessions. To recover an approval reported by ba run, your application must list, decide, and join it through the SDK, or use the matching REST operations. Review the Tool approval lifecycle before implementing that flow.

Exit statuses and signals

Status	Meaning
`0`	Turn succeeded
`1`	Authentication, lookup, API, stream, model, Tool, or other operational failure
`2`	Invalid invocation or malformed local input
`130`	Interrupted by SIGINT
`143`	Terminated by SIGTERM

SIGINT and SIGTERM abort the active request through the SDK. The CLI does not retry because a Tool may already have completed a side effect even when the client reports cancellation or failure.