Cursor CLI 명령어·실전 예제 총정리: 설치부터 CI 자동화 스크립트까지 (2026)

핵심 요약: Cursor CLI는 터미널에서 agent 한 단어로 Cursor 에이전트를 쓰는 도구입니다. 이 글은 명령어·플래그 레퍼런스와 복붙용 실전 예제를 한곳에 모은 쿡북이에요("이게 뭔가"는 개요 글에서 다뤘습니다). 외울 건 많지 않습니다 — 대화형은 agent, 스크립트·CI는 agent -p(프린트 모드), 파일을 실제로 고치려면 --force, 모드는 --mode=plan/ask, 이전 대화는 agent resume. 여기에 헤드리스 모드로 배치 리팩터링·자동 코드 리뷰·이미지 분석을 돌리는 실제 스크립트 예제를 붙였습니다. 명령어는 모두 공식 문서 기준으로 확인했고(하단 링크), 바로 복사해 쓸 수 있게 정리했어요.

※ 이 글은 2026년 9월 6일 기준 공식 문서(cursor.com/docs/cli)를 확인해 정리한 실전 가이드입니다. 플래그는 버전에 따라 바뀔 수 있으니 자동화에 넣기 전 agent --help로 한 번 확인하세요.

개요 글에서 "Cursor CLI가 뭐고 왜 쓰나"를 다뤘으니, 여기서는 곧장 손에 익는 것부터 갑니다 — 설치하고, 명령어를 훑고, 실제 스크립트로 돌리는 순서로요.

설치: 명령어 한 줄

운영체제별로 한 줄이면 끝납니다. 설치되는 실행 파일 이름은 이제 agent예요(예전 이름 cursor-agent도 별칭으로 아직 동작합니다).

# macOS · Linux · WSL
curl https://cursor.com/install -fsS | bash

# Windows (PowerShell)
irm 'https://cursor.com/install?win32=true' | iex

# 설치 후 대화형 세션 시작
agent

명령어 한눈에 (치트시트)

▲ 이 카드 한 장이면 대부분 커버됩니다. 아래는 상황별 설명.

목적	명령어
대화형 세션 시작	agent
초기 프롬프트와 함께 시작	agent "인증 모듈을 JWT로 리팩터"
계획 모드(코딩 전 설계)	agent --mode=plan 또는 /plan, Shift+Tab
읽기 전용 탐색(수정 안 함)	agent --mode=ask 또는 /ask
비대화형(스크립트·CI)	agent -p "질문"
파일을 실제로 수정	agent -p --force "..."
모델 지정	agent -p "..." --model "gpt-5"
출력 형식	--output-format text|json|stream-json
이전 대화 목록·재개	agent ls · agent resume · agent --continue
클라우드로 위임	메시지 앞에 & — & 테스트까지 추가해줘
샌드박스 토글	/sandbox 또는 --sandbox enabled|disabled

대화형 기본: 모드 세 가지

그냥 agent를 치면 대화형 세션이 열립니다. 목표를 말하면 변경안을 제안하고, 명령 실행은 승인받아 진행해요. 에디터와 같은 모드·같은 Rules·같은 MCP 설정을 공유하는 게 핵심입니다 — 그래서 에디터에서 쓰던 감각 그대로 터미널에서 쓸 수 있어요.

모드는 셋입니다. Agent(기본)는 모든 도구를 써서 실제 작업을 하고, Plan은 코딩 전에 접근 방식을 설계하며 필요하면 되묻고, Ask는 읽기 전용이라 코드를 건드리지 않고 탐색만 합니다. "일단 구조부터 파악하고 싶다"면 Ask, "큰 변경 전에 계획부터"면 Plan으로 시작하는 습관이 사고를 줄여줍니다.

세션 관리: 맥락 이어가기

긴 작업은 세션을 이어가는 게 편합니다. 이전 대화를 다시 불러와 맥락을 유지할 수 있어요.

# 이전 대화 목록에서 골라 재개
agent ls

# 가장 최근 대화 재개
agent resume

# 직전 세션 이어서
agent --continue

# 특정 대화 ID로 재개
agent --resume="chat-id-here"

헤드리스·CI: -p가 핵심

▲ "사람이 볼 거냐, 스크립트가 돌 거냐"로 갈리고, 파일을 실제로 고칠 때만 --force.

자동화의 출발점은 프린트 모드(-p 또는 --print)입니다. 결과만 stdout으로 깔끔히 뱉어서 다른 도구로 파이프하기 좋아요. 중요한 안전장치 하나 — 기본은 변경을 "제안만" 하고 파일을 안 고칩니다. 실제로 수정하게 하려면 --force(또는 --yolo)를 붙여야 해요. CI에서는 인증을 위해 CURSOR_API_KEY 환경변수를 먼저 설정합니다.

# 질문만 — 파일 안 고침(기본)
agent -p "이 코드베이스는 무슨 일을 하나?"

# 실제로 파일 수정 — --force 필요
agent -p --force "src의 코드를 최신 ES6+ 문법으로 리팩터"

# 스크립트용: API 키 설정 후 실행
export CURSOR_API_KEY=your_api_key_here
agent -p "이 변경의 보안 이슈를 리뷰해줘" --output-format text

