SpyBara
Go Premium

cli-reference.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 52 additions and 42 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

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 gateway 자체 호스팅 Claude 앱 게이트웨이 서버를 시작합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry의 Claude Code 앞에 SSO 및 정책을 배포하는 관리자용입니다. gateway.yaml을 가리키는 --config가 필요합니다. Claude Code v2.1.195 이상에서 사용 가능합니다. claude gateway --config gateway.yaml
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 에이전트 보기를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. --cwd <path>를 사용하여 해당 디렉토리 아래에서 시작된 세션만 표시하거나, --json을 사용하여 스크립팅을 위해 활성 세션을 JSON 배열로 인쇄합니다(--json --all은 완료된 백그라운드 세션도 포함합니다). --permission-mode, --model, --effort 또는 --agent를 전달하여 디스패치된 세션의 기본값을 설정합니다. 최상위 claude 명령어처럼 --settings, --add-dir, --plugin-dir 및 --mcp-config를 허용합니다. 에이전트 보기를 열려면 대화형 터미널이 필요합니다 claude agents --json
claude attach <id> 이 터미널에서 백그라운드 세션에 연결합니다 claude attach 7c5dcf5d
claude auto-mode defaults 기본 제공 자동 모드 분류기 규칙을 JSON으로 인쇄합니다. claude auto-mode config를 사용하여 설정이 적용된 유효한 구성을 확인합니다. --label <prefix>는 해당 접두사로 시작하는 레이블이 있는 규칙만 인쇄합니다(대소문자 구분 안 함). Claude Code v2.1.208 이상이 필요합니다 claude auto-mode defaults --label 'Git Destructive'
claude auto-mode reset 사용자 설정 파일에서 autoMode 섹션을 제거하여 기본 자동 모드 구성을 복원합니다. 작성하기 전에 확인을 요청합니다. -y/--yes를 전달하여 프롬프트를 건너뜁니다. 관리되는 설정 또는 --settings 플래그의 규칙은 여전히 적용됩니다. Claude Code v2.1.212 이상이 필요합니다. 기본값 및 유효한 구성 검사 참조 claude auto-mode reset --yes
claude daemon status 백그라운드 세션 감독자의 상태, 버전, 소켓 디렉토리 및 진단을 위한 워커 수를 인쇄합니다. 감독자가 실행 중이 아니면 1로 종료됩니다 claude daemon status
claude daemon stop --any 백그라운드 세션 감독자와 이를 호스팅하는 세션을 중지합니다. --keep-workers를 전달하여 백그라운드 세션을 실행 중인 상태로 두면 다음 감독자가 이들에 다시 연결됩니다. --any는 기본값인 온디맨드 감독자 중지를 확인합니다. 이를 사용하여 응답하지 않는 감독자에서 복구합니다 claude daemon stop --any --keep-workers
claude doctor 세션을 시작하지 않고 터미널에서 읽기 전용 설치 및 설정 진단을 인쇄합니다. 설치 상태, 설정 파일 검증 오류 및 Remote Control 적격성을 포함합니다. 수정을 적용할 수도 있는 세션 내 설정 점검을 위해 /doctor를 실행합니다 claude doctor
claude import [codex|gemini] 다른 코딩 에이전트의 구성을 Claude Code로 가져오기 위해 /import를 실행하는 대화형 세션을 시작합니다. 명령어와 동일한 --dry-run 및 --yes 옵션을 허용합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 AWS의 Claude Platform에서는 사용할 수 없습니다. 기능 플래그 가져오기를 끄면 사용할 수 없습니다. Claude Code v2.1.213 이상이 필요합니다 claude import codex --dry-run
claude logs <id> 백그라운드 세션의 최근 출력을 인쇄합니다 claude logs 7c5dcf5d
claude mcp Model Context Protocol (MCP) 서버 구성 Claude Code MCP 문서 참조
claude mcp login <name> 구성된 MCP 서버의 OAuth 흐름을 대화형 /mcp 패널을 열지 않고 실행합니다. HTTP, SSE 및 claude.ai 커넥터 서버에서 작동합니다. SSH를 통해 --no-browser를 추가하여 브라우저를 열지 않고 인증 URL을 인쇄한 다음 리다이렉트 URL을 프롬프트에 다시 붙여넣습니다. Claude Code v2.1.186 이상이 필요합니다. 명령줄에서 인증 참조 claude mcp login sentry
claude mcp logout <name> MCP 서버에 대해 저장된 OAuth 자격 증명을 지웁니다. Claude Code v2.1.186 이상이 필요합니다 claude mcp logout sentry
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 Code 바이너리를 선택하기 위해) claude respawn 7c5dcf5d
claude rm <id> 백그라운드 세션을 목록에서 제거합니다. 대화 기록은 로컬 머신에 남아 있으며 claude --resume을 통해 사용할 수 있습니다 claude rm 7c5dcf5d
claude self-hosted-runner 이 머신 또는 컨테이너를 자체 호스팅 환경에 등록하고 인프라에서 Claude Code 클라우드 세션을 호스팅하는 러너 프로세스를 시작합니다. 안내식 운영자 연습을 위해 claude self-hosted-runner setup을 실행하고, 배포된 러너를 진단하기 위해 claude self-hosted-runner doctor를 실행하고, 온디맨드 러너를 생성하기 위해 claude self-hosted-runner orchestrator를 실행합니다. Claude Code v2.1.224 이상이 필요합니다 claude self-hosted-runner setup
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을 사용하고 45분 기본값을 재정의하려면 --timeout <minutes>를 사용합니다. github.com 풀 요청 대상에서 --post를 사용하여 완료된 결과를 GitHub 계정에서 PR에 일반 댓글로 게시합니다. --no-post가 기본값입니다. --post 및 --no-post는 Claude Code v2.1.227 이상이 필요합니다. 풀 요청에 결과 게시 참조 claude ultrareview 1234 --json

