Die Cursor Agent CLI bietet mit der Option --output-format in Kombination mit --print mehrere Ausgabeformate. Dazu zählen strukturierte Formate für die programmgesteuerte Nutzung (json, stream-json) sowie ein vereinfachtes Textformat zur gut lesbaren Fortschrittsverfolgung.
Das Standard---output-format ist stream-json. Diese Option ist nur gültig beim Drucken (--print) oder wenn der Druckmodus inferiert wird (nicht-TTY-stdout oder per Pipe zugeführtes stdin).

​
JSON-Format

Das json-Ausgabeformat gibt ein einzelnes JSON-Objekt (gefolgt von einem Zeilenumbruch) aus, wenn der Run erfolgreich abgeschlossen wurde. Deltas und Tool-Events werden nicht ausgegeben; der Text wird zum finalen Ergebnis 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 wohlgeformtes JSON-Objekt ausgegeben.

​
Erfolgs-Response

Bei Erfolg gibt die CLI ein JSON-Objekt mit der folgenden 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 terminale Ergebnisse
subtypeImmer "success" für erfolgreiche Runs
is_errorImmer false für erfolgreiche Responses
duration_msGesamtausführungszeit in Millisekunden
duration_api_msAPI-Request-Zeit in Millisekunden (derzeit identisch zu duration_ms)
resultVollständiger Assistant-Response-Text (Konkatenation aller Text-Deltas)
session_idEindeutige Session-ID
request_idOptionale Request-ID (kann entfallen)

​
Stream JSON Format

Das stream-json Ausgabeformat gibt newline-delimited JSON (NDJSON) aus. Jede Zeile enthält ein einzelnes JSON-Objekt, das ein Echtzeit-Event während der Ausführung repräsentiert. Der Stream endet mit einem terminalen result Event bei Erfolg. Bei einem Fehler beendet sich der Prozess mit einem Non-Zero-Code und der Stream kann vorzeitig ohne ein terminales Event enden; eine Fehlermeldung wird nach stderr geschrieben.

​
Event-Typen

​
System-Initialisierung

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.

​
User Message

Enthält den Input-Prompt des Nutzers: 
{
  "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-Chunks: 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta chunk>" }]
  },
  "session_id": "<uuid>"
}
Verkette alle message.content[].text Werte in der richtigen Reihenfolge, um die vollständige Assistant-Antwort zu rekonstruieren.

​
Tool Call Events

Tool Calls werden mit Start- und Completion-Events verfolgt: 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:
  • Gestartet: tool_call.readToolCall.args enthält { "path": "file.txt" }
  • Abgeschlossen: tool_call.readToolCall.result.success enthält Datei-Metadaten und Inhalt
Write File Tool:
  • Gestartet: tool_call.writeToolCall.args enthält { "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
  • Abgeschlossen: tool_call.writeToolCall.result.success enthält { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
Andere Tools:
  • Können die tool_call.function Struktur mit { "name": "tool_name", "arguments": "..." } verwenden

​
Terminales Ergebnis

Das finale 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>"
}

​
Beispiel-Sequenz

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 erstell eine Zusammenfassung"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Ich "}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"lese die README.md-Datei"}]},"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 erstelle eine Zusammenfassung"}]},"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":"Ich lese die README.md-Datei und erstelle eine Zusammenfassung","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

​
Textformat

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

​
Beispielausgabe

Read file
Edited file
Ran terminal command
Created new file
Jede Aktion erscheint in einer neuen Zeile, sobald der Agent sie ausführt, und liefert sofortiges Feedback zum Fortschritt des Agents bei der Aufgabe.

​
Implementierungshinweise

  • Jedes Event wird als einzelne Zeile ausgegeben, die mit \n terminiert wird
  • thinking Events werden im Print-Modus unterdrückt und erscheinen in keinem der beiden Ausgabeformate
  • Felderweiterungen können im Laufe der Zeit rückwärtskompatibel hinzugefügt werden (Consumer sollten unbekannte Felder ignorieren)
  • Das Stream-Format liefert Echtzeit-Updates, während das JSON-Format mit der Ausgabe wartet, bis die Verarbeitung abgeschlossen ist
  • Verkette alle assistant Message-Deltas, um die vollständige Antwort zu rekonstruieren
  • Tool-Call-IDs können verwendet werden, um Start- und Completion-Events zu korrelieren
  • Session-IDs bleiben während einer einzelnen Agent-Ausführung konsistent