Cursor CLI 헤드리스 모드: --print, --force와 파일을 수정하는 스크립트

04-non-interactive에서는 --no-interactive로 Agent가 입력 대기 없이 끝까지 실행하는 것을 다뤘다. 이번에는 헤드리스 모드의 -p / --print(「터미널로만 출력」 실행)와 --force(또는 --yolo)로 Agent가 프로젝트 파일을 실제로 변경할 수 있게 한다 — CI·배치 JSDoc·자동 lint 수정·리포트 생성용.

요약하면: Cursor 창도 키 확인도 없이；스크립트가 CLI를 호출해 코드를 바꾸고, 스크립트가 이어간다.

--print: 비대화형, 출력은 터미널로

cursor agent -p "What does this project do?"
# or
cursor agent --print "List all API endpoints under src/"

--force 없이: Agent는 파일 읽기·코드베이스 검색·분석 결과 반환은 할 수 있지만 파일에 쓰지는 않음 — 제안이나 내용 출력만
적합한 용도: Q&A, 분석, 리포트를 stdout에 쓰기, 파이프나 스크립트에서 파싱

즉 -p만 쓰면 「끝까지 실행하고 출력은 터미널」；파일을 바꿀지는 --force를 붙이느냐에 달렸다.

--force: 파일 직접 편집 허용

--print와 --force(또는 --yolo)를 같이 쓰면 Agent가 Y/N 없이 생성·수정·삭제할 수 있다:

cursor agent -p --force "Refactor src/utils.js to ES6+ syntax"

용도	예
단일 파일 리팩터	`agent -p --force "Refactor src/foo.ts to use async/await"`
설정에 맞게 lint 수정	`agent -p --force "Fix all auto-fixable errors per .eslintrc"`
배치 JSDoc	아래 스크립트 예 참고
프로젝트 안에 파일 생성	`agent -p --force "Generate CONTRIBUTING.md from README"`

⚠️ 스크립트에서 --force를 쓰기 전에, 단일 파일이나 좁은 범위에서 동작을 확인한 뒤 전체로 넓히자.

스크립트 예: 배치 JSDoc

#!/bin/bash
# For each .js under src/, ask Agent to add JSDoc and write directly
find src/ -name "*.js" | while read -r file; do
  echo "Processing $file..."
  cursor agent -p --force "Add full JSDoc comments to $file, editing the file in place"
done

각 파일을 Agent가 읽고 쓰므로, 프로젝트 사본이나 브랜치에서 실행하거나, 먼저 한두 파일로 시험해 보자.

스크립트 예: 자동 코드 리뷰 및 리포트 작성

#!/bin/bash
cursor agent -p --force --output-format text \
  "Do a code review of recent changes: readability, potential bugs, security, best practices. Write conclusions and concrete suggestions to review.txt"

--output-format text로 출력을 평문으로 유지해 파일에 쓰거나 grep/스크립트로 파이프하기 좋다. 다음 글에서는 json과 stream-json을 다룬다.

환경: API 키

헤드리스 모드는 Cursor 창이 없는 환경(CI·원격 머신 등)에서 돌리는 경우가 많아서 인증이 필요하다:

환경 변수: export CURSOR_API_KEY=your_key
또는 해당 환경에서 먼저 cursor auth login 실행(지원되는 경우)

없으면 에러가 나고 Agent가 동작하지 않는다.

--no-interactive와의 차이(요약)

모드	주 용도	파일 수정?
`--no-interactive`	터미널에서 실행, 출력을 단계별로 보기, 키 불필요	수정 가능하나 설정에 따라 확인할 수 있음
`-p` / `--print`	스크립트·CI, 완전 비대화형, 출력은 stdout	기본값은 안 함
`-p --force`	위와 같되 Agent의 파일 편집 허용	함, 확인 없음

즉 「실제로 파일을 바꾸는」스크립트에는 -p --force；분석이나 리포트를 터미널에만 낼 때는 -p만으로 충분하다.

요약

-p / --print: 비대화형, 끝날 때 터미널로 출력；기본값은 파일 편집 안 함
--force / --yolo: print 모드에서 Agent의 파일 편집 허용；스크립트·CI용
스크립트/CI에서는 CURSOR_API_KEY 설정 또는 로그인 완료
전체에서 돌리기 전에 좁은 범위에서 먼저 시험

다음: 11-output-ci — 출력 형식 text / json / stream-json과 CI 연동 예.