Output formats

acpx streams agent activity in three output modes plus two modifiers. Pick the one that matches your consumer: a human terminal, an automation pipeline, or a script that only wants the final answer.

#text (default)

Human-readable stream:

• assistant text as it arrives
• [thinking] blocks for reasoning chunks
• [tool] <title> (<status>) blocks with output, diff previews, and plan updates
• [done] <stopReason> at the end

acpx codex 'review the auth module'

[thinking] Reading src/auth and looking for token validation
[tool] Read src/auth/index.ts (completed)
[tool] Run grep -n 'verifyToken' src/auth (completed)
  output:
    src/auth/jwt.ts:42:export function verifyToken
The auth module is structured as …
[done] end_turn

text is best for interactive use. It is not stable for parsing — error messages, prompts, and progress updates can change between releases.

#json

NDJSON stream of raw ACP JSON-RPC messages on stdout:

acpx --format json codex exec 'review changed files' \
  | jq -r 'select(.method=="session/update")'

{"jsonrpc":"2.0","id":"req-1","method":"session/prompt","params":{"sessionId":"019c…","prompt":"hi"}}
{"jsonrpc":"2.0","method":"session/update","params":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Hello"}}}
{"jsonrpc":"2.0","id":"req-1","result":{"stopReason":"end_turn"}}

Hard rules for json:

• No acpx-specific event envelope wrapping ACP messages.
• No synthetic type / stream / eventVersion keys injected onto raw ACP traffic.
• No payload key renaming.

What you read on stdout is the same wire-level JSON that would have crossed the ACP transport, in submission order.

stderr can still contain prompts, progress, or warnings. If your script reads only stdout, that is fine. If you pipe both, see --json-strict below.

#--format json --json-strict

Strict JSON suppresses non-JSON output that would otherwise land on stderr:

acpx --format json --json-strict codex exec 'list TODO comments' > events.ndjson

--json-strict requires --format json. It guarantees:

• stdout is one ACP JSON-RPC message per line
• stderr stays quiet for non-error informational output

This is the right combination for "fully machine-consumed pipelines that should fail visibly on real errors."

#quiet

Final assistant text only — no tool blocks, no thinking, no [done]:

SUMMARY=$(acpx --format quiet codex exec 'one-line summary of this branch')
echo "$SUMMARY"

When the adapter includes final token usage and cost metadata in the prompt result, acpx emits that to stderr in quiet mode. stdout stays as the assistant text only.

quiet is unaffected by --suppress-reads because it does not print tool call output to begin with.

#--suppress-reads

Replaces raw read-file payloads with a placeholder so logs stay readable when an agent reads a large file:

acpx --suppress-reads codex exec 'inspect repo and report tool usage'

The replacement preserves the surrounding ACP message shape so json consumers can still parse the stream — only the content payload is masked.

#Session-control command output

Local query commands emit local JSON shapes (not ACP wire traffic) under --format json:

Closed sessions are marked [closed] in text and quiet.

#Identity fields in JSON

Session-control JSON always includes:

Do not assume the acpxRecordId can be passed to a native provider CLI. Use agentSessionId for that, when present.

#Picking a mode

#See also

• Sessions — what session-control commands return.
• Permissions — how denials surface in each format.
• CLI reference — full per-mode behavior table.