Claude Code CLI 완벽 레퍼런스 가이드

최종 업데이트: 2025년 2월
대상 버전: Claude Code (최신)
공식 문서: code.claude.com/docs/en/cli-reference

---

목차

1. 설치 및 인증
2. CLI 기본 명령어
3. CLI 플래그 (옵션)
4. 시스템 프롬프트 플래그
5. 슬래시 명령어 (대화형 세션 내)
6. 키보드 단축키
7. 대화형 입력 특수 문법
8. MCP 서버 관리
9. 설정 관리 (claude config)
10. 환경변수
11. 서브에이전트 (--agents)
12. 실전 조합 예시

---

1. 설치 및 인증

작업	명령어
설치	npm install -g @anthropic-ai/claude-code
최신 버전 업데이트	claude update
API 키 로그인	claude auth login
인증 상태 확인	claude auth status
로그아웃	claude auth logout
버전 확인	claude --version 또는 claude -v

참고: Claude Pro 또는 Max 구독이 있으면 브라우저 인증도 가능합니다. API 키 사용 시 ANTHROPIC_API_KEY 환경변수로 설정할 수도 있습니다.

---

2. CLI 기본 명령어

명령어	설명	사용 예시
claude	대화형 REPL 세션 시작	claude
claude "질의"	초기 프롬프트와 함께 REPL 시작	claude "이 프로젝트 구조 설명해줘"
claude -p "질의"	비대화형(1회) 질의 후 종료	claude -p "이 함수 설명해줘"
cat file \| claude -p "질의"	파이프로 내용 전달 후 질의	cat logs.txt \| claude -p "에러 분석"
claude -c	가장 최근 대화 이어서 진행	claude -c
claude -c -p "질의"	최근 대화 이어서 비대화형 질의	claude -c -p "타입 에러 확인해줘"
claude -r "세션ID"	특정 세션 ID로 재개	claude -r "abc123" "PR 마무리해줘"
claude update	최신 버전으로 업데이트	claude update
claude mcp	MCP 서버 설정/관리	claude mcp list

---

3. CLI 플래그 (옵션)

3-1. 세션 관리

플래그	설명	사용 예시
--continue, -c	현재 디렉토리의 가장 최근 대화 이어서 진행	claude -c
--resume, -r	특정 세션 ID로 재개 (대화형에서는 선택 UI 표시)	claude -r abc123 "질의"
--fork-session	세션 재개 시 새 세션 ID로 분기 (--resume/--continue와 함께 사용)	claude --resume abc123 --fork-session
--session-id	특정 UUID를 세션 ID로 사용	claude --session-id "550e8400-..."
--print, -p	비대화형 모드 (응답 출력 후 종료)	claude -p "질의"

3-2. 모델 및 에이전트

플래그	설명	사용 예시
--model	세션에서 사용할 모델 지정 (sonnet, opus, haiku 또는 전체 모델명)	claude --model opus
--fallback-model	기본 모델 과부하 시 자동 폴백 모델 지정 (print 모드 전용)	claude -p --fallback-model sonnet "질의"
--agent	현재 세션에서 사용할 에이전트 지정 (설정의 agent 값 오버라이드)	claude --agent my-custom-agent
--agents	JSON으로 커스텀 서브에이전트 정의	아래 서브에이전트 섹션 참조

3-3. 도구 및 권한

플래그	설명	사용 예시
--allowedTools	사용자 확인 없이 허용할 도구 목록 추가	--allowedTools "Bash(git log:*)" "Read"
--disallowedTools	사용 불가로 설정할 도구 목록	--disallowedTools "Bash(rm:*)" "Edit"
--tools	사용 가능한 내장 도구 목록 지정 ("": 전체 비활성화, "default": 전체, 개별 지정 가능)	--tools "Bash,Edit,Read"
--dangerously-skip-permissions	모든 권한 프롬프트 건너뛰기 (주의: 신뢰할 수 있는 환경에서만)	claude --dangerously-skip-permissions
--permission-mode	지정된 권한 모드로 시작 (plan 등)	claude --permission-mode plan
--permission-prompt-tool	비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구 지정	claude -p --permission-prompt-tool mcp_tool "질의"

3-4. 출력 및 포맷

