Passer au contenu principal
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 suivre l’avancement de manière lisible.
Le --output-format par défaut est stream-json. Cette option n’est valable que lors de l’impression (--print) ou lorsque le mode impression est déduit (stdout non TTY ou stdin passé en 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. Aucune delta ni aucun événement d’outil n’est é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 réussite, la CLI affiche un objet JSON avec la structure suivante : 
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "result": "<texte intégral de l’assistant>",
  "session_id": "<uuid>",
  "request_id": "<ID de requête (optionnel)>"
}
ChampDescription
typeToujours "result" pour les résultats du terminal
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 facultatif (peut être omis)

​
Format JSON de flux

Le format de sortie stream-json émet du JSON délimité par des retours à la ligne (NDJSON). Chaque ligne contient un unique objet JSON représentant un événement en temps réel pendant l’exécution. Le flux se termine par un événement final result en cas de réussite. En cas d’échec, le processus se termine avec un code différent de zéro et le flux peut s’arrêter plus tôt sans événement final ; 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": "/chemin/absolu",
  "session_id": "<uuid>",
  "model": "<nom d’affichage du modèle>",
  "permissionMode": "par défaut"
}
Des champs comme tools et mcp_servers pourraient être ajoutés à cet événement à l’avenir.

​
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 au fil de l’eau : 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<fragment delta>" }]
  },
  "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’outil sont suivis par 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": "contenu du fichier…",
          "isEmpty": false,
          "exceededLimit": false,
          "totalLines": 54,
          "totalChars": 1254
        }
      }
    }
  },
  "session_id": "<uuid>"
}

​
Types d’appels d’outils

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

​
Résultat du terminal

L’événement final émis en cas de réussite : 
{
  "type": "result",
  "subtype": "réussite",
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "is_error": false,
  "result": "<texte complet de l’assistant>",
  "session_id": "<uuid>",
  "request_id": "<ID de requête (optionnel)>"
}

​
Exemple de séquence

Voici une séquence NDJSON représentative illustrant le déroulement 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. Au lieu d’événements JSON détaillés, il produit des descriptions concises de ce que fait l’agent en temps réel. Ce format est utile pour suivre la progression de l’agent sans le coût d’analyse de données structurées, ce qui le rend idéal pour la journalisation, le débogage ou un simple suivi de l’avancement.

​
Exemple de sortie

Fichier lu
Fichier modifié
Commande de terminal exécutée
Nouveau fichier créé
Chaque action s’affiche sur une nouvelle ligne à mesure que 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 stream fournit des mises à jour en temps réel, tandis que le format JSON attend la fin avant d’afficher les résultats
  • Concatène tous les deltas du message assistant pour reconstituer la réponse complète
  • Les IDs d’appels d’outils peuvent être utilisés pour faire correspondre les événements de début et de fin
  • Les IDs de session restent identiques tout au long d’une exécution unique de l’agent