Cursor Agent CLI는 --print와 함께 사용할 때 --output-format 옵션으로 여러 출력 형식을 제공해. 여기에는 프로그램적 사용을 위한 구조화된 형식(json, stream-json)과 사람이 읽기 쉬운 진행 상황 추적용 단순 텍스트 형식이 포함돼.
기본 --output-format은 stream-json이야. 이 옵션은 출력 중일 때(--print)나 출력 모드가 추론될 때(비 TTY stdout 또는 파이프된 stdin)만 유효해.

​
JSON 형식

json 출력 형식은 실행이 성공적으로 완료되면 단일 JSON 객체(뒤에 개행 포함)를 출력해. 델타와 도구 이벤트는 출력되지 않고, 텍스트는 최종 결과로 합쳐져. 실패하면 프로세스는 0이 아닌 종료 코드를 반환하고 stderr에 오류 메시지를 기록해. 실패한 경우에는 올바른 JSON 객체가 출력되지 않아.

​
성공 응답

성공하면 CLI는 다음 구조의 JSON 객체를 출력해: 
{
  "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
type터미널 결과일 때 항상 "result"
subtype성공적인 완료일 때 항상 "success"
is_error성공적인 응답일 때 항상 false
duration_ms총 실행 시간(밀리초)
duration_api_msAPI 요청 시간(밀리초) (현재 duration_ms와 동일)
result전체 assistant 응답 텍스트(모든 텍스트 델타를 연결한 값)
session_id고유 세션 식별자
request_id선택적 요청 식별자(생략될 수 있음)

​
스트림 JSON 형식

stream-json 출력 형식은 줄바꿈으로 구분된 JSON(NDJSON)을 내보내. 각 줄에는 실행 중 발생하는 실시간 이벤트를 나타내는 단일 JSON 객체가 담겨 있어. 스트림은 성공 시 마지막에 result 종료 이벤트로 끝나. 실패하면 프로세스가 0이 아닌 코드로 종료되고, 종료 이벤트 없이 스트림이 조기 종료될 수 있어. 오류 메시지는 stderr로 출력돼.

​
이벤트 유형

​
시스템 초기화

각 세션 시작 시 한 번만 발생: 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/absolute/path",
  "session_id": "<uuid>",
  "model": "<model display name>",
  "permissionMode": "default"
}
앞으로 tools와 mcp_servers 같은 필드가 이 이벤트에 추가될 수 있어.

​
사용자 메시지

사용자의 입력 프롬프트를 포함: 
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

​
Assistant 텍스트 델타

assistant가 응답을 생성하는 동안 여러 번 발생해. 각 이벤트는 누적되는 텍스트 조각을 담고 있어: 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta chunk>" }]
  },
  "session_id": "<uuid>"
}
완전한 assistant 응답을 복원하려면 모든 message.content[].text 값을 순서대로 이어 붙여.

​
도구 호출 이벤트

도구 호출은 시작과 완료 이벤트로 추적돼: 도구 호출 시작: 
{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" }
    }
  },
  "session_id": "<uuid>"
}
도구 호출 완료: 
{
  "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>"
}

​
도구 호출 유형

파일 읽기 도구:
  • Started: tool_call.readToolCall.args에 { "path": "file.txt" } 포함
  • Completed: tool_call.readToolCall.result.success에 파일 메타데이터와 내용 포함
파일 쓰기 도구:
  • Started: tool_call.writeToolCall.args에 { "path": "file.txt", "fileText": "content...", "toolCallId": "id" } 포함
  • Completed: tool_call.writeToolCall.result.success에 { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 } 포함
기타 도구:
  • { "name": "tool_name", "arguments": "..." } 형태의 tool_call.function 구조를 사용할 수 있어

​
터미널 결과

성공적으로 완료되면 마지막으로 발생하는 이벤트: 
{
  "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>"
}

​
예시 시퀀스

일반적인 이벤트 흐름을 보여주는 대표 NDJSON 시퀀스: 
{"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":"README.md를 읽고 요약을 만들어줘"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"좋아 "}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"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":" 그리고 요약을 만들어줄게"}]},"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":"README.md 파일을 읽고 요약을 만들어줄게","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

​
텍스트 형식

text 출력 형식은 에이전트 동작을 단순화해 사람이 읽기 쉬운 스트림으로 보여줘. 자세한 JSON 이벤트 대신 에이전트가 실시간으로 무엇을 하는지 간결한 텍스트로 설명해. 이 형식은 구조화된 데이터를 파싱하는 오버헤드 없이 에이전트 진행 상황을 모니터링하기에 유용해서, 로깅, 디버깅, 또는 단순 진행 추적에 딱 좋아.

​
출력 예시

Read file
Edited file
Ran terminal command
Created new file
각 동작은 수행되는 즉시 새 줄에 표시돼서, 작업 전반에서 에이전트의 진행 상황을 바로바로 알려줘.

​
구현 참고 사항

  • 각 이벤트는 \n으로 끝나는 단일 줄로 전송됨
  • thinking 이벤트는 print 모드에서 억제되며 어느 출력 형식에도 나타나지 않음
  • 필드는 시간이 지나며 하위 호환 방식으로 추가될 수 있음(클라이언트는 알 수 없는 필드를 무시해야 함)
  • 스트림 형식은 실시간으로 업데이트되고, JSON 형식은 완료 후 결과를 출력함
  • 전체 응답을 재구성하려면 모든 assistant 메시지 델타를 연결할 것
  • 도구 호출 ID로 시작/완료 이벤트를 상관시킬 수 있음
  • 세션 ID는 단일 에이전트 실행 내내 일관되게 유지됨