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 auth login	Anthropic 계정에 로그인. --email로 이메일 주소를 미리 입력하고 --sso로 SSO 인증을 강제할 수 있습니다	claude auth login --email [email protected] --sso
claude auth logout	Anthropic 계정에서 로그아웃	claude auth logout
claude auth status	인증 상태를 JSON으로 표시. --text를 사용하면 사람이 읽기 쉬운 형태로 출력. 로그인 상태이면 종료 코드 0, 아니면 1을 반환	claude auth status
claude agents	구성된 모든 서브에이전트를 소스별로 그룹화하여 표시	claude agents
claude mcp	Model Context Protocol (MCP) 서버 구성	Claude Code MCP 문서를 참조하세요.
claude remote-control	Claude.ai 또는 Claude 앱에서 로컬로 실행 중인 Claude Code를 제어할 수 있는 원격 제어 세션을 시작합니다. 플래그는 원격 제어를 참조하세요	claude remote-control

CLI 플래그

다음 명령줄 플래그로 Claude Code의 동작을 커스터마이즈할 수 있습니다:

플래그	설명	예시
--add-dir	Claude가 접근할 수 있는 추가 작업 디렉토리를 추가합니다 (각 경로가 디렉토리로 존재하는지 검증)	claude --add-dir ../apps ../lib
--agent	현재 세션에 사용할 에이전트를 지정합니다 (agent 설정을 재정의)	claude --agent my-custom-agent
--agents	JSON을 통해 커스텀 서브에이전트를 동적으로 정의합니다 (아래 형식 참조)	claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'
--allow-dangerously-skip-permissions	즉시 활성화하지 않고 권한 우회를 옵션으로 활성화합니다. --permission-mode와 조합하여 사용 가능합니다 (주의해서 사용)	claude --permission-mode plan --allow-dangerously-skip-permissions
--allowedTools	권한 확인 없이 실행되는 도구입니다. 패턴 매칭은 권한 규칙 구문을 참조하세요. 사용 가능한 도구를 제한하려면 --tools를 대신 사용하세요	"Bash(git log *)" "Bash(git diff *)" "Read"
--append-system-prompt	기본 시스템 프롬프트 끝에 커스텀 텍스트를 추가합니다	claude --append-system-prompt "Always use TypeScript"
--append-system-prompt-file	파일에서 추가 시스템 프롬프트 텍스트를 로드하여 기본 프롬프트에 추가합니다	claude --append-system-prompt-file ./extra-rules.txt
--betas	API 요청에 포함할 베타 헤더 (API 키 사용자 전용)	claude --betas interleaved-thinking
--chrome	웹 자동화 및 테스트를 위한 Chrome 브라우저 통합을 활성화합니다	claude --chrome
--continue, -c	현재 디렉토리에서 가장 최근 대화를 로드합니다	claude --continue
--dangerously-skip-permissions	모든 권한 프롬프트를 건너뜁니다 (주의해서 사용)	claude --dangerously-skip-permissions
--debug	선택적 카테고리 필터링과 함께 디버그 모드를 활성화합니다 (예: "api,hooks" 또는 "!statsig,!file")	claude --debug "api,mcp"
--disable-slash-commands	이 세션에서 모든 스킬과 명령어를 비활성화합니다	claude --disable-slash-commands
--disallowedTools	모델의 컨텍스트에서 제거되어 사용할 수 없는 도구입니다	"Bash(git log *)" "Bash(git diff *)" "Edit"
--fallback-model	기본 모델이 과부하일 때 지정된 모델로 자동 폴백을 활성화합니다 (print 모드 전용)	claude -p --fallback-model sonnet "query"
--fork-session	재개 시 원본을 재사용하지 않고 새 세션 ID를 생성합니다 (--resume 또는 --continue와 함께 사용)	claude --resume abc123 --fork-session
--from-pr	특정 GitHub PR에 연결된 세션을 재개합니다. PR 번호 또는 URL을 허용합니다. 세션은 gh pr create를 통해 생성될 때 자동으로 연결됩니다	claude --from-pr 123
--ide	시작 시 유효한 IDE가 정확히 하나일 경우 자동으로 연결합니다	claude --ide
--init	초기화 훅을 실행하고 대화형 모드를 시작합니다	claude --init
--init-only	초기화 훅만 실행하고 종료합니다 (대화형 세션 없음)	claude --init-only
--include-partial-messages	출력에 부분 스트리밍 이벤트를 포함합니다 (--print 및 --output-format=stream-json 필요)	claude -p --output-format stream-json --include-partial-messages "query"
--input-format	print 모드의 입력 형식을 지정합니다 (옵션: text, stream-json)	claude -p --output-format json --input-format stream-json
--json-schema	에이전트가 워크플로를 완료한 후 JSON Schema에 맞는 검증된 JSON 출력을 받습니다 (print 모드 전용, 구조화된 출력 참조)	claude -p --json-schema '{"type":"object","properties":{...}}' "query"
--maintenance	유지보수 훅을 실행하고 종료합니다	claude --maintenance
--max-budget-usd	중지 전 API 호출에 사용할 최대 달러 금액 (print 모드 전용)	claude -p --max-budget-usd 5.00 "query"
--max-turns	에이전트 턴 수를 제한합니다 (print 모드 전용). 제한에 도달하면 오류와 함께 종료됩니다. 기본값은 제한 없음	claude -p --max-turns 3 "query"
--mcp-config	JSON 파일 또는 문자열에서 MCP 서버를 로드합니다 (공백으로 구분)	claude --mcp-config ./mcp.json
--model	현재 세션의 모델을 설정합니다. 최신 모델의 별칭(sonnet 또는 opus) 또는 모델의 전체 이름을 사용할 수 있습니다	claude --model claude-sonnet-4-6
--no-chrome	이 세션에서 Chrome 브라우저 통합을 비활성화합니다	claude --no-chrome
--no-session-persistence	세션 영속성을 비활성화하여 세션이 디스크에 저장되지 않고 재개할 수 없게 합니다 (print 모드 전용)	claude -p --no-session-persistence "query"
--output-format	print 모드의 출력 형식을 지정합니다 (옵션: text, json, stream-json)	claude -p "query" --output-format json
--permission-mode	지정된 권한 모드로 시작합니다	claude --permission-mode plan
--permission-prompt-tool	비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다	claude -p --permission-prompt-tool mcp_auth_tool "query"
--plugin-dir	이 세션에서만 디렉토리에서 플러그인을 로드합니다 (반복 가능)	claude --plugin-dir ./my-plugins
--print, -p	대화형 모드 없이 응답을 출력합니다 (프로그래밍 방식 사용에 대한 자세한 내용은 Agent SDK 문서를 참조하세요)	claude -p "query"
--remote	claude.ai에서 제공된 작업 설명으로 새 웹 세션을 생성합니다	claude --remote "Fix the login bug"
--resume, -r	ID 또는 이름으로 특정 세션을 재개하거나, 세션을 선택할 수 있는 대화형 선택기를 표시합니다	claude --resume auth-refactor
--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 문자열	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	웹 세션을 로컬 터미널에서 재개합니다	claude --teleport
--teammate-mode	에이전트 팀 팀원의 표시 방식을 설정합니다: auto (기본값), in-process, 또는 tmux. 에이전트 팀 설정을 참조하세요	claude --teammate-mode in-process
--tools	Claude가 사용할 수 있는 내장 도구를 제한합니다. ""로 모두 비활성화, "default"로 모두 활성화, 또는 "Bash,Edit,Read"처럼 도구 이름을 지정합니다	claude --tools "Bash,Edit,Read"
--verbose	상세 로깅을 활성화하여 전체 턴별 출력을 표시합니다	claude --verbose
--version, -v	버전 번호를 출력합니다	claude -v
--worktree, -w	<repo>/.claude/worktrees/<name>에 격리된 git worktree에서 Claude를 시작합니다. 이름을 지정하지 않으면 자동 생성됩니다	claude -w feature-auth

