#004 · 48편 중
Claude CLI 사용법 완전 가이드 - 터미널에서 Claude 쓰는 방법 2026

Claude CLI 사용법 완전 가이드 - 터미널에서 Claude 쓰는 방법 2026

· 수정 2026. 4. 22. AI 통통

터미널 하나로 Claude와 대화할 수 있다. 브라우저 탭을 열 필요도 없다.

직접 써보니 코드 리뷰, 커밋 메시지 생성, 로그 분석을 전부 셸 안에서 끝낼 수 있었다. 컨텍스트 스위칭이 줄어드니까 체감 생산성이 확 달라졌다. 아래에 설치부터 실전 활용까지 순서대로 정리했다.

(2026-04-22 확인 기준) 가격·플랜 정보는 Anthropic 공식 페이지 기준입니다. 변경 가능성이 있으므로 공식 페이지 재확인을 권장합니다.

Claude CLI 사용법 완전 가이드 2026

Claude CLI란 무엇인가

Claude CLI는 터미널(명령줄)에서 Claude AI를 직접 호출하는 도구다. 웹 인터페이스 없이 키보드 명령어만으로 Claude와 대화하거나, 셸 스크립트·파이프라인에 Claude를 끼워넣을 수 있다.

개발자가 주로 쓰는 이유는 간단하다. 코드 에디터나 터미널을 쓰는 중에 브라우저로 이동하지 않아도 된다. 결과물을 파일로 바로 리다이렉션할 수도 있다. 자동화 스크립트에 Claude를 붙이는 것도 가능하다.

Claude Code(코딩 특화 에이전트)와 헷갈리기 쉬운데, 둘은 다른 도구다. CLI는 내가 명령을 하나씩 내리는 방식이고, Claude Code는 파일 수정·터미널 실행까지 스스로 처리하는 에이전트다. 용도에 따라 골라 쓰면 된다.

Claude CLI 설치부터 비용 관리까지 여섯 단계를 순서대로 정리한 단계별 로드맵

아래 여섯 단계를 순서대로 따라가면 끝난다. 단계별 시간은 평균 15~20분이면 충분하다.

Step 1, 사전 준비: Node.js와 API 키

Node.js 버전 확인부터 시작한다.

node --version

18.0 이상이 출력돼야 한다. 더 낮으면 nodejs.org에서 LTS 버전을 먼저 설치하자. 솔직히 이 단계에서 막히는 경우가 제일 많다. Node 버전 체크를 먼저 하는 습관을 들이자.

API 키 발급 순서는 다음과 같다.

단계설명
1console.anthropic.com 접속 후 로그인
2왼쪽 메뉴 API Keys 클릭
3Create Key 버튼 클릭, 이름 입력
4생성된 키(sk-ant-...) 즉시 복사

키는 생성 직후 한 번만 표시된다. 창을 닫으면 다시 볼 수 없다. 반드시 어딘가 안전한 곳에 복사해두어야 한다.

API 크레딧도 확인한다. CLI는 API를 직접 호출하므로 사용량만큼 요금이 발생한다. 콘솔의 Billing 메뉴에서 잔액과 월간 한도를 미리 설정해두는 걸 추천한다. 처음에는 낮게 설정하고, 익숙해진 뒤 올리면 된다.

Step 2, Claude CLI 설치

npm으로 한 줄이면 끝난다.

npm install -g @anthropic-ai/claude

설치가 끝나면 버전을 확인한다.

claude --version

버전 번호가 출력되면 설치 성공이다. 출력이 없으면 npm의 global bin 경로가 PATH에 등록되지 않은 경우다. npm bin -g 명령어로 경로를 확인하고 셸 설정에 추가하면 된다.

Windows 사용자는 PowerShell을 관리자 권한으로 열고 동일한 명령어를 실행한다. WSL2 환경이라면 리눅스와 완전히 동일하게 쓸 수 있다.

Step 3, API 키 환경변수 설정

매번 키를 입력하지 않으려면 환경변수로 등록해야 한다.

macOS / Linux (zsh 기준):

