How to enable JSON output in Codex

JSON output makes Codex runs easier to consume from scripts, CI jobs, and log processors because each event is emitted as a separate JSON object instead of plain terminal text.

In codex exec, the --json flag switches stdout to a JSON Lines (JSONL) stream. The stream can include lifecycle events such as thread.started and turn.completed plus item records for agent messages, tool calls, file changes, and errors when they occur.

JSONL is useful when automation needs every event from a run, but it is noisier than the default final-message output. Use it when another program will read the event stream, switch to --output-schema when a single final JSON object is required, and keep the run inside a trusted repository directory unless the task intentionally needs the repository check disabled.

1. Run codex exec with --json and a short prompt.

   $ codex exec --json "Return OK."
   {"type":"thread.started"}
   {"type":"turn.started"}
   {"type":"item.completed","item":{"type":"agent_message","text":"OK"}}
   {"type":"turn.completed"}

   Each stdout line is a separate JSON object. Related: How to fix Codex trusted directory error
   Related: How to skip Codex git repository checks

2. Redirect stdout to a file when another tool should consume the JSONL stream later.

   $ codex exec --json "Return OK." > codex-run.jsonl

   With --json enabled, stdout is the event stream, so shell redirection writes JSONL instead of a plain reply.

3. Open the saved file and confirm the run finished with a turn.completed event.

   $ cat codex-run.jsonl
   {"type":"thread.started"}
   {"type":"turn.started"}
   {"type":"item.completed","item":{"type":"agent_message","text":"OK"}}
   {"type":"turn.completed"}

   A turn.failed or error event indicates the run did not finish cleanly.

4. Pipe the JSONL stream to jq when a script only needs selected fields from each event.

   $ codex exec --json "Return OK." | jq -r '.type'
   thread.started
   turn.started
   item.completed
   turn.completed