터미널형 AI 코딩 도구를 하나 더 늘릴 때 시간이 가장 많이 새는 구간은 설치가 아니라 그 직후예요. 설치 스크립트 자체는 명령어 한 줄이라 1분이면 끝나는데, 터미널이 명령어를 못 찾거나 로그인 인증이 안 붙거나 cursor와 cursor-agent를 헷갈려서 붙잡히는 시간이 훨씬 깁니다. 결론부터 말하면 Cursor CLI는 설치 스크립트 실행 → 셸 재시작(또는 PATH 등록) → cursor-agent login → 프로젝트 폴더에서 cursor-agent 실행, 이 네 단계만 순서대로 밟으면 끝나고, 막히는 지점은 거의 전부 PATH와 인증 두 군데예요. 아래에서 맥·윈도우·리눅스별 설치 순서와 명령어 치트시트, 그리고 Claude Code를 이미 쓰는 사람이 언제 Cursor CLI로 갈아타면 좋은지까지 순서대로 정리했어요.
- Cursor CLI란? cursor와 cursor-agent가 헷갈리는 이유
- 설치 전 확인할 3가지
- OS별 설치 순서: 맥·리눅스·윈도우
- 로그인과 첫 실행: 인증부터 프롬프트 한 줄까지
- 자주 쓰는 명령어와 옵션 치트시트
- 비대화형 모드와 자동화 붙이기
- 설치 직후 막히는 지점 5가지와 해결법
- Claude Code와 비교해 언제 Cursor CLI를 쓸까
- 자주 묻는 질문
- 참고자료
Cursor CLI란? cursor와 cursor-agent가 헷갈리는 이유
Cursor CLI는 터미널에서 Cursor를 다루는 명령줄 도구예요. 그런데 여기서 초보자가 가장 먼저 꼬이는 지점이 있어요. 이름이 비슷한 두 개의 명령어가 서로 완전히 다른 일을 한다는 거예요.
첫 번째는 cursor입니다. 이건 AI와 아무 상관이 없어요. 터미널에서 cursor .이라고 치면 현재 폴더를 Cursor 에디터(GUI 창)로 열어주는 역할만 해요. VS Code의 code 명령어와 완전히 같은 성격이라고 보면 됩니다. 파일 열기, 새 창 띄우기, 두 파일 비교하기 같은 일을 담당해요.
두 번째는 cursor-agent입니다. 우리가 흔히 “터미널에서 AI 코딩”이라고 부르는 게 바로 이쪽이에요. 에디터 창을 띄우지 않고 터미널 안에서 AI 에이전트가 직접 파일을 읽고, 수정하고, 명령어를 실행해요. Claude Code를 써봤다면 그 구조가 거의 그대로 겹친다고 느낄 거예요.
검색해서 나오는 글들이 이 둘을 섞어 쓰는 경우가 많아요. “cursor cli 설치했는데 AI가 안 나와요”라는 질문의 절반은 cursor만 설치해놓고 에이전트를 기대한 경우입니다. 반대로 cursor-agent만 깔아놓고 “왜 에디터가 안 열리냐”고 하는 경우도 있고요.
| 구분 | cursor | cursor-agent |
|---|---|---|
| 하는 일 | 에디터 창 실행·파일 열기 | 터미널 안에서 AI가 코드 작성·수정 |
| 설치 방법 | 에디터 설치 후 명령 팔레트에서 PATH 등록 | 설치 스크립트 한 줄 실행 |
| 에디터 필요 여부 | 필수 | 없어도 동작(서버·CI에서도 사용) |
| Claude Code 대응 | 해당 없음 | claude 명령어와 같은 자리 |
이 글에서 “Cursor CLI 사용법”이라고 할 때는 주로 cursor-agent를 다뤄요. 다만 cursor 명령어도 실무에서 꽤 요긴하니 옵션 치트시트 섹션에서 같이 정리했습니다.
설치 전 확인할 3가지
설치를 바로 시작하기 전에 3분만 투자해서 환경을 점검하면 뒤에서 막히는 시간이 확 줄어요. 특히 코딩 비전공자가 터미널 도구를 처음 두 개 이상 깔 때는 이 확인이 없으면 어디서 꼬였는지 되짚기가 어렵습니다.
📋 설치 전 점검 체크리스트
✓ 윈도우라면 PowerShell로 할지 WSL로 할지 먼저 결정
✓ Cursor 계정 로그인 상태와 구독 플랜 확인
✓ 실습용 빈 폴더 하나 미리 만들어두기
✓ 기존에 깔린 AI CLI(claude 등)와 충돌 여부 확인
1) 셸 종류 확인. 터미널에 echo $SHELL을 치면 /bin/zsh 또는 /bin/bash가 나와요. 이게 중요한 이유는 나중에 PATH를 수동으로 등록할 때 편집할 파일이 달라지기 때문이에요. zsh면 ~/.zshrc, bash면 ~/.bashrc 또는 ~/.bash_profile을 건드립니다. 이걸 모르고 엉뚱한 파일에 경로를 추가해놓고 “왜 안 되지” 하는 경우가 정말 흔해요.
2) 윈도우는 경로를 먼저 정하세요. PowerShell에서 바로 쓸 건지, WSL(윈도우 안의 리눅스) 안에서 쓸 건지에 따라 설치 방법과 파일 경로가 완전히 달라져요. WSL 안에 설치하면 리눅스와 똑같은 절차를 쓸 수 있어서 인터넷 자료를 그대로 따라 하기 편하다는 장점이 있습니다. 대신 윈도우 탐색기의 폴더 경로와 WSL 안의 경로가 달라서 처음엔 헷갈려요.
3) 구독 상태. Cursor CLI는 별도 요금 체계가 아니라 Cursor 계정의 사용량을 그대로 씁니다. 즉 에디터에서 쓰던 요금제를 터미널에서도 공유해요. 무료 플랜으로도 맛보기는 되지만, 에이전트가 파일을 여러 개 읽고 수정하는 작업은 토큰 소모가 빠른 편이라 금방 한도에 닿을 수 있어요. 현재 적용되는 무료 한도와 플랜별 가격은 수시로 바뀌니 공식 요금 페이지에서 확인하는 게 정확합니다.
OS별 설치 순서: 맥·리눅스·윈도우
여기서는 AI 에이전트인 cursor-agent 설치를 기준으로 정리했어요. 순서만 지키면 대부분 5분 안에 끝납니다.
맥(macOS)·리눅스 설치
터미널 열고 설치 스크립트 실행
공식 문서에 안내된 설치 명령(curl로 설치 스크립트를 받아 sh로 실행하는 한 줄)을 그대로 복사해 붙여넣어요. 설치 경로는 보통 홈 디렉터리 아래 숨김 폴더에 잡힙니다.
터미널을 완전히 껐다 켜기
설치 직후 바로 명령어를 치면 못 찾는 경우가 대부분이에요. 새 탭이 아니라 터미널 앱 자체를 종료 후 재실행하거나, source ~/.zshrc로 설정을 다시 읽어야 PATH가 반영됩니다.
설치 확인
cursor-agent --version을 실행해 버전 번호가 출력되면 성공이에요. which cursor-agent로 실제 설치 경로도 같이 확인해두면 나중에 문제 생겼을 때 추적이 쉬워집니다.
에디터용 cursor 명령어도 등록(선택)
Cursor 에디터를 실행한 뒤 명령 팔레트(맥은 Cmd+Shift+P)에서 shell command 설치 항목을 찾아 실행하면 cursor 명령어가 PATH에 등록돼요. 이건 에이전트와 별개 절차입니다.
윈도우 설치
윈도우는 별도 섹션으로 다뤄야 할 만큼 갈림길이 많아요. 가장 편한 길은 WSL 설치 후 리눅스와 동일한 절차를 밟는 거예요. 윈도우 터미널에서 wsl --install로 우분투를 깔고, 그 안에서 위 1~3번을 그대로 하면 됩니다.
PowerShell에서 직접 쓰고 싶다면 공식 문서의 윈도우용 설치 안내를 따르고, 설치 후 cursor-agent가 인식되지 않으면 환경 변수 Path에 설치 폴더를 수동으로 추가해야 해요. 시스템 속성 → 환경 변수 → 사용자 변수의 Path 편집에서 설치 경로를 새로 추가하고, PowerShell 창을 새로 열면 적용됩니다.
⚠️ 주의사항
WSL 안에 설치했다면 윈도우 쪽 C드라이브 폴더(/mnt/c/…)에서 작업할 때 파일 읽기·쓰기 속도가 눈에 띄게 느려집니다. 실습 프로젝트는 WSL 홈 디렉터리 안(~/projects 같은 경로)에 두는 편이 훨씬 쾌적해요.
로그인과 첫 실행: 인증부터 프롬프트 한 줄까지
설치가 끝났다고 바로 쓸 수 있는 게 아니에요. 인증을 붙여야 합니다. 이 구간이 초보자가 두 번째로 많이 막히는 곳이에요.
1단계, 로그인. cursor-agent login을 실행하면 브라우저가 열리면서 Cursor 계정 인증 페이지로 넘어가요. 로그인 후 승인하면 터미널에 인증 완료 메시지가 뜹니다. 브라우저가 자동으로 안 열리면 터미널에 출력된 URL을 직접 복사해서 붙여넣으면 돼요.
2단계, 상태 확인. cursor-agent status로 지금 어느 계정으로 로그인돼 있는지 확인할 수 있어요. 회사 계정과 개인 계정을 같이 쓰는 경우 엉뚱한 계정으로 붙어서 사용량이 이상하게 잡히는 일이 있으니 첫 실행 때 꼭 한 번 보고 넘어가세요.
3단계, 프로젝트 폴더에서 실행. 여기가 핵심이에요. 터미널형 AI 도구는 “지금 내가 어느 폴더에 서 있는지”가 곧 작업 범위가 됩니다. cd 명령으로 작업할 프로젝트 폴더로 이동한 다음 cursor-agent를 치면 대화형 모드가 열려요. 홈 디렉터리에서 그냥 실행하면 AI가 엉뚱한 파일들을 훑으면서 토큰만 쓰게 됩니다.
4단계, 첫 프롬프트. 대화형 모드에 들어갔다면 평소 채팅하듯 한국어로 요청하면 돼요. 예를 들어 “이 폴더 구조를 설명해줘”처럼 읽기만 하는 요청부터 시작하는 게 좋아요. 파일을 수정하는 요청은 도구가 어떻게 동작하는지 감을 잡은 뒤에 하는 편이 안전합니다.
대화형 모드에 들어가지 않고 한 번에 처리하고 싶다면 cursor-agent "README 파일 초안을 만들어줘"처럼 프롬프트를 따옴표로 감싸 인자로 넘기면 돼요. 이 방식이 뒤에서 다룰 자동화의 출발점이 됩니다.
💡 꼭 알아두세요
첫 실습은 반드시 백업이 있거나 버려도 되는 폴더에서 하세요. git으로 관리되는 폴더라면 작업 전 커밋을 한 번 해두면 AI가 파일을 엉뚱하게 바꿔도 git checkout 한 줄로 되돌릴 수 있어요. 터미널형 AI 도구를 쓸 때 git은 선택이 아니라 안전벨트입니다.
자주 쓰는 명령어와 옵션 치트시트
옵션을 한 번에 다 외울 필요는 없어요. 실제로 손에 붙는 건 5~6개 정도예요. 아래 표에서 굵은 것부터 익히면 됩니다.
에이전트(cursor-agent) 쪽 주요 옵션
| 플래그 | 역할 | 사용 예시 |
|---|---|---|
| -p / –print | 대화창 없이 결과만 출력(비대화형) | cursor-agent -p “버그 원인 요약해줘” |
| -m / –model | 사용할 모델 지정 | cursor-agent -m 모델명 “리팩터링해줘” |
| –output-format | 출력 형식 지정(text·json 등) | 스크립트로 결과를 파싱할 때 |
| –resume | 이전 대화 이어서 진행 | 터미널을 껐다 켠 뒤 맥락 복구 |
| login / logout / status | 인증 관리 | cursor-agent status |
| –help | 현재 버전의 전체 옵션 확인 | cursor-agent –help |
플래그 이름과 지원 범위는 버전에 따라 바뀔 수 있어요. 그래서 가장 확실한 방법은 설치 직후 cursor-agent --help를 한 번 돌려서 지금 내 버전이 실제로 지원하는 목록을 눈으로 확인하는 거예요. 블로그 글의 옵션이 안 먹는 이유는 대부분 버전 차이입니다.
에디터(cursor) 쪽 주요 옵션도 같이 알아두면 편해요. 이쪽은 VS Code와 거의 동일합니다.
cursor .— 현재 폴더를 에디터로 열기. 가장 많이 씁니다.cursor -n— 새 창으로 열기. 프로젝트를 나란히 띄울 때.cursor -r— 기존 창을 재사용해서 열기.cursor -d 파일A 파일B— 두 파일 비교(diff) 화면 열기.cursor -g 파일:줄번호— 특정 줄로 바로 이동해서 열기. 오류 로그 추적할 때 유용해요.cursor -w 파일— 파일을 닫을 때까지 터미널이 기다림. git 커밋 메시지 편집기로 지정할 때 필요합니다.cursor -a 폴더— 이미 열린 창에 폴더를 추가(워크스페이스 확장).
비대화형 모드와 자동화 붙이기
Cursor CLI가 에디터 안의 채팅창과 결정적으로 갈리는 지점이 바로 여기예요. 터미널 명령어라는 건 곧 다른 명령어와 연결할 수 있다는 뜻이거든요.
1) 파이프로 넘기기. 앞 명령어의 결과를 그대로 AI에게 넘길 수 있어요. 예를 들어 git 변경 내역을 뽑아 바로 리뷰를 받는 식이에요.
git diff | cursor-agent -p "이 변경사항에서 위험해 보이는 부분만 짚어줘"
에러 로그를 파일로 저장해뒀다면 cat error.log | cursor-agent -p "원인 후보 3개만 정리해줘"처럼 쓸 수도 있어요. 복사·붙여넣기 없이 바로 넘어가니까 반복 작업에서 체감 차이가 큽니다.
2) 셸 별칭(alias) 등록. 자주 쓰는 조합은 ~/.zshrc에 별칭으로 등록해두세요. 예를 들어 alias review='git diff | cursor-agent -p "변경사항 코드리뷰"'처럼 넣어두면 터미널에서 review 한 단어로 끝나요. 등록 후엔 source ~/.zshrc로 반영하는 걸 잊지 마세요.
3) git 연동. git config --global core.editor "cursor -w"로 설정하면 커밋 메시지를 Cursor에서 작성하게 돼요. difftool로 등록하면 변경 비교도 에디터 화면에서 볼 수 있고요. 터미널 기본 편집기(vim)가 어려운 비전공자에게 특히 도움이 되는 설정이에요.
4) 자동화 스크립트와 GitHub Actions. 비대화형 모드는 사람이 앉아 있지 않아도 돌아가기 때문에 CI 파이프라인에 넣을 수 있어요. PR이 올라오면 변경 파일을 읽어 리뷰 코멘트를 남기거나, 문서 갱신 여부를 점검하는 식이에요. 다만 워크플로에서 쓰려면 API 키를 저장소 시크릿으로 등록하고 비대화형 인증을 붙여야 하는데, 이 부분은 공식 문서의 headless 안내를 그대로 따르는 게 안전합니다.
⚠️ 주의사항
자동화에 붙이는 순간 토큰 소모가 사람이 통제하지 못하는 속도로 늘어날 수 있어요. 처음에는 PR 한 건마다 실행되는 워크플로 대신, 수동 실행(workflow_dispatch) 방식으로 먼저 몇 번 돌려보고 사용량을 확인한 뒤 자동 트리거로 바꾸는 걸 권합니다.
설치 직후 막히는 지점 5가지와 해결법
설치 5분, 트러블슈팅 35분이 되는 이유가 대부분 아래 다섯 가지 안에 있어요.
1) command not found: cursor-agent
압도적 1위 문제입니다. 설치는 됐는데 터미널이 실행 파일을 못 찾는 상태예요. 순서대로 확인하세요. ① 터미널을 완전히 재시작했는지 ② echo $PATH에 설치 경로가 들어 있는지 ③ 설치 폴더에 실제 파일이 있는지(ls ~/.local/bin 같은 경로 확인). 경로가 빠져 있다면 셸 설정 파일에 export PATH="$HOME/.local/bin:$PATH" 형태로 추가한 뒤 source로 반영하면 됩니다.
2) 윈도우에서만 인식이 안 될 때
PowerShell은 환경 변수 Path를 창이 열릴 때 읽어요. 그래서 Path를 수정하고도 기존 창에서 계속 시도하면 영원히 안 됩니다. 반드시 창을 새로 열어야 해요. 그래도 안 되면 관리자 권한 PowerShell에서 확인하거나, 실행 정책 때문에 스크립트가 막힌 건 아닌지 점검해보세요.
3) 로그인은 됐는데 요청이 거부될 때
계정은 붙었는데 사용량 한도에 걸렸거나, 조직 계정의 정책으로 CLI 접근이 막힌 경우예요. cursor-agent status로 계정을 먼저 확인하고, 개인 계정으로 로그아웃 후 재로그인해보면 원인이 갈립니다.
4) AI가 명령어를 실행하려는데 계속 멈출 때
에이전트가 셸 명령을 돌리려면 승인이 필요해요. 기본값은 사람이 매번 확인하는 방식이라 자리를 비우면 진행이 멈춰 있습니다. 승인 없이 진행하는 모드도 있지만, 파일 삭제나 설치 명령까지 그냥 통과시키는 셈이라 처음엔 켜지 않는 게 좋아요. 익숙해진 뒤에도 격리된 실습 폴더에서만 쓰는 걸 권합니다.
5) 블로그에서 본 옵션이 안 먹을 때
버전 차이입니다. CLI 도구는 업데이트 주기가 빨라서 몇 달 전 글의 플래그가 이름이 바뀌거나 사라지는 일이 흔해요. cursor-agent --help와 --version 두 줄이 가장 빠른 확인 방법이에요.
💡 꼭 알아두세요
에러 메시지를 그대로 복사해서 이미 설치돼 있는 다른 AI CLI에게 물어보는 것도 좋은 방법이에요. 터미널 오류는 문장 자체에 원인이 들어 있는 경우가 많아서, 영문 메시지를 통째로 붙여넣으면 PATH 문제인지 권한 문제인지 빠르게 갈립니다.
Claude Code와 비교해 언제 Cursor CLI를 쓸까
터미널형 AI 코딩 도구를 두 개 이상 깔면 자연스럽게 드는 질문이 “그래서 뭘 쓰지”예요. 결론부터 말하면 둘 중 하나를 버릴 필요는 없고, 상황에 따라 나눠 쓰는 게 현실적이에요.
| 비교 항목 | Cursor CLI | Claude Code |
|---|---|---|
| 모델 선택 | 여러 제공사 모델을 옵션으로 전환 | Claude 계열 중심 |
| 에디터 연계 | Cursor 에디터와 설정·구독 공유 | 에디터 독립, 확장으로 연동 |
| 요금 구조 | Cursor 구독 사용량을 그대로 소모 | 별도 구독 또는 API 과금 |
| 한국어 자료 | 상대적으로 적은 편 | 비교적 많음 |
| 적합한 상황 | 에디터를 이미 쓰는 중, 모델 비교가 필요할 때 | 긴 맥락의 설계·리팩터링 작업 |
Cursor CLI를 쓰면 좋은 경우는 이렇게 정리돼요. 첫째, 이미 Cursor 에디터 구독을 쓰고 있어서 추가 비용 없이 터미널까지 확장하고 싶을 때. 둘째, 같은 요청을 여러 모델에 던져 결과를 비교하고 싶을 때. 옵션 하나만 바꾸면 되니까 비교 실험이 편해요. 셋째, GUI를 띄울 수 없는 원격 서버나 CI 환경에서 코드 작업을 돌려야 할 때예요.
Claude Code를 계속 쓰는 게 나은 경우도 있어요. 프로젝트 전체 구조를 파악하면서 여러 파일을 오가는 긴 작업, 그리고 막혔을 때 한국어 레퍼런스를 찾아야 하는 상황이에요. 비전공자 입장에서 한국어 자료의 양은 생각보다 큰 변수입니다.
요금 면에서 놓치기 쉬운 부분도 있어요. Cursor CLI는 별도 요금이 아니라 에디터 구독 사용량을 같이 깎습니다. 즉 터미널에서 크게 한 번 돌리면 에디터 채팅에서 쓸 여유가 줄어요. 두 창구가 지갑을 공유한다는 감각을 갖고 쓰는 게 좋습니다. 구체적인 한도와 플랜별 금액은 변동이 있으니 공식 요금 페이지에서 확인하세요.
자주 묻는 질문
Cursor CLI만 설치해도 되나요? 에디터가 꼭 있어야 하나요?
AI 에이전트(cursor-agent)는 에디터 없이 단독으로 동작해요. 원격 서버나 CI에서도 쓸 수 있는 이유가 그것입니다. 다만 cursor 명령어(파일·폴더 열기)는 에디터가 설치돼 있어야 의미가 있어요.
무료로 쓸 수 있나요?
Cursor 계정의 플랜을 그대로 따릅니다. 무료 플랜으로도 기본 체험은 가능하지만 에이전트 작업은 토큰 소모가 빨라 한도에 금방 닿을 수 있어요. 현재 적용되는 무료 한도와 유료 플랜 금액은 수시로 바뀌므로 공식 요금 페이지 확인을 권합니다.
터미널에서 AI가 명령어를 직접 실행하게 해도 안전한가요?
기본 설정은 실행 전 사용자 승인을 받도록 돼 있어서 그대로 두면 비교적 안전해요. 승인을 건너뛰는 모드는 편하지만 파일 삭제나 패키지 설치까지 통과되니, 쓴다면 git으로 관리되는 실습용 폴더에서만 사용하세요.
Claude Code를 쓰다가 갈아타면 적응이 어렵나요?
구조가 비슷해서 개념 자체는 금방 붙어요. 터미널에서 프로젝트 폴더로 이동한 뒤 명령어를 실행하고, 프롬프트로 요청하고, 파일 변경을 승인하는 흐름이 같습니다. 헷갈리는 건 주로 플래그 이름과 인증 방식 차이예요.
윈도우에서는 PowerShell과 WSL 중 뭐가 낫나요?
비전공자라면 WSL을 권합니다. 인터넷에 있는 리눅스·맥 기준 자료를 그대로 따라 할 수 있어서 막혔을 때 해결이 훨씬 빨라요. 대신 작업 폴더는 WSL 홈 디렉터리 안에 두어야 속도 저하를 피할 수 있습니다.
참고자료
- Cursor 공식 문서 — CLI 설치 명령, 옵션 목록, 헤드리스·CI 연동 안내를 가장 정확하게 확인할 수 있는 곳
- Cursor 요금 안내 — 플랜별 사용량과 무료 범위 확인
- GitHub Actions 공식 문서 — 자동화 워크플로와 시크릿 등록 방법
- Microsoft WSL 공식 문서 — 윈도우에서 리눅스 환경을 구성하는 설치·설정 안내
터미널형 AI 코딩 도구가 하나 더 늘었다고 해서 처음부터 다시 배울 건 많지 않아요. 결국 설치 스크립트 실행, PATH 반영, 로그인, 프로젝트 폴더에서 실행이라는 네 단계가 전부고, 막히는 지점도 command not found와 인증 두 군데로 거의 수렴합니다. 이 글의 순서대로만 밟으면 첫 실행까지 오래 붙잡힐 일은 줄어들 거예요. 처음 며칠은 파일을 읽고 설명하게 하는 가벼운 요청으로 감을 잡고, 그다음에 파이프와 별칭으로 반복 작업을 묶고, 사용량이 예측되기 시작하면 그때 자동화를 붙이는 순서를 권합니다. 그리고 어떤 도구를 쓰든 git으로 되돌릴 수 있는 상태를 만들어두는 것, 이것 하나만 지켜도 실습 중 사고의 대부분은 몇 초 만에 복구할 수 있어요.
함께 보면 좋은 글
