CLI 명령어
| 명령어 | 설명 | 예시 |
|---|
claude | 대화형 REPL 시작 | claude |
claude "query" | 초기 프롬프트로 REPL 시작 | 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-id>" "query" | ID로 세션 재개 | claude -r "abc123" "Finish this PR" |
claude update | 최신 버전으로 업데이트 | claude update |
claude mcp | Model Context Protocol (MCP) 서버 구성 | Claude Code MCP 문서를 참조하세요. |
CLI 플래그
이러한 명령줄 플래그로 Claude Code의 동작을 사용자 정의합니다:
| 플래그 | 설명 | 예시 |
|---|
--add-dir | Claude가 액세스할 추가 작업 디렉토리 추가 (각 경로가 디렉토리로 존재하는지 검증) | claude --add-dir ../apps ../lib |
--agents | JSON을 통해 사용자 정의 서브에이전트를 동적으로 정의 (형식은 아래 참조) | claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}' |
--allowedTools | settings.json 파일에 추가로 사용자 권한 요청 없이 허용되어야 하는 도구 목록 | "Bash(git log:*)" "Bash(git diff:*)" "Read" |
--disallowedTools | settings.json 파일에 추가로 사용자 권한 요청 없이 거부되어야 하는 도구 목록 | "Bash(git log:*)" "Bash(git diff:*)" "Edit" |
--print, -p | 대화형 모드 없이 응답 출력 (SDK 문서에서 프로그래밍 방식 사용 세부 정보 참조) | claude -p "query" |
--system-prompt | 전체 시스템 프롬프트를 사용자 정의 텍스트로 바꾸기 (대화형 및 인쇄 모드 모두에서 작동; v2.0.14에 추가됨) | claude --system-prompt "You are a Python expert" |
--system-prompt-file | 파일에서 시스템 프롬프트 로드, 기본 프롬프트 바꾸기 (인쇄 모드만; v1.0.54에 추가됨) | claude -p --system-prompt-file ./custom-prompt.txt "query" |
--append-system-prompt | 기본 시스템 프롬프트 끝에 사용자 정의 텍스트 추가 (대화형 및 인쇄 모드 모두에서 작동; v1.0.55에 추가됨) | claude --append-system-prompt "Always use TypeScript" |
--output-format | 인쇄 모드의 출력 형식 지정 (옵션: text, json, stream-json) | claude -p "query" --output-format json |
--input-format | 인쇄 모드의 입력 형식 지정 (옵션: text, stream-json) | claude -p --output-format json --input-format stream-json |
--include-partial-messages | 출력에 부분 스트리밍 이벤트 포함 (--print 및 --output-format=stream-json 필요) | claude -p --output-format stream-json --include-partial-messages "query" |
--verbose | 상세 로깅 활성화, 전체 턴별 출력 표시 (인쇄 및 대화형 모드 모두에서 디버깅에 유용) | claude --verbose |
--max-turns | 비대화형 모드에서 에이전트 턴 수 제한 | claude -p --max-turns 3 "query" |
--model | 현재 세션의 모델을 최신 모델의 별칭(sonnet 또는 opus) 또는 모델의 전체 이름으로 설정 | claude --model claude-sonnet-4-5-20250929 |
--permission-mode | 지정된 권한 모드에서 시작 | claude --permission-mode plan |
--permission-prompt-tool | 비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구 지정 | claude -p --permission-prompt-tool mcp_auth_tool "query" |
--resume | ID로 특정 세션을 재개하거나 대화형 모드에서 선택하여 재개 | claude --resume abc123 "query" |
--continue | 현재 디렉토리에서 가장 최근 대화 로드 | claude --continue |
--dangerously-skip-permissions | 권한 프롬프트 건너뛰기 (주의해서 사용) | claude --dangerously-skip-permissions |
--output-format json 플래그는 스크립팅 및 자동화에 특히 유용하며,
Claude의 응답을 프로그래밍 방식으로 구문 분석할 수 있습니다.
에이전트 플래그 형식
--agents 플래그는 하나 이상의 사용자 정의 서브에이전트를 정의하는 JSON 객체를 허용합니다. 각 서브에이전트는 고유한 이름(키로 사용)과 다음 필드를 포함하는 정의 객체가 필요합니다:
| 필드 | 필수 | 설명 |
|---|
description | 예 | 서브에이전트를 호출해야 할 때를 설명하는 자연어 설명 |
prompt | 예 | 서브에이전트의 동작을 안내하는 시스템 프롬프트 |
tools | 아니오 | 서브에이전트가 사용할 수 있는 특정 도구의 배열 (예: ["Read", "Edit", "Bash"]). 생략하면 모든 도구를 상속받습니다 |
model | 아니오 | 사용할 모델 별칭: sonnet, opus, 또는 haiku. 생략하면 기본 서브에이전트 모델을 사용합니다 |
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}'
시스템 프롬프트 플래그
Claude Code는 시스템 프롬프트를 사용자 정의하기 위한 세 가지 플래그를 제공하며, 각각 다른 목적으로 사용됩니다:
| 플래그 | 동작 | 모드 | 사용 사례 |
|---|
--system-prompt | 전체 기본 프롬프트 바꾸기 | 대화형 + 인쇄 | Claude의 동작 및 지시사항에 대한 완전한 제어 |
--system-prompt-file | 파일 내용으로 바꾸기 | 인쇄만 | 재현성 및 버전 제어를 위해 파일에서 프롬프트 로드 |
--append-system-prompt | 기본 프롬프트에 추가 | 대화형 + 인쇄 | 기본 Claude Code 동작을 유지하면서 특정 지시사항 추가 |
-
--system-prompt: Claude의 시스템 프롬프트에 대한 완전한 제어가 필요할 때 사용합니다. 이는 모든 기본 Claude Code 지시사항을 제거하여 백지 상태를 제공합니다.
claude --system-prompt "You are a Python expert who only writes type-annotated code"
-
--system-prompt-file: 파일에서 사용자 정의 프롬프트를 로드하려고 할 때 사용합니다. 팀 일관성 또는 버전 제어 프롬프트 템플릿에 유용합니다.
claude -p --system-prompt-file ./prompts/code-review.txt "Review this PR"
-
--append-system-prompt: Claude Code의 기본 기능을 유지하면서 특정 지시사항을 추가하려고 할 때 사용합니다. 대부분의 사용 사례에서 가장 안전한 옵션입니다.
claude --append-system-prompt "Always use TypeScript and include JSDoc comments"
--system-prompt와 --system-prompt-file은 상호 배타적입니다. 두 플래그를 동시에 사용할 수 없습니다.
대부분의 사용 사례에서 --append-system-prompt를 권장합니다. Claude Code의 기본 제공 기능을 유지하면서 사용자 정의 요구사항을 추가합니다. --system-prompt 또는 --system-prompt-file은 시스템 프롬프트에 대한 완전한 제어가 필요할 때만 사용하세요.
-p)에 대한 자세한 정보(출력 형식, 스트리밍, 상세 로깅 및 프로그래밍 방식 사용 포함)는
SDK 문서를 참조하세요.
참고 항목