팁:

--output-format json 플래그는 스크립팅과 자동화에 특히 유용하며,
Claude의 응답을 프로그래밍 방식으로 파싱할 수 있게 해줍니다.

Agents 플래그 형식

--agents 플래그는 하나 이상의 커스텀 서브에이전트를 정의하는 JSON 객체를 받습니다. 각 서브에이전트는 고유한 이름(키)과 다음 필드를 가진 정의 객체가 필요합니다:

필드	필수	설명
description	예	서브에이전트가 호출되어야 할 시점에 대한 자연어 설명
prompt	예	서브에이전트의 동작을 안내하는 시스템 프롬프트
tools	아니오	서브에이전트가 사용할 수 있는 특정 도구의 배열, 예: ["Read", "Edit", "Bash"]. 생략하면 모든 도구를 상속합니다. Agent(agent_type) 구문을 지원합니다
disallowedTools	아니오	이 서브에이전트에 대해 명시적으로 거부할 도구 이름의 배열
model	아니오	사용할 모델 별칭: sonnet, opus, haiku, 또는 inherit. 생략하면 inherit이 기본값입니다
skills	아니오	서브에이전트의 컨텍스트에 사전 로드할 스킬 이름의 배열
mcpServers	아니오	이 서브에이전트를 위한 MCP 서버의 배열. 각 항목은 서버 이름 문자열 또는 {name: config} 객체입니다
maxTurns	아니오	서브에이전트가 중지되기 전 최대 에이전트 턴 수