echo 'export ANTHROPIC_API_KEY="sk-ant-여기에붙여넣기"' >> ~/.zshrc
source ~/.zshrc

bash를 쓴다면 ~/.zshrc 대신 ~/.bashrc를 쓴다.

Windows PowerShell:

Add-Content $PROFILE 'export ANTHROPIC_API_KEY="sk-ant-여기에붙여넣기"'
. $PROFILE

설정 후 키가 제대로 로드됐는지 확인한다.

echo $ANTHROPIC_API_KEY

sk-ant-...로 시작하는 키가 출력되면 완료다. 아무것도 출력되지 않으면 설정 파일을 다시 source해야 한다. 이걸 빠뜨리는 실수가 생각보다 자주 나온다.

Step 4, 기본 사용법: 첫 번째 명령어

설치가 끝났으면 바로 써볼 수 있다.

단일 질문 (non-interactive):

claude "파이썬으로 피보나치 수열을 출력하는 함수 작성해줘"

결과가 터미널에 바로 출력된다. 간단하다.

대화형 모드 (interactive):

claude

프롬프트(>)가 나타나면 입력을 기다리는 상태다. 이 모드에서는 여러 차례 주고받으며 대화할 수 있다. 종료하려면 exit 또는 Ctrl+D를 누른다.

파일 내용 전달:

claude --file ./main.py "이 코드에서 개선할 점을 알려줘"

파일 전체를 컨텍스트로 넘기고 질문할 수 있다. 코드 리뷰나 문서 요약에 바로 활용 가능하다. 직접 써봤을 때 긴 파일도 꽤 잘 처리했다.

모델 지정:

claude --model claude-3-5-sonnet-20241022 "질문 내용"

사용 가능한 최신 모델명은 Anthropic 공식 문서에서 확인하는 걸 권장한다. 모델명은 업데이트될 수 있다.

Claude CLI 기본 옵션과 파이프 연동 예시를 정리한 명령어 요약 표

Step 5, 개발 워크플로 통합: 실전 활용

CLI의 진짜 강점은 파이프라인에 붙이는 것이다.

커밋 메시지 자동 생성:

git diff --staged | claude "이 diff를 보고 간결한 커밋 메시지를 작성해줘"

git diff 결과를 파이프로 넘기면 커밋 메시지를 바로 뽑아준다. 근데 의외로 품질이 좋아서 거의 그대로 쓴다.

로그 분석:

cat error.log | claude "이 에러 로그에서 핵심 문제점을 요약해줘"

결과를 파일로 저장:

claude "README 초안을 작성해줘" > README.md

stdout으로 나오는 결과를 리다이렉션으로 파일에 바로 저장할 수 있다.

셸 스크립트 통합 예시:

