메인 콘텐츠로 건너뛰기
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": "<전체 assistant 텍스트>",
  "session_id": "<uuid>",
  "request_id": "<선택적 요청 ID>"
}
FieldDescription
type터미널 결과의 경우 항상 "result"
subtype성공적으로 완료된 경우 항상 "success"
is_error성공적인 응답인 경우 항상 false
duration_ms총 실행 시간(밀리초)
duration_api_msAPI 요청 시간(밀리초) (현재 duration_ms와 동일)
result어시스턴트의 전체 응답 텍스트(모든 텍스트 델타를 연결한 값)
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>"
}

​
어시스턴트 텍스트 델타

어시스턴트가 응답을 생성하는 동안 여러 번 발생해. 이 이벤트에는 누적되는 텍스트 조각들이 포함돼: 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<델타 청크>" }]
  },
  "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": "파일 내용...",
          "isEmpty": false,
          "exceededLimit": false,
          "totalLines": 54,
          "totalChars": 1254
        }
      }
    }
  },
  "session_id": "<uuid>"
}

​
도구 호출 유형

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

​
터미널 결과

성공적으로 완료될 때 내보내지는 최종 이벤트: 
{
  "type": "result",
  "subtype": "성공",
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "is_error": false,
  "result": "<전체 어시스턴트 텍스트>",
  "session_id": "<uuid>",
  "request_id": "<선택적 요청 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":"# 프로젝트\n\n샘플 프로젝트입니다...","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 요약\n\n이 프로젝트는...","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 요약\n\n이 프로젝트는...","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 이벤트 대신, 에이전트가 실시간으로 무엇을 하는지에 대한 짧은 텍스트 설명을 출력해. 이 형식은 구조화된 데이터를 파싱하는 오버헤드 없이 에이전트 진행 상황을 모니터링하기에 유용해서, 로깅, 디버깅, 또는 간단한 진행 상황 추적에 이상적이야.

​
출력 예시

파일 읽기
파일 편집
터미널 명령 실행
새 파일 생성
에이전트가 작업을 수행할 때마다 각 동작이 새 줄에 나타나서, 작업 진행 상황에 대한 즉각적인 피드백을 제공해.

​
구현 노트

  • 각 이벤트는 \n으로 끝나는 한 줄로 출력됨
  • thinking 이벤트는 print 모드에서 숨겨지며 어떤 출력 형식에도 나타나지 않음
  • 필드는 시간이 지나며 역호환 방식으로 추가될 수 있음(클라이언트는 알 수 없는 필드를 무시해야 함)
  • 스트림 형식은 실시간 업데이트를 제공하고, JSON 형식은 완료될 때까지 기다렸다가 결과를 출력함
  • 전체 응답을 재구성하려면 모든 assistant 메시지 델타를 이어 붙이면 됨
  • 툴 호출 ID로 시작/완료 이벤트를 매칭할 수 있음
  • 세션 ID는 단일 에이전트 실행 내내 동일하게 유지됨