A CLI do Cursor Agent oferece vários formatos de saída com a opção --output-format quando combinada com --print. Esses formatos incluem opções estruturadas para uso programático (json, stream-json) e um formato de texto simplificado para acompanhar o progresso de forma legível por humanos.
O --output-format padrão é stream-json. Essa opção só é válida ao imprimir (--print) ou quando o modo de impressão é inferido (stdout não TTY ou stdin encadeado).

​
Formato JSON

O formato de saída json emite um único objeto JSON (seguido por uma quebra de linha) quando a execução é concluída com sucesso. Deltas e eventos de ferramentas não são emitidos; o texto é agregado no resultado final. Em caso de falha, o processo termina com um código diferente de zero e escreve uma mensagem de erro em stderr. Nenhum objeto JSON bem-formado é emitido em casos de falha.

​
Resposta de sucesso

Quando bem-sucedido, a CLI emite um objeto JSON com a seguinte estrutura: 
{
  "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
typeSempre "result" para resultados finais
subtypeSempre "success" para conclusões bem-sucedidas
is_errorSempre false para respostas bem-sucedidas
duration_msTempo total de execução em milissegundos
duration_api_msTempo da requisição à API em milissegundos (atualmente igual a duration_ms)
resultTexto completo da resposta do assistente (concatenação de todos os deltas de texto)
session_idIdentificador único da sessão
request_idIdentificador opcional da requisição (pode ser omitido)

​
Formato JSON de stream

O formato de saída stream-json emite JSON delimitado por quebra de linha (NDJSON). Cada linha contém um único objeto JSON representando um evento em tempo real durante a execução. O stream termina com um evento terminal result em caso de sucesso. Em caso de falha, o processo encerra com um código diferente de zero e o stream pode terminar prematuramente sem um evento terminal; uma mensagem de erro é escrita no stderr.

​
Tipos de evento

​
Inicialização do sistema

Emitido uma vez no início de cada sessão: 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/absolute/path",
  "session_id": "<uuid>",
  "model": "<model display name>",
  "permissionMode": "default"
}
Campos futuros como tools e mcp_servers podem ser adicionados a este evento.

​
Mensagem do usuário

Contém o prompt de entrada do usuário: 
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

​
Delta de texto do assistente

Emitido várias vezes conforme o assistente gera sua resposta. Esses eventos contêm fragmentos de texto incrementais: 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta chunk>" }]
  },
  "session_id": "<uuid>"
}
Concatene todos os valores message.content[].text em ordem para reconstruir a resposta completa do assistente.

​
Eventos de chamada de ferramenta

Chamadas de ferramenta são rastreadas com eventos de início e conclusão: Chamada de ferramenta iniciada: 
{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" }
    }
  },
  "session_id": "<uuid>"
}
Chamada de ferramenta concluída: 
{
  "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>"
}

​
Tipos de chamada de ferramenta

Ferramenta de leitura de arquivo:
  • Iniciada: tool_call.readToolCall.args contém { "path": "file.txt" }
  • Concluída: tool_call.readToolCall.result.success contém metadados e conteúdo do arquivo
Ferramenta de escrita de arquivo:
  • Iniciada: tool_call.writeToolCall.args contém { "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
  • Concluída: tool_call.writeToolCall.result.success contém { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
Outras ferramentas:
  • Podem usar a estrutura tool_call.function com { "name": "tool_name", "arguments": "..." }

​
Resultado terminal

O evento final emitido na conclusão bem-sucedida: 
{
  "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>"
}

​
Sequência de exemplo

Aqui está uma sequência NDJSON representativa mostrando o fluxo típico de eventos: 
{"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":"Lê o README.md e cria um resumo"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Vou "}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"ler o arquivo 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":" e criar um resumo"}]},"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":"Vou ler o arquivo README.md e criar um resumo","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

​
Formato de texto

O formato de saída text fornece um fluxo simplificado e legível por pessoas das ações do agente. Em vez de eventos JSON detalhados, ele gera descrições de texto concisas do que o agente está fazendo em tempo real. Esse formato é útil para acompanhar o progresso do agente sem a sobrecarga de analisar dados estruturados, tornando-o ideal para logging, depuração ou acompanhamento simples de progresso.

​
Exemplo de saída

Read file
Edited file
Ran terminal command
Created new file
Cada ação aparece em uma nova linha conforme o agente a executa, oferecendo feedback imediato sobre o andamento da tarefa.

​
Notas de implementação

  • Cada evento é emitido como uma única linha terminada por \n
  • Eventos thinking são suprimidos no modo de impressão e não aparecerão em nenhum formato de saída
  • Adições de campos podem ocorrer ao longo do tempo de forma retrocompatível (consumidores devem ignorar campos desconhecidos)
  • O formato de stream fornece atualizações em tempo real, enquanto o formato JSON aguarda a conclusão antes de gerar os resultados
  • Concatene todos os deltas de mensagem assistant para reconstruir a resposta completa
  • IDs de chamadas de ferramenta podem ser usados para correlacionar eventos de início/conclusão
  • IDs de sessão permanecem consistentes durante toda a execução de um único agente