#!/bin/bash
for file in ./src/*.py; do
 echo "=== $file ===" >> review.txt
 claude --file "$file" "이 파일의 잠재적 버그를 찾아줘" >> review.txt
done

여러 파일을 루프 돌리면서 리뷰를 자동으로 쌓을 수 있다. 대규모 코드베이스 점검할 때 꽤 유용하다.

Step 6, 비용 관리와 주의사항

API 호출은 토큰(텍스트 단위) 수만큼 요금이 발생한다. 파이프로 큰 파일을 자주 넘기면 예상보다 빠르게 크레딧이 소진된다.

비용 관리 체크리스트:

항목방법
월간 한도 설정콘솔 → Billing → 지출 한도 설정
사용량 모니터링콘솔 → Usage 탭에서 일별 확인
불필요한 긴 컨텍스트 제한파일 전달 시 필요한 부분만 전달
모델 선택단순 작업은 더 가벼운 모델 사용 고려

Claude 플랜별 웹·앱 인터페이스 사용 한도와 API 요금은 별개다. Pro(월 $20) 또는 Max(월 $100부터) 플랜을 구독해도 CLI API 호출은 별도 API 크레딧에서 차감된다. 혼동하지 말자. 플랜 상세 비교가 궁금하면 Claude AI 가격 완벽 정리를 참고하면 된다.

결론

Claude CLI 설치는 5분이면 끝난다. Node.js 버전 확인 → npm 설치 → API 키 환경변수 등록 → 첫 명령어 실행. 이 순서를 따르면 막히는 구간이 없다.

터미널 기반 개발 환경에 Claude를 붙이면, 브라우저로 이동하는 컨텍스트 스위칭이 사라진다. 커밋 메시지·코드 리뷰·로그 분석을 셸 안에서 해결할 수 있다. claude cli를 한 번 워크플로에 통합하면 다시 없애기 어려워진다.

FAQ

Q. Claude CLI는 무료로 사용할 수 있나요? A. CLI 도구 자체는 무료다. 다만 실행할 때 Anthropic API를 호출하므로 API 사용량만큼 요금이 청구된다. 요금은 Anthropic 콘솔에서 확인할 수 있다.

Q. Claude CLI 설치에 Node.js가 꼭 필요한가요? A. 현재 공식 Claude CLI는 npm 패키지로 배포된다. Node.js 18 이상이 설치되어 있어야 한다. node --version으로 버전을 먼저 확인하자.

Q. API 키는 어디서 발급받나요? A. console.anthropic.com에 접속해 로그인 후 API Keys 메뉴에서 생성한다. 키는 생성 직후 한 번만 보이므로 바로 복사해두어야 한다.

Q. ANTHROPIC_API_KEY를 영구 저장하는 가장 빠른 방법은? A. macOS·Linux 기준으로 ~/.zshrc 또는 ~/.bashrc 맨 아래에 export ANTHROPIC_API_KEY='sk-ant-...'를 추가하고 source ~/.zshrc를 실행하면 된다.

Q. 터미널에서 Claude에게 파일을 통째로 넘길 수 있나요? A. 된다. claude --file 경로/파일명 "질문" 형태로 쓰면 파일 내용을 컨텍스트에 포함해 응답한다. 코드 리뷰나 문서 요약에 바로 활용 가능하다.

Q. Claude CLI로 모델을 지정할 수 있나요? A. 가능하다. --model 플래그로 원하는 모델명을 지정하면 된다. 최신 모델명 목록은 Anthropic 공식 문서에서 확인하는 걸 권장한다.

Q. 셸 스크립트 안에서 Claude를 쓸 수 있나요? A. 된다. claude '질문' 형태로 실행하면 결과를 stdout으로 받는다. 파이프나 리다이렉션과 조합해 배치 작업에 바로 붙일 수 있다.

Q. Claude CLI와 Claude Code는 같은 건가요? A. 다르다. Claude CLI는 내가 명령을 하나씩 내리는 커맨드라인 도구다. Claude Code는 파일 수정·터미널 실행까지 스스로 처리하는 에이전트다. 둘 다 터미널에서 쓰지만 목적이 다르다.

Q. Windows에서도 Claude CLI가 동작하나요? A. 동작한다. PowerShell 또는 Windows Terminal에서 동일하게 npm으로 설치하면 된다. WSL2 환경에서 쓰면 리눅스와 거의 동일한 경험을 얻을 수 있다.

Q. API 사용량이 걱정되면 어떻게 제한할 수 있나요? A. Anthropic 콘솔 Billing 메뉴에서 월간 지출 한도를 설정할 수 있다. 한도를 초과하면 API 호출이 자동으로 중단된다. 처음에는 낮게 설정하고 올리는 걸 추천한다.

Q. Claude CLI 실행 중 ‘invalid API key’ 오류가 나면? A. echo $ANTHROPIC_API_KEY로 키가 제대로 출력되는지 먼저 확인한다. 빈 값이 나오면 셸 설정 파일을 다시 source해야 한다. 키 자체가 만료됐을 수도 있으니 콘솔에서 재발급도 확인해보자.

Q. Claude 무료 플랜으로 CLI를 쓸 수 있나요? A. 무료 플랜은 웹·앱 인터페이스용이다. CLI는 API를 직접 호출하므로 별도 API 크레딧이 필요하다. 신규 계정에 무료 크레딧이 지급되는 경우가 있으니 콘솔에서 잔액을 확인해보자.

출처

#claude cli#claude api 사용법#클로드 터미널