Cursor CLI (agent) & Projects 가이드

터미널 에이전트 agent 중심 완전 가이드 — 2026-09-11 조사 기준(로컬 CLI 2026.09.10-fd3934a) · 2026-09-10 출시된 Projects(beta)와의 계층 차이까지 정리

⭐ 가장 자주 쓰는 것

다른 코딩 CLI 경험이 있다면 아래 여덟 개만 익혀도 Cursor CLI의 일상 작업은 거의 덮입니다.

1. 제품 구분 — 혼동 금지

Cursor는 “에이전트”라는 이름을 쓰는 제품이 다섯 갈래입니다. 이름이 비슷해서 문서를 섞어 읽으면 존재하지 않는 명령을 찾게 됩니다. 먼저 갈라 두고 시작합니다.

2. 설치 · 인증 · 업데이트

2-1. 설치 · 버전 필수

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

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

# PATH 등록 후 확인
export PATH="$HOME/.local/bin:$PATH"
agent --version
agent about          # 버전 · OS · 구독 · 계정

2-2. 인증 필수

2-3. 업데이트 · 채널 가끔

3. 모드 · Headless

3-1. Agent / Plan / Ask 매일

CLI의 모드는 에디터와 동일한 3종입니다.

3-2. 추가 모드 · 승인 모드 중요

• Debug — /debug. 슬래시 목록에 존재
• Run Everything — /run-everything(별칭 /auto-run) ↔ 플래그로는 --force/--yolo. 명시적으로 deny된 것 외에는 전부 실행
• Auto-review (Smart Auto) — --auto-review · /auto-review. allowlist → sandbox → 서버 분류기 순으로 판정
• Shell Mode — /shell(/sh, /run). 대화를 벗어나지 않고 셸 명령을 빠르게 실행, 30초 타임아웃
• Goal — /goal. 장기 목표 기능이며 롤아웃·게이팅 중(2026-08 changelog)
• Custom Mode — 스킬을 Option+Enter로 sticky 하게 붙여 쓰는 방식

3-3. Headless -p / --print CI 필수

agent -p "테스트 실패 원인 요약" --model auto
agent -p --force "파일 수정까지 수행"            # --yolo 와 동일
agent -p --trust "…"                             # 워크스페이스 trust
agent -p --output-format text|json|stream-json "…"
agent -p --output-format stream-json --stream-partial-output "…"

• 이미지: 프롬프트에 파일 경로를 포함하면 에이전트가 툴로 읽습니다. changelog에는 --image 옵션도 있습니다.
• CI: 공식 GitHub Actions 가이드 + CURSOR_API_KEY secret 조합. 권한 JSON에서 git·gh 계열을 deny 하는 구성이 권장됩니다.
• 엔터프라이즈: 팀 차원에서 headless를 비활성화할 수 있습니다(changelog 2026-06-09).

4. 모델 선택 매일

agent models              # 또는 agent --list-models
agent --model auto "…"
agent --model 'claude-opus-4-8[context=1m,effort=high,fast=false]' "…"
# 세션 중: /model, 패밀리 숏컷 /opus /composer /fast …
# 사용량: /usage

모델 목록은 계정·플랜에 따라 달라집니다. 2026-09-11 Ultra 계정에서 agent models 출력은 227줄 규모였고, 세션 기본 표시 모델은 Composer 2.5 Fast였습니다. 대표 계열만 스냅샷으로 적으면:

5. 권한 · Sandbox · Trust

5-1. 권한 토큰 문법 중요

권한은 전역 cli-config.json과 프로젝트 .cursor/cli.json에서 allow/deny 목록으로 씁니다. 토큰 형식은 다음과 같습니다.

5-2. 런타임 플래그 매일

5-3. Sandbox 상황별

agent sandbox enable|disable|reset|run …
# run 옵션
--network            # 네트워크 접근
--allow-paths        # 쓰기 허용 경로
--readonly-paths     # 읽기 전용 경로
--blocked-patterns   # 차단 패턴
# 세션 중: /sandbox

• 정책 파일: ~/.cursor/sandbox.json(전역), .cursor/sandbox.json(프로젝트)
• sandbox 서브커맨드는 parameters 문서에는 있지만 --help에서는 감춰져 있을 수 있습니다.
• 로컬 샘플 설정 값: approvalMode=allowlist, sandbox.mode=disabled, network.useHttp1ForAgent=false

5-4. sudo 처리 알아둘 것

6. Workspace · Worktree · 세션 매일

agent --worktree fix-flaky "플래키 테스트 원인 추적하고 고쳐줘"
agent --worktree try-rewrite "같은 문제를 리라이트 방식으로"
# 각각 ~/.cursor/worktrees/<repo>/{fix-flaky,try-rewrite} 에서 독립 작업

7. MCP · Plugins · Rules · Skills · Hooks

MCP 자주

agent mcp list
agent mcp list-tools <id>
agent mcp login <id>
agent mcp enable|disable
# 세션 중: /mcp

• 설정 파일: .cursor/mcp.json(프로젝트), ~/.cursor/mcp.json(전역)
• 일괄 승인은 --approve-mcps
• Team MCP는 ACP 모드에서 지원되지 않습니다(ACP 문서 명시)

Plugins 가끔

agent plugin marketplace add <git-url> [--git-ref]
agent plugin marketplace list|update|remove
agent --plugin-dir <path>      # 반복 지정 가능
# 세션 중: /plugin

Rules 중요

