이 페이지의 목차
이 페이지의 목차
확인 날짜 안내
공식 문서 "CLI reference" Claude Code CLI 레퍼런스(본문 날짜 없음, 서버 Last-Modified 2026-10-20, 수집 2026-10-21) 기준이다. 플래그 이름·값·버전 조건은 원본 표기를 그대로 옮겼고 "원본 행"은 원문의 줄 번호다. 플래그와 버전 조건은 몇 주 단위로 바뀌므로 대외 자료·실제 스크립트에 쓰기 전에 공식 문서를 다시 확인한다.
Claude Code를 시작할 때 주는 하위 명령과 플래그(용어 사전) 가운데 에이전트 활용(대화 이어 가기, -p 자동화, 시스템 프롬프트, 권한, 설정·확장 로드)에 쓰는 것을 주제별로 모은 찾아보기 페이지다. 같은 일을 하는 설정 키는 Claude Code 설정 키 레퍼런스, 한 세션만 바꾸는 절차는 Claude Code 설정 바꾸기·확인·문제 해결에 있다.
원본은 claude --help가 모든 플래그를 보여 주지 않으므로 --help에 없다고 쓸 수 없는 플래그는 아니라고 말한다. Claude Code CLI 레퍼런스
이 페이지에 담은 범위#
- 담았다: 세션 시작·재개, 비대화형(
-p) 출력·한도, 시스템 프롬프트 다섯 개 전부, 권한·도구, 모델·effort·컨텍스트, 설정·확장 로드와 진단·안전 모드, 디버그. - 뺐다: 브라우저·IDE·데스크톱 연동(
--chrome,--ide,--desktop), 원격·클라우드(--remote-control,--cloud,--teleport,--environment,--ref), 채널(--channels등), 화면 표시(--ax-screen-reader,--teammate-mode,--tmux),--betas,--exec, 셀프 호스팅·게이트웨이 하위 명령. 이름은 표에 있다.
하위 명령#
| 명령 | 원본 설명 (요지) |
|---|---|
claude / claude "query" | 대화형 세션 시작 / 첫 프롬프트를 주고 시작 |
claude -p "query" | SDK로 질의하고 끝냄. cat logs.처럼 파이프 입력도 받는다 |
claude -c / claude -c -p "query" | 현재 디렉터리의 가장 최근 대화 이어 가기 / SDK로 이어 가기 |
claude -r "<session>" "query" | ID나 이름으로 세션 재개 |
claude update / claude install [version] | 최신으로 업데이트 / 네이티브 바이너리 설치·2. 같은 버전, stable, latest) |
claude auth login / logout / status | 로그인--console은 구독 대신 Console API 과금) / 로그아웃 / 인증 상태 JSONconfigDirectory 필드는 v2.1.268 이상) |
claude agents | 병렬 백그라운드 세션을 보고 보내는 agent view. --json은 스크립트용 목록. 대화형 터미널 필요 |
claude attach / logs / stop / respawn / rm | 백그라운드 세션에 붙기 / 최근 출력 / 멈추기 / 대화를 유지한 채 재시작 / 목록에서 지우기claude --resume으로 연다) |
claude auto-mode defaults / reset | 자동 모드 분류기 기본 규칙 JSON 출력autoMode 절을 지워 기본값 복원--settings 규칙은 계속 적용) |
claude doctor | 세션 없이 읽기 전용 설치·/ |
claude import [source] | 다른 코딩 에이전트의 설정을 가져오는 /를 실행--dry-run, --yes). Bedrock· |
claude mcp / claude mcp login <name> | MCP 서버 설정 / / 창 없이 OAuth 진행--no-browser) |
claude plugin | 플러그인 관리claude plugins) |
claude purge [path] | 프로젝트의 로컬 상태~/. 항목) 삭제. --dry-run으로 미리 보기 |
claude setup-token | CI· |
claude ultrareview [target] | ultrareview를 비대화형으로 실행. 성공 0, 실패 1로 종료. --json, --timeout <분> |
(2026-10-21 기준) 공식 자동 모드 설정 문서가 더하는 claude auto-mode 하위 명령: config는 내 설정을 적용한 실제 규칙을, defaults와 같은 모양(네 목록을 담은 JSON 객체 하나, 규칙마다 문장 하나)으로 출력한다. defaults --label '<규칙 이름 앞부분>'은 그 규칙 전체 문장만 보여 준다(대소문자 무시 접두어 일치, 맞는 것이 없는 섹션은 빈 목록). critique는 직접 쓴 allow·soft_deny·hard_deny·environment 항목 중 모호하거나 중복되거나 오탐을 낼 만한 것을 AI가 짚는다. reset은 Reset auto mode configuration to defaults?라고 묻고 --yes면 건너뛴다. Claude Code 자동 모드 설정 → Claude Code 자동 모드 설정하기
세션 시작·재개 플래그#
| 플래그 | 원본 설명 (요지) |
|---|---|
--continue, -c | 현재 디렉터리의 가장 최근 대화를 연다. 끝난 백그라운드 세션 포함claude -p·/인 세션은 건너뛴다. claude -p --continue는 이것들도 포함한다 |
--resume, -r | ID·. 절대 경로도 받는다. ID로 찾을 때 현재 프로젝트와 git worktree, 그다음 이 기기의 다른 모든 프로젝트를 찾는다 |
--fork-session | 재개할 때 원래 ID를 다시 쓰지 않고 새 세션 ID를 만든다--resume·--continue와 함께) |
--session-id | 대화에 특정 세션 ID를 쓴다 |
--name, -n | 세션 표시 이름. claude --resume <name>으로 재개 |
--no-session-persistence | 세션을 디스크에 저장하지 않아 재개할 수 없다. print 모드 전용. CLAUDE_ 환경 변수는 어느 모드에서든 같은 일을 한다 |
--bg, --background | 백그라운드 에이전트로 시작하고 바로 돌아온다. 시작 전에 그 디렉터리의 작업 공간 신뢰를 확인한다. -p와 함께 못 쓴다 |
--worktree, -w | <repo>/.의 격리된 git worktree에서 시작. #<번호>나 PR URL로 그 PR에서 분기 |
재개할 때 시스템 프롬프트가 어떻게 되는지는 아래 "재개한 대화의 시스템 프롬프트". 세션·체크포인트 실무는 Claude Code 세션·체크포인트 다루기.
비대화형(-p) 출력·한도 플래그#
| 플래그 | 원본 설명 (요지) |
|---|---|
--print, -p | 대화형 모드 없이 응답을 출력 |
--output-format | print 모드 출력 형식: text, json, stream-json |
--input-format | print 모드 입력 형식: text, stream-json |
--json-schema | 작업이 끝난 뒤 JSON Schema에 맞춘 검증된 JSON 출력 |
--max-turns | 에이전트 턴 수 제한 |
--max-budget-usd | 추정 API 지출이 이 금액에 닿으면 멈춘다--continue·--resume으로 돌아오면 이전 실행에서 복원한 합계는 세지 않는다. 상한에 닿으면 새 서브에이전트 생성이 Budget limit reached로 실패하고 실행 중인 백그라운드 서브에이전트를 멈춘다 |
--include-partial-messages | 부분 스트리밍 이벤트 포함. --print와 --output-format stream-json 필요 |
--include-hook-events | 훅 생명주기 이벤트를 출력 스트림에 포함. SessionStart·Setup은 항상 포함되고, Notification·SessionEnd·PreCompact·PostCompact 등은 이 플래그가 있어도 hook_started를 내지 않는다. --output-format stream-json 필요 |
--forward-subagent-text | 포그라운드 서브에이전트의 텍스트·parent_tool_use_id가 붙은 메시지로 내보내 서브에이전트 기록을 재구성할 수 있게 한다. --print와 --output-format stream-json 필요, v2.1.211 이상 |
--init / --maintenance | 세션 전에 init / maintenance matcher의 Setup 훅 실행 |
--init-only | Setup·SessionStart 훅을 돌리고 대화 없이 끝낸다 |
시스템 프롬프트 플래그#
원본은 시스템 프롬프트를 바꾸는 플래그 다섯 개를 둔다. 넷은 텍스트를 정하고, --system-prompt-snapshot은 대화가 시작 때의 텍스트를 계속 쓸지 정한다. 다섯 모두 대화형·비대화형에서 작동한다. Claude Code CLI 레퍼런스
| 플래그 | 동작 (원본) | 원본 예 |
|---|---|---|
--system-prompt | 기본 프롬프트 전체를 대체 | claude --system-prompt "You are a Python expert" |
--system-prompt-file | 파일 내용으로 대체 | claude --system-prompt-file ./ |
--append-system-prompt | 기본 프롬프트 끝에 덧붙임 | claude --append-system-prompt "Always use TypeScript" |
--append-system-prompt-file | 파일 내용을 기본 프롬프트에 덧붙임 | claude --append-system-prompt-file ./ |
--system-prompt-snapshot | off면 매 요청 프롬프트를 다시 만든다. 기본값 on이면 기록이 적용되는 곳에서 기록된 프롬프트를 다시 쓴다. v2.1.257 이상 | claude --append-system-prompt "Draft rules" --system-prompt-snapshot off |
- 조합: 기본 프롬프트를 대체하면서 자기 텍스트를 덧붙이려면 대체 플래그와 덧붙이기 플래그를 함께 준다. v2.1.283 이상에서는 같은 플래그의 문자열형과 파일형(
--append-system-prompt와--append-system-prompt-file)도 함께 쓰고 둘 다 반영된다. - 순서:
claude -p --append-system-prompt-file ./style.md --append-system-prompt "Always reply in French" "Summarize README.md"에서 Claude는 기본 시스템 프롬프트,style.md내용, 빈 줄,Always reply in French순으로 받는다.--append-system-prompt를 먼저 적어도 파일 내용이 먼저 온다. - 캐시 경계: 대체 텍스트에 매번 같은 지시와 실행마다 바뀌는 맥락이 섞이면 둘 사이에
__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__만 있는 줄을 넣는다. Claude Code는 첫 번째 그런 줄에서 프롬프트를 나누고 그 줄을 지우며, 위쪽은 캐시에 남고 아래쪽만 바뀐다. v2.1.275 이상. 이 분할이 적용되는 구성은 원본이 Agent SDK 문서로 넘긴다. - 여러 사용자·기기의 같은 작업:
--exclude-dynamic-system-prompt-sections는 자동 메모리 위치 같은 사용자별 맥락을 시스템 프롬프트에서 첫 사용자 메시지로 옮겨 프롬프트 캐시 재사용을 높인다. 기본 시스템 프롬프트일 때만 적용되고--system-prompt·--system-prompt-file이 있으면 무시된다. 스크립트형 다중 사용자 작업에-p와 함께 쓰라고 한다. - 서브에이전트:
--append-subagent-system-prompt는 모든 서브에이전트(중첩 포함, 포크 서브에이전트 제외. 포크는 대화 자신의 프롬프트를 다시 쓴다)의 시스템 프롬프트 끝에 덧붙인다.-p비대화형에서만 적용되고 v2.1.205 이상이다. 파일형--append-subagent-system-prompt-file은 v2.1.261 이상이고 두 플래그는 함께 쓸 수 없다. → 서브에이전트
덧붙이기와 대체를 고르는 기준#
| 상황 | 쓸 것 | 원본의 이유 |
|---|---|---|
Claude가 코딩 도우미로 남되 추가 규칙을 따라야 함: 실행마다 주는 지시, 출력 서식, -p 스크립트의 도메인 맥락 | --append-system-prompt(-file) | 기본 도구 안내· |
| 화면· | --system-prompt(-file) | 도구 안내와 안전 지시를 포함한 기본 프롬프트 전체가 빠지므로, 그 작업에 여전히 필요한 것은 직접 책임진다 |
| 프로젝트에서 바꿔 가며 공유할 지속 페르소나 | 출력 스타일 | 원본이 이 용도로 출력 스타일을 가리킨다 |
| Claude가 항상 따라야 할 프로젝트 관례 | 메모리 | 원본이 이 용도로 CLAUDE.md를 가리킨다 |
근거: Claude Code CLI 레퍼런스. 다른 확장 기능과의 비교 전체는 Claude Code 확장 기능 고르기.
재개한 대화의 시스템 프롬프트#
- 기본 동작: Claude Code는 대화의 첫 요청에서 시스템 프롬프트 플래그 텍스트를 반영해 시스템 프롬프트를 한 번 만들고 세션에 기록한다. 대화가 컴팩션되기 전까지 이후 모든 요청은 기록된 프롬프트를 쓰고,
--resume·--continue로 돌아와도 마찬가지다. 나중 실행에서 다른 플래그 텍스트를 주거나 아무것도 주지 않으면, 그 변화는 대화가 컴팩션될 때나 새 대화를 시작할 때 반영된다. - 기록하지 않는 경우: 클라우드 세션 밖에서
--bare나CLAUDE_CODE_SIMPLE=1로 시작하면--system-prompt-snapshot on을 주지 않는 한 기록하지 않는다. v2.1.268 이전에는 feature flag를 받지 않는 세션(Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry 포함)이 매 요청 프롬프트를 다시 만들었고--system-prompt-snapshot은 효과가 없었다. - 캐시와의 관계(2026-10-26 기준): 공식 Prompt caching 문서도 같은 동작을 적는다. 재개할 때 다른
--append-system-prompt텍스트를 주면 시스템 프롬프트가 바뀌지만, 기본으로 재개한 대화는 시작할 때의 시스템 프롬프트를 유지해 기록이 같은 앞부분 뒤에 남고, 변화는 컴팩션 때나 새 대화에서 반영된다. 시스템 프롬프트가 바뀌면 그 뒤 캐시가 모두 무효가 된다. Claude Code 프롬프트 캐싱 → 프롬프트 캐싱 - 문구를 다듬는 중이면:
--continue로 이어 가며 문구를 고칠 때처럼 매 요청 다시 만들려면--system-prompt-snapshot off를 준다. v2.1.265 이전에는 시스템 프롬프트 플래그를 주기만 해도--system-prompt-snapshot on이 없으면 기록이 꺼졌다.
원본끼리 달랐던 점(정리됨)--append-system-prompt 재개 동작
- Steering Claude Code (2026-06-18): 시스템 프롬프트 덧붙이기는 "Never compacted; applies only to that invocation"이고, 실행할 때 넘겨 "only applies to that invocation, rather than persisted as a file across sessions"라고 쓴다.
- Claude Code CLI 레퍼런스 (원본 날짜 미상, 서버 Last-Modified 2026-10-20, 수집 2026-10-21): 플래그 텍스트는 대화의 첫 요청에서 만든 시스템 프롬프트에 들어가 세션에 기록되고, 컴팩션 전까지
--resume·--continue로 돌아온 나중 실행에서도 그대로 쓰인다. 나중 실행에서 플래그를 바꾸거나 빼면 컴팩션 때나 새 대화에서 반영된다. 위 "기록하지 않는 경우"의 예외가 있다. - 차이: 같은 대화를 재개하면 블로그의 "그 실행에만"과 달리 앞 실행의 텍스트가 컴팩션 전까지 남는다. 또 나중 실행의 다른 플래그 텍스트(또는 플래그 없음)는 컴팩션 때나 새 대화에서 반영되므로, 재개하면서 플래그를 뺐다면 컴팩션 뒤에는 덧붙인 텍스트가 빠진다.
- 블로그 문장이 남은 페이지(출력 스타일, 메모리(CLAUDE.md), 컨텍스트 비용, Claude Code 확장 기능 고르기, 장기 작업 컨텍스트 관리)에는 두 주장과 이 페이지 링크만 담은 짧은 ‘원본끼리 달랐던 점’ 상자를 둔다.
- 덧붙인 텍스트가 설정 파일 같은 파일로 저장되는지는 CLI 문서가 말하지 않는다. 공식 메모리 문서는 이 플래그를 "You pass it at launch"라고만 하고 재개 동작은 CLI 문서로 넘긴다. Claude Code 메모리
- 설명과 실무에는 공식 CLI 문서의 동작을 기준으로 쓴다. 블로그 문장은 2026-06-18 글의 표현으로 남긴다.
권한·도구 플래그 (조건 포함)#
| 플래그 | 원본 설명 (요지) |
|---|---|
--permission-mode | 지정한 권한 모드로 시작: default, acceptEdits, plan, auto, dontAsk, bypassPermissions, 그리고 default의 별칭 manualdefaultMode를 덮는다 |
--dangerously-skip-permissions | 권한 확인 창을 건너뛴다. --permission-mode bypassPermissions와 같다. 무엇을 건너뛰고 무엇을 건너뛰지 않는지는 원본이 권한 모드 문서로 넘긴다. --bg로 시작한 세션은 supervisor가 재시작해도 이 모드가 유지된다 |
--allow-dangerously-skip-permissions | bypassPermissions를 Shift+Tab 순환에 넣되 그 모드로 시작하지는 않는다 |
--allowedTools, --allowed-tools | 묻지 않고 실행할 도구. 네트워크 경로 읽기는 예외. 쓸 수 있는 도구 자체를 줄이려면 --tools |
--disallowedTools, --disallowed-tools | deny 규칙. 도구 이름만 쓰면 그 도구를 Claude의 컨텍스트에서 뺀다"*"는 모든 도구, "mcp__*"는 모든 MCP 도구). Bash(rm *) 같은 범위 규칙은 도구를 남기고 맞는 호출만 막으며, 원본은 그 일치가 "as written"이라고 링크한다 |
--tools | 쓸 수 있는 내장 도구 제한""는 전부 끄기, "default", "Bash,Edit,Read"). macOS·default 세트는 Glob·Grep을 뺀다. MCP 도구에는 영향이 없어 함께 막으려면 --disallowedTools "mcp__*" |
--permission-prompt-tool | 비대화형에서 권한 확인을 처리할 MCP 도구mcp__). 사용자 상호작용이 필요하다고 표시된 MCP 도구는 승인하지 못하고, allow 결과를 deny로 바꾼다 |
--permission-prompts | print 모드에서 확인 창에 누가 답할지. 기본 host는 Agent SDK 호스트나 --permission-prompt-tool로 보내고, none이면 아무도 답할 수 없다고 보고 거부한다. v2.1.259 이상 |
--add-dir | 읽고 고칠 작업 디렉터리 추가. 파일 접근만 주고 그 디렉터리의 . 설정 대부분은 찾지 않는다. 세션을 넘어 유지하려면 permissions. 설정 |
권한 모드 고르기는 Claude Code 권한 모드 고르기, 모드 정의는 권한 모드.
모델·effort·컨텍스트 플래그#
| 플래그 | 원본 설명 (요지) |
|---|---|
--model | 세션 모델을 별칭sonnet, opus, haiku, fable)이나 전체 이름으로. model 설정과 ANTHROPIC_MODEL을 덮는다 |
--fallback-model | 주 모델이 과부하거나 쓸 수 없을 때fallbackModel 설정 |
--effort | 세션 effort: low, medium, high, xhigh, max, ultracodeultracode는 v2.1.203 이상). modelSettings·effortLevel 설정을 이 세션만 덮고 저장되지 않는다 |
--autocompact <auto|tokens> | 저장된 설정을 바꾸지 않고 이 세션의 자동 컴팩션 창을 정한다. /와 같은 값. v2.1.221 이상 |
--advisor <model> | 이 세션에 서버 쪽 advisor 도구를 켠다fable, opus, sonnet 또는 전체 ID). advisorModel 설정보다 우선. fable은 Fable 접근 권한 필요 |
컨텍스트가 찰 때의 대처는 장기 작업 컨텍스트 관리.
설정·확장 로드와 안전 모드 플래그 (조건 포함)#
| 플래그 | 원본 설명 (요지) |
|---|---|
--settings | 설정 JSON 파일 경로나 인라인 JSON. 같은 키의 settings. 값을 이 세션만 덮고, 빠진 키는 파일 값을 유지한다. 파일은 2 MiB 이하의 일반 파일이어야 한다 |
--setting-sources | 로드할 설정 출처를 쉼표로user, project, local) |
--bare | 최소 모드: 훅, 스킬, 커스텀 명령, 서브에이전트, 설치된 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 탐색을 건너뛰어 스크립트 호출을 빨리 시작한다. --add-dir로 준 디렉터리의 스킬은 로드된다. Bash·CLAUDE_CODE_SIMPLE을 설정한다 |
--safe-mode | 깨진 설정을 진단하려고 사용자 정의를 모두 끄고 시작: CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 커스텀 명령·CLAUDE_를 설정한다 |
--restricted | 공유 기기에서 평가 하네스가 claude를 돌릴 때 명령 실행과 그 기기의 user·--tools에 개별 이름으로 지정하면 예외default 프리셋으로는 안 됨). 내장 파일 도구를 작업 디렉터리로 묶고, managed settings와 --settings만 로드하며, bypassPermissions와 클라우드 세션 생성을 거부한다. v2.1.248 이상 |
--mcp-config | JSON 파일·-p와 함께면 연결 중인 서버를 MCP_TIMEOUT |
--strict-mcp-config | --mcp-config의 MCP 서버만 쓰고 다른 MCP 설정은 무시한다. managed MCP 파일이 있을 때의 동작은 원본이 managed MCP 문서로 넘긴다 |
--plugin-dir / --plugin-url | 디렉터리·..에서 이 세션만 플러그인 로드 |
--agents | JSON으로 서브에이전트 정의. --print와 함께면 JSON 파일 경로도 받는다 |
--agent | 현재 세션의 에이전트 지정agent 설정을 덮는다) |
--disable-slash-commands | 이 세션의 모든 스킬· |
- 보안 문장의 조건:
--bare·--safe-mode·--restricted는 모두 "무엇을 로드하지 않는가"를 바꾸는 시작 플래그다.--safe-mode에서도 managed 정책은 계속 적용돼 정책으로 설정한 훅·상태 줄·파일 제안 명령은 돌지만, managed 플러그인·스킬·CLAUDE.md와 정책으로 설정한 MCP 서버는 로드되지 않는다.--restricted는 managed settings와--settings만 로드한다.--bare가 managed 정책을 어떻게 다루는지는 원본이 말하지 않는다.--restricted가 빼는 실행 도구와 WebFetch도--tools에 개별 이름으로 적으면 다시 들어온다(default프리셋으로는 안 된다). Claude Code CLI 레퍼런스 조직은 manageddisableSideloadFlags로--agents같은 시작 플래그를 거부할 수 있다(v2.1.193 이상). Claude Code managed settings 배포 → Claude Code 관리자 권한 통제 - 남의 저장소에서
-p를 돌릴 때--bare를 쓰는 이유는 Claude Code 차단 훅 단단하게 만들기.
디버그 플래그#
| 플래그 | 원본 설명 (요지) |
|---|---|
--debug | 디버그 모드, 범주 필터 선택--debug, --debug='!mcp'). 필터는 = 형태에서만 걸리고, 공백으로 띄우면 필터 없이 디버그만 켠다 |
--debug-file <path> | 디버그 로그를 특정 파일에. 디버그 모드를 함께 켜고 CLAUDE_보다 우선 |
--verbose | 턴별 전체 출력. 이 세션의 viewMode 설정을 덮는다 |
훅이 안 돌 때 디버그 로그 보는 법은 Claude Code 훅 문제 해결.
관련 페이지#
- Claude Code — 명령·플래그 요약
- 출력 스타일 — 덧붙이기와 출력 스타일 고르기, ‘원본끼리 달랐던 점’ 상자
- 메모리(CLAUDE.md) — 지시를 CLAUDE.md에 둘지 플래그로 줄지
- Claude Code 설정 키 레퍼런스 — 같은 동작을 파일로 영구히 정하는 키
- Claude Code 설정 바꾸기·확인·문제 해결 — 한 세션만 바꾸기
- Claude Code 세션·체크포인트 다루기 — 이어 가기와 갈라 보기