Cursor CLI 출력 형식과 CI 연동
5 min read
이전 글 10-headless-scripts에서는 -p --force로 스크립트에서 파일을 변경했다. 이번에는 출력 형식：같은 Agent 실행에 대해 "최종 텍스트만", "전체 구조화 JSON", "실행 중 스트리밍 JSON" 중 하나를 고를 수 있다 — CI에서는 이 세 형식으로 결과를 파싱하거나 시간을 재거나 진행을 보여준다.
출력 형식 3가지
| 형식 | 플래그 | 적합한 용도 |
|---|---|---|
| text | 기본값, 또는 --output-format text |
사람이 읽기, 최종 답변만, 파일로 쓰기 |
| json | --output-format json |
스크립트 파싱, CI pass/fail, 필드 추출 |
| stream-json | --output-format stream-json |
라이브 진행, 도구 호출 추적, 긴 실행 모니터링 |
text: 최종 답변만
cursor agent -p "What is the entry point of this repo?"--output-format을 안 주면 text: 출력은 최종 응답만이고, 도구 호출이나 중간 단계는 안 나온다 — 문서에 붙이거나 짧은 설명용.
CI에서 Agent 결론을 파일에 쓰는 예:
cursor agent -p "Generate release notes for this version from CHANGELOG" > release_notes.txtjson: 스크립트·CI용
cursor agent -p --output-format json "Analyze src/ dependencies and return JSON: { \"entry\": \"...\", \"deps\": [...] }"출력은 구조화된 JSON. result, duration_ms나 프롬프트에서 요청한 필드가 포함될 수 있다.
CI에서는:
jq로 필드 추출·빈 값 확인·키워드 검색- 종료 코드와 내용으로 job pass/fail 결정
개념적 예:
cursor agent -p --output-format json "Do a short code review; return {\"ok\": true/false, \"summary\": \"...\"}" | jq -r '.result'
# Then use .ok or .summary for next steps or to fail the build정확한 필드는 Cursor 문서에 따름；여기서는 "json은 프로그램으로 파싱하는 용도"로 이해하면 된다.
stream-json: 라이브 진행과 도구 추적
cursor agent -p --output-format stream-json --stream-partial-output "Analyze project and write analysis.txt"- 한 줄이 JSON 이벤트 하나(
system,assistant,tool_call,result등) --stream-partial-output으로 assistant 텍스트가 증분 델타로 전달되어 "실시간 문자 수"나 "진행 %" 표시 가능tool_call시작/완료를 파싱하면 Agent가 어떤 파일을 읽고/쓰는지, 얼마나 걸리는지 알 수 있음
긴 실행, CI 로그나 UI에서 "파일 N 처리 중" 표시, 도구 호출 횟수·시간 집계에 적합.
CI 연동 팁
| 필요 | 제안 |
|---|---|
| "끝났는지·결론이 뭔지"만 필요 | text + 파일/변수로 리다이렉트；종료 코드 확인 |
| 내용으로 pass/fail 결정 | json + jq 파싱 |
| 라이브 로그·진행 | stream-json + 줄마다 type/subtype으로 파싱 |
| Agent가 파일을 수정해야 함 | --force 추가 (10-headless-scripts 참고) |
| CI에서 실행 | CURSOR_API_KEY 설정；필요하면 --model로 모델 고정 |
실패 처리
- Agent 실행이 실패하면 CLI는 보통 0이 아닌 종료 코드를 반환한다
- 스크립트에서는
if [ $? -ne 0 ]; then exit 1; fi또는set -e로 CI가 제대로 실패하게 하자 - json이면
error필드나 커스텀ok: false도 검사하면 더 안전하다
요약
- text: 기본값, 사람이 읽기, 최소 출력；파일 쓰기·설명용
- json:
jq·스크립트용 구조화；CI 판단·추출용 - stream-json + --stream-partial-output: 라이브 이벤트 스트림；진행·도구 추적용
- CI에서는:
CURSOR_API_KEY설정, 종료 코드 존중, 필요 시 JSON 파싱으로 pass/fail
다음: 12-sessions-cloud — --resume으로 세션 재개, -c로 클라우드 실행.