CLI 참조
Claude Code 명령줄 인터페이스의 완전한 참조로, 명령어와 플래그를 포함합니다.
CLI 명령어
이러한 명령어를 사용하여 세션을 시작하고, 콘텐츠를 파이프하고, 대화를 재개하고, 업데이트를 관리할 수 있습니다:
| 명령어 | 설명 | 예시 |
|---|---|---|
claude |
대화형 세션 시작 | claude |
claude "query" |
초기 프롬프트로 대화형 세션 시작 | claude "explain this project" |
claude -p "query" |
SDK를 통해 쿼리하고 종료 | claude -p "explain this function" |
cat file | claude -p "query" |
파이프된 콘텐츠 처리 | cat logs.txt | claude -p "explain" |
claude -c |
현재 디렉토리에서 가장 최근 대화 계속 | claude -c |
claude -c -p "query" |
SDK를 통해 계속 | claude -c -p "Check for type errors" |
claude -r "<session>" "query" |
ID 또는 이름으로 세션 재개 | claude -r "auth-refactor" "Finish this PR" |
claude update |
최신 버전으로 업데이트 | claude update |
claude install [version] |
네이티브 바이너리를 설치하거나 재설치합니다. 2.1.118과 같은 버전, 또는 stable 또는 latest를 허용합니다. 특정 버전 설치 참조 |
claude install stable |
claude auth login |
Anthropic 계정에 로그인합니다. --email을 사용하여 이메일 주소를 미리 입력하고, --sso를 사용하여 SSO 인증을 강제하고, --console을 사용하여 Claude 구독 대신 API 사용 청구를 위해 Anthropic Console로 로그인할 수 있습니다 |
claude auth login --console |
claude auth logout |
Anthropic 계정에서 로그아웃합니다 | claude auth logout |
claude auth status |
인증 상태를 JSON으로 표시합니다. 사람이 읽을 수 있는 출력을 위해 --text를 사용합니다. 로그인된 경우 코드 0으로 종료되고, 로그인되지 않은 경우 1로 종료됩니다 |
claude auth status |
claude agents |
에이전트 보기를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. 출력이 파이프될 때는 구성된 subagents를 대신 나열합니다 | claude agents |
claude attach <id> |
이 터미널에서 백그라운드 세션에 연결합니다 | claude attach 7c5dcf5d |
claude auto-mode defaults |
기본 제공 자동 모드 분류기 규칙을 JSON으로 인쇄합니다. claude auto-mode config를 사용하여 설정이 적용된 유효한 구성을 확인합니다 |
claude auto-mode defaults > rules.json |
claude logs <id> |
백그라운드 세션의 최근 출력을 인쇄합니다 | claude logs 7c5dcf5d |
claude mcp |
Model Context Protocol (MCP) 서버 구성 | Claude Code MCP 문서 참조 |
claude plugin |
Claude Code plugins를 관리합니다. 별칭: claude plugins. 하위 명령어는 plugin 참조를 참조하세요 |
claude plugin install code-review@claude-plugins-official |
claude project purge [path] |
프로젝트의 모든 로컬 Claude Code 상태를 삭제합니다: 대화 기록, 작업 목록, 디버그 로그, 파일 편집 기록, 프롬프트 기록 라인 및 ~/.claude.json의 프로젝트 항목. [path]를 생략하면 대화형 목록에서 선택할 수 있습니다. 플래그: --dry-run으로 미리 보기, -y/--yes로 확인 건너뛰기, -i/--interactive로 각 항목 확인, --all로 모든 프로젝트. 로컬 데이터 지우기 참조 |
claude project purge ~/work/repo --dry-run |
claude remote-control |
Claude.ai 또는 Claude 앱에서 Claude Code를 제어하기 위한 Remote Control 서버를 시작합니다. 서버 모드에서 실행됩니다(로컬 대화형 세션 없음). 서버 모드 플래그 참조 | claude remote-control --name "My Project" |
claude respawn <id> |
대화를 유지하면서 중지된 백그라운드 세션을 다시 시작합니다. --all을 사용하여 중지된 모든 세션을 다시 시작합니다 |
claude respawn 7c5dcf5d |
claude rm <id> |
백그라운드 세션을 목록에서 제거합니다 | claude rm 7c5dcf5d |
claude setup-token |
CI 및 스크립트를 위한 장기 OAuth 토큰을 생성합니다. 토큰을 저장하지 않고 터미널에 인쇄합니다. Claude 구독이 필요합니다. 장기 토큰 생성 참조 | claude setup-token |
claude stop <id> |
백그라운드 세션을 중지합니다. claude kill도 허용됩니다 |
claude stop 7c5dcf5d |
claude ultrareview [target] |
ultrareview를 비대화형으로 실행합니다. 결과를 stdout으로 인쇄하고 성공 시 0으로 종료되거나 실패 시 1로 종료됩니다. 원본 페이로드는 --json을 사용하고 30분 기본값을 재정의하려면 --timeout <minutes>를 사용합니다 |
claude ultrareview 1234 --json |
하위 명령어를 잘못 입력하면 Claude Code는 가장 가까운 일치를 제안하고 세션을 시작하지 않고 종료합니다. 예를 들어, claude udpate는 Did you mean claude update?를 인쇄합니다.
CLI 플래그
이러한 명령줄 플래그를 사용하여 Claude Code의 동작을 사용자 정의합니다. claude --help는 모든 플래그를 나열하지 않으므로, --help에 플래그가 없다고 해서 사용할 수 없다는 의미는 아닙니다.
| 플래그 | 설명 | 예시 |
|---|---|---|
--add-dir |
Claude가 파일을 읽고 편집할 수 있는 추가 작업 디렉토리를 추가합니다. 파일 액세스를 부여합니다. 대부분의 .claude/ 구성은 이러한 디렉토리에서 검색되지 않습니다. 각 경로가 디렉토리로 존재하는지 검증합니다. 이러한 디렉토리를 세션 간에 유지하려면 설정에서 permissions.additionalDirectories를 설정합니다 |
claude --add-dir ../apps ../lib |
--agent |
현재 세션에 대한 에이전트를 지정합니다(agent 설정 재정의) |
claude --agent my-custom-agent |
--agents |
JSON을 통해 사용자 정의 subagents를 동적으로 정의합니다. subagent frontmatter와 동일한 필드 이름과 에이전트의 지시사항에 대한 prompt 필드를 사용합니다 |
claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}' |
--allow-dangerously-skip-permissions |
Shift+Tab 모드 사이클에 bypassPermissions를 추가합니다. 이를 통해 plan과 같은 다른 모드에서 시작하고 나중에 bypassPermissions로 전환할 수 있습니다. 권한 모드 참조 |
claude --permission-mode plan --allow-dangerously-skip-permissions |
--allowedTools |
권한 프롬프트 없이 실행되는 도구입니다. 패턴 매칭에 대해 권한 규칙 구문을 참조하세요. 사용 가능한 도구를 제한하려면 --tools를 대신 사용하세요 |
"Bash(git log *)" "Bash(git diff *)" "Read" |
--append-system-prompt |
기본 시스템 프롬프트의 끝에 사용자 정의 텍스트를 추가합니다 | claude --append-system-prompt "Always use TypeScript" |
--append-system-prompt-file |
파일에서 추가 시스템 프롬프트 텍스트를 로드하고 기본 프롬프트에 추가합니다 | claude --append-system-prompt-file ./extra-rules.txt |
--bare |
최소 모드: hooks, skills, plugins, MCP 서버, 자동 메모리 및 CLAUDE.md의 자동 검색을 건너뜁니다. 스크립트된 호출이 더 빠르게 시작됩니다. Claude는 Bash, 파일 읽기 및 파일 편집 도구에 액세스할 수 있습니다. CLAUDE_CODE_SIMPLE을 설정합니다. bare 모드 참조 |
claude --bare -p "query" |
--betas |
API 요청에 포함할 베타 헤더(API 키 사용자만 해당) | claude --betas interleaved-thinking |
--bg |
세션을 백그라운드 에이전트로 시작하고 즉시 반환합니다. 세션 ID와 관리 명령어를 인쇄합니다. --agent와 결합하여 특정 subagent를 실행합니다 |
claude --bg "investigate the flaky test" |
--channels |
(연구 미리보기) Claude가 이 세션에서 수신해야 할 채널 알림이 있는 MCP 서버입니다. plugin:<name>@<marketplace> 항목의 공백으로 구분된 목록입니다. Claude.ai 인증이 필요합니다 |
claude --channels plugin:my-notifier@my-marketplace |
--chrome |
웹 자동화 및 테스트를 위해 Chrome 브라우저 통합을 활성화합니다 | claude --chrome |
--continue, -c |
현재 디렉토리에서 가장 최근 대화를 로드합니다. /add-dir으로 이 디렉토리를 추가한 세션을 포함합니다 |
claude --continue |
--dangerously-load-development-channels |
로컬 개발을 위해 승인된 허용 목록에 없는 채널을 활성화합니다. plugin:<name>@<marketplace> 및 server:<name> 항목을 허용합니다. 확인을 요청합니다 |
claude --dangerously-load-development-channels server:webhook |
--dangerously-skip-permissions |
권한 프롬프트를 건너뜁니다. --permission-mode bypassPermissions와 동일합니다. 이것이 건너뛰는 것과 건너뛰지 않는 것에 대해 권한 모드를 참조하세요 |
claude --dangerously-skip-permissions |
--debug |
선택적 카테고리 필터링을 사용하여 디버그 모드를 활성화합니다(예: "api,hooks" 또는 "!statsig,!file") |
claude --debug "api,mcp" |
--debug-file <path> |
디버그 로그를 특정 파일 경로에 씁니다. 암묵적으로 디버그 모드를 활성화합니다. CLAUDE_CODE_DEBUG_LOGS_DIR보다 우선합니다 |
claude --debug-file /tmp/claude-debug.log |
--disable-slash-commands |
이 세션에 대해 모든 skills 및 명령어를 비활성화합니다 | claude --disable-slash-commands |
--disallowedTools |
모델의 컨텍스트에서 제거되고 사용할 수 없는 도구 | "Bash(git log *)" "Bash(git diff *)" "Edit" |
--effort |
현재 세션에 대한 노력 수준을 설정합니다. 옵션: low, medium, high, xhigh, max; 사용 가능한 수준은 모델에 따라 다릅니다. effortLevel 설정을 이 세션에 대해 재정의하며 지속되지 않습니다 |
claude --effort high |
--enable-auto-mode |
{/* max-version: 2.1.110 */}v2.1.111에서 제거됨. 자동 모드는 이제 Shift+Tab 사이클에 기본적으로 포함됩니다. --permission-mode auto를 사용하여 시작합니다 |
claude --permission-mode auto |
--exclude-dynamic-system-prompt-sections |
시스템 프롬프트의 머신별 섹션(작업 디렉토리, 환경 정보, 메모리 경로, git 상태)을 첫 번째 사용자 메시지로 이동합니다. 동일한 작업을 실행하는 다양한 사용자 및 머신 간에 프롬프트 캐시 재사용을 개선합니다. 기본 시스템 프롬프트에만 적용됩니다. --system-prompt 또는 --system-prompt-file이 설정되면 무시됩니다. 스크립트된 다중 사용자 워크로드의 경우 -p와 함께 사용합니다 |
claude -p --exclude-dynamic-system-prompt-sections "query" |
--fallback-model |
기본 모델이 과부하 상태일 때 지정된 모델로 자동 폴백을 활성화합니다(인쇄 모드만 해당) | claude -p --fallback-model sonnet "query" |
--fork-session |
재개할 때 원본을 재사용하는 대신 새 세션 ID를 생성합니다(--resume 또는 --continue와 함께 사용) |
claude --resume abc123 --fork-session |
--from-pr |
특정 pull request에 연결된 세션을 재개합니다. PR 번호, GitHub 또는 GitHub Enterprise PR URL, GitLab merge request URL 또는 Bitbucket pull request URL을 허용합니다. Claude가 pull request를 생성할 때 세션이 자동으로 연결됩니다 | claude --from-pr 123 |
--ide |
정확히 하나의 유효한 IDE를 사용할 수 있는 경우 시작 시 IDE에 자동으로 연결합니다 | claude --ide |
--init |
Setup hooks를 init 매처로 실행한 후 세션을 시작합니다(인쇄 모드만 해당) |
claude -p --init "query" |
--init-only |
Setup 및 SessionStart hooks를 실행한 후 대화를 시작하지 않고 종료합니다 |
claude --init-only |
--include-hook-events |
모든 hook 라이프사이클 이벤트를 출력 스트림에 포함합니다. --output-format stream-json이 필요합니다 |
claude -p --output-format stream-json --include-hook-events "query" |
--include-partial-messages |
부분 스트리밍 이벤트를 출력에 포함합니다. --print와 --output-format stream-json이 필요합니다 |
claude -p --output-format stream-json --include-partial-messages "query" |
--input-format |
인쇄 모드에 대한 입력 형식을 지정합니다(옵션: text, stream-json) |
claude -p --output-format json --input-format stream-json |
--json-schema |
에이전트가 워크플로우를 완료한 후 JSON Schema와 일치하는 검증된 JSON 출력을 가져옵니다(인쇄 모드만 해당, 구조화된 출력 참조) | claude -p --json-schema '{"type":"object","properties":{...}}' "query" |
--maintenance |
Setup hooks를 maintenance 매처로 실행한 후 세션을 시작합니다(인쇄 모드만 해당) |
claude -p --maintenance "query" |
--max-budget-usd |
중지하기 전에 API 호출에 소비할 최대 달러 금액(인쇄 모드만 해당) | claude -p --max-budget-usd 5.00 "query" |
--max-turns |
에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 제한에 도달하면 오류로 종료됩니다. 기본적으로 제한 없음 | claude -p --max-turns 3 "query" |
--mcp-config |
JSON 파일 또는 문자열에서 MCP 서버를 로드합니다(공백으로 구분) | claude --mcp-config ./mcp.json |
--model |
최신 모델의 별칭(sonnet 또는 opus) 또는 모델의 전체 이름으로 현재 세션에 대한 모델을 설정합니다. model 설정 및 ANTHROPIC_MODEL을 재정의합니다 |
claude --model claude-sonnet-4-6 |
--name, -n |
세션의 표시 이름을 설정합니다. /resume과 터미널 제목에 표시됩니다. claude --resume <name>으로 명명된 세션을 재개할 수 있습니다. /rename은 세션 중에 이름을 변경하고 프롬프트 표시줄에도 표시합니다 |
claude -n "my-feature-work" |
--no-chrome |
이 세션에 대해 Chrome 브라우저 통합을 비활성화합니다 | claude --no-chrome |
--no-session-persistence |
세션 지속성을 비활성화하여 세션이 디스크에 저장되지 않고 재개할 수 없습니다(인쇄 모드만 해당). CLAUDE_CODE_SKIP_PROMPT_HISTORY 환경 변수는 모든 모드에서 동일한 작업을 수행합니다 |
claude -p --no-session-persistence "query" |
--output-format |
인쇄 모드에 대한 출력 형식을 지정합니다(옵션: text, json, stream-json) |
claude -p "query" --output-format json |
--permission-mode |
지정된 권한 모드에서 시작합니다. default, acceptEdits, plan, auto, dontAsk 또는 bypassPermissions를 허용합니다. 설정 파일의 defaultMode를 재정의합니다 |
claude --permission-mode plan |
--permission-prompt-tool |
비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다 | claude -p --permission-prompt-tool mcp_auth_tool "query" |
--plugin-dir |
이 세션에만 디렉토리 또는 .zip 아카이브에서 plugin을 로드합니다. 각 플래그는 하나의 경로를 사용합니다. 여러 plugins의 경우 플래그를 반복합니다: --plugin-dir A --plugin-dir B.zip |
claude --plugin-dir ./my-plugin |
--plugin-url |
이 세션에만 URL에서 plugin .zip 아카이브를 가져옵니다. 여러 plugins의 경우 플래그를 반복하거나 단일 따옴표 값에 공백으로 구분된 URL을 전달합니다 |
claude --plugin-url https://example.com/plugin.zip |
--print, -p |
대화형 모드 없이 응답을 인쇄합니다(Agent SDK 문서에서 프로그래밍 방식 사용 세부 정보 참조) | claude -p "query" |
--remote |
제공된 작업 설명으로 claude.ai에서 새 웹 세션을 생성합니다 | claude --remote "Fix the login bug" |
--remote-control, --rc |
claude.ai 또는 Claude 앱에서도 제어할 수 있도록 Remote Control이 활성화된 대화형 세션을 시작합니다. 선택적으로 세션의 이름을 전달할 수 있습니다 | claude --remote-control "My Project" |
--remote-control-session-name-prefix <prefix> |
명시적 이름이 설정되지 않은 경우 자동 생성된 Remote Control 세션 이름의 접두사입니다. 기본값은 머신의 호스트명이며, myhost-graceful-unicorn과 같은 이름을 생성합니다. 동일한 효과를 위해 CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX를 설정합니다 |
claude remote-control --remote-control-session-name-prefix dev-box |
--replay-user-messages |
stdin에서 사용자 메시지를 다시 내보내 stdout으로 승인합니다. --input-format stream-json과 --output-format stream-json이 필요합니다 |
claude -p --input-format stream-json --output-format stream-json --replay-user-messages |
--resume, -r |
ID 또는 이름으로 특정 세션을 재개하거나 세션을 선택할 수 있는 대화형 선택기를 표시합니다. /add-dir으로 이 디렉토리를 추가한 세션을 포함합니다 |
claude --resume auth-refactor |
--session-id |
대화에 특정 세션 ID를 사용합니다(유효한 UUID여야 함) | claude --session-id "550e8400-e29b-41d4-a716-446655440000" |
--setting-sources |
로드할 설정 소스의 쉼표로 구분된 목록(user, project, local) |
claude --setting-sources user,project |
--settings |
설정 JSON 파일 또는 인라인 JSON 문자열의 경로입니다. 여기서 설정한 값은 이 세션에 대해 settings.json 파일의 동일한 키를 재정의합니다. 생략한 키는 파일 기반 값을 유지합니다. 설정 우선순위 참조 |
claude --settings ./settings.json |
--strict-mcp-config |
--mcp-config의 MCP 서버만 사용하고 다른 모든 MCP 구성을 무시합니다 |
claude --strict-mcp-config --mcp-config ./mcp.json |
--system-prompt |
전체 시스템 프롬프트를 사용자 정의 텍스트로 바꿉니다 | claude --system-prompt "You are a Python expert" |
--system-prompt-file |
파일에서 시스템 프롬프트를 로드하여 기본 프롬프트를 바꿉니다 | claude --system-prompt-file ./custom-prompt.txt |
--teleport |
로컬 터미널에서 웹 세션을 재개합니다 | claude --teleport |
--teammate-mode |
에이전트 팀 팀원 표시 방식을 설정합니다: auto(기본값), in-process 또는 tmux. teammateMode 설정을 이 세션에 대해 재정의합니다. 디스플레이 모드 선택 참조 |
claude --teammate-mode in-process |
--tmux |
worktree에 대한 tmux 세션을 생성합니다. --worktree가 필요합니다. 사용 가능한 경우 iTerm2 네이티브 창을 사용합니다. 기존 tmux의 경우 --tmux=classic을 전달합니다 |
claude -w feature-auth --tmux |
--tools |
Claude가 사용할 수 있는 기본 제공 도구를 제한합니다. 모두 비활성화하려면 ""를 사용하고, 모두 사용하려면 "default"를 사용하거나, "Bash,Edit,Read"와 같은 도구 이름을 사용합니다 |
claude --tools "Bash,Edit,Read" |
--verbose |
자세한 로깅을 활성화하고 전체 턴별 출력을 표시합니다. viewMode 설정을 이 세션에 대해 재정의합니다 |
claude --verbose |
--version, -v |
버전 번호를 출력합니다 | claude -v |
--worktree, -w |
Claude를 <repo>/.claude/worktrees/<name>의 격리된 git worktree에서 시작합니다. 이름이 지정되지 않으면 자동으로 생성됩니다. #<number> 또는 GitHub pull request URL을 전달하여 origin에서 해당 PR을 가져오고 worktree를 분기합니다 |
claude -w feature-auth |
시스템 프롬프트 플래그
Claude Code는 시스템 프롬프트를 사용자 정의하기 위한 4가지 플래그를 제공합니다. 4가지 모두 대화형 및 비대화형 모드에서 작동합니다.
| 플래그 | 동작 | 예시 |
|---|---|---|
--system-prompt |
전체 기본 프롬프트를 바꿉니다 | claude --system-prompt "You are a Python expert" |
--system-prompt-file |
파일 내용으로 바꿉니다 | claude --system-prompt-file ./prompts/review.txt |
--append-system-prompt |
기본 프롬프트에 추가합니다 | claude --append-system-prompt "Always use TypeScript" |
--append-system-prompt-file |
파일 내용을 기본 프롬프트에 추가합니다 | claude --append-system-prompt-file ./style-rules.txt |
--system-prompt와 --system-prompt-file은 상호 배타적입니다. 추가 플래그는 바꾸기 플래그 중 하나와 결합할 수 있습니다.
대부분의 사용 사례에서는 추가 플래그를 사용합니다. 추가하면 Claude Code의 기본 제공 기능을 유지하면서 요구 사항을 추가합니다. 시스템 프롬프트를 완전히 제어해야 할 때만 바꾸기 플래그를 사용합니다.
참고 항목
- Chrome 확장 프로그램 - 브라우저 자동화 및 웹 테스트
- 대화형 모드 - 바로 가기, 입력 모드 및 대화형 기능
- 빠른 시작 가이드 - Claude Code 시작하기
- 일반적인 워크플로우 - 고급 워크플로우 및 패턴
- 설정 - 구성 옵션
- Agent SDK 문서 - 프로그래밍 방식 사용 및 통합