플래그	설명	사용 예시
--output-format	print 모드 출력 형식: text, json, stream-json	claude -p --output-format json "질의"
--input-format	print 모드 입력 형식: text, stream-json	claude -p --input-format stream-json
--json-schema	에이전트 완료 후 JSON Schema에 맞는 구조화된 출력 (print 모드 전용)	claude -p --json-schema '{...}' "질의"
--include-partial-messages	스트리밍 중 부분 이벤트 포함 (--print + --output-format stream-json 필수)	claude -p --output-format stream-json --include-partial-messages "질의"
--verbose	상세 로그 출력 (디버깅용, turn별 전체 출력 표시)	claude --verbose

3-5. 시스템 프롬프트 (별도 섹션 참조)

플래그	설명	사용 예시
--system-prompt	기본 시스템 프롬프트를 완전히 교체	claude --system-prompt "Python 전문가로 동작해"
--system-prompt-file	파일에서 시스템 프롬프트 로드하여 교체 (print 모드 전용)	claude -p --system-prompt-file ./prompt.txt "질의"
--append-system-prompt	기본 시스템 프롬프트 끝에 추가 (기존 기능 유지)	claude --append-system-prompt "항상 TypeScript 사용"

3-6. 작업 디렉토리 및 설정

플래그	설명	사용 예시
--add-dir	추가 작업 디렉토리 지정 (경로 존재 여부 검증)	claude --add-dir ../apps ../lib
--settings	추가 설정 JSON 파일 또는 JSON 문자열 로드	claude --settings ./settings.json
--setting-sources	로드할 설정 소스 지정 (쉼표 구분: user, project, local)	claude --setting-sources user,project
--plugin-dir	이번 세션에서만 플러그인 디렉토리 로드 (반복 가능)	claude --plugin-dir ./my-plugins

3-7. MCP 설정

플래그	설명	사용 예시
--mcp-config	JSON 파일 또는 문자열에서 MCP 서버 로드 (공백 구분)	claude --mcp-config ./mcp.json
--strict-mcp-config	--mcp-config에 지정된 서버만 사용 (다른 MCP 설정 무시)	claude --strict-mcp-config --mcp-config ./mcp.json

3-8. 기타

플래그	설명	사용 예시
--max-turns	비대화형 모드에서 에이전트 턴 수 제한	claude -p --max-turns 3 "질의"
--betas	API 요청에 포함할 베타 헤더 (API 키 사용자 전용)	claude --betas interleaved-thinking
--debug	디버그 모드 활성화 (카테고리 필터 가능: "api,hooks", 제외: "!statsig")	claude --debug "api,mcp"
--ide	시작 시 자동으로 IDE에 연결 (유효한 IDE가 하나일 때)	claude --ide
--version, -v	버전 번호 출력	claude -v

---

4. 시스템 프롬프트 플래그 비교

플래그	동작	사용 가능 모드	용도
--system-prompt	기본 프롬프트 완전 교체	대화형 + Print	Claude 동작을 완전히 제어해야 할 때
--system-prompt-file	파일 내용으로 완전 교체	Print 전용	재현 가능한 프롬프트, 버전 관리
--append-system-prompt	기본 프롬프트 끝에 추가	대화형 + Print	기본 기능을 유지하면서 지시사항 추가 ✅ 권장

⚠️ 주의: --system-prompt과 --system-prompt-file은 동시에 사용할 수 없습니다. 대부분의 경우 --append-system-prompt 사용을 권장합니다.

---

5. 슬래시 명령어 (대화형 세션 내)

대화형 REPL 세션 내에서 / 접두사로 실행하는 명령어입니다.

5-1. 핵심 명령어

명령어	설명
/help	사용 가능한 모든 슬래시 명령어 목록 표시 (커스텀 명령어 포함)
/clear	대화 히스토리 초기화 (새로 시작)
/exit	REPL 세션 종료 (Ctrl+D와 동일)
/status	버전 정보 및 연결 상태 표시

5-2. 컨텍스트 관리

명령어	설명
/compact [지시사항]	대화 히스토리 압축 (컨텍스트 절약). 선택적 지시사항으로 특정 주제 유지 가능 (예: /compact 인증 로직 중심)
/context	현재 컨텍스트 사용량을 컬러 그리드로 시각화 (컨텍스트 "연료 게이지")

5-3. 모델 및 세션

