La CLI de Cursor Agent ofrece varios formatos de salida con la opción --output-format cuando se usa junto con --print. Estos formatos incluyen formatos estructurados para uso programático (json, stream-json) y un formato de texto simplificado para hacer seguimiento del progreso en un formato legible.
El --output-format predeterminado es stream-json. Esta opción solo es válida al imprimir (--print) o cuando se infiere el modo de impresión (stdout no TTY o stdin por tubería).

​
Formato JSON

El formato de salida json emite un único objeto JSON (seguido de un salto de línea) cuando la ejecución se completa correctamente. No se emiten deltas ni eventos de herramientas; el texto se agrega en el resultado final. En caso de error, el proceso termina con un código distinto de cero y escribe un mensaje de error en stderr. No se emite ningún objeto JSON bien formado en caso de error.

​
Respuesta exitosa

Cuando se completa correctamente, la CLI imprime un objeto JSON con la siguiente estructura: 
{
  "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>"
}
CampoDescripción
typeSiempre "result" para resultados finales
subtypeSiempre "success" para ejecuciones exitosas
is_errorSiempre false para respuestas exitosas
duration_msTiempo total de ejecución en milisegundos
duration_api_msTiempo de la solicitud a la API en milisegundos (actualmente igual a duration_ms)
resultTexto completo de la respuesta del asistente (concatenación de todos los deltas de texto)
session_idIdentificador único de la sesión
request_idIdentificador opcional de la solicitud (puede omitirse)

​
Formato JSON de streaming

El formato de salida stream-json emite JSON delimitado por saltos de línea (NDJSON). Cada línea contiene un único objeto JSON que representa un evento en tiempo real durante la ejecución. El streaming termina con un evento terminal result en caso de éxito. En caso de error, el proceso finaliza con un código distinto de cero y el streaming puede terminar antes sin un evento terminal; se escribe un mensaje de error en stderr.

​
Tipos de eventos

​
Inicialización del sistema

Emitido una vez al comienzo de cada sesión: 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/absolute/path",
  "session_id": "<uuid>",
  "model": "<model display name>",
  "permissionMode": "default"
}
En el futuro, podrían añadirse campos como tools y mcp_servers a este evento.

​
Mensaje del usuario

Contiene el prompt de entrada del usuario: 
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

​
Delta de texto del asistente

Emitido varias veces mientras el asistente genera su respuesta. Estos eventos contienen fragmentos de texto incrementales: 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta chunk>" }]
  },
  "session_id": "<uuid>"
}
Concatena todos los valores de message.content[].text en orden para reconstruir la respuesta completa del asistente.

​
Eventos de llamadas a herramientas

Las llamadas a herramientas se registran con eventos de inicio y finalización: Llamada a herramienta iniciada: 
{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" }
    }
  },
  "session_id": "<uuid>"
}
Llamada a herramienta completada: 
{
  "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>"
}

​
Tipos de llamadas a herramientas

Herramienta de lectura de archivos:
  • Iniciada: tool_call.readToolCall.args contiene { "path": "file.txt" }
  • Completada: tool_call.readToolCall.result.success contiene metadatos y contenido del archivo
Herramienta de escritura de archivos:
  • Iniciada: tool_call.writeToolCall.args contiene { "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
  • Completada: tool_call.writeToolCall.result.success contiene { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
Otras herramientas:
  • Pueden usar la estructura tool_call.function con { "name": "tool_name", "arguments": "..." }

​
Resultado terminal

El evento final emitido al completarse correctamente: 
{
  "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>"
}

​
Secuencia de ejemplo

Aquí tienes una secuencia NDJSON representativa que muestra el flujo típico de eventos: 
{"type":"system","subtype":"init","apiKeySource":"login","cwd":"/Users/user/project","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","model":"Claude 4 Sonnet","permissionMode":"default"}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Lee README.md y crea un resumen"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Voy a "}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"leer README.md"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"},"result":{"success":{"content":"# Project\n\nThis is a sample project...","isEmpty":false,"exceededLimit":false,"totalLines":54,"totalChars":1254}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":" y crear un resumen"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README Summary\n\nThis project contains...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README Summary\n\nThis project contains...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"},"result":{"success":{"path":"/Users/user/project/summary.txt","linesCreated":19,"fileSize":942}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"result","subtype":"success","duration_ms":5234,"duration_api_ms":5234,"is_error":false,"result":"Voy a leer README.md y crear un resumen","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

​
Formato de texto

El formato de salida text ofrece un flujo simplificado y legible para personas con las acciones del agente. En lugar de eventos JSON detallados, muestra descripciones de texto concisas de lo que el agente hace en tiempo real. Este formato es útil para monitorear el progreso del agente sin la carga de parsear datos estructurados, lo que lo hace ideal para logging, depuración o un seguimiento simple del progreso.

​
Ejemplo de salida

Read file
Edited file
Ran terminal command
Created new file
Cada acción aparece en una línea nueva a medida que el agente la ejecuta, ofreciendo retroalimentación inmediata sobre el progreso del agente en la tarea.

​
Notas de implementación

  • Cada evento se emite como una sola línea terminada en \n
  • Los eventos thinking se suprimen en modo print y no aparecerán en ningún formato de salida
  • Pueden añadirse campos con el tiempo de forma retrocompatible (los consumidores deben ignorar los campos desconocidos)
  • El formato streaming ofrece actualizaciones en tiempo real, mientras que el formato JSON espera a la finalización antes de mostrar resultados
  • Concatená todos los deltas del mensaje de assistant para reconstruir la respuesta completa
  • Los IDs de llamadas a herramientas pueden usarse para correlacionar los eventos de inicio y finalización
  • Los IDs de sesión se mantienen consistentes durante una única ejecución del agente