CLI 레퍼런스

공식 문서: https://code.claude.com/docs/ko/cli-reference

Claude Code의 CLI 명령어와 옵션을 정리합니다.

CLI 명령어 카테고리 맵

4가지 카테고리로 분류된 전체 명령어 구조

▶

기본 명령

claude

claude "프롬프트"

claude -c / -r

인터랙티브 모드 시작 · 세션 이어하기

⚙️

자동화

-p / --print

--bare

--output-format json

비대화형 실행 · CI/CD 파이프라인 연동

🔧

설정

/config

--model / --effort

--permission-mode

모델·품질·권한 설정 · 시스템 프롬프트

🩺

관리

/doctor

--version / --help

--max-budget-usd

환경 진단 · 버전 확인 · 비용 제한

오타 자동 제안

존재하지 않는 서브명령어를 입력하면 Claude Code가 가장 유사한 명령어를 자동으로 제안합니다. 예: claude athh → Did you mean: claude auth?

기본 명령어

claude

인터랙티브(Interactive) 모드로 Claude Code를 시작합니다.

# 기본 실행
claude

# 초기 프롬프트와 함께 실행
claude "이 프로젝트의 구조를 설명해줘"

# 특정 권한 모드로 실행
claude --permission-mode auto

최상위 하위 명령어

claude agents

에이전트 보기를 열어 병렬 백그라운드 세션을 실시간으로 모니터링하고 디스패치합니다. --cwd <path> 옵션으로 특정 디렉토리의 세션만 표시할 수 있습니다:

# 에이전트 보기 열기 (실행 중인 백그라운드 세션 모니터링/디스패치)
claude agents

# 특정 디렉토리의 세션만 표시
claude agents --cwd ~/work/my-project

claude attach

이 터미널에서 백그라운드 세션에 연결합니다:

# 세션 ID로 연결
claude attach 7c5dcf5d

claude logs

백그라운드 세션의 최근 출력을 조회합니다:

# 세션 출력 확인
claude logs 7c5dcf5d

claude respawn

대화 기록을 유지하면서 중지된 백그라운드 세션을 다시 시작합니다. --all 플래그로 모든 중지된 세션을 한 번에 재시작할 수 있습니다:

# 특정 세션 재시작
claude respawn 7c5dcf5d

# 중지된 모든 세션 재시작
claude respawn --all

claude rm

백그라운드 세션을 목록에서 제거합니다:

# 세션 제거
claude rm 7c5dcf5d

claude stop

백그라운드 세션을 중지합니다. claude kill도 동일하게 동작합니다:

# 세션 중지
claude stop 7c5dcf5d

claude auto-mode

자동 모드를 관리합니다:

# 자동 모드 분류기 규칙 출력
claude auto-mode defaults

# 자동 모드 설정 대화형 편집
claude auto-mode config

claude plugin

플러그인을 관리합니다:

# 플러그인 목록 표시
claude plugin list

# 플러그인 설치 (공식 레지스트리에서)
claude plugin install code-review@claude-plugins-official

# 플러그인 제거
claude plugin remove <plugin-name>

claude remote-control

원격 제어 모드로 실행합니다:

# 원격 제어 서버 시작
claude remote-control

# 특정 포트로 실행
claude remote-control --port 8080

# 프로젝트 이름 지정
claude remote-control --name "My Project"

claude auth

Anthropic 계정 인증을 관리합니다:

# 기본 로그인 (브라우저 열기)
claude auth login

# 이메일/패스워드 로그인
claude auth login --email

# SSO(싱글 사인온) 로그인
claude auth login --sso

# 콘솔 전용 환경(브라우저 없음)에서 로그인
claude auth login --console

# 로그아웃
claude auth logout

# 현재 인증 상태 확인 (JSON 형식)
claude auth status

# 사람이 읽기 쉬운 텍스트 형식으로 출력
claude auth status --text

claude auth status 종료 코드

claude auth status는 종료 코드로 인증 상태를 반환합니다:

종료 코드 0: 로그인된 상태
종료 코드 1: 로그인되지 않은 상태

이를 활용하면 CI/CD 스크립트에서 인증 여부를 쉽게 확인할 수 있습니다:

if claude auth status; then
  echo "인증됨, 작업 진행"
else
  echo "인증 필요"
  exit 1
fi

claude install

특정 버전의 Claude Code를 설치합니다:

# 최신 버전 설치
claude install

# 특정 버전 설치
claude install 2.1.118

# 안정 버전 설치
claude install stable

# 최신 버전 설치
claude install latest

claude setup-token

CI와 스크립트를 위한 장기 OAuth 토큰을 생성합니다. 토큰을 터미널에 출력하되 저장하지 않습니다. Claude 구독이 필요합니다:

# 장기 OAuth 토큰 생성 (터미널에 출력)
claude setup-token

claude ultrareview

ultrareview를 비대화형으로 실행합니다. 결과를 stdout으로 출력하고 성공 시 0, 실패 시 1로 종료합니다.

# PR 번호로 ultrareview 실행
claude ultrareview 1234

# JSON 형식으로 원본 페이로드 출력
claude ultrareview 1234 --json