명령어	설명
/model	현재 세션의 모델 변경 (Sonnet, Opus, Haiku 선택)
/resume	이전 세션 목록 표시 및 선택하여 재개
/rename	현재 세션에 이름 부여 (나중에 이름으로 재개 가능)
/stats	사용 통계 (선호 모델, 사용 그래프, 연속 사용일 등)
/usage	현재 토큰 사용량 및 비용 확인

5-4. 도구 및 권한

명령어	설명
/permissions	권한 설정 보기/수정
/allowed-tools	허용된 도구 목록 확인
/hooks	Hooks 설정을 메뉴 인터페이스로 구성
/mcp	MCP 서버 설정 관리

5-5. 프로젝트 초기화 및 코드

명령어	설명
/init	프로젝트 루트에 CLAUDE.md 파일 생성 (프로젝트 메모리 역할)
/install-github-app	GitHub 앱 설치 (자동 PR 리뷰 활성화)
/plan	플랜 모드 전환 (코드 변경 없이 계획만 수립)

5-6. 기타

명령어	설명
/config	설정 보기/수정
/cost	세션 비용 정보
/login	인증 전환
/logout	로그아웃
/doctor	Claude Code 설치 상태 진단
/vim	Vim 모드 토글
/project:명령어	프로젝트 커스텀 슬래시 명령어 실행
/user:명령어	사용자 글로벌 커스텀 슬래시 명령어 실행

---

6. 키보드 단축키

6-1. 대화형 REPL 기본 단축키

단축키	설명
Escape	Claude 응답 중단 (⚠️ Ctrl+C가 아님!)
Escape × 2	이전 메시지 목록 표시 및 이동
Ctrl+D	세션 종료 (/exit과 동일)
Ctrl+C	CLI 완전 종료
↑ (위 화살표)	이전 입력 히스토리 탐색 (이전 세션 포함)

6-2. 기능 토글 단축키

단축키 (macOS)	단축키 (Linux/Windows)	설명
Cmd+T	Ctrl+T	Extended Thinking 토글
Option+P	Alt+P	프롬프트 작성 중 모델 전환
Ctrl+G	Ctrl+G	외부 편집기에서 입력 편집
Shift+Tab	Shift+Tab	권한 모드 전환
Ctrl+V	Ctrl+V	클립보드 이미지 붙여넣기

---

7. 대화형 입력 특수 문법

문법	설명	사용 예시
@파일경로	특정 파일을 컨텍스트에 포함	@src/auth.ts 이 파일 리뷰해줘
@디렉토리경로	디렉토리 참조	@src/components/ 구조 분석
!명령어	쉘 명령어 직접 실행 (Claude 대화 없이)	!npm test
think:	Think 모드 (표준보다 깊이 있는 사고)	think: DB 커넥션 최적 구조는?
think hard:	Think Hard 모드 (복잡한 아키텍처 결정)	think hard: 전체 API 리팩토링 계획

---

8. MCP 서버 관리

명령어	설명	사용 예시
claude mcp add <이름> -- <명령어>	MCP 서버 추가	claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp add --transport http <이름> <URL>	HTTP 전송 MCP 서버 추가	claude mcp add --transport http github https://mcp.github.com
claude mcp add --client-id <ID> --client-secret <SECRET>	OAuth 클라이언트 자격증명과 함께 MCP 서버 추가	Dynamic Client Registration 미지원 서버용
claude mcp list	등록된 MCP 서버 목록 확인	claude mcp list
claude mcp remove <이름>	MCP 서버 제거	claude mcp remove github

---

9. 설정 관리 (claude config)

명령어	설명	사용 예시
claude config list	모든 설정 확인	claude config list
claude config set <키> <값>	설정 값 지정	claude config set model claude-sonnet-4-5-20250929
claude config set --global <키> <값>	글로벌 설정 값 지정	claude config set --global preferredNotifChannel terminal_bell
claude config reset	설정 초기화	claude config reset

주요 설정 항목

설정 키	설명	예시 값
model	기본 모델	claude-sonnet-4-5-20250929
maxTokens	최대 토큰 수	4096
preferredNotifChannel	알림 채널	terminal_bell
editor	기본 편집기	code, vim

---

10. 환경변수