실전 예제 모음 (복붙용)

여기가 이 글의 본론입니다. 자주 쓰는 패턴 넷을 실제 스크립트로 정리했어요.

① 배치 리팩터링 — 파일마다 순회
여러 파일에 같은 작업을 돌릴 때. --force가 있어야 실제로 반영됩니다.

# src의 모든 .js에 JSDoc 주석 추가
find src/ -name "*.js" | while read file; do
  agent -p --force "이 파일에 JSDoc 주석을 꼼꼼히 추가: $file"
done

② 자동 코드 리뷰 — 성공/실패 처리까지
CI 파이프라인에 넣기 좋은 형태. 종료 코드로 성공 여부를 판정합니다.

#!/bin/bash
# code-review.sh — 최근 변경 자동 리뷰
agent -p --force --output-format text \
  "최근 변경을 리뷰하고 코드 품질·잠재 버그·보안·베스트프랙티스 관점의
   구체적 개선안을 review.txt에 정리해줘"

if [ $? -eq 0 ]; then
  echo "✅ 코드 리뷰 완료"
else
  echo "❌ 리뷰 실패"; exit 1
fi

③ JSON 출력 → jq로 파싱
구조화된 결과가 필요할 때. 다른 도구와 연결하기 좋습니다.

# 결과를 JSON으로 받아 특정 필드만 추출
agent -p --output-format json "이 프로젝트 구조를 요약해줘" | jq -r '.result'

④ 이미지·목업 분석
프롬프트에 파일 경로를 적으면 에이전트가 알아서 읽습니다 — 스크린샷·디자인 목업도요.

# 스크린샷 분석
agent -p "이 이미지를 분석해서 무엇이 보이는지 설명: ./screenshot.png"

# 코드와 디자인 목업을 함께 주고 개선안 요청
agent -p "src/app.ts의 코드와 designs/home.png 목업을 보고,
          디자인에 맞게 개선안을 제안해줘"

클라우드로 넘기기: & 한 글자

오래 걸리는 작업은 자리를 비워도 계속 돌게 클라우드 에이전트로 넘길 수 있어요. 대화 중 메시지 앞에 &만 붙이면 됩니다. 넘긴 작업은 웹·모바일(cursor.com/agents)에서 이어봅니다 — 노트북을 닫아도 진행되는 구조예요.

# 대화 도중 이 작업을 클라우드로 위임
& 인증 모듈을 리팩터하고 테스트도 꼼꼼히 추가해줘

안전장치: --force는 신중히

편의만큼 주의도 필요합니다. --force는 확인 없이 파일을 바꿉니다 — 커밋되지 않은 작업이 있는 저장소에서 헤드리스로 돌리면 되돌리기 번거로워요. 습관 둘을 권합니다: 깨끗한 브랜치에서 돌리고, 명령 실행 격리가 필요하면 --sandbox enabled로 샌드박스를 켜세요(네트워크 접근까지 제어, 설정은 세션 간 유지). 참고로 sudo가 필요한 명령은 마스킹된 프롬프트로 비밀번호를 받고 모델에는 전달되지 않습니다.

자주 묻는 질문 (FAQ)

Q. 명령어가 agent인가요 cursor-agent인가요?

A. 현재 설치되는 실행 파일은 agent입니다. 예전 이름 cursor-agent도 별칭으로 아직 동작하지만, 새 스크립트는 agent로 쓰는 것이 좋습니다.

Q. -p로 돌렸는데 파일이 안 바뀌어요.

A. 정상입니다. 프린트 모드는 기본적으로 변경을 제안만 하고 적용하지 않습니다. 실제로 파일을 수정하려면 --force(또는 --yolo)를 함께 붙이세요.

Q. CI에서 인증은 어떻게 하나요?

A. CURSOR_API_KEY 환경변수에 API 키를 넣고 실행하면 됩니다. 키는 저장소에 하드코딩하지 말고 CI의 시크릿(secret)으로 주입하세요.

Q. Claude Code와 뭐가 다른가요?

A. 둘 다 터미널 에이전트지만, Cursor CLI는 Cursor 구독으로 쓰고 에디터와 설정을 공유한다는 점이 다릅니다. 이미 Cursor Pro라면 추가 비용 없이 쓸 수 있습니다. 자세한 위치 관계는 개요 글에 정리했습니다.

정리하면

Cursor CLI는 agent로 시작해서, 스크립트엔 -p, 실제 수정엔 --force, 모드는 --mode, 이어가기는 resume — 이 다섯 개가 뼈대입니다. 나머지는 위 예제를 상황에 맞게 변주하면 돼요. 저는 이걸 정리하면서 다시 느꼈는데, CLI의 진짜 값은 "터미널에서도 된다"가 아니라 "스크립트·CI에 에이전트를 끼워 넣을 수 있다"는 데 있습니다. 반복 작업 하나를 -p --force 스크립트로 옮겨보는 것부터 시작해보세요.

함께 보면 좋은 글

Cursor CLI 사용법 (개요·시작하기)
Cursor Router: 모델 자동 라우팅
작업별 모델 라우팅 기준

참고 자료

Cursor CLI 공식 문서 (Overview)
Headless / CI 공식 문서