# 타임아웃 설정 (기본값 30분 재정의)
claude ultrareview 1234 --timeout 60

옵션	설명
`[target]`	리뷰 대상 (PR 번호 또는 URL)
`--json`	JSON 형식으로 원본 페이로드 출력
`--timeout <minutes>`	기본 30분 타임아웃 재정의

claude update

Claude Code를 최신 버전으로 업데이트합니다:

# 최신 버전으로 업데이트
claude update

# 업데이트 가능 여부만 확인 (업데이트 미적용)
claude update --check

주요 플래그

실행 모드

플래그	설명	예시
`-p`, `--print`	비대화형 모드 (결과만 출력 후 종료)	`claude -p "README 생성해줘"`
`-c`, `--continue`	마지막 세션 이어하기	`claude -c`
`-r`, `--resume`	특정 세션 ID로 이어하기	`claude -r SESSION_ID`
`--bg`	세션을 백그라운드 에이전트로 시작하고 즉시 반환. `claude agents`로 모니터링, `claude attach`로 연결	`claude --bg "flaky 테스트 원인 조사"`
`--bare`	최소 모드: hooks, skills, plugins, MCP 서버, 자동 메모리 및 CLAUDE.md 자동 검색을 건너뜀	`claude -p --bare "분석해줘"`

모델 및 품질

플래그	설명	예시
`--model`	사용할 모델 지정	`claude --model claude-opus-4-6`
`--effort`	응답 품질 조절 (`low`/`medium`/`high`/`xhigh`/`max`). 지원 수준은 모델에 따라 다름. `effortLevel` 설정 키와 달리 CLI 플래그는 `max`를 허용	`claude --effort xhigh "복잡한 버그 분석"`
`--fallback-model`	기본 모델 실패 시 대체 모델	`claude --fallback-model claude-haiku-4-5`
`--permission-mode`	권한 모드 설정	`claude --permission-mode auto`

출력 형식

플래그	설명	예시
`--output-format`	출력 형식 (text/json/stream-json)	`claude -p --output-format json "분석"`
`--json-schema`	구조화된 출력 스키마 지정	아래 예제 참고
`--verbose`	상세 로그 출력	`claude --verbose`

비용 및 제한

플래그	설명	예시
`--max-budget-usd`	세션 최대 비용 제한 (USD)	`claude --max-budget-usd 5`
`--max-turns`	최대 대화 턴 수 제한	`claude -p --max-turns 10 "리팩토링"`

세션 및 컨텍스트

플래그	설명	예시
`--add-dir`	추가 디렉토리 참조	`claude --add-dir ../shared-lib`
`--fork-session`	기존 세션을 포크하여 새 세션 생성	`claude --fork-session SESSION_ID`
`--from-pr`	PR 연결 세션 재개. PR 번호, GitHub/GitHub Enterprise PR URL, GitLab Merge Request URL, Bitbucket PR URL 허용	`claude --from-pr 123`
`--system-prompt`	시스템 프롬프트 지정	`claude -p --system-prompt "한국어로 답변"`
`--append-system-prompt`	기존 시스템 프롬프트에 추가	`claude -p --append-system-prompt "간결하게"`

원격 및 고급

플래그	설명	예시
`--remote`	클라우드에서 세션 실행	`claude --remote "장시간 리팩토링"`
`--teleport`	클라우드 세션을 웹 브라우저로 이동	`claude --teleport`
`--tmux`	worktree에 대한 tmux 세션 생성 (`--worktree` 필요). 사용 가능한 경우 iTerm2 네이티브 창 사용. 기존 tmux를 강제하려면 `--tmux=classic` 사용	`claude -w feature-auth --tmux`
`--worktree`, `-w`	git worktree로 격리된 환경에서 실행	`claude -w "실험적 변경"`
`--teammate-mode`	에이전트 팀 표시 방식 설정: `auto`(기본값, tmux/iTerm2에서 분할 창 선택), `in-process`, `tmux`	`claude --teammate-mode in-process`
`--agent`	특정 에이전트 지정	`claude --agent my-agent`

디버그 및 진단

플래그	설명	예시
`--debug [categories]`	디버그 모드 활성화 (선택적 카테고리 필터링)	`claude --debug "api,mcp"`
`--debug-file <path>`	디버그 출력을 파일로 저장	`claude --debug-file debug.log`
`--maintenance`	유지보수 모드 실행	`claude --maintenance`
`--setting-sources`	로드할 설정 소스의 쉼표로 구분된 목록 (`user`, `project`, `local`)	`claude --setting-sources user,project`

세션 관리 (신규)

플래그	설명	예시
`-n`, `--name <name>`	세션 이름 지정	`claude -n "리팩토링 작업"`
`--session-id <id>`	특정 세션 ID로 시작	`claude --session-id abc123`
`--no-session-persistence`	세션 저장 비활성화	`claude --no-session-persistence`

MCP 설정

플래그	설명	예시
`--mcp-config <path>`	MCP 설정 파일 경로 지정	`claude --mcp-config .mcp.json`
`--strict-mcp-config`	지정한 MCP 설정 파일만 사용	`claude --strict-mcp-config --mcp-config prod.json`

IDE 및 통합