환경변수	설명	사용 예시
ANTHROPIC_API_KEY	Anthropic API 키	export ANTHROPIC_API_KEY="sk-..."
CLAUDE_CODE_EFFORT_LEVEL	사고 수준 (low, medium, high)	CLAUDE_CODE_EFFORT_LEVEL=high claude
MAX_MCP_OUTPUT_TOKENS	MCP 출력 토큰 제한	MAX_MCP_OUTPUT_TOKENS=50000 claude
BASH_DEFAULT_TIMEOUT_MS	Bash 명령어 타임아웃 (밀리초)	BASH_DEFAULT_TIMEOUT_MS=300000 claude
CLAUDE_CODE_SHELL	자동 감지 대신 사용할 셸 지정	export CLAUDE_CODE_SHELL="/bin/zsh"

---

11. 서브에이전트 (--agents)

--agents 플래그로 JSON 형식의 커스텀 서브에이전트를 정의할 수 있습니다.

에이전트 정의 필드

필드	필수	설명
description	✅	서브에이전트가 호출되어야 할 상황을 자연어로 설명
prompt	✅	서브에이전트의 동작을 안내하는 시스템 프롬프트
tools	❌	사용 가능한 도구 배열 (예: ["Read", "Edit", "Bash"]). 미지정 시 모든 도구 상속
model	❌	모델 별칭: sonnet, opus, haiku. 미지정 시 기본 서브에이전트 모델 사용

사용 예시

claude --agents '{
  "code-reviewer": {
    "description": "코드 변경 후 적극적으로 리뷰 수행",
    "prompt": "시니어 코드 리뷰어로서 코드 품질, 보안, 모범 사례에 집중하세요.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "에러 및 테스트 실패 디버깅 전문가",
    "prompt": "전문 디버거로서 에러를 분석하고 근본 원인을 파악하여 수정 방안을 제시하세요."
  }
}'

Tip: .claude/agents/ 디렉토리에 마크다운 파일로 서브에이전트를 정의할 수도 있습니다.

---

12. 실전 조합 예시

자동화 스크립팅 (CI/CD)

# 보안 리뷰 자동화 → JSON 출력
claude -p "보안 이슈 코드 리뷰" \
  --output-format json \
  --allowedTools Read,Grep,Glob \
  --max-turns 3 > security_report.json

파이프라인 활용

# 로그 분석
cat error.log | claude -p "이 에러 로그의 근본 원인 분석"

# diff 리뷰
git diff main | claude -p "이 변경사항을 리뷰해줘"

커스텀 프롬프트로 전문 모드

# TypeScript 전문가 모드
claude --append-system-prompt "항상 TypeScript와 JSDoc 주석을 사용하세요"

# 완전한 커스텀 프롬프트
claude --system-prompt "당신은 Python 보안 전문가입니다. 모든 코드에 타입 힌트를 포함하세요."

멀티 디렉토리 작업

# 여러 디렉토리를 동시에 참조
claude --model opus --verbose --add-dir ../apps ../lib

세션 관리

# 세션 이어서 작업
claude -c

# 특정 세션 분기 후 작업
claude --resume abc123 --fork-session

# 명명된 세션 재개 (REPL 내에서 /rename으로 이름 지정 후)
claude --resume "my-feature-session"

---

빠른 참조 요약

하고 싶은 일	명령어
대화 시작	claude
1회 질의 후 종료	claude -p "질의"
이전 대화 이어서	claude -c
모델 변경 (CLI)	claude --model opus
모델 변경 (세션 내)	/model
컨텍스트 초기화	/clear
컨텍스트 압축	/compact
프로젝트 초기화	/init
파일 참조	@파일경로
쉘 명령어 실행	!명령어
응답 중단	Escape
사용량 확인	/usage
권한 프롬프트 건너뛰기	--dangerously-skip-permissions
JSON 출력	--output-format json

---

💡 Tip: /help 명령어로 커스텀 명령어를 포함한 전체 슬래시 명령어 목록을 항상 확인할 수 있습니다.
📁 CLAUDE.md 계층 구조: ~/.claude/CLAUDE.md (글로벌) → 프로젝트 루트 CLAUDE.md → 하위 디렉토리 CLAUDE.md
🔧 커스텀 슬래시 명령어: .claude/commands/ (프로젝트) 또는 ~/.claude/commands/ (글로벌)에 마크다운 파일로 정의