Le CLI Cursor Agent propose plusieurs formats de sortie via l’option --output-format lorsqu’elle est utilisée avec --print. Ces formats incluent des formats structurés pour un usage programmatique (json, stream-json) et un format texte simplifié pour un suivi de progression lisible.
Le format par défaut de --output-format est stream-json. Cette option n’est valide que lors de l’impression (--print) ou lorsque le mode impression est déduit (stdout non TTY ou stdin acheminé via un pipe).

​
Format JSON

Le format de sortie json émet un seul objet JSON (suivi d’un saut de ligne) lorsque l’exécution se termine avec succès. Les deltas et les événements d’outils ne sont pas émis ; le texte est agrégé dans le résultat final. En cas d’échec, le processus se termine avec un code non nul et écrit un message d’erreur sur stderr. Aucun objet JSON valide n’est émis en cas d’échec.

​
Réponse en cas de succès

En cas de succès, la CLI produit un objet JSON avec la structure suivante : 
{
  "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>"
}
ChampDescription
typeToujours "result" pour les résultats terminaux
subtypeToujours "success" pour les exécutions réussies
is_errorToujours false pour les réponses réussies
duration_msDurée totale d’exécution en millisecondes
duration_api_msDurée de la requête API en millisecondes (actuellement égale à duration_ms)
resultTexte complet de la réponse de l’assistant (concaténation de tous les deltas de texte)
session_idIdentifiant de session unique
request_idIdentifiant de requête optionnel (peut être omis)

​
Format JSON en flux

Le format de sortie stream-json émet du JSON délimité par des sauts de ligne (NDJSON). Chaque ligne contient un seul objet JSON représentant un événement en temps réel pendant l’exécution. Le flux se termine par un événement terminal result en cas de succès. En cas d’échec, le processus se termine avec un code non nul et le flux peut s’interrompre plus tôt sans événement terminal ; un message d’erreur est écrit sur stderr.

​
Types d’événements

​
Initialisation du système

Émis une fois au début de chaque session : 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/absolute/path",
  "session_id": "<uuid>",
  "model": "<model display name>",
  "permissionMode": "default"
}
Des champs supplémentaires comme tools et mcp_servers pourront être ajoutés à cet événement.

​
Message utilisateur

Contient l’invite saisie par l’utilisateur : 
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

​
Delta de texte de l’assistant

Émis plusieurs fois pendant que l’assistant génère sa réponse. Ces événements contiennent des fragments de texte incrémentaux : 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta chunk>" }]
  },
  "session_id": "<uuid>"
}
Concatène toutes les valeurs message.content[].text dans l’ordre pour reconstruire la réponse complète de l’assistant.

​
Événements d’appel d’outil

Les appels d’outils sont suivis avec des événements de démarrage et d’achèvement : Appel d’outil démarré : 
{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" }
    }
  },
  "session_id": "<uuid>"
}
Appel d’outil terminé : 
{
  "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>"
}

​
Types d’appels d’outil

Outil de lecture de fichier :
  • Démarré : tool_call.readToolCall.args contient { "path": "file.txt" }
  • Terminé : tool_call.readToolCall.result.success contient les métadonnées et le contenu du fichier
Outil d’écriture de fichier :
  • Démarré : tool_call.writeToolCall.args contient { "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
  • Terminé : tool_call.writeToolCall.result.success contient { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
Autres outils :
  • Peuvent utiliser la structure tool_call.function avec { "name": "tool_name", "arguments": "..." }

​
Résultat final

Événement final émis en cas d’achèvement réussi : 
{
  "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>"
}

​
Séquence d’exemple

Voici une séquence NDJSON représentative illustrant le flux typique des événements : 
{"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":"Lis README.md et fais un résumé"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Je vais "}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"lire le fichier 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":" et faire un résumé"}]},"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":"Je vais lire le fichier README.md et faire un résumé","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

​
Format texte

Le format de sortie text fournit un flux simplifié et lisible des actions de l’agent. Plutôt que des événements JSON détaillés, il affiche des descriptions textuelles concises de ce que l’agent fait en temps réel. Ce format est utile pour suivre la progression de l’agent sans le coût supplémentaire de l’analyse de données structurées, ce qui le rend idéal pour la journalisation, le débogage ou un simple suivi de progression.

​
Exemple de sortie

Read file
Edited file
Ran terminal command
Created new file
Chaque action apparaît sur une nouvelle ligne au moment où l’agent l’exécute, offrant un retour immédiat sur l’avancement de l’agent dans la tâche.

​
Notes d’implémentation

  • Chaque événement est émis sur une seule ligne terminée par \n
  • Les événements thinking sont masqués en mode impression et n’apparaissent dans aucun des formats de sortie
  • Des champs peuvent être ajoutés au fil du temps de manière rétrocompatible (les consommateurs doivent ignorer les champs inconnus)
  • Le format en streaming fournit des mises à jour en temps réel, tandis que le format JSON attend la fin avant de produire les résultats
  • Concatène tous les deltas du message assistant pour reconstituer la réponse complète
  • Les IDs d’appel d’outil peuvent être utilisés pour corréler les événements de début et de fin
  • Les IDs de session restent constants tout au long d’une exécution unique de l’agent