플래그	설명	예시
`--ide`	IDE 통합 모드 활성화	`claude --ide vscode`
`--chrome`	Chrome 브라우저 통합 활성화	`claude --chrome`
`--no-chrome`	Chrome 통합 비활성화	`claude --no-chrome`
`--rc`, `--remote-control`	원격 제어 모드 활성화	`claude --rc`
`--remote-control-session-name-prefix <prefix>`	원격 제어 세션 이름 접두사 설정	`claude --remote-control-session-name-prefix "proj-"`

자동화 (신규)

플래그	설명	예시
`--enable-auto-mode`	⚠️ 사용 중단됨 (v2.1.111에서 제거). `--permission-mode auto` 사용 권장	`claude --permission-mode auto`
`--agents <json>`	다중 에이전트 JSON 정의 (이름 키 객체 형식)	`claude --agents '{"reviewer":{"description":"코드 리뷰","prompt":"코드 리뷰어입니다"}}'`
`--tools <list>`	Claude가 사용할 기본 제공 도구 제한. 모두 비활성화: `""`, 모두 활성화: `"default"`, 특정 도구: `"Bash,Edit,Read"`	`claude --tools "Bash,Edit,Read"`
`--disallowedTools <list>`	사용 금지할 도구 목록 지정	`claude --disallowedTools "Bash,Edit"`
`--disable-slash-commands`	슬래시 커맨드 비활성화	`claude -p --disable-slash-commands "분석"`
`--include-hook-events`	출력에 훅 이벤트 포함	`claude --include-hook-events`
`--init`	CLAUDE.md 초기화 (비대화형)	`claude --init`
`--init-only`	초기화만 수행하고 종료	`claude --init-only`
`--input-format <format>`	입력 형식 지정 (text/stream-json)	`claude -p --input-format stream-json`
`--include-partial-messages`	스트리밍 응답에 부분 메시지 포함	`claude -p --include-partial-messages`
`--replay-user-messages`	이전 사용자 메시지 재생	`claude --replay-user-messages`

권한 및 보안

플래그	설명	예시
`--dangerously-skip-permissions`	모든 권한 확인 건너뛰기 ⚠️	`claude -p --dangerously-skip-permissions "작업"`
`--allow-dangerously-skip-permissions`	Shift+Tab 모드 사이클에 bypassPermissions를 추가합니다	`claude --allow-dangerously-skip-permissions`
`--permission-prompt-tool <tool>`	커스텀 권한 프롬프트 도구 지정	`claude --permission-prompt-tool my-tool`
`--exclude-dynamic-system-prompt-sections <섹션>`	동적 시스템 프롬프트에서 특정 섹션 제외	`claude --exclude-dynamic-system-prompt-sections memory`

주의

--dangerously-skip-permissions 플래그는 모든 권한 확인을 건너뜁니다. 신뢰할 수 있는 환경(CI/CD, 격리된 컨테이너)에서만 사용하세요.

설정 파일

플래그	설명	예시
`--settings <path>`	설정 파일 경로 지정	`claude --settings ~/custom-settings.json`
`--system-prompt-file <path>`	시스템 프롬프트 파일 지정	`claude --system-prompt-file prompt.txt`
`--append-system-prompt-file <path>`	시스템 프롬프트 파일 추가	`claude --append-system-prompt-file extra.txt`
`--plugin-dir <path>`	플러그인 디렉토리 지정	`claude --plugin-dir ~/.claude/plugins`
`--betas <list>`	베타 기능 활성화	`claude --betas feature1,feature2`
`--channels <list>`	활성화할 플러그인 채널 목록 (`plugin:<name>@<marketplace>` 항목의 공백 구분 목록)	`claude --channels 'plugin:beta@my-marketplace'`
`--dangerously-load-development-channels`	개발 중인 채널 로드 허용 ⚠️	`claude --dangerously-load-development-channels`

기타

플래그	설명	예시
`--version`	버전 확인	`claude --version`
`--help`	도움말	`claude --help`

슬래시 명령어

인터랙티브 모드에서 사용할 수 있는 슬래시 명령어입니다.

일반 명령어

명령어	설명
`/help`	도움말 표시
`/clear`	대화 히스토리 초기화
`/compact`	대화 내용을 요약하여 컨텍스트 절약
`/cost`	현재 세션의 토큰 사용량과 비용 표시
`/quit`	Claude Code 종료

설정 명령어

명령어	설명
`/permissions`	권한 설정 관리
`/model`	사용 중인 모델 변경
`/fast`	빠른 모드 토글 (같은 모델, 빠른 출력)

도구/확장 명령어

명령어	설명
`/mcp`	MCP 서버 관리 (추가/확인/제거)
`/plugin`	플러그인(Plugin) 관리
`/remote-control`	현재 세션에서 원격 제어 활성화
`/hooks`	현재 설정된 훅(Hook) 목록 확인
`/config`	설정 변경
`/doctor`	환경 진단

내장 스킬 명령어

명령어	설명
`/batch`	대규모 변경을 병렬 워크트리에서 실행
`/loop`	프롬프트를 주기적으로 반복 실행
`/debug`	디버그 로깅 활성화
`/simplify`	변경된 코드의 품질 개선
`/claude-api`	Claude API/SDK 레퍼런스 로딩

