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 opciones estructuradas para uso programático (json, stream-json) y un formato de texto simplificado para un seguimiento del progreso legible por humanos.
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 encadenado).

​
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 casos de error.

​
Respuesta correcta

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>"
}
FieldDescription
typeSiempre "result" para resultados terminales
subtypeSiempre "success" para ejecuciones correctas
is_errorSiempre false para respuestas correctas
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 de solicitud opcional (puede omitirse)

​
Formato JSON de stream

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 stream termina con un evento terminal result en caso de éxito. En caso de fallo, el proceso termina con un código distinto de cero y el stream puede terminar antes de tiempo sin un evento terminal; se escribe un mensaje de error a stderr.

​
Tipos de eventos

​
Inicialización del sistema

Se emite 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 se pueden agregar 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

Se emite múltiples 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 message.content[].text en orden para reconstruir la respuesta completa del asistente.

​
Eventos de llamadas a herramientas

Las llamadas a herramientas se rastrean 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 del archivo y contenido
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 exitosamente: 
{
  "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 el 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 el archivo 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":"# Proyecto\n\nEste es un proyecto de ejemplo...","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":"# Resumen del README\n\nEste proyecto contiene...","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":"# Resumen del README\n\nEste proyecto contiene...","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 el archivo 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 proporciona un flujo simplificado y legible de las acciones del agente. En lugar de eventos JSON detallados, muestra descripciones concisas en texto de lo que el agente está haciendo 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 nueva línea 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 por \n
  • Los eventos thinking se suprimen en modo de impresión y no aparecerán en ningún formato de salida
  • Pueden agregarse campos con el tiempo de manera compatible con versiones anteriores (los consumidores deben ignorar campos desconocidos)
  • El formato de stream proporciona actualizaciones en tiempo real, mientras que el formato JSON espera a completarse antes de mostrar los resultados
  • Concatena todos los deltas de mensajes assistant para reconstruir la respuesta completa
  • Los IDs de llamadas de herramientas se pueden usar para correlacionar eventos de inicio/finalización
  • Los IDs de sesión se mantienen consistentes durante toda la ejecución de un solo agente