Die Cursor Agent CLI stellt mit der Option --output-format in Kombination mit --print mehrere Ausgabeformate bereit. Dazu gehören strukturierte Formate für die programmgesteuerte Nutzung (json, stream-json) sowie ein vereinfachtes Textformat zur menschlich lesbaren Fortschrittsverfolgung.
Das Standard---output-format ist stream-json. Diese Option ist nur gültig beim Ausgeben (--print) oder wenn der Print-Modus abgeleitet wird (nicht-TTY-stdout oder per Pipe weitergeleitetes stdin).

​
JSON-Format

Das json-Ausgabeformat gibt ein einzelnes JSON-Objekt (gefolgt von einem Newline) aus, wenn der Run erfolgreich abgeschlossen wird. Deltas und Tool-Events werden nicht ausgegeben; Text wird zum Endergebnis zusammengeführt. Bei einem Fehler beendet sich der Prozess mit einem von null verschiedenen Exit-Code und schreibt eine Fehlermeldung nach stderr. In Fehlerfällen wird kein wohldefiniertes JSON-Objekt ausgegeben.

​
Erfolgsantwort

Bei Erfolg gibt die CLI ein JSON-Objekt mit folgender Struktur aus: 
{
  "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
typeImmer "result" für finale Ergebnisse
subtypeImmer "success" für erfolgreiche Completions
is_errorImmer false für erfolgreiche Antworten
duration_msGesamte Ausführungszeit in Millisekunden
duration_api_msAPI-Laufzeit in Millisekunden (derzeit gleich duration_ms)
resultVollständiger Assistant-Antworttext (Konkatenation aller Text-Deltas)
session_idEindeutiger Sitzungsbezeichner
request_idOptionaler Anfragebezeichner (kann weggelassen werden)

​
Stream-JSON-Format

Das Ausgabeformat stream-json erzeugt zeilengetrenntes JSON (NDJSON). Jede Zeile enthält ein einzelnes JSON-Objekt, das ein Echtzeit-Ereignis während der Ausführung darstellt. Der Stream endet bei Erfolg mit einem abschließenden result-Event. Bei einem Fehler beendet sich der Prozess mit einem von Null verschiedenen Exit-Code und der Stream kann ohne abschließendes Event vorzeitig enden; eine Fehlermeldung wird auf stderr geschrieben.

​
Ereignistypen

​
Systeminitialisierung

Wird einmal zu Beginn jeder Session ausgegeben: 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/absolute/path",
  "session_id": "<uuid>",
  "model": "<model display name>",
  "permissionMode": "default"
}
Zukünftige Felder wie tools und mcp_servers können zu diesem Event hinzugefügt werden.

​
Nutzer-Nachricht

Enthält den Prompt des Users: 
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

​
Assistant-Text-Delta

Wird mehrfach ausgegeben, während der Assistant seine Antwort generiert. Diese Events enthalten inkrementelle Text-Teilstücke: 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta chunk>" }]
  },
  "session_id": "<uuid>"
}
Hänge alle message.content[].text-Werte der Reihe nach aneinander, um die vollständige Assistant-Antwort zu rekonstruieren.

​
Tool-Call-Events

Tool-Calls werden mit Start- und Abschluss-Events nachverfolgt: Tool-Call gestartet: 
{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" }
    }
  },
  "session_id": "<uuid>"
}
Tool-Call abgeschlossen: 
{
  "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-Typen

Read-File-Tool:
  • Started: tool_call.readToolCall.args enthält { "path": "file.txt" }
  • Completed: tool_call.readToolCall.result.success enthält Dateimetadaten und Inhalt
Write-File-Tool:
  • Started: tool_call.writeToolCall.args enthält { "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
  • Completed: tool_call.writeToolCall.result.success enthält { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
Andere Tools:
  • Können die Struktur tool_call.function mit { "name": "tool_name", "arguments": "..." } verwenden

​
Terminales Ergebnis

Das letzte Event, das bei erfolgreichem Abschluss ausgegeben wird: 
{
  "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>"
}

​
Beispielsequenz

Hier ist eine repräsentative NDJSON-Sequenz, die den typischen Ablauf der Events zeigt: 
{"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":"Lies die README.md und erstelle eine Zusammenfassung"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Ich werde "}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"die README.md lesen"}]},"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":" und eine Zusammenfassung erstellen"}]},"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-Zusammenfassung\n\nDieses Projekt enthält...","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-Zusammenfassung\n\nDieses Projekt enthält...","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":"Ich werde die README.md lesen und eine Zusammenfassung erstellen","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

​
Textformat

Das text-Ausgabeformat liefert einen vereinfachten, gut lesbaren Stream der Aktionen des Agents. Statt detaillierter JSON-Events gibt es prägnante Textbeschreibungen dessen aus, was der Agent in Echtzeit macht. Dieses Format ist hilfreich, um den Fortschritt des Agents zu verfolgen, ohne den Overhead beim Parsen strukturierter Daten – ideal für Logging, Debugging oder einfaches Fortschritts-Tracking.

​
Beispielausgabe

Datei gelesen
Datei bearbeitet
Terminalbefehl ausgeführt
Neue Datei erstellt
Jede Aktion erscheint in einer neuen Zeile, sobald der Agent sie ausführt, und liefert unmittelbares Feedback zum Fortschritt des Agents bei der Aufgabe.

​
Implementierungsnotizen

  • Jedes Event wird als einzelne Zeile ausgegeben, die mit \n endet
  • thinking-Events werden im Print-Modus unterdrückt und erscheinen in keinem der Ausgabeformate
  • Felder können im Laufe der Zeit rückwärtskompatibel ergänzt werden (Consumers sollten unbekannte Felder ignorieren)
  • Das Stream-Format liefert Echtzeit-Updates, während das JSON-Format auf die Fertigstellung wartet, bevor Ergebnisse ausgegeben werden
  • Konkateniere alle assistant-Message-Deltas, um die vollständige Antwort zu rekonstruieren
  • Tool-Call-IDs können verwendet werden, um Start-/Abschluss-Events zu korrelieren
  • Session-IDs bleiben während einer einzelnen Agent-Ausführung konsistent