기타 명령어

명령어	설명
`/vim`	Vim 모드 토글(Toggle)
`/btw`	Claude 처리 중에도 사용 가능한 사이드 질문 (도구 접근 없음, 단일 응답, 프롬프트 캐시 재사용으로 저비용)
`/recap`	현재 세션 요약 생성 (필요할 때 수동으로 호출)
`/rename`	현재 대화 세션 이름 변경
`/teleport`	클라우드 세션을 웹 브라우저로 이동
`/desktop`	Desktop Commander 모드 활성화 (macOS)
`/schedule`	예약 작업 설정
`/terminal-setup`	터미널 키 바인딩 설정
`/init`	CLAUDE.md 자동 생성
`/memory`	프로젝트 메모리 관리
`/sessions`	최근 세션 목록 보기
`/think`	확장 사고(Extended Thinking) 활성화

키보드 단축키

대화형 모드에서 사용할 수 있는 키보드 단축키입니다.

macOS에서 Option/Alt 단축키 활성화

Alt+B, Alt+F, Alt+Y, Alt+M, Alt+P, Alt+T, Option+O 등의 단축키를 사용하려면 터미널에서 Option 키를 Meta로 설정해야 합니다:

iTerm2: 설정 → 프로필 → 키 → 일반 → Left/Right Option 키를 Esc+로 설정
Apple Terminal: 설정 → 프로필 → 키보드 → "Option을 Meta 키로 사용" 체크
VS Code: 설정에서 "terminal.integrated.macOptionIsMeta": true로 설정

일반 제어

단축키	기능
`Ctrl+C`	현재 작업 중단
`Ctrl+D`	Claude Code 세션 종료 (EOF 신호)
`Ctrl+L`	프롬프트 입력 지우기 및 화면 다시 그리기 (대화 기록 유지)
`Ctrl+R`	역방향 명령 기록 검색
`Ctrl+O`	트랜스크립트 뷰어 토글 (도구 사용 및 MCP 호출 상세 보기)
`Ctrl+B`	현재 bash 명령 또는 에이전트를 백그라운드로 실행 (tmux 사용자는 두 번)
`Ctrl+X Ctrl+K`	모든 백그라운드 에이전트 종료 (3초 내 확인 필요)
`Ctrl+T`	작업 목록(To-do list) 표시/숨기기 토글 (최대 5개 표시)
`Shift+Tab`	권한 모드 순환 (default → acceptEdits → plan → auto)
`Esc` + `Esc`	되돌리기 또는 요약 (코드/대화를 이전 지점으로 복원하거나 선택 메시지에서 요약)
`Left/Right 화살표`	권한 대화 상자 및 메뉴의 탭 간 탐색
`↑ / ↓` 또는 `Ctrl+P`/`Ctrl+N`	여러 줄 입력에서 커서 이동 또는 명령 기록 탐색

텍스트 편집

단축키	기능
`Ctrl+A`	현재 줄의 시작으로 커서 이동
`Ctrl+E`	현재 줄의 끝으로 커서 이동
`Ctrl+K`	줄 끝까지 삭제 (삭제된 텍스트 저장)
`Ctrl+U`	커서에서 줄 시작까지 삭제 (삭제된 텍스트 저장)
`Ctrl+W`	이전 단어 삭제 (삭제된 텍스트 저장)
`Ctrl+Y`	`Ctrl+K`/`Ctrl+U`/`Ctrl+W`로 삭제한 텍스트 붙여넣기
`Alt+Y`	붙여넣기 기록 순환 (`Ctrl+Y` 이후 사용, macOS에서 Option을 Meta로 설정 필요)
`Alt+B`	커서를 한 단어 뒤로 이동
`Alt+F`	커서를 한 단어 앞으로 이동
`Ctrl+G` / `Ctrl+X Ctrl+E`	기본 텍스트 편집기에서 현재 프롬프트 편집
`Ctrl+V` / `Cmd+V` / `Alt+V`	클립보드에서 이미지 붙여넣기

여러 줄 입력