• CLI는 에디터와 동일한 rules를 읽습니다.
• 대상: .cursor/rules/*.mdc(하위 디렉터리 포함), AGENTS.md, 그리고 루트의 CLAUDE.md도 읽습니다.
• 생성: agent generate-rule · agent rule(인터랙티브). 세션 중 /rules, IDE는 /create-rule.
• 우선순위(공식): Team → Project → User

Skills · Hooks 가끔

• Skills: .cursor/skills. 타 도구 디렉터리(.claude/skills 등)도 탐색합니다. 세션 중 /skills, -p 헤드리스에서도 /skill-name 호출 가능.
• Hooks: .cursor/hooks.json (Claude Code settings와 병합). Cloud Agents는 repo hooks + Enterprise team hooks만 적용되며, ~/.cursor/hooks.json은 클라우드 VM에 존재하지 않습니다.

8. Worker · ACP

8-1. agent worker — Cloud Agent를 내 머신에서 상황별

# My Machines (개인용, Enterprise 불필요)
agent worker start

# Self-Hosted Pool (Enterprise + 서비스 계정 API key)
agent worker --pool [name] start

agent worker debug [--json]
agent worker controller …      # claim-then-spawn / warm pool

주요 옵션 요약: --worker-dir, --pool/--pool-name, --computer-use, --share-desktop, --auth-token-file, --management-addr, --idle-release-timeout, --label, --data-dir 등.

8-2. ACP (Agent Client Protocol) — 다른 에디터에 붙이기 상황별

agent acp     # 숨김 커맨드. stdio + JSON-RPC(NDJSON)

• 인증: 사전 agent login, 또는 API key / auth token. 프로토콜상 methodId는 cursor_login.
• 모드: agent / plan / ask
• 권한 응답: allow-once · allow-always · reject-once
• Cursor 확장 메서드: cursor/ask_question, cursor/create_plan(blocking), cursor/update_todos, cursor/task, cursor/generate_image(notification)
• 연결 대상: JetBrains, Neovim(avante.nvim), Zed 등
• 제약: Team MCP는 ACP 모드에서 미지원

9. 네트워크 · 프록시 · allowlist 엔터프라이즈

export HTTP_PROXY=… HTTPS_PROXY=… NODE_USE_ENV_PROXY=1
export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem

# cli-config.json — Zscaler 등 HTTP/2가 막힌 환경
"network": { "useHttp1ForAgent": true }

엔터프라이즈 방화벽 allowlist는 공식 network-configuration 문서를 기준으로 하되, 대표 도메인만 옮기면 다음과 같습니다.

10. 슬래시 명령 치트시트 매일

11. Cursor Projects (2026-09-10 beta)

2026-09-10에 공개된 Projects는 CLI의 기능이 아니라 별도 계층의 제품입니다. 출처는 공식 blog/projects와 changelog/projects이며, 아래는 그 문서에 적힌 범위만 옮긴 것입니다.

11-1. 무엇인가 · 코디네이터

• 장기 작업 단위: 하나의 피처, 마이그레이션, 앱 전체처럼 수개월에 걸친 “body of work”를 담는 그릇.
• Coordinator agent: 코드를 직접 쓰지 않습니다. 계획하고, 위임하고, 결과를 회수합니다. 작업에 블로킹되지 않으므로 사용자는 언제든 지시를 넣을 수 있습니다.
• 다수 서브에이전트 병렬 위임 — 공식 카피는 “수천 개”라고 표현합니다.
• 공식이 든 내부 사례: 수백 개 PR 규모의 마이그레이션, 디자인 시스템 일관성 유지, Projects 자체의 출시 작업.
• 시작 위치: IDE 좌측 navigation에서 Project를 만듭니다. beta이며 전 사용자 대상 롤아웃 중.

11-2. 세 기둥

11-3. 사용 패턴 (공식 문서 기준)

11-4. CLI와의 관계 핵심

11-5. Background Agents · Cloud Agents · Automations · Projects

12. Claude Code ↔ Grok ↔ Cursor 매핑 이주용

다른 CLI를 쓰던 사람이 대응 명령만 빠르게 찾을 수 있게 정리했습니다. 상세는 Claude Code 가이드, Grok CLI 가이드를 보세요.

13. 체크리스트 & 치트시트

처음 세팅할 때

• ☐ curl https://cursor.com/install -fsS | bash 후 PATH에 ~/.local/bin 추가
• ☐ agent login → agent whoami로 계정·플랜 확인 (agent auth 아님)
• ☐ agent about으로 버전 기록, 필요하면 --disable-auto-update 정책 결정
• ☐ 프로젝트에 .cursor/cli.json을 두고 deny 규칙부터 작성 (deny > allow)
• ☐ 기존 CLAUDE.md·AGENTS.md가 있으면 그대로 두기 — CLI가 읽습니다
• ☐ 사내망이면 HTTPS_PROXY·NODE_EXTRA_CA_CERTS, HTTP/2 문제 시 useHttp1ForAgent

CI에 넣기 전에

• ☐ CURSOR_API_KEY를 secret으로 주입 (로그에 노출 금지)
• ☐ 파일을 실제로 바꾸려면 --force가 필요하다는 점 확인
• ☐ --output-format json으로 결과를 파싱하고 실패 처리
• ☐ git·gh 등 위험 명령은 권한 JSON에서 deny
• ☐ 팀이 headless를 비활성화했는지(엔터프라이즈 정책) 확인

명령 치트시트

curl https://cursor.com/install -fsS | bash
agent login && agent whoami
agent about
agent models                        # 또는 --list-models
agent "refactor auth"               # 인터랙티브
agent --plan "설계부터 하자"
agent -p --force --output-format json "…"
agent --worktree fix-flaky "…"
agent ls
agent resume                        # 또는 --continue / --resume=<chatId>
agent mcp list
agent plugin marketplace list
agent generate-rule
agent worker start                  # My Machines
agent update
agent set-channel lab               # 채널 전환 시