하위 명령어를 잘못 입력하면 Claude Code는 가장 가까운 일치를 제안하고 세션을 시작하지 않고 종료합니다. 예를 들어, claude udpate는 Did you mean claude update?를 인쇄합니다.

v2.1.199부터 claude --dangerously-skip-permissions daemon <subcommand>는 daemon 하위 명령어를 실행합니다. 이전 버전에서는 daemon <subcommand>를 새 대화형 세션의 프롬프트로 처리했으므로 플래그가 먼저 올 때 하위 명령어가 실행되지 않았습니다. 이는 claude가 플래그를 포함하도록 별칭이 지정된 경우 일반적인 설정입니다. 선행 --dangerously-skip-permissions 또는 --allow-dangerously-skip-permissions만 이 방식으로 daemon으로 라우팅됩니다. 다른 선행 플래그는 여전히 대화형 세션을 시작합니다.

CLI 플래그

이러한 명령줄 플래그를 사용하여 Claude Code의 동작을 사용자 정의합니다. claude --help는 모든 플래그를 나열하지 않으므로, --help에 플래그가 없다고 해서 사용할 수 없다는 의미는 아닙니다.

플래그 설명 예시
--add-dir Claude가 파일을 읽고 편집할 수 있는 추가 작업 디렉토리를 추가합니다. 파일 액세스를 부여합니다. Claude Code는 이러한 디렉토리에서 대부분의 .claude/ 구성을 검색하지 않습니다. 각 경로가 디렉토리로 존재하는지 검증합니다. 대부분의 네트워크 경로(예: \\server\share)를 추가할 수 없습니다. 이러한 디렉토리를 세션 간에 유지하려면 설정에서 permissions.additionalDirectories를 설정합니다 claude --add-dir ../apps ../lib
--advisor <model> 이 세션에 대해 서버 측 advisor 도구를 활성화합니다. 모델 별칭 fable, opus 또는 sonnet, 또는 전체 모델 ID를 사용합니다. advisorModel 설정보다 우선합니다. fable은 Fable 액세스가 필요합니다 claude --advisor opus
--agent 현재 세션에 대한 에이전트를 지정합니다(agent 설정 재정의) claude --agent my-custom-agent
--agents JSON을 통해 사용자 정의 subagents를 동적으로 정의합니다. CLI 정의 subagents에 대해 나열된 필드를 허용합니다. Claude Code는 시작 시 JSON을 검증하고 잘못된 값에서 종료합니다. Invalid --agents configuration에서 메시지와 검증을 건너뛰는 플래그 및 환경 변수를 참조하세요. 검증에는 Claude Code v2.1.242 이상이 필요합니다 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, --allowed-tools 권한 프롬프트 없이 실행되는 도구입니다. 패턴 매칭에 대해 권한 규칙 구문을 참조하세요. 사용 가능한 도구를 제한하려면 --tools를 대신 사용하세요. 작업 추적 도구 중 하나를 여기에 이름 지으면 Claude Code도 세션을 옵트인합니다 "Bash(git log *)" "Bash(git diff *)" "Read"
--append-subagent-system-prompt 모든 subagent의 시스템 프롬프트 끝에 사용자 정의 텍스트를 추가합니다. 중첩된 subagents를 포함하며, 포크된 subagent는 제외합니다. 포크된 subagent는 대화 자체의 프롬프트를 재사용합니다. -p를 사용한 비대화형 모드에만 적용됩니다. Claude Code v2.1.205 이상이 필요합니다 claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"
--append-subagent-system-prompt-file 파일에서 텍스트를 로드하고 subagent 시스템 프롬프트에 추가합니다. 명령줄에 전달하기에 너무 긴 텍스트의 경우 --append-subagent-system-prompt의 대안입니다. 두 플래그를 결합할 수 없습니다. -p를 사용한 비대화형 모드에만 적용됩니다. Claude Code v2.1.261 이상이 필요합니다 claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"
--append-system-prompt 기본 시스템 프롬프트의 끝에 사용자 정의 텍스트를 추가합니다 claude --append-system-prompt "Always use TypeScript"
--append-system-prompt-file 파일에서 추가 시스템 프롬프트 텍스트를 로드하고 기본 프롬프트에 추가합니다 claude --append-system-prompt-file ./extra-rules.txt
--autocompact <auto|tokens> 이 세션에 대해 저장된 설정을 변경하지 않고 auto-compact 윈도우를 설정합니다. /autocompact와 동일한 값을 허용합니다. 해당 섹션에서 값 형식과 플래그를 재정의하는 것을 다룹니다. Claude Code v2.1.221 이상이 필요합니다 claude --autocompact 500k
--ax-screen-reader 스크린 리더 친화적 출력을 렌더링합니다: 장식용 테두리나 애니메이션 없는 평문입니다. 클래식 렌더러를 강제하므로 tui 설정은 이 세션에 효과가 없습니다. 연결된 백그라운드 세션은 여전히 전체 화면으로 렌더링됩니다. CLAUDE_AX_SCREEN_READER 및 axScreenReader 설정보다 우선합니다. Claude Code v2.1.181 이상이 필요합니다 claude --ax-screen-reader
--bare 최소 모드: hooks, skills, 사용자 정의 명령어, subagents, plugins, MCP 서버, 자동 메모리 및 CLAUDE.md의 자동 검색을 건너뜁니다. 스크립트된 호출이 더 빠르게 시작됩니다. --add-dir로 전달하는 디렉토리의 Skills는 여전히 로드됩니다. Claude는 Bash, 파일 읽기 및 파일 편집 도구에 액세스할 수 있습니다. CLAUDE_CODE_SIMPLE을 설정합니다. bare 모드 참조 claude --bare -p "query"
--betas API 요청에 포함할 베타 헤더(API 키 사용자만 해당) claude --betas interleaved-thinking
--bg, --background 세션을 백그라운드 에이전트로 시작하고 즉시 반환합니다. 세션 ID와 관리 명령어를 인쇄합니다. --exec과 결합하여 Claude 세션 대신 셸 명령어를 백그라운드 작업으로 실행하거나, --agent와 결합하여 특정 subagent를 실행합니다. -p/--print와 결합할 수 없습니다. 오류 참조 참조 claude --bg "investigate the flaky test"
--channels (연구 미리보기) Claude가 이 세션에서 수신해야 할 채널 알림이 있는 MCP 서버입니다. plugin:<name>@<marketplace> 항목의 공백으로 구분된 목록입니다. Claude.ai 또는 Console API 키를 통한 Anthropic 인증이 필요합니다 claude --channels plugin:my-notifier@my-marketplace
--chrome 웹 자동화 및 테스트를 위해 Chrome 브라우저 통합을 활성화합니다 claude --chrome
--cloud 작업 설명으로 claude.ai에서 새 웹 세션을 생성합니다. 세션 ID(session_... 또는 cse_...) 또는 claude.ai/code URL로 -p를 사용하여 기존 세션에 메시지를 대기열에 넣습니다. 후속 메시지 전송 참조 claude --cloud "Fix the login bug"
--continue, -c 현재 디렉토리에서 가장 최근 대화를 로드합니다. 완료된 백그라운드 세션을 포함합니다. 완료된 백그라운드 세션을 열려면 Claude Code v2.1.257 이상이 필요합니다. claude -p 또는 Agent SDK로 생성된 세션과 첫 번째 프롬프트가 /loop인 세션을 건너뜁니다. claude -p --continue는 -p, SDK 및 /loop 세션을 포함합니다. /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와 동일합니다. 이것이 건너뛰는 것과 건너뛰지 않는 것에 대해 권한 모드를 참조하세요. --bg로 시작된 세션의 경우, 모드는 감독자가 세션을 다시 시작할 때 지속됩니다 claude --dangerously-skip-permissions
--debug 선택적 카테고리 필터링을 사용하여 디버그 모드를 활성화합니다(예: --debug='mcp,startup' 또는 --debug='!1p'). 필터는 = 형식에만 바인딩됩니다. 공백으로 구분된 필터는 필터링 없이 디버그 모드를 활성화합니다 claude --debug='mcp,startup'
--debug-file <path> 디버그 로그를 특정 파일 경로에 씁니다. 암묵적으로 디버그 모드를 활성화합니다. CLAUDE_CODE_DEBUG_LOGS_DIR보다 우선합니다 claude --debug-file /tmp/claude-debug.log
--disable-slash-commands 이 세션에 대해 모든 skills 및 명령어를 비활성화합니다 claude --disable-slash-commands
--disallowedTools, --disallowed-tools 거부 규칙입니다. 단순 도구 이름은 Claude의 컨텍스트에서 해당 도구를 제거합니다: "Edit"는 Edit를 제거하고, "*"는 모든 도구를 제거하며, "mcp__*"는 모든 MCP 도구를 제거합니다. Bash(rm *)과 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 일치하는 호출만 거부합니다. EndConversation을 이름 지은 규칙은 다른 도구가 남아 있는 동안 이를 제거할 수 없습니다 "Bash(git log *)" "Bash(git diff *)" "Edit"
--effort 현재 세션에 대한 노력 수준을 설정합니다. 옵션: low, medium, high, xhigh, max 또는 ultracode. 사용 가능한 수준은 모델에 따라 다릅니다. ultracode는 세션을 xhigh 노력으로 시작하고 ultracode를 켜며, Claude Code v2.1.203 이상이 필요합니다. modelSettings 및 effortLevel 설정을 이 세션에 대해 재정의하며 지속되지 않습니다 claude --effort high
--enable-auto-mode v2.1.111에서 제거됨. 자동 모드는 이제 Shift+Tab 사이클에 기본적으로 포함됩니다. --permission-mode auto를 사용하여 시작합니다 claude --permission-mode auto
--environment <environment-id> 주어진 ID를 가진 자체 호스팅 환경에서 실행되는 새 클라우드 세션을 생성합니다. 환경 ID는 ccpool_로 시작합니다. 디스패치 동작 및 거부하는 플래그 조합에 대해 --environment 디스패치 동작을 참조하세요. Claude Code v2.1.224 이상이 필요합니다 claude -p "Fix the login bug" --environment ccpool_abc123
--exclude-dynamic-system-prompt-sections 시스템 프롬프트의 머신별 섹션(작업 디렉토리, 환경 정보, 메모리 경로, git 상태)을 첫 번째 사용자 메시지로 이동합니다. 동일한 작업을 실행하는 다양한 사용자 및 머신 간에 프롬프트 캐시 재사용을 개선합니다. 기본 시스템 프롬프트에만 적용됩니다. --system-prompt 또는 --system-prompt-file이 설정되면 무시됩니다. 스크립트된 다중 사용자 워크로드의 경우 -p와 함께 사용합니다 claude -p --exclude-dynamic-system-prompt-sections "query"
--exec 셸 명령어를 Claude 세션을 시작하는 대신 PTY 기반 백그라운드 작업으로 실행합니다. --bg와 함께 사용하여 셸에서 시작합니다 claude --bg --exec 'pytest -x'
--fallback-model 기본 모델이 과부하 상태이거나 사용할 수 없을 때(예: 폐기된 모델) 지정된 모델로 자동 폴백을 활성화합니다. 순서대로 시도되는 쉼표로 구분된 목록을 허용합니다. 폴백 모델 체인 참조. 세션 간에 체인을 유지하려면 fallbackModel 설정을 사용하며, 이 플래그가 이를 재정의합니다 claude --fallback-model sonnet,haiku
--fork-session 재개할 때 원본을 재사용하는 대신 새 세션 ID를 생성합니다(--resume 또는 --continue와 함께 사용) claude --resume abc123 --fork-session
--forward-subagent-text subagent 텍스트 및 사고 블록을 parent_tool_use_id 설정으로 assistant 및 user 메시지로 출력 스트림에 내보내므로 각 subagent의 트랜스크립트를 재구성할 수 있습니다. 이 플래그 없이 Claude Code는 subagent tool_use 및 tool_result 블록만 내보냅니다. --print 및 --output-format stream-json이 필요합니다. Claude Code는 또한 중첩된 subagents의 메시지를 전달하며, parent_tool_use_id를 각 subagent를 생성한 Agent 도구 호출의 ID로 설정합니다. 이는 Claude Code v2.1.219 이상이 필요합니다. CLAUDE_CODE_FORWARD_SUBAGENT_TEXT 환경 변수는 동일한 동작을 활성화합니다. Claude Code v2.1.211 이상이 필요합니다 claude -p --output-format stream-json --verbose --forward-subagent-text "query"
--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 라이프사이클 이벤트를 출력 스트림에 포함합니다. SessionStart 및 Setup hook 이벤트는 항상 포함되며 이 플래그가 필요하지 않습니다. Notification, SessionEnd, PreCompact 및 PostCompact와 같은 일부 hook 이벤트는 이 플래그를 사용해도 hook_started 이벤트를 생성하지 않습니다. 이러한 이벤트의 경우 Claude Code는 여전히 명령어 hook이 1초 이상 실행되는 동안 hook_progress를 내보내고, 백그라운드에서 실행되는 hook이 완료될 때만 hook_response를 내보냅니다. --output-format stream-json이 필요합니다 claude -p --output-format stream-json --verbose --include-hook-events "query"
--include-partial-messages 부분 스트리밍 이벤트를 출력에 포함합니다. --print 및 --output-format stream-json이 필요합니다 claude -p --output-format stream-json --verbose --include-partial-messages "query"
--input-format 인쇄 모드에 대한 입력 형식을 지정합니다(옵션: text, stream-json) claude -p --output-format json --input-format stream-json
--json-schema 에이전트가 워크플로우를 완료한 후 JSON Schema와 일치하는 검증된 JSON 출력을 가져옵니다(인쇄 모드만 해당). 구조화된 출력 참조. Claude Code는 잘못된 스키마에서 오류로 종료되고 클라이언트 측 검증 없이 주석으로 format 키워드를 허용합니다 claude -p --json-schema '{"type":"object","properties":{...}}' "query"
--maintenance Setup hooks를 maintenance 매처로 실행한 후 세션을 시작합니다(인쇄 모드만 해당) claude -p --maintenance "query"
--max-budget-usd 중지하기 전에 API 호출에 소비할 최대 달러 금액(인쇄 모드만 해당). subagents의 지출이 한도에 포함됩니다. 지출이 한도에 도달하면 다른 subagent를 생성하면 Budget limit reached로 실패하고 Claude Code는 여전히 실행 중인 백그라운드 subagents를 중지합니다. 한도 적용 동작에는 Claude Code v2.1.217 이상이 필요합니다 claude -p --max-budget-usd 5.00 "query"
--max-turns 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 제한에 도달하면 오류로 종료됩니다. 기본적으로 제한 없음. --input-format stream-json을 사용하면 제한이 턴을 끝낼 때 대기열에 있는 메시지는 대기열에 남아 있고 자신의 제한으로 새 턴을 시작합니다 claude -p --max-turns 3 "query"
--mcp-config JSON 파일 또는 문자열에서 MCP 서버를 로드합니다(공백으로 구분). 이 플래그를 -p와 함께 전달하면 Claude Code는 여전히 보류 중인 서버가 연결될 때까지 대기합니다. MCP_TIMEOUT 시작 시간 초과인 30초까지입니다. 캐시된 도구 목록이 있는 서버는 대기를 건너뛰고 처음 사용할 때 연결됩니다. 대기에는 Claude Code v2.1.221 이상이 필요합니다 claude --mcp-config ./mcp.json
--model sonnet, opus, haiku 또는 fable과 같은 모델 별칭 또는 모델의 전체 이름으로 현재 세션에 대한 모델을 설정합니다. model 설정 및 ANTHROPIC_MODEL을 재정의합니다 claude --model claude-sonnet-5
--name, -n 세션의 표시 이름을 설정합니다. /resume 및 터미널 제목에 표시됩니다. claude --resume <name>으로 명명된 세션을 재개할 수 있습니다. 대화형 세션에서 이 머신의 다른 라이브 세션이 이미 이름을 사용하는 경우 Claude Code는 이의 변형을 적용합니다.

