#cursor#cli#ci#output-format#automation

Formatos de salida de Cursor CLI e integración CI

4 min read

El post anterior 10-headless-scripts usó -p --force para cambiar archivos desde scripts. Este trata el formato de salida: para la misma ejecución del Agent puedes elegir "solo texto final", "JSON estructurado completo" o "JSON en streaming mientras corre" — en CI parseas resultados, mides tiempo o muestras progreso con estos tres formatos.

Tres formatos de salida

Formato Flag Mejor para
text Por defecto, o --output-format text Lectura humana, solo respuesta final, escribir a archivo
json --output-format json Parseo en scripts, pass/fail en CI, extraer campos
stream-json --output-format stream-json Progreso en vivo, seguimiento de tool calls, monitoreo de runs largos

text: Respuesta final limpia

cursor agent -p "What is the entry point of this repo?"

Sin --output-format obtienes text: la salida es solo la respuesta final, sin tool calls ni pasos intermedios — útil para pegar en docs o como descripción corta.

En CI, para escribir la conclusión del Agent a un archivo:

cursor agent -p "Generate release notes for this version from CHANGELOG" > release_notes.txt

json: Para scripts y CI

cursor agent -p --output-format json "Analyze src/ dependencies and return JSON: { \"entry\": \"...\", \"deps\": [...] }"

La salida es JSON estructurado, con result, duration_ms o campos que pidas en el prompt.
En CI puedes:

  • Usar jq para obtener campos, comprobar vacíos o buscar palabras clave
  • Usar código de salida y contenido para decidir pass/fail del job

Ejemplo conceptual:

cursor agent -p --output-format json "Do a short code review; return {\"ok\": true/false, \"summary\": \"...\"}" | jq -r '.result'
# Then use .ok or .summary for next steps or to fail the build

Los campos exactos dependen de la doc de Cursor; la idea es "json para parseo programático."

stream-json: Progreso en vivo y seguimiento de herramientas

cursor agent -p --output-format stream-json --stream-partial-output "Analyze project and write analysis.txt"
  • Cada línea es un evento JSON (p. ej. system, assistant, tool_call, result)
  • --stream-partial-output envía el texto del assistant como deltas incrementales, para mostrar "contador de caracteres en vivo" o "progreso %"
  • Parsea tool_call started/completed para ver qué archivo lee/escribe el Agent y cuánto tarda

Útil para: runs largos, mostrar "procesando archivo N" en logs de CI o en una UI, o contar tool calls y duración.

Consejos de integración CI

Necesidad Sugerencia
Solo importa "¿terminó y cuál es la conclusión?" text + redirigir a archivo o variable; comprobar código de salida
Pass/fail según contenido json + parseo con jq
Log en vivo o progreso stream-json + parsear línea a línea por tipo/subtipo
El Agent debe editar archivos Añade --force (ver 10-headless-scripts)
Ejecutar en CI Configura CURSOR_API_KEY; usa --model para fijar modelo si hace falta

Manejo de fallos

  • Cuando falla la ejecución del Agent, la CLI suele devolver código de salida distinto de cero
  • En scripts usa if [ $? -ne 0 ]; then exit 1; fi o set -e para que CI falle correctamente
  • Con json también puedes comprobar un campo error o tu ok: false personalizado como refuerzo

Resumen

  • text: Por defecto, legible, salida mínima; bueno para escribir a archivo o como descripción
  • json: Estructurado para jq o scripts; bueno para decisiones CI y extracción
  • stream-json + --stream-partial-output: Flujo de eventos en vivo; bueno para progreso y seguimiento de herramientas
  • En CI: configura CURSOR_API_KEY, respeta el código de salida y parsea JSON para pass/fail cuando haga falta

Siguiente: 12-sessions-cloud — Reanudar sesión con --resume y ejecución en la nube con -c.