Claude Code CLI 레퍼런스

한 줄 요약: Claude Code 공식 문서 "CLI reference". claude 하위 명령(세션 시작·재개, 인증, 백그라운드 세션, MCP·플러그인, 진단)과 실행 플래그 전체를 표로 싣고, 시스템 프롬프트를 바꾸는 플래그 다섯 개의 동작·조합 순서·고르는 기준과, 재개한 대화에서 시스템 프롬프트가 어떻게 유지되는지를 따로 설명한다.

원본 정보#

• 제목: CLI reference
• 발행: Anthropic, Claude Code 공식 문서. 본문에 날짜 없음(원본 날짜 미상). 서버 Last-Modified 2026-10-20
• URL: https://code.claude.com/docs/en/cli-reference (새 창)
• 수집(fetch)일: 2026-10-21. 본문의 플래그 이름, 값, 버전 조건(v2.1.111~v2.1.290)은 이 날짜 기준이다.
• 구성: CLI commands 표 → CLI flags 표 → System prompt flags → System prompt flags in resumed conversations → See also.

핵심 주장#

1. claude --help에 없다고 없는 플래그가 아니다. 원본: "claude --help does not list every flag, so a flag's absence from --help does not mean it is unavailable." 하위 명령을 잘못 치면 가장 가까운 명령을 제안하고 세션을 시작하지 않고 끝난다. → Claude Code CLI 플래그
2. 시스템 프롬프트 플래그는 다섯 개이고, 대화형·비대화형 모두에서 작동한다. 넷은 텍스트를 정하고(--system-prompt, --system-prompt-file은 기본 프롬프트 전체를 대체, --append-system-prompt, --append-system-prompt-file은 기본 프롬프트 끝에 덧붙임), --system-prompt-snapshot은 대화가 시작 때의 텍스트를 계속 쓸지 정한다. 대체 플래그와 덧붙이기 플래그는 함께 쓸 수 있고, v2.1.283 이상에서는 같은 플래그의 문자열형과 파일형도 함께 쓸 수 있다. 이때 파일 내용이 먼저, 빈 줄, 그다음 문자열이 붙고 인자 순서와 상관없다. → Claude Code CLI 플래그
3. 고르는 기준은 "기본 정체성이 그 일에 맞는가"다. 덧붙이기는 Claude가 코딩 도우미로 남되 추가 규칙(실행마다 주는 지시, 출력 서식, -p 스크립트의 도메인 맥락)을 따라야 할 때 쓰고, 기본 도구 안내·안전 지시·코딩 관례를 유지한다. 대체는 화면·정체성·권한 모델이 Claude Code와 다를 때(사람이 보지 않는 파이프라인의 비코딩 에이전트) 쓰고, 도구 안내와 안전 지시까지 모두 빠지므로 필요한 것을 직접 책임져야 한다. 프로젝트에서 바꿔 가며 공유할 지속 페르소나는 출력 스타일, 항상 따라야 할 프로젝트 관례는 CLAUDE.md를 쓴다. → 출력 스타일, 메모리(CLAUDE.md)
4. 시스템 프롬프트는 대화의 첫 요청에서 한 번 만들어 세션에 기록되고, 컴팩션 전까지 재개해도 그대로 쓴다. 원본: "By default, Claude Code builds the system prompt once, on a conversation's first request, with the text from any system prompt flags applied, and records it in the session. Until the conversation is compacted, every later request uses that recorded prompt, including after you return to the conversation with --resume or --continue. If you pass different system prompt flag text, or none, on that later launch, it takes effect once the conversation is compacted or when you start a new conversation." 예외는 --system-prompt-snapshot off(매 요청 다시 만듦, v2.1.257 이상), 클라우드 세션 밖의 --bare·CLAUDE_CODE_SIMPLE=1(--system-prompt-snapshot on을 주지 않으면 기록하지 않음), v2.1.268 이전의 feature flag를 받지 않는 세션(Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry 포함, 매 요청 다시 만듦), v2.1.265 이전의 시스템 프롬프트 플래그 사용(--system-prompt-snapshot on이 없으면 기록 꺼짐)이다. 블로그 Steering Claude Code의 "그 실행에만 적용된다"와 다르다. 상충 표시는 Claude Code CLI 플래그(허브).
5. 많은 플래그가 "이 세션만, 저장된 설정은 그대로"이고, 일부는 조건이 붙은 안전장치다. --effort는 세션만 덮고 저장되지 않으며, --autocompact는 저장된 설정을 바꾸지 않고, --settings는 같은 키의 파일 값을 그 세션만 덮는다. --restricted는 평가 하네스용으로 명령·코드 실행 도구와 WebFetch를 빼고(--tools로 개별 지정하면 예외), 파일 도구를 작업 디렉터리로 묶고, managed settings와 --settings만 로드하며, bypassPermissions와 클라우드 세션 생성을 거부한다(v2.1.248 이상). --safe-mode는 CLAUDE.md·스킬·플러그인·훅·MCP 등 사용자 정의를 끄지만 managed 정책은 계속 적용돼 정책으로 설정한 훅·상태 줄·파일 제안 명령은 돈다. 반면 managed 플러그인·스킬·CLAUDE.md와 정책으로 설정한 MCP 서버는 로드되지 않는다. → Claude Code CLI 플래그

원본의 예시 (2026-10-21 기준)#

• 덧붙이기 두 개를 함께: 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를 받는다.
• 덧붙이기 문구를 다듬는 동안 매 요청 다시 만들기: claude --append-system-prompt "Draft rules" --system-prompt-snapshot off.
• 캐시 경계: 대체 텍스트에 실행마다 같은 지시와 실행마다 바뀌는 맥락이 섞이면 둘 사이에 __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__만 있는 줄을 넣는다. Claude Code는 첫 번째 그런 줄에서 프롬프트를 나누고 그 줄을 지우며, 위쪽은 캐시에 남고 아래쪽만 바뀐다. v2.1.275 이상.
• 여러 사용자·기기의 같은 작업에서 캐시 재사용: claude -p --exclude-dynamic-system-prompt-sections "query". 기본 시스템 프롬프트일 때만 적용되고 --system-prompt·--system-prompt-file이 있으면 무시된다.
• 서브에이전트에 덧붙이기: claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query". -p 비대화형에서만, 포크 서브에이전트 제외, v2.1.205 이상. 파일형 --append-subagent-system-prompt-file은 v2.1.261 이상이고 두 플래그는 함께 쓸 수 없다.
• CI 무인 실행에서 권한 확인 창을 아무도 답할 수 없을 때: claude -p --permission-prompts none "query"(v2.1.259 이상).

원본이 링크한 관련 문서#

Headless(bare mode, 서브에이전트 메시지 따라가기, 무인 실행 권한), Agent SDK의 Modifying system prompts(캐시 분할이 적용되는 구성), Sessions(재개·백그라운드 세션), Agent view, Model configuration(auto-compact 창, fallback 체인), Environment variables, Permissions(작업 디렉터리, 네트워크 경로 → Claude Code 권한 설정), Errors, Channels, Remote Control, Self-hosted environments, Plugins CLI reference, Worktrees, Cloud environments.