방법	단축키	비고
`\` + Enter	`\` + `Enter`	모든 터미널에서 작동
Shift+Enter	`Shift+Enter`	iTerm2, WezTerm, Ghostty, Kitty, Warp, Apple Terminal 기본 지원
Option/Alt Enter	`Option+Enter`	macOS에서 Option을 Meta로 활성화 후
제어 시퀀스	`Ctrl+J`	구성 없이 모든 터미널에서 작동

VS Code, Cursor, Windsurf, Alacritty, Zed에서 Shift+Enter를 사용하려면 /terminal-setup을 실행하여 바인딩을 설치하세요.

확장 기능

단축키	기능
`Option+P` / `Alt+P`	모델 전환 (프롬프트를 지우지 않고)
`Option+T` / `Alt+T`	확장 사고 토글
`Option+O` / `Alt+O`	빠른 모드 토글
`Alt+M`	권한 모드 순환 (일부 터미널 구성에서 사용 가능)
`Tab` / `→`	파일 경로 자동 완성 및 프롬프트 제안 수락
`?`	사용 가능한 단축키 목록 표시
`Space` 길게 누르기	음성 입력(Voice Dictation) 활성화

트랜스크립트 뷰어 단축키

Ctrl+O로 트랜스크립트 뷰어를 열었을 때 사용할 수 있는 단축키입니다:

단축키	기능
`Ctrl+E`	모든 콘텐츠 표시 토글
`[`	전체 대화를 터미널 스크롤백에 작성 (Cmd+F, tmux 복사 모드 등으로 검색 가능)
`v`	대화를 임시 파일에 작성하고 `$VISUAL` 또는 `$EDITOR`에서 열기
`q`, `Ctrl+C`, `Esc`	트랜스크립트 뷰어 종료

계획 모드 활용

Shift+Tab으로 계획 모드를 켜면 Claude가 파일을 수정하지 않고 작업 계획만 세웁니다. 복잡한 리팩토링 전에 계획을 먼저 검토하고 싶을 때 유용합니다.

세션 선택기 단축키

--resume 모드에서 세션 목록이 표시될 때 사용할 수 있는 단축키입니다:

단축키	기능
`Space`	선택한 세션 미리보기
`Ctrl+R`	선택한 세션 이름 변경
`/`	세션 검색
`Ctrl+A`	모든 프로젝트의 세션 표시
`Ctrl+W`	모든 워크트리의 세션 표시
`Ctrl+B`	현재 브랜치로 세션 필터링
`Esc`	세션 선택기 종료

Vim 편집기 모드

/config → 편집기 모드를 통해 Vim 스타일 편집을 활성화할 수 있습니다. editorMode: "vim" 설정으로도 활성화됩니다.

모드 전환

명령	작업	모드에서
`Esc`	NORMAL 모드 진입	INSERT, VISUAL
`i`	커서 앞에 삽입	NORMAL
`I`	줄 시작에 삽입	NORMAL
`a`	커서 뒤에 삽입	NORMAL
`A`	줄 끝에 삽입	NORMAL
`o`	아래 줄 열기	NORMAL
`O`	위 줄 열기	NORMAL
`v`	문자 단위 시각적 선택 시작	NORMAL
`V`	줄 단위 시각적 선택 시작	NORMAL

탐색 (NORMAL 모드)

명령	작업
`h`/`j`/`k`/`l`	왼쪽/아래/위/오른쪽
`w`/`e`/`b`	다음 단어 / 단어 끝 / 이전 단어
`0` / `$`	줄 시작 / 줄 끝
`^`	첫 번째 공백이 아닌 문자
`gg` / `G`	입력 시작 / 입력 끝
`f{char}` / `F{char}`	다음/이전 문자로 점프
`t{char}` / `T{char}`	다음/이전 문자 직전/후로 점프
`;` / `,`	마지막 f/F/t/T 반복 / 역순 반복

NORMAL 모드에서 입력의 시작/끝에 있을 때 j/k는 명령 기록을 탐색합니다.

셸 명령 즉시 실행 (! 접두사)

대화 중 줄 첫 번째에 !를 붙이면 Claude를 거치지 않고 셸 명령을 즉시 실행합니다:

!ls -la          # 파일 목록 즉시 확인
!git status      # Git 상태 확인
!npm test        # 테스트 즉시 실행
!cat error.log   # 파일 내용 확인

Claude 응답 대기 없이 터미널처럼 즉시 실행되며, 실행 결과가 현재 대화 컨텍스트에 자동으로 포함됩니다.

커스텀 슬래시 명령어 만들기

.claude/commands/ 디렉토리에 마크다운 파일을 만들어 프로젝트 전용 슬래시 명령어를 정의할 수 있습니다.

파일 구조

프로젝트/
└── .claude/
    └── commands/
        ├── review.md     →  /review 명령어
        ├── deploy.md     →  /deploy 명령어
        └── test.md       →  /test 명령어

커스텀 명령어 예시 (`review.md`)

---
description: PR 코드 리뷰 수행
allowed-tools: Read, Bash(git diff *)
---

다음 파일들을 시니어 개발자 시각으로 리뷰해주세요:
$ARGUMENTS

체크 항목:
- 코드 스타일 및 가독성
- 잠재적 버그 및 엣지 케이스
- 보안 취약점
- 성능 최적화 기회
- 테스트 커버리지

사용법

> /review src/components/Login.tsx src/utils/auth.ts

$ARGUMENTS: 명령어 뒤에 입력한 내용이 자동으로 대체됩니다
allowed-tools: 이 명령어에서만 사용할 도구를 제한할 수 있습니다
사용자 전역 명령어는 ~/.claude/commands/에 추가합니다

파이프라인(Pipeline) 모드

Claude Code를 스크립트나 파이프라인에서 사용할 수 있습니다:

# 파이프를 통한 입력
echo "이 파일의 버그를 찾아줘" | claude

# 파일 내용 전달
cat error.log | claude "이 에러 로그를 분석해줘"

# 비대화형 모드
claude -p "package.json의 의존성을 나열해줘"

-p (print) 모드

비대화형으로 실행하고 결과만 출력합니다:

# 결과를 파일로 저장
claude -p "이 프로젝트의 README를 생성해줘" > README.md

# 다른 명령어와 조합
claude -p "이 프로젝트에서 사용하지 않는 의존성을 나열해줘" | xargs npm uninstall

실전 활용 예제

CI/CD 파이프라인에서 사용

--bare 플래그로 자동 탐색을 건너뛰고, --output-format json으로 기계 판독 가능한 출력을 받습니다:

# GitHub Actions에서 코드 리뷰 자동화
claude -p --bare --output-format json \
  "이 diff의 잠재적 버그를 JSON으로 보고해줘"

# CI에서 테스트 실패 분석
cat test-results.log | claude -p --bare \
  "실패한 테스트의 원인을 분석하고 수정 방안을 제시해줘"

비용 제한 설정

예산을 초과하지 않도록 세션 비용을 제한합니다:

# 최대 5달러까지만 사용
claude --max-budget-usd 5 "이 프로젝트를 리팩토링해줘"

# 턴 수도 함께 제한
claude -p --max-budget-usd 2 --max-turns 5 "코드 분석"

구조화된 출력 (JSON Schema)

--json-schema 플래그로 정해진 형식의 출력을 받을 수 있습니다:

echo "분석할 코드" | claude -p \
  --json-schema '{"type":"object","properties":{"bugs":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"severity":{"type":"string"},"description":{"type":"string"}}}}}}' \
  "이 코드의 버그를 찾아줘"

출력 예시:

{
  "bugs": [
    {
      "file": "src/utils.ts",
      "line": 42,
      "severity": "high",
      "description": "null 체크 누락으로 런타임 에러 발생 가능"
    }
  ]
}

세션 이어하기

# 마지막 세션 이어서 진행
claude -c

# 특정 세션 ID로 복원
claude -r abc123-def456

# 세션을 포크하여 다른 방향으로 시도
claude --fork-session abc123-def456

추가 디렉토리 참조

모노레포에서 여러 패키지를 참조해야 할 때:

# 공유 라이브러리를 함께 참조
claude --add-dir ../shared-lib --add-dir ../common-types \
  "shared-lib의 타입을 사용해서 새 API를 만들어줘"

워크트리 격리 실행

Git Worktrees를 사용하면 실험적인 변경을 원본 브랜치와 완전히 격리된 환경에서 실행할 수 있습니다:

# 별도의 git worktree에서 작업 (원본 브랜치 영향 없음)
claude -w "전체 코드를 TypeScript로 마이그레이션해줘"

# 또는 --worktree 플래그 사용
claude --worktree "새 인증 시스템 구현해줘"

.worktreeinclude 파일로 포함할 파일 패턴 지정:

프로젝트 루트에 .worktreeinclude 파일을 만들어 워크트리에 포함할 파일 패턴을 지정합니다:

# .worktreeinclude
src/**
tests/**
package.json
tsconfig.json

이 파일에 지정되지 않은 파일은 워크트리에 복사되지 않아 작업 범위가 제한됩니다.

워크트리 관련 훅:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npm install"
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '워크트리 정리 완료'"
          }
        ]
      }
    ]
  }
}

시스템 프롬프트 활용

시스템 프롬프트 관련 플래그 4가지의 차이점:

플래그	동작	사용 시나리오
`--system-prompt`	기본 시스템 프롬프트를 완전 교체	특정 역할이나 규칙을 완전히 재정의할 때
`--append-system-prompt`	기존 시스템 프롬프트에 추가	기본 동작을 유지하면서 추가 지침만 넣을 때
`--system-prompt-file`	파일에서 시스템 프롬프트 로드 후 교체	긴 프롬프트를 파일로 관리할 때

# 한국어 답변 강제 (기본 프롬프트 교체)
claude -p --system-prompt "항상 한국어로 답변하세요" "Explain this code"

# 기존 프롬프트에 추가 지시
claude -p --append-system-prompt "코드 예제를 반드시 포함하세요" "React 상태 관리 설명"

# 파일에서 시스템 프롬프트 로드
claude -p --system-prompt-file ./system-prompt.txt "분석해줘"

GitHub Actions CI/CD 통합 전체 예시

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash

      - name: Code Review
        run: |
          claude -p \
            --bare \
            --output-format json \
            --permission-mode dontAsk \
            --max-turns 10 \
            "이 PR의 변경사항을 리뷰해줘. git diff origin/main...HEAD 를 확인해." \
            > review.json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Post Comment
        uses: actions/github-script@v7
        with:
          script: |
            const review = JSON.parse(require('fs').readFileSync('review.json', 'utf8'));
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🤖 Claude Code Review\n\n${review.result}`
            });

