CLI에서 에이전트 사용하기

모드

CLI는 에디터와 동일한 모드를 지원합니다. 슬래시 명령어 또는 --mode 플래그로 모드를 전환할 수 있습니다.

계획 모드

코딩을 시작하기 전에 계획 모드를 사용해 접근 방식을 설계하세요. 에이전트가 계획을 구체화하기 위해 추가 질문을 합니다.

• Shift+Tab을 눌러 계획 모드로 전환
• /plan을 사용해 계획 모드로 전환
• --plan 또는 --mode=plan 플래그로 시작

Ask 모드

코드를 변경하지 않고 탐색하려면 Ask 모드를 사용하세요. 에이전트가 코드베이스를 검색하고 파일을 편집하지 않은 채 답변을 제공합니다.

• /ask로 Ask 모드로 전환
• --mode=ask 플래그로 시작

프롬프트 작성

최상의 결과를 얻으려면 의도를 명확히 밝히는 것이 좋습니다. 예를 들어 에이전트가 파일을 수정하지 않도록 하려면 "do not write any code"와 같은 프롬프트를 사용할 수 있습니다. 이는 구현 전에 작업을 계획할 때 특히 유용합니다.

Agent는 파일 작업, 검색, 셸 명령 실행, 웹 접근을 위한 도구를 제공합니다.

MCP

Agent는 기능 확장과 통합을 위해 MCP(Model Context Protocol)를 지원합니다. CLI는 mcp.json 구성 파일을 자동으로 감지하고 이를 적용하여 에디터에서 구성한 동일한 MCP 서버와 도구를 사용할 수 있도록 합니다.

ACP

Agent는 사용자 정의 클라이언트 통합을 위해 ACP(Agent Client Protocol)도 지원합니다. agent acp를 사용하면 JSON-RPC 메시징을 통해 stdio에서 Cursor CLI를 ACP 서버로 실행할 수 있습니다.

규칙

CLI 에이전트는 에디터와 동일한 규칙 시스템을 지원합니다. .cursor/rules 디렉터리에서 규칙을 생성해 에이전트에 컨텍스트와 지침을 제공할 수 있습니다. 규칙은 구성에 따라 자동으로 로드되고 적용되므로, 프로젝트의 여러 부분이나 특정 파일 형식에 맞춰 에이전트의 동작을 사용자 지정할 수 있습니다.

Agent 사용하기

탐색

위쪽 화살표(ArrowUpArrow Up)를 사용하면 이전 메시지를 순서대로 확인할 수 있습니다.

입력 단축키

• Shift+Tab — 모드(Agent, Plan, Ask) 간 전환
• Shift+Enter — 제출하지 않고 줄바꿈을 삽입하여 여러 줄 프롬프트를 더 쉽게 작성
• Ctrl+D — CLI 종료. 표준 셸 동작을 따르므로 종료하려면 두 번 눌러야 합니다.
• Ctrl+J 또는 +Enter — 모든 터미널에서 작동하는 범용 줄바꿈 입력 방법

리뷰

Ctrl+R로 변경 사항을 검토합니다. i를 눌러 추가 지시를 입력합니다. ArrowUpArrow Up/ArrowDownArrow Down로 스크롤하고 ArrowLeftArrow Left/ArrowRightArrow Right로 파일을 전환합니다.

컨텍스트 선택

@로 컨텍스트에 포함할 파일과 폴더를 선택하세요. /summarize를 실행해 컨텍스트 창의 공간을 확보할 수 있습니다. /compress도 계속 별칭으로 사용할 수 있습니다.

Cloud Agent로 전달

대화를 Cloud Agent로 푸시하면 자리를 비운 동안에도 계속 실행됩니다. 메시지 앞에 &를 붙이면 클라우드로 전송할 수 있습니다. 웹 또는 모바일에서 cursor.com/agents로 돌아와 작업을 이어서 할 수 있습니다.

# 대화 도중 Cloud Agent에 task 전달하기& refactor the auth module and add comprehensive tests

CLI 워크트리

현재 체크아웃을 직접 편집하지 않고 새 Git 워크트리에서 에이전트를 실행하려면 -w 또는 --worktree [name]을 전달하세요. Cursor는 에디터에서 생성한 워크트리와 나란히 이러한 체크아웃을 ~/.cursor/worktrees/<reponame>/<name> 아래에 생성합니다. name을 생략하면 Cursor가 자동으로 생성합니다.

Cursor는 에디터 워크트리에 적용하는 것과 동일한 보존 규칙으로 CLI 워크트리를 정리합니다. 정리 설정 및 제한에 대해서는 오래된 워크트리는 어떻게 정리되나요?를 참조하세요.

명시적으로 저장소 루트를 지정해야 하는 경우 --workspace <path>를 함께 사용하세요. 그렇지 않으면 CLI는 현재 작업 디렉터리를 사용합니다. --worktree는 해당 프로젝트 내에서 에이전트가 파일을 수정하는 위치만 변경합니다.

# 현재 저장소에서 자동 생성된 이름으로 임시 워크트리 생성agent --worktree "upgrade the test runner and fix any broken snapshots"# 다른 저장소에서 이름을 지정한 워크트리 생성agent --workspace ~/src/my-app --worktree auth-fix "fix the flaky auth test and open a PR"

기록

기존 스레드를 이어서 사용하려면 --resume [thread id]로 이전 컨텍스트를 로드하세요.

가장 최근 대화를 재개하려면 agent resume, --continue 또는 /resume 슬래시 명령어를 사용하세요.

agent ls를 실행해 이전 채팅을 열고 원하는 채팅을 재개할 수도 있습니다.

명령 승인

터미널 명령을 실행하기 전에 CLI에서 실행을 승인(y)하거나 거부(n)할지 묻습니다.

비대화형 모드

-p 또는 --print를 사용하면 비대화형 모드에서 Agent를 실행할 수 있습니다. 응답이 콘솔에 출력됩니다.

비대화형 모드에서는 Agent를 비대화형 방식으로 호출할 수 있습니다. 따라서 스크립트, CI 파이프라인 등에 통합할 수 있습니다.

--output-format과 함께 사용하면 출력 형식을 제어할 수 있습니다. 예를 들어 스크립트에서 쉽게 파싱할 수 있는 구조화된 출력에는 --output-format json을 사용하고, 에이전트의 최종 응답을 일반 텍스트로 출력하려면 --output-format text를 사용합니다.