> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 "" "query"` | ID 또는 이름으로 세션 재개 | `claude -r "auth-refactor" "Finish this PR"` |
| `claude update` | 최신 버전으로 업데이트 | `claude update` |
| `claude gateway` | 자체 호스팅 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 서버를 시작합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry의 Claude Code 앞에 SSO 및 정책을 배포하는 관리자용입니다. [`gateway.yaml`](/docs/ko/claude-apps-gateway-config)을 가리키는 `--config`가 필요합니다. Claude Code v2.1.195 이상에서 사용 가능합니다. | `claude gateway --config gateway.yaml` |
| `claude install [version]` | 네이티브 바이너리를 설치하거나 재설치합니다. `2.1.118`과 같은 버전, 또는 `stable` 또는 `latest`를 허용합니다. [특정 버전 설치](/docs/ko/setup#install-a-specific-version) 참조 | `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` | [에이전트 보기](/docs/ko/agent-view)를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. `--cwd `를 사용하여 해당 디렉토리 아래에서 시작된 세션만 표시하거나, `--json`을 사용하여 스크립팅을 위해 활성 세션을 JSON 배열로 인쇄합니다(`--json --all`은 완료된 백그라운드 세션도 포함합니다). `--permission-mode`, `--model`, `--effort` 또는 `--agent`를 전달하여 [디스패치된 세션의 기본값](/docs/ko/agent-view#permission-mode-model-and-effort)을 설정합니다. 최상위 `claude` 명령어처럼 `--settings`, `--add-dir`, `--plugin-dir` 및 `--mcp-config`를 허용합니다. 에이전트 보기를 열려면 대화형 터미널이 필요합니다 | `claude agents --json` |
| `claude attach ` | 이 터미널에서 [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다 | `claude attach 7c5dcf5d` |
| `claude auto-mode defaults` | 기본 제공 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다. {/* min-version: 2.1.208 */}}`--label `는 해당 접두사로 시작하는 레이블이 있는 규칙만 인쇄합니다(대소문자 구분 안 함). Claude Code v2.1.208 이상이 필요합니다 | `claude auto-mode defaults --label 'Git Destructive'` |
| `claude daemon status` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)의 상태, 버전, 소켓 디렉토리 및 진단을 위한 워커 수를 인쇄합니다. 감독자가 실행 중이 아니면 1로 종료됩니다 | `claude daemon status` |
| `claude daemon stop --any` | 백그라운드 세션 [감독자](/docs/ko/agent-view#the-supervisor-process)와 이를 호스팅하는 세션을 중지합니다. `--keep-workers`를 전달하여 백그라운드 세션을 실행 중인 상태로 두면 다음 감독자가 이들에 다시 연결됩니다. `--any`는 기본값인 온디맨드 감독자 중지를 확인합니다. 이를 사용하여 [응답하지 않는 감독자](/docs/ko/agent-view#agent-view-says-the-background-service-did-not-respond)에서 복구합니다 | `claude daemon stop --any --keep-workers` |
| `claude doctor` | 세션을 시작하지 않고 터미널에서 읽기 전용 설치 및 설정 진단을 인쇄합니다. 설치 상태, 설정 파일 검증 오류 및 Remote Control 적격성을 포함합니다. 수정을 적용할 수도 있는 세션 내 설정 점검을 위해 [`/doctor`](/docs/ko/commands#all-commands)를 실행합니다 | `claude doctor` |
| `claude logs ` | [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)의 최근 출력을 인쇄합니다 | `claude logs 7c5dcf5d` |
| `claude mcp` | Model Context Protocol (MCP) 서버 구성 | [Claude Code MCP 문서](/docs/ko/mcp) 참조 |
| `claude mcp login ` | {/* min-version: 2.1.186 */}구성된 MCP 서버의 OAuth 흐름을 대화형 `/mcp` 패널을 열지 않고 실행합니다. HTTP, SSE 및 claude.ai 커넥터 서버에서 작동합니다. SSH를 통해 `--no-browser`를 추가하여 브라우저를 열지 않고 인증 URL을 인쇄한 다음 리다이렉트 URL을 프롬프트에 다시 붙여넣습니다. Claude Code v2.1.186 이상이 필요합니다. [명령줄에서 인증](/docs/ko/mcp#authenticate-from-the-command-line) 참조 | `claude mcp login sentry` |
| `claude mcp logout ` | {/* min-version: 2.1.186 */}MCP 서버에 대해 저장된 OAuth 자격 증명을 지웁니다. Claude Code v2.1.186 이상이 필요합니다 | `claude mcp logout sentry` |
| `claude plugin` | Claude Code [plugins](/docs/ko/plugins)를 관리합니다. 별칭: `claude plugins`. 하위 명령어는 [plugin 참조](/docs/ko/plugins-reference#cli-commands-reference)를 참조하세요 | `claude plugin install code-review@claude-plugins-official` |
| `claude project purge [path]` | 프로젝트의 모든 로컬 Claude Code 상태를 삭제합니다: 대화 기록, 작업 목록, 디버그 로그, 파일 편집 기록, 프롬프트 기록 라인 및 `~/.claude.json`의 프로젝트 항목. `[path]`를 생략하면 대화형 목록에서 선택할 수 있습니다. 플래그: `--dry-run`으로 미리 보기, `-y`/`--yes`로 확인 건너뛰기, `-i`/`--interactive`로 각 항목 확인, `--all`로 모든 프로젝트. [로컬 데이터 지우기](/docs/ko/claude-directory#clear-local-data) 참조 | `claude project purge ~/work/repo --dry-run` |
| `claude remote-control` | Claude.ai 또는 Claude 앱에서 Claude Code를 제어하기 위한 [Remote Control](/docs/ko/remote-control) 서버를 시작합니다. 서버 모드에서 실행됩니다(로컬 대화형 세션 없음). [서버 모드 플래그](/docs/ko/remote-control#start-a-remote-control-session) 참조 | `claude remote-control --name "My Project"` |
| `claude respawn ` | 대화를 유지하면서 실행 중이거나 중지된 [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)을 다시 시작합니다. `--all`을 사용하여 모든 실행 중인 세션을 다시 시작합니다(예: 업데이트된 Claude Code 바이너리를 선택하기 위해) | `claude respawn 7c5dcf5d` |
| `claude rm ` | [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)을 목록에서 제거합니다. 대화 기록은 로컬 머신에 남아 있으며 `claude --resume`을 통해 사용할 수 있습니다 | `claude rm 7c5dcf5d` |
| `claude setup-token` | CI 및 스크립트를 위한 장기 OAuth 토큰을 생성합니다. 토큰을 저장하지 않고 터미널에 인쇄합니다. Claude 구독이 필요합니다. [장기 토큰 생성](/docs/ko/authentication#generate-a-long-lived-token) 참조 | `claude setup-token` |
| `claude stop ` | [백그라운드 세션](/docs/ko/agent-view#manage-sessions-from-the-shell)을 중지합니다. `claude kill`도 허용됩니다 | `claude stop 7c5dcf5d` |
| `claude ultrareview [target]` | [ultrareview](/docs/ko/ultrareview#run-ultrareview-non-interactively)를 비대화형으로 실행합니다. 결과를 stdout으로 인쇄하고 성공 시 0으로 종료되거나 실패 시 1로 종료됩니다. 원본 페이로드는 `--json`을 사용하고 30분 기본값을 재정의하려면 `--timeout `를 사용합니다 | `claude ultrareview 1234 --json` |
하위 명령어를 잘못 입력하면 Claude Code는 가장 가까운 일치를 제안하고 세션을 시작하지 않고 종료합니다. 예를 들어, `claude udpate`는 `Did you mean claude update?`를 인쇄합니다.
{/* min-version: 2.1.199 */}v2.1.199부터 `claude --dangerously-skip-permissions daemon `는 `daemon` 하위 명령어를 실행합니다. 이전 버전에서는 `daemon `를 새 대화형 세션의 프롬프트로 처리했으므로 플래그가 먼저 올 때 하위 명령어가 실행되지 않았습니다. 이는 `claude`가 플래그를 포함하도록 별칭이 지정된 경우 일반적인 설정입니다. 선행 `--dangerously-skip-permissions` 또는 `--allow-dangerously-skip-permissions`만 이 방식으로 `daemon`으로 라우팅됩니다. 다른 선행 플래그는 여전히 대화형 세션을 시작합니다.
CLI 플래그
이러한 명령줄 플래그를 사용하여 Claude Code의 동작을 사용자 정의합니다. `claude --help`는 모든 플래그를 나열하지 않으므로, `--help`에 플래그가 없다고 해서 사용할 수 없다는 의미는 아닙니다.
| 플래그 | 설명 | 예시 |
| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| `--add-dir` | Claude가 파일을 읽고 편집할 수 있는 추가 작업 디렉토리를 추가합니다. 파일 액세스를 부여합니다. 대부분의 `.claude/` 구성은 이러한 디렉토리에서 [검색되지 않습니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration). 각 경로가 디렉토리로 존재하는지 검증합니다. 이러한 디렉토리를 세션 간에 유지하려면 설정에서 [`permissions.additionalDirectories`](/docs/ko/settings#permission-settings)를 설정합니다 | `claude --add-dir ../apps ../lib` |
| `--advisor ` | 이 세션에 대해 서버 측 [advisor 도구](/docs/ko/advisor)를 활성화합니다. 모델 별칭 사용: `opus`, `sonnet` 또는 `fable` ({/* min-version: 2.1.170 */}v2.1.170+) 또는 전체 모델 ID입니다. `advisorModel` 설정보다 우선합니다 | `claude --advisor opus` |
| `--agent` | 현재 세션에 대한 에이전트를 지정합니다(`agent` 설정 재정의) | `claude --agent my-custom-agent` |
| `--agents` | JSON을 통해 사용자 정의 subagents를 동적으로 정의합니다. subagent [frontmatter](/docs/ko/sub-agents#supported-frontmatter-fields)와 동일한 필드 이름과 에이전트의 지시사항에 대한 `prompt` 필드를 사용합니다 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |
| `--allow-dangerously-skip-permissions` | `Shift+Tab` 모드 사이클에 `bypassPermissions`를 추가합니다. 이를 통해 `plan`과 같은 다른 모드에서 시작하고 나중에 `bypassPermissions`로 전환할 수 있습니다. [권한 모드](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 참조 | `claude --permission-mode plan --allow-dangerously-skip-permissions` |
| `--allowedTools`, `--allowed-tools` | 권한 프롬프트 없이 실행되는 도구입니다. 패턴 매칭에 대해 [권한 규칙 구문](/docs/ko/settings#permission-rule-syntax)을 참조하세요. 사용 가능한 도구를 제한하려면 `--tools`를 대신 사용하세요 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |
| `--append-subagent-system-prompt` | {/* min-version: 2.1.205 */}모든 [subagent](/docs/ko/sub-agents)의 시스템 프롬프트 끝에 사용자 정의 텍스트를 추가합니다. 중첩된 subagents를 포함합니다. `-p`를 사용한 비대화형 모드에만 적용됩니다. Claude Code v2.1.205 이상이 필요합니다 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |
| `--append-system-prompt` | 기본 시스템 프롬프트의 끝에 사용자 정의 텍스트를 추가합니다 | `claude --append-system-prompt "Always use TypeScript"` |
| `--append-system-prompt-file` | 파일에서 추가 시스템 프롬프트 텍스트를 로드하고 기본 프롬프트에 추가합니다 | `claude --append-system-prompt-file ./extra-rules.txt` |
| `--ax-screen-reader` | {/* min-version: 2.1.181 */}스크린 리더 친화적 출력을 렌더링합니다: 장식용 테두리나 애니메이션 없는 평문입니다. 클래식 렌더러를 강제하므로 이 세션에 대해 [`tui`](/docs/ko/settings#available-settings) 설정은 효과가 없습니다. 연결된 [백그라운드 세션](/docs/ko/agent-view)은 여전히 전체 화면으로 렌더링됩니다. [`CLAUDE_AX_SCREEN_READER`](/docs/ko/env-vars) 및 [`axScreenReader`](/docs/ko/settings#available-settings) 설정보다 우선합니다. Claude Code v2.1.181 이상이 필요합니다 | `claude --ax-screen-reader` |
| `--bare` | 최소 모드: hooks, skills, plugins, MCP 서버, 자동 메모리 및 CLAUDE.md의 자동 검색을 건너뜁니다. 스크립트된 호출이 더 빠르게 시작됩니다. Claude는 Bash, 파일 읽기 및 파일 편집 도구에 액세스할 수 있습니다. [`CLAUDE_CODE_SIMPLE`](/docs/ko/env-vars)을 설정합니다. [bare 모드](/docs/ko/headless#start-faster-with-bare-mode) 참조 | `claude --bare -p "query"` |
| `--betas` | API 요청에 포함할 베타 헤더(API 키 사용자만 해당) | `claude --betas interleaved-thinking` |
| `--bg`, `--background` | 세션을 [백그라운드 에이전트](/docs/ko/agent-view)로 시작하고 즉시 반환합니다. 세션 ID와 관리 명령어를 인쇄합니다. `--exec`과 결합하여 Claude 세션 대신 셸 명령어를 백그라운드 작업으로 실행하거나, `--agent`와 결합하여 특정 subagent를 실행합니다. {/* min-version: 2.1.198 */}`-p`/`--print`와 결합할 수 없습니다. [오류 참조](/docs/ko/errors#command-line-errors) 참조 | `claude --bg "investigate the flaky test"` |
| `--channels` | (연구 미리보기) Claude가 이 세션에서 수신해야 할 [채널](/docs/ko/channels) 알림이 있는 MCP 서버입니다. `plugin:@` 항목의 공백으로 구분된 목록입니다. Claude.ai 인증이 필요합니다 | `claude --channels plugin:my-notifier@my-marketplace` |
| `--chrome` | 웹 자동화 및 테스트를 위해 [Chrome 브라우저 통합](/docs/ko/chrome)을 활성화합니다 | `claude --chrome` |
| `--cloud` | 제공된 작업 설명으로 claude.ai에서 새 [웹 세션](/docs/ko/claude-code-on-the-web)을 생성합니다 | `claude --cloud "Fix the login bug"` |
| `--continue`, `-c` | 현재 디렉토리에서 가장 최근 대화를 로드합니다. `/add-dir`으로 이 디렉토리를 추가한 세션을 포함합니다 | `claude --continue` |
| `--dangerously-load-development-channels` | 로컬 개발을 위해 승인된 허용 목록에 없는 [채널](/docs/ko/channels-reference#test-during-the-research-preview)을 활성화합니다. `plugin:@` 및 `server:` 항목을 허용합니다. 확인을 요청합니다 | `claude --dangerously-load-development-channels server:webhook` |
| `--dangerously-skip-permissions` | 권한 프롬프트를 건너뜁니다. `--permission-mode bypassPermissions`와 동일합니다. 이것이 건너뛰는 것과 건너뛰지 않는 것에 대해 [권한 모드](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)를 참조하세요. `--bg`로 시작된 세션의 경우, 모드는 [감독자가 세션을 다시 시작할 때 지속됩니다](/docs/ko/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |
| `--debug` | 선택적 카테고리 필터링을 사용하여 디버그 모드를 활성화합니다(예: `"api,hooks"` 또는 `"!statsig,!file"`) | `claude --debug "api,mcp"` |
| `--debug-file ` | 디버그 로그를 특정 파일 경로에 씁니다. 암묵적으로 디버그 모드를 활성화합니다. `CLAUDE_CODE_DEBUG_LOGS_DIR`보다 우선합니다 | `claude --debug-file /tmp/claude-debug.log` |
| `--disable-slash-commands` | 이 세션에 대해 모든 skills 및 명령어를 비활성화합니다 | `claude --disable-slash-commands` |
| `--disallowedTools`, `--disallowed-tools` | 거부 규칙입니다. 단순 도구 이름은 모델의 컨텍스트에서 해당 도구를 제거합니다: `"Edit"`는 Edit를 제거하고, `"*"`는 모든 도구를 제거하며, `"mcp__*"`는 모든 MCP 도구를 제거합니다. `Bash(rm *)`과 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 일치하는 호출만 거부합니다 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |
| `--effort` | 현재 세션에 대한 [노력 수준](/docs/ko/model-config#adjust-effort-level)을 설정합니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max` 또는 {/* min-version: 2.1.203 */}}`ultracode`. 사용 가능한 수준은 모델에 따라 다릅니다. `ultracode`는 세션을 `xhigh` 노력으로 시작하고 [ultracode](/docs/ko/workflows#let-claude-decide-with-ultracode)를 켜며, Claude Code v2.1.203 이상이 필요합니다. [`effortLevel`](/docs/ko/settings#available-settings) 설정을 이 세션에 대해 재정의하며 지속되지 않습니다 | `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"` |
| `--exec` | 셸 명령어를 Claude 세션을 시작하는 대신 PTY 기반 백그라운드 작업으로 실행합니다. `--bg`와 함께 사용하여 셸에서 시작합니다 | `claude --bg --exec 'pytest -x'` |
| `--fallback-model` | 기본 모델이 과부하 상태이거나 사용할 수 없을 때 지정된 모델로 자동 폴백을 활성화합니다(예: 폐기된 모델). 쉼표로 구분된 목록을 순서대로 시도합니다. [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains) 참조. 세션 간에 체인을 유지하려면 [`fallbackModel` 설정](/docs/ko/settings#available-settings)을 사용하며, 이 플래그가 이를 재정의합니다 | `claude --fallback-model sonnet,haiku` |
| `--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](/docs/ko/hooks#setup)를 `init` 매처로 실행한 후 세션을 시작합니다(인쇄 모드만 해당) | `claude -p --init "query"` |
| `--init-only` | [Setup](/docs/ko/hooks#setup) 및 `SessionStart` hooks를 실행한 후 대화를 시작하지 않고 종료합니다 | `claude --init-only` |
| `--include-hook-events` | 모든 hook 라이프사이클 이벤트를 출력 스트림에 포함합니다. `SessionStart` 및 `Setup` hook 이벤트는 항상 포함되며 이 플래그가 필요하지 않습니다. `--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 출력을 가져옵니다(인쇄 모드만 해당). [구조화된 출력](/docs/ko/agent-sdk/structured-outputs) 참조. {/* min-version: 2.1.205 */}Claude Code는 잘못된 스키마에서 오류로 종료되고 클라이언트 측 검증 없이 주석으로 `format` 키워드를 허용합니다. v2.1.205 이전에는 잘못된 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format`을 사용하는 스키마는 잘못된 것으로 취급되었습니다 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |
| `--maintenance` | [Setup hooks](/docs/ko/hooks#setup)를 `maintenance` 매처로 실행한 후 세션을 시작합니다(인쇄 모드만 해당) | `claude -p --maintenance "query"` |
| `--max-budget-usd` | 중지하기 전에 API 호출에 소비할 최대 달러 금액(인쇄 모드만 해당) | `claude -p --max-budget-usd 5.00 "query"` |
| `--max-turns` | 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 제한에 도달하면 오류로 종료됩니다. 기본적으로 제한 없음. {/* min-version: 2.1.205 */}}`--input-format stream-json`을 사용하면 Claude가 작업 중일 때 전송된 메시지는 대기열에 남아 있고 제한이 현재 메시지를 종료할 때 자신의 제한으로 자신의 턴으로 실행됩니다. v2.1.205 이전에는 Claude Code가 해당 메시지를 버렸습니다 | `claude -p --max-turns 3 "query"` |
| `--mcp-config` | JSON 파일 또는 문자열에서 MCP 서버를 로드합니다(공백으로 구분) | `claude --mcp-config ./mcp.json` |
| `--model` | 최신 모델의 별칭(`sonnet`, `opus`, `haiku` 또는 `fable`) 또는 모델의 전체 이름으로 현재 세션에 대한 모델을 설정합니다. [`model`](/docs/ko/settings#available-settings) 설정 및 [`ANTHROPIC_MODEL`](/docs/ko/model-config#environment-variables)을 재정의합니다 | `claude --model claude-sonnet-5` |
| `--name`, `-n` | 세션의 표시 이름을 설정합니다. `/resume`과 터미널 제목에 표시됩니다. `claude --resume `으로 명명된 세션을 재개할 수 있습니다.
[`/rename`](/docs/ko/commands)은 세션 중에 이름을 변경하고 프롬프트 표시줄에도 표시합니다 | `claude -n "my-feature-work"` |
| `--no-chrome` | 이 세션에 대해 [Chrome 브라우저 통합](/docs/ko/chrome)을 비활성화합니다 | `claude --no-chrome` |
| `--no-session-persistence` | 세션 지속성을 비활성화하여 세션이 디스크에 저장되지 않고 재개할 수 없습니다(인쇄 모드만 해당). [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/ko/env-vars) 환경 변수는 모든 모드에서 동일한 작업을 수행합니다 | `claude -p --no-session-persistence "query"` |
| `--output-format` | 인쇄 모드에 대한 출력 형식을 지정합니다(옵션: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |
| `--permission-mode` | 지정된 [권한 모드](/docs/ko/permission-modes)에서 시작합니다. `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` 또는 {/* min-version: 2.1.200 */}}`manual`을 허용합니다. `manual`은 `default`의 별칭이며 UI가 Manual로 표시하는 모드를 선택하고 Claude Code v2.1.200 이상이 필요합니다. `claude --help`는 `default` 대신 이를 나열하며 두 값 모두 작동합니다. 설정 파일의 `defaultMode`를 재정의합니다 | `claude --permission-mode plan` |
| `--permission-prompt-tool` | 비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다. {/* min-version: 2.1.206 */}}Claude Code는 해당 도구의 MCP 서버가 연결될 때까지 대기합니다. 첫 번째 턴을 실행하기 전에 [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 시간 초과인 30초까지입니다. v2.1.206 이전에는 느리게 시작되는 서버로 인해 실행이 [MCP 도구를 찾을 수 없다는 오류로 종료될 수 있습니다](/docs/ko/errors#mcp-permission-prompt-tool-not-found).
{/* min-version: 2.1.199 */}}프롬프트 도구는 [사용자 상호작용이 필요한](/docs/ko/mcp#require-approval-for-a-specific-tool) 것으로 표시된 MCP 도구를 승인할 수 없습니다: Claude Code는 하나에 대한 `allow` 결과를 거부로 변환합니다. 이 제한은 Claude Code v2.1.199 이상이 필요합니다 | `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 문서](/docs/ko/agent-sdk/overview)에서 프로그래밍 방식 사용 세부 정보 참조) | `claude -p "query"` |
| `--prompt-suggestions` | 각 턴 후에 예측된 다음 사용자 프롬프트를 포함하는 `prompt_suggestion` 메시지를 내보냅니다. `--print`, `--output-format stream-json` 및 `--verbose`가 필요합니다. [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions) 참조 | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |
| `--remote` | `--cloud`의 더 이상 사용되지 않는 별칭 | `claude --remote "Fix the login bug"` |
| `--remote-control`, `--rc` | claude.ai 또는 Claude 앱에서도 제어할 수 있도록 [Remote Control](/docs/ko/remote-control#start-a-remote-control-session)이 활성화된 대화형 세션을 시작합니다. 선택적으로 세션의 이름을 전달할 수 있습니다 | `claude --remote-control "My Project"` |
| `--remote-control-session-name-prefix ` | 명시적 이름이 설정되지 않은 경우 자동 생성된 [Remote Control](/docs/ko/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` |
| `--resume`, `-r` | ID 또는 이름으로 특정 세션을 재개하거나 세션을 선택할 수 있는 대화형 선택기를 표시합니다. `/add-dir`으로 이 디렉토리를 추가한 세션을 포함합니다. 세션 ID를 전달하면 현재 프로젝트 디렉토리 및 해당 git worktrees만 검색합니다. v2.1.144부터 [백그라운드 세션](/docs/ko/agent-view)은 선택기에 `bg`로 표시됩니다 | `claude --resume auth-refactor` |
| `--safe-mode` | {/* min-version: 2.1.169 */}손상된 구성을 문제 해결하기 위해 모든 사용자 정의를 비활성화한 상태로 시작합니다: CLAUDE.md, skills, plugins, hooks, MCP 서버, 사용자 정의 명령어 및 에이전트, 출력 스타일, 워크플로우, 사용자 정의 테마, 사용자 정의 키 바인딩, 상태 줄 및 파일 제안 명령어, LSP 서버 및 자동 메모리가 로드되지 않습니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동하며, 이는 [`--bare`](/docs/ko/headless#start-faster-with-bare-mode)와 다릅니다. 관리되는 설정 정책은 여전히 적용되며, 정책 구성 hooks, 상태 줄 및 파일 제안 명령어를 포함합니다. 관리되는 plugins, 관리되는 skills, 관리되는 CLAUDE.md 및 정책 구성 MCP 서버는 로드되지 않습니다. [Fable 5에서 자동 폴백](/docs/ko/model-config#automatic-model-fallback)을 트리거하는 사용자 정의인지 확인하는 데 유용합니다. [`CLAUDE_CODE_SAFE_MODE`](/docs/ko/env-vars)를 설정합니다 | `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` 파일의 동일한 키를 재정의합니다. 생략한 키는 파일 기반 값을 유지합니다. [설정 우선순위](/docs/ko/settings#settings-precedence) 참조 | `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` | 로컬 터미널에서 [웹 세션](/docs/ko/claude-code-on-the-web)을 재개합니다 | `claude --teleport` |
| `--teammate-mode` | [에이전트 팀](/docs/ko/agent-teams) 팀원 표시 방식을 설정합니다: `in-process`(기본값), `auto`, `tmux` 또는 {/* min-version: 2.1.186 */}}`iterm2`(v2.1.186에서 추가됨). 기본값은 v2.1.179에서 `auto`에서 변경되었습니다. [`teammateMode`](/docs/ko/settings#available-settings) 설정을 이 세션에 대해 재정의합니다. [디스플레이 모드 선택](/docs/ko/agent-teams#choose-a-display-mode) 참조 | `claude --teammate-mode auto` |
| `--tmux` | worktree에 대한 tmux 세션을 생성합니다. `--worktree`가 필요합니다. 사용 가능한 경우 iTerm2 네이티브 창을 사용합니다. 기존 tmux의 경우 `--tmux=classic`을 전달합니다 | `claude -w feature-auth --tmux` |
| `--tools` | Claude가 사용할 수 있는 기본 제공 도구를 제한합니다. 모두 비활성화하려면 `""`를 사용하고, 모두 사용하려면 `"default"`를 사용하거나, `"Bash,Edit,Read"`와 같은 도구 이름을 사용합니다. MCP 도구는 영향을 받지 않습니다. 이들도 거부하려면 `--disallowedTools "mcp__*"`를 사용하거나, `--mcp-config` 없이 `--strict-mcp-config`를 전달하여 MCP 서버가 로드되지 않도록 합니다 | `claude --tools "Bash,Edit,Read"` |
| `--verbose` | 자세한 로깅을 활성화하고 전체 턴별 출력을 표시합니다. [`viewMode`](/docs/ko/settings#available-settings) 설정을 이 세션에 대해 재정의합니다 | `claude --verbose` |
| `--version`, `-v` | 버전 번호를 출력합니다 | `claude -v` |
| `--worktree`, `-w` | Claude를 `/.claude/worktrees/`의 격리된 [git worktree](/docs/ko/worktrees)에서 시작합니다. 이름이 지정되지 않으면 자동으로 생성됩니다. `#` 또는 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의 기본 정체성이 여전히 작업에 맞는지에 따라 선택합니다. Claude가 코딩 어시스턴트로 남아 있으면서 추가 규칙도 따라야 할 때 추가 플래그를 사용합니다: 호출별 지시사항, 출력 형식 또는 `-p` 스크립트에 대한 도메인 컨텍스트입니다. 추가하면 기본 도구 지침, 안전 지시사항 및 코딩 규칙이 유지되므로 다른 부분만 제공하면 됩니다. Claude Code의 표면, 정체성 또는 권한 모델과 다를 때 바꾸기 플래그를 사용합니다. 예를 들어 사람이 감시하지 않는 파이프라인의 비코딩 에이전트입니다. 바꾸면 도구 지침 및 안전 지시사항을 포함한 전체 기본 프롬프트가 제거되므로 작업에 필요한 모든 것에 대해 책임을 져야 합니다.
이러한 플래그는 현재 호출에만 적용됩니다. 프로젝트 간에 전환하고 공유할 수 있는 지속적인 페르소나의 경우 [출력 스타일](/docs/ko/output-styles)을 사용합니다. 프로젝트 규칙 Claude가 항상 따라야 할 경우 [CLAUDE.md](/docs/ko/memory)를 사용합니다. [시스템 프롬프트에 대한 Agent SDK 가이드](/docs/ko/agent-sdk/modifying-system-prompts#decide-on-a-starting-point)는 더 깊이 있는 동일한 결정을 다룹니다.
참고 항목
* [Chrome 확장 프로그램](/docs/ko/chrome) - 브라우저 자동화 및 웹 테스트
* [대화형 모드](/docs/ko/interactive-mode) - 바로 가기, 입력 모드 및 대화형 기능
* [빠른 시작 가이드](/docs/ko/quickstart) - Claude Code 시작하기
* [일반적인 워크플로우](/docs/ko/common-workflows) - 고급 워크플로우 및 패턴
* [설정](/docs/ko/settings) - 구성 옵션
* [Agent SDK 문서](/docs/ko/agent-sdk/overview) - 프로그래밍 방식 사용 및 통합