비대화형 모드 종료 코드

종료 코드	의미
`0`	성공
`1`	일반 오류
`2`	비용 한도 초과 (`--max-budget-usd`)
`3`	최대 턴 수 초과 (`--max-turns`)
`4`	인증 오류

# 종료 코드로 성공/실패 판단
claude -p "테스트 실행" && echo "성공" || echo "실패: $?"

환경 변수

변수	설명	기본값
`ANTHROPIC_API_KEY`	API 인증 키	없음
`CLAUDE_MODEL`	사용할 모델	`claude-sonnet-4-6`
`CLAUDE_MAX_TOKENS`	최대 출력 토큰	모델 기본값
`DISABLE_AUTOUPDATER`	자동 업데이트 비활성화	`0` (활성)
`CLAUDE_CODE_DISABLE_CRON`	크론/스케줄 기능 비활성화	`0` (활성)
`MAX_MCP_OUTPUT_TOKENS`	MCP 도구 출력 토큰 제한	기본값
`ENABLE_CLAUDEAI_MCP_SERVERS`	claude.ai MCP 서버 사용 여부	`true`
`HTTPS_PROXY`	HTTPS 프록시 서버	없음
`HTTP_PROXY`	HTTP 프록시 서버	없음
`USE_BUILTIN_RIPGREP`	내장 ripgrep 사용 여부	`1` (사용)
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Claude 응답 최대 토큰	모델 기본값
`CLAUDE_CODE_TASK_LIST_ID`	여러 세션 간 태스크 목록 공유	없음
`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`	세션 시작 시 프롬프트 제안 표시 여부	`true` (`false`로 비활성화)