예시:

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 동작을 유지하면서 특정 지침을 추가
--append-system-prompt-file	파일 내용을 기본 프롬프트에 추가	기본값을 유지하면서 파일에서 추가 지침을 로드

각각의 사용 시점:

• --system-prompt: Claude의 시스템 프롬프트를 완전히 제어해야 할 때 사용합니다. 이 옵션은 모든 기본 Claude Code 지침을 제거하여 백지 상태를 제공합니다.

  claude --system-prompt "You are a Python expert who only writes type-annotated code"
  

• --system-prompt-file: 파일에서 커스텀 프롬프트를 로드하고 싶을 때 사용합니다. 팀 일관성이나 버전 관리되는 프롬프트 템플릿에 유용합니다.

  claude --system-prompt-file ./prompts/code-review.txt
  

• --append-system-prompt: Claude Code의 기본 기능을 유지하면서 특정 지침을 추가하고 싶을 때 사용합니다. 대부분의 사용 사례에서 가장 안전한 옵션입니다.

  claude --append-system-prompt "Always use TypeScript and include JSDoc comments"
  

• --append-system-prompt-file: Claude Code의 기본값을 유지하면서 파일에서 지침을 추가하고 싶을 때 사용합니다. 버전 관리되는 추가 사항에 유용합니다.

  claude --append-system-prompt-file ./prompts/style-rules.txt
  

--system-prompt과 --system-prompt-file은 상호 배타적입니다. 추가 플래그는 두 교체 플래그 중 하나와 함께 사용할 수 있습니다.

대부분의 사용 사례에서는 Claude Code의 내장 기능을 유지하면서 커스텀 요구사항을 추가하는 --append-system-prompt 또는 --append-system-prompt-file을 권장합니다. --system-prompt 또는 --system-prompt-file은 시스템 프롬프트를 완전히 제어해야 할 때만 사용하세요.

관련 문서

• Chrome 확장 - 브라우저 자동화 및 웹 테스트
• 대화형 모드 - 단축키, 입력 모드, 대화형 기능
• 빠른 시작 가이드 - Claude Code 시작하기
• 일반적인 워크플로 - 고급 워크플로 및 패턴
• 설정 - 구성 옵션
• Agent SDK 문서 - 프로그래밍 방식 사용 및 통합