pages/cli/reference/output-format.txt

route: /docs/cli/reference/output-format
title: Output format
description: Control output formatting for Cursor CLI commands and responses.

Output format
The Cursor Agent CLI provides multiple output formats with the --output-format option when combined with --print. These formats include structured formats for programmatic use (json, stream-json) and a simplified text format for human-readable output (text).
The default --output-format is text. This option is only valid when
printing (--print) or when print mode is inferred (non-TTY stdout or piped
stdin).
JSON format
The json output format emits a single JSON object (followed by a newline) when the run completes successfully. Deltas and tool events are not emitted; text is aggregated into the final result.
On failure, the process exits with a non-zero code and writes an error message to stderr. No well-formed JSON object is emitted in failure cases.
Success response
When successful, the CLI outputs a JSON object with the following structure:
{
"type": "result",
"subtype": "success",
"is_error": false,
"duration_ms": 1234,
"duration_api_ms": 1234,
"result": "<full assistant text>",
"session_id": "<uuid>",
"request_id": "<optional request id>"
}
Field
Description
type
Always "result" for terminal results
subtype
Always "success" for successful completions
is_error
Always false for successful responses
duration_ms
Total execution time in milliseconds
duration_api_ms
API request time in milliseconds (currently equal to duration_ms)
result
Complete assistant response text (concatenation of all text deltas)
session_id
Unique session identifier
request_id
Optional request identifier (may be omitted)
Stream JSON format
The stream-json output format emits newline-delimited JSON (NDJSON). Each line contains a single JSON object representing an event during execution. This format aggregates text deltas and outputs one line per assistant message (the complete message between tool calls).
The stream ends with a terminal result event on success. On failure, the process exits with a non-zero code and the stream may end early without a terminal event; an error message is written to stderr.
Streaming partial output: For real-time character-level streaming, use --stream-partial-output with --output-format stream-json. This emits text as it's generated in small chunks, with multiple assistant events per message.
With --stream-partial-output, the CLI emits three kinds of assistant events. Only the first kind contains new text:
timestamp_ms
model_call_id
What it is
Action
Present
Absent
Streaming delta with new text
Use — append message.content[].text
Present
Buffered flush before a tool call (duplicate)
Skip
Absent
Final flush at end of turn (duplicate)
Skip
If you don't need real-time streaming and only want the finished answer, skip all assistant events and read the result field from the terminal result event.
Event types
System initialization
Emitted once at the beginning of each session:
{
"type": "system",
"subtype": "init",
"apiKeySource": "env|flag|login",
"cwd": "/absolute/path",
"session_id": "<uuid>",
"model": "<model display name>",
"permissionMode": "default"
}
Future fields like tools and mcp_servers may be added to this event.
User message
Contains the user's input prompt:
{
"type": "user",
"message": {
"role": "user",
"content": [{ "type": "text", "text": "<prompt>" }]
},
"session_id": "<uuid>"
}
Assistant message
Emitted once per complete assistant message (between tool calls). Each event contains the full text of that message segment:
{
"type": "assistant",
"message": {
"role": "assistant",
"content": [{ "type": "text", "text": "<complete message text>" }]
},
"session_id": "<uuid>"
}
When --stream-partial-output is enabled, assistant events may include two additional fields:
Field
Description
timestamp_ms
Present on streaming deltas and pre-tool-call flushes. Absent on the final flush at the end of a turn.
model_call_id
Present only on the buffered flush emitted before a tool call. Use this to identify and skip duplicate text.
See the streaming partial output note above for how to filter these events.
Tool call events
Tool calls are tracked with start and completion events:
Tool call started:
{
"type": "tool_call",
"subtype": "started",
"call_id": "<string id>",
"tool_call": {
"readToolCall": {
"args": { "path": "file.txt" }
}
},
"session_id": "<uuid>"
}
Tool call completed:
{
"type": "tool_call",
"subtype": "completed",
"call_id": "<string id>",
"tool_call": {
"readToolCall": {
"args": { "path": "file.txt" },
"result": {
"success": {
"content": "file contents...",
"isEmpty": false,
"exceededLimit": false,
"totalLines": 54,
"totalChars": 1254
}
},
"session_id": "<uuid>"
}
Tool call types
Read file tool:
Started: tool_call.readToolCall.args contains { "path": "file.txt" }
Completed: tool_call.readToolCall.result.success contains file metadata and content
Write file tool:
Started: tool_call.writeToolCall.args contains { "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
Completed: tool_call.writeToolCall.result.success contains { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
Other tools:
May use tool_call.function structure with { "name": "tool_name", "arguments": "..." }
Terminal result
The final event emitted on successful completion:
{
"type": "result",
"subtype": "success",
"duration_ms": 1234,
"duration_api_ms": 1234,
"is_error": false,
"result": "<full assistant text>",
"session_id": "<uuid>",
"request_id": "<optional request id>"
}
Example sequence
Here's a representative NDJSON sequence showing the typical flow of events:
$70
Text format
The text output format provides only the final assistant message without any intermediate progress updates or tool call summaries. This is the cleanest output format for scripts that only need the agent's final response.
This format is ideal when you want just the answer or final message from the agent, without any progress indicators or tool execution details.
Example output
The command to move this branch onto main is `git rebase --onto main HEAD~3`.
Only the final assistant message (after the last tool call) is output, with no tool call summaries or intermediate text.
Notes
Each event is emitted as a single line terminated by \n
thinking events are suppressed in print mode and will not appear in any output format
Field additions may occur over time in a backward-compatible way (consumers should ignore unknown fields)
The json format waits for completion before outputting results
The stream-json format outputs complete agent messages
The --stream-partial-output flag provides real-time text deltas for character-level streaming (only works with stream-json format)
Tool call IDs can be used to correlate start/completion events
Session IDs remain consistent throughout a single agent execution