환경 변수 설정 방법

자주 사용하는 환경 변수는 셸 설정 파일에 추가하면 편리합니다:

# ~/.zshrc 또는 ~/.bashrc에 추가
export ANTHROPIC_API_KEY="sk-ant-..."
export CLAUDE_MODEL="claude-sonnet-4-6"

인터랙티브 기능

프롬프트 제안 (Prompt Suggestions)

세션 시작 시 이전 대화 내용을 바탕으로 이어서 사용할 수 있는 프롬프트를 제안합니다.

Tab 또는 → 화살표로 제안 수락
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false로 비활성화 가능

PR 리뷰 상태 표시

gh CLI가 설치되어 있으면 현재 작업 중인 브랜치의 PR 리뷰 상태를 터미널 하단에 색상으로 표시합니다:

색상	상태
초록	승인됨 (approved)
노랑	검토 대기 (pending)
빨강	변경 요청 (changes requested)
회색	초안 (draft)
보라	병합됨 (merged)

60초마다 자동 새로고침됩니다.

세션 자동 요약

마지막 대화 후 3분 이상 터미널이 포커스를 잃으면 세션 요약이 자동 생성됩니다. /recap 명령으로 언제든지 수동으로 생성할 수도 있습니다.

백그라운드 Bash 출력 제한

백그라운드로 실행된 bash 명령의 출력이 5GB를 초과하면 자동 종료되며, stderr에 알림이 표시됩니다.

트러블슈팅

증상	해결 방법
`claude -p` 출력이 잘림	`CLAUDE_MAX_TOKENS` 또는 `--max-tokens`를 늘려보세요
JSON 출력이 파싱 안됨	`--output-format json`과 `-p`를 함께 사용하세요
세션 복원 실패	`claude -r` 대신 `claude -c`로 마지막 세션 시도
`--bare` 모드에서 컨텍스트 부족	CLAUDE.md 내용을 `--system-prompt`로 직접 전달
비용 제한 초과 경고	`--max-budget-usd`를 늘리거나 `--effort low`로 비용 절감

연계 기능

CLI를 더욱 효과적으로 활용하는 연계 기능들

🔄

기본 워크플로우

CLI 명령어가 실제 개발 워크플로우에 어떻게 통합되는지 확인하세요. 프로젝트 탐색부터 PR 생성까지의 흐름을 이해할 수 있습니다.

⚡

고급 기능

CLI의 --remote, --worktree 플래그와 연계하여 클라우드 세션, 에이전트 팀, 후크 등 고급 기능을 활용할 수 있습니다.

⚙️

설정 (Settings)

/config 및 환경 변수로 조정한 설정이 CLI 플래그와 상호 작용하는 방식을 이해하고, 일관된 환경을 구성할 수 있습니다.

장점, 단점과 한계점

장점

풍부한 플래그 옵션: --model, --effort, --max-budget-usd 등 세밀한 제어가 가능하여 상황에 맞게 동작을 조정할 수 있습니다.
파이프라인 연동: echo, cat 등과 파이프로 연결하여 기존 셸 워크플로우에 자연스럽게 통합됩니다.
CI/CD 자동화: -p(print) 모드와 --bare 플래그를 조합하면 GitHub Actions 등 자동화 파이프라인에서 비대화형으로 활용할 수 있습니다.
다양한 출력 형식: text, json, stream-json 출력 형식과 --json-schema를 지원하여 구조화된 데이터를 받을 수 있습니다.

단점과 한계점

플래그 조합 복잡: 플래그 수가 많아 처음 사용자가 어떤 플래그를 조합해야 하는지 파악하기 어렵습니다.
일부 플래그 상호 배타적: 특정 플래그들은 함께 사용할 수 없지만, 에러 메시지만으로는 원인을 바로 파악하기 어려운 경우가 있습니다.
환경변수와 플래그 우선순위 혼동: CLAUDE_MODEL 환경변수와 --model 플래그가 동시에 설정되면 어느 쪽이 우선인지 혼란이 생길 수 있습니다.
버전별 플래그 차이: 빠른 업데이트 주기로 인해 버전에 따라 지원 플래그가 달라질 수 있으며, 이전 버전 문서와 현재 동작이 다를 수 있습니다.