/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 또는 manual을 허용합니다. manual은 default의 별칭이며 UI가 Manual로 표시하는 모드를 선택하고 Claude Code v2.1.200 이상이 필요합니다. claude --help는 default 대신 이를 나열하며 두 값 모두 작동합니다. 설정 파일의 defaultMode를 재정의합니다. 이 플래그 또는 --dangerously-skip-permissions 없이 새 세션은 세션이 시작되는 권한 모드에 설명된 권한 모드에서 시작됩니다. -p의 경우 아무것도 구성되지 않으면 default입니다 claude --permission-mode plan
--permission-prompt-tool 비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다. Claude Code는 해당 도구의 MCP 서버가 연결될 때까지 대기합니다. MCP_TIMEOUT 시작 시간 초과인 30초까지입니다.

프롬프트 도구는 사용자 상호작용이 필요한 것으로 표시된 MCP 도구를 승인할 수 없습니다: Claude Code는 하나에 대한 allow 결과를 거부로 변환합니다. 이 제한은 Claude Code v2.1.199 이상이 필요합니다		 claude -p --permission-prompt-tool mcp_auth_tool "query"
--permission-prompts 인쇄 모드에서 권한 프롬프트에 응답하는 사람을 설정합니다. 기본 host를 사용하면 Claude Code는 Agent SDK 호스트 또는 --permission-prompt-tool 도구로 보냅니다. 아무도 응답할 수 없을 때 none을 전달하면 Claude Code는 대신 거부합니다. 무인 실행에서 권한 프롬프트 끄기 참조. Claude Code v2.1.259 이상이 필요합니다 claude -p --permission-prompts none "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"
--prompt-suggestions 각 턴 후에 예측된 다음 사용자 프롬프트를 포함하는 prompt_suggestion 메시지를 내보냅니다. 매우 짧은 대화는 없을 수 있습니다. --print, --output-format stream-json 및 --verbose가 필요합니다. 프롬프트 제안 참조 claude -p --prompt-suggestions --output-format stream-json --verbose "query"
--ref <branch> --environment을 사용하여 새 세션의 체크아웃을 로컬 HEAD 대신 명명된 ref를 기반으로 합니다 claude -p "Run the smoke test" --environment ccpool_abc123 --ref main
--remote --cloud의 더 이상 사용되지 않는 별칭. 기존 세션 형식 포함 claude --remote "Fix the login bug"
--remote-control, --rc Remote Control이 활성화된 대화형 세션을 시작하므로 claude.ai 또는 Claude 앱에서도 제어할 수 있습니다. 선택적으로 세션의 이름을 전달할 수 있습니다 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 --verbose --replay-user-messages
--restricted 제한된 모드에서 시작합니다. 평가 하네스가 공유 머신에서 claude를 구동하고 Claude Code가 명령어를 실행하거나 해당 머신의 사용자 및 프로젝트 설정을 읽지 않아야 할 때 사용합니다. Claude Code는 명령어를 실행하거나 코드를 실행하는 기본 제공 도구와 WebFetch를 제거합니다. --tools에서 개별적으로 이름을 지으면 제외됩니다. default 프리셋을 통하지 않습니다. 또한 기본 제공 파일 도구를 작업 디렉토리로 제한하고, 관리되는 설정 및 --settings만 로드하며, bypassPermissions를 거부하고, 제한된 세션에서 클라우드 세션을 생성하기를 거부합니다. Claude Code v2.1.248 이상이 필요합니다 claude --restricted -p "query"
--resume, -r ID 또는 이름으로 특정 세션을 재개하거나 세션을 선택할 수 있는 대화형 선택기를 표시합니다. ID 대신 세션의 .jsonl 트랜스크립트 파일의 절대 경로를 전달할 수 있습니다. 선택기 및 이름 검색은 /add-dir으로 이 디렉토리를 추가한 세션을 포함합니다. 세션 ID를 전달하면 Claude Code는 현재 프로젝트 디렉토리 및 해당 git worktrees를 검색한 후 이 머신의 다른 모든 프로젝트를 검색합니다. v2.1.223 이전에는 ID 검색이 현재 프로젝트 디렉토리 및 해당 git worktrees만 다루었습니다. 백그라운드 세션은 선택기에 bg로 표시됩니다 claude --resume auth-refactor
--safe-mode 손상된 구성을 문제 해결하기 위해 모든 사용자 정의를 비활성화한 상태로 시작합니다: CLAUDE.md, skills, plugins, hooks, MCP 서버, 사용자 정의 명령어 및 에이전트, 출력 스타일, 워크플로우, 사용자 정의 테마, 사용자 정의 키 바인딩, 상태 줄 및 파일 제안 명령어, LSP 서버 및 자동 메모리가 로드되지 않습니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동하며, 이는 --bare와 다릅니다. 관리되는 설정 정책은 여전히 적용되며, 정책 구성 hooks, 상태 줄 및 파일 제안 명령어를 포함합니다. 관리되는 plugins, 관리되는 skills, 관리되는 CLAUDE.md 및 정책 구성 MCP 서버는 로드되지 않습니다. 자동 모델 폴백을 트리거하는 사용자 정의인지 확인하는 데 유용합니다. CLAUDE_CODE_SAFE_MODE를 설정합니다 claude --safe-mode
--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 파일의 동일한 키를 재정의합니다. 생략한 키는 파일 기반 값을 유지합니다. 파일은 2 MiB 이하의 일반 파일이어야 합니다. 설정 우선순위 참조 claude --settings ./settings.json
--strict-mcp-config --mcp-config의 MCP 서버만 사용하고 다른 모든 MCP 구성을 무시합니다. 관리되는 MCP 파일에서 플래그가 수행하는 작업에 대해 관리되는 mcp.json으로 독점 제어 참조 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 에이전트 팀 팀원 표시 방식을 설정합니다: in-process(기본값), auto, tmux 또는 iterm2(v2.1.186에서 추가됨). teammateMode 설정을 이 세션에 대해 재정의합니다. 디스플레이 모드 선택 참조 claude --teammate-mode auto
--tmux worktree에 대한 tmux 세션을 생성합니다. --worktree가 필요합니다. 사용 가능한 경우 iTerm2 네이티브 창을 사용합니다. 기존 tmux의 경우 --tmux=classic을 전달합니다 claude -w feature-auth --tmux
--tools Claude가 사용할 수 있는 기본 제공 도구를 제한합니다. 모두 비활성화하려면 ""를 사용하고, 모두 사용하려면 "default"를 사용하거나, "Bash,Edit,Read"와 같은 도구 이름을 사용합니다. 작업 추적 도구 중 하나를 여기에 이름 지으면 Claude Code도 세션을 옵트인합니다. 플래그는 MCP 도구에 영향을 주지 않습니다. 이들도 거부하려면 --disallowedTools "mcp__*"를 사용합니다. EndConversation을 생략하는 목록은 이를 제거하지 않습니다. ""는 다른 MCP 도구가 남아 있지 않을 때만 이를 제거합니다 claude --tools "Bash,Edit,Read"
--verbose 자세한 로깅을 활성화하고 전체 턴별 출력을 표시합니다. viewMode 설정을 이 세션에 대해 재정의합니다 claude --verbose
--version, -v 버전 번호를 출력합니다 claude -v
--worktree, -w Claude를 <repo>/.claude/worktrees/<name>의 격리된 git worktree에서 시작합니다. 이름이 지정되지 않으면 Claude Code가 자동으로 생성합니다. #<number>, GitHub pull request URL 또는 GitLab merge request URL을 전달하여 origin에서 해당 PR 또는 MR을 가져오고 worktree를 분기합니다. GitLab merge request에서 분기하려면 Claude Code v2.1.233 이상이 필요합니다 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의 기본 정체성이 여전히 작업에 맞는지에 따라 선택합니다. Claude가 코딩 어시스턴트로 남아 있으면서 추가 규칙도 따라야 할 때 추가 플래그를 사용합니다: 호출별 지시사항, 출력 형식 또는 -p 스크립트에 대한 도메인 컨텍스트입니다. 추가하면 기본 도구 지침, 안전 지시사항 및 코딩 규칙이 유지되므로 다른 부분만 제공하면 됩니다. Claude Code의 표면, 정체성 또는 권한 모델과 다를 때 바꾸기 플래그를 사용합니다. 예를 들어 사람이 감시하지 않는 파이프라인의 비코딩 에이전트입니다. 바꾸면 도구 지침 및 안전 지시사항을 포함한 전체 기본 프롬프트가 제거되므로 작업에 필요한 모든 것에 대해 책임을 져야 합니다.

이러한 플래그는 현재 호출에만 적용됩니다. 프로젝트 간에 전환하고 공유할 수 있는 지속적인 페르소나의 경우 출력 스타일을 사용합니다. 프로젝트 규칙 Claude가 항상 따라야 할 경우 CLAUDE.md를 사용합니다. 시스템 프롬프트에 대한 Agent SDK 가이드는 더 깊이 있는 동일한 결정을 다룹니다.

참고 항목