Pular para o conteúdo principal
A CLI do Cursor Agent oferece vários formatos de saída com a opção --output-format quando usada junto com --print. Esses formatos incluem opções estruturadas para uso programático (json, stream-json) e um formato de texto simplificado para acompanhamento de progresso 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 nova linha) quando a execução é concluída com sucesso. Deltas e eventos de ferramenta não são emitidos; o texto é agregado ao resultado final. Em caso de falha, o processo encerra 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": "<texto completo do assistente>",
  "session_id": "<uuid>",
  "request_id": "<ID de solicitação opcional>"
}
FieldDescription
typeSempre "result" para resultados do terminal
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 chamada à 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 em stream

O formato de saída stream-json emite JSON delimitado por novas linhas (NDJSON). Cada linha contém um único objeto JSON que representa 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 antes, sem um evento terminal; uma mensagem de erro é escrita em stderr.

​
Tipos de eventos

​
Inicialização do sistema

Emitido uma vez no início de cada sessão: 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/caminho/absoluto",
  "session_id": "<uuid>",
  "model": "<nome de exibição do modelo>",
  "permissionMode": "padrão"
}
Campos futuros, como tools e mcp_servers, podem ser adicionados a este evento.

​
Mensagem do usuário

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

​
Delta de texto do assistant

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

​
Eventos de chamadas de ferramenta

Chamadas de ferramenta são acompanhadas por 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": "conteúdo do arquivo...",
          "isEmpty": false,
          "exceededLimit": false
          "totalLines": 54,
          "totalChars": 1254
        }
      }
    }
  },
  "session_id": "<uuid>"
}

​
Tipos de chamadas 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 do terminal

O evento final emitido em caso de conclusão bem-sucedida: 
{
  "type": "result",
  "subtype": "success",
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "is_error": false,
  "result": "<texto completo do assistente>",
  "session_id": "<uuid>",
  "request_id": "<id de requisição opcional>"
}

​
Sequência de exemplo

Aqui vai uma sequência NDJSON representativa que mostra 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":"# Projeto\n\nEste é um projeto de exemplo...","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":"# Resumo do README\n\nEste projeto contém...","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":"# Resumo do README\n\nEste projeto contém...","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 emite descrições de texto concisas do que o agente está fazendo em tempo real. Esse formato é útil para acompanhar o progresso do agente sem o custo de analisar dados estruturados, sendo ideal para logs, depuração ou um acompanhamento simples de progresso.

​
Exemplo de saída

Leu o arquivo
Editou o arquivo
Executou um comando no terminal
Criou um novo arquivo
Cada ação aparece em uma nova linha conforme o agente a executa, oferecendo feedback imediato sobre o progresso do agente na tarefa.

​
Notas de implementação

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