활용 팁

claude --help로 현재 설치된 버전의 전체 플래그 목록을 확인하세요. CI/CD에서는 claude -p --bare --output-format json 조합을 기본 템플릿으로 사용하면 대부분의 자동화 시나리오에 대응할 수 있습니다.

다음 단계

고급 기능 - MCP 서버, 후크 활용
기본 워크플로우 - 일상적인 개발 작업
스킬 - 커스텀 슬래시 명령어 만들기
기능 비교 - 모든 원격/자동화 기능 한눈에 비교

슬래시 명령어 완전 가이드

Claude Code 세션 내에서 사용할 수 있는 슬래시 명령어입니다.

/ask (대화형 권한 확인)

각 작업마다 사용자에게 확인을 요청합니다.

/ask

언제 사용하나요?

처음 Claude Code를 사용할 때 (기본값)
불명확한 상황에서 안전한 실행을 원할 때
파일 수정이 많거나 중요한 명령을 실행하기 전

/auto (자동 실행 모드)

Claude가 필요한 작업을 자동으로 실행합니다. 확인 없이 진행합니다.

/auto

주의: 이 모드는 전환 후 모든 작업이 자동 승인되므로, 신뢰할 수 있는 코드에서만 사용하세요.

/config (설정 변경)

Claude Code 설정을 대화형으로 변경합니다.

/config

설정 항목:

모델 (claude-opus, claude-sonnet 등)
노력도 (빠름/균형/철저함)
권한 모드 (ask/auto)
예산 제한 설정

/mcp (MCP 서버 관리)

외부 도구와 서비스를 연결합니다.

/mcp

할 수 있는 것:

GitHub, Sentry, PostgreSQL 등 MCP 서버 추가
연결된 서버 목록 확인
OAuth 인증 설정/초기화
기존 서버 제거

/cost (토큰 비용 확인)

현재 세션의 예상 비용을 확인합니다.

/cost

표시 내용:

지금까지 사용한 입력/출력 토큰
예상 비용 (USD 기준)
남은 예산 (설정한 경우)

/doctor (환경 진단)

시스템 설정과 환경이 올바른지 확인합니다.

/doctor

검사 항목:

Node.js 버전 확인
Git 설정 확인
필수 도구 설치 여부
권한 설정 확인
MCP 서버 연결 상태

/help (도움말)

사용 가능한 명령어와 플래그를 표시합니다.

/help

공식 문서 링크 검증

최종 업데이트: 2026-04-18

이 문서의 공식 Anthropic 문서 링크는:

공식 CLI 레퍼런스: code.claude.com/docs/reference/cli
최신 변경사항: GitHub 릴리즈
이슈 보고: GitHub Issues

링크 정확성 확인:

✅ 이 가이드는 Claude Code v1.0+ 기준
✅ 모든 명령어 및 플래그는 최신 버전 확인 완료
⚠️ 주기적으로 공식 문서와 비교하여 업데이트하고 있습니다

CLI 명령어 카테고리 맵​

기본 명령어​

claude​

최상위 하위 명령어​

claude agents​

claude attach​

claude logs​

claude respawn​

claude rm​

claude stop​

claude auto-mode​

claude plugin​

claude remote-control​

claude auth​

claude install​

claude setup-token​

claude ultrareview​

claude update​

주요 플래그​

실행 모드​

모델 및 품질​

출력 형식​

비용 및 제한​

세션 및 컨텍스트​

원격 및 고급​

디버그 및 진단​

세션 관리 (신규)​

MCP 설정​

IDE 및 통합​

자동화 (신규)​

권한 및 보안​

설정 파일​

기타​

슬래시 명령어​

일반 명령어​

설정 명령어​

도구/확장 명령어​

내장 스킬 명령어​

기타 명령어​

키보드 단축키​

일반 제어​

텍스트 편집​

여러 줄 입력​

확장 기능​

트랜스크립트 뷰어 단축키​

세션 선택기 단축키​

Vim 편집기 모드​

모드 전환​

탐색 (NORMAL 모드)​

셸 명령 즉시 실행 (! 접두사)​

커스텀 슬래시 명령어 만들기​

파일 구조​

커스텀 명령어 예시 (review.md)​

사용법​

파이프라인(Pipeline) 모드​

-p (print) 모드​

실전 활용 예제​

CI/CD 파이프라인에서 사용​

비용 제한 설정​

구조화된 출력 (JSON Schema)​

세션 이어하기​

추가 디렉토리 참조​

워크트리 격리 실행​

시스템 프롬프트 활용​

GitHub Actions CI/CD 통합 전체 예시​

비대화형 모드 종료 코드​

환경 변수​

인터랙티브 기능​

프롬프트 제안 (Prompt Suggestions)​

PR 리뷰 상태 표시​

세션 자동 요약​

백그라운드 Bash 출력 제한​

트러블슈팅​

연계 기능​

장점, 단점과 한계점​

장점​

단점과 한계점​

다음 단계​

슬래시 명령어 완전 가이드​

/ask (대화형 권한 확인)​