Claude Code CLI 명령어 총정리

Anthropic Claude Code의 설치부터 CLI 플래그, 슬래시 명령어, 설정 파일, 훅(Hooks), MCP, 백그라운드 에이전트까지 세부 항목 하나하나 빠짐없이 정리했습니다. 대분류만 훑고 지나가지 않고, 각 카테고리 안에 실제로 존재하는 명령어와 옵션까지 다 풀어서 담았습니다.

Claude Code는 매주 단위로 업데이트되는 도구라 명령어/플래그가 계속 추가·변경됩니다. 세션 안에서 /만 입력하면 지금 설치된 버전에서 실제 지원하는 명령어 목록을 바로 확인할 수 있으니, 이 글과 함께 항상 대조해보세요.

1. 설치 및 인증

1-1. 설치 방법 (우선순위 순)

# 1) 네이티브 바이너리 (권장)
curl -fsSL https://claude.ai/install.sh | bash

# 2) Homebrew (macOS)
brew install --cask claude-code

# 3) npm (구버전 방식, claude install로 마이그레이션 권장)
npm install -g @anthropic-ai/claude-code

# 버전 확인 / 업데이트
claude --version
claude update

1-2. 인증

명령어	기능
claude auth login	로그인 또는 계정 전환
claude auth status	현재 인증 상태 확인
claude auth logout	저장된 인증 정보 삭제

2. CLI 플래그 (터미널에서 실행할 때)

2-1. 세션 시작/제어

플래그	기능
--model <name>	사용할 모델 지정 (opus / sonnet / haiku / opusplan / fable 등)
--effort <level>	추론 강도 지정 (모델별로 지원 레벨 다름, 예: xhigh)
--permission-mode <mode>	시작할 승인 모드 (plan / acceptEdits / auto / bypassPermissions / dontAsk / manual)
-p, --print <prompt>	비대화형 모드. 한 번만 실행하고 결과 출력 후 종료
-c, --continue	현재 디렉토리의 가장 최근 세션 이어서 시작
-r, --resume <name|id>	이름 또는 세션 ID로 특정 세션 재개
--resume --fork-session	재개하되 새 세션 ID로 분기 (원본 세션은 그대로 보존)
--from-pr <번호>	특정 Pull Request와 연결된 세션 재개
-n, --name <name>	세션에 이름 붙이기
--cd <path>	세션 시작 시 작업 루트 디렉토리 지정
--add-dir <path>	쓰기 가능한 추가 디렉토리 확장 (반복 사용 가능)
--agents '<json>'	서브에이전트를 JSON 객체로 정의 (설명/프롬프트/도구/모델 지정)
--agent <name>	특정 서브에이전트 지정해서 실행
--settings <file|json>	이번 실행에만 적용할 설정 오버라이드
--mcp-config <file>	외부 파일에서 MCP 서버 설정 불러오기
--plugin-dir <path>	로컬 플러그인 디렉토리 지정
--safe-mode	모든 커스터마이징(설정/훅/플러그인) 비활성화 후 트러블슈팅용으로 실행
--dangerously-skip-permissions	모든 승인 프롬프트 생략 (격리 환경 전용)

2-2. 비대화형(print) 모드 전용 옵션

플래그	기능
--max-turns <n>	에이전트 턴 수 제한 (CI 안전장치)
--max-budget-usd <금액>	비용 상한선 지정, 초과 전에 중단
--no-session-persistence	세션 영속화 생략 (일회성 CI/CD 실행에 적합)
--output-format <format>	출력 형식 지정 (예: json, stream-json)
--input-format stream-json	스트리밍 JSON 입력 사용 (SDK/자동화용)
--session-id <uuid>	고정된 세션 ID로 실행 (UUID 형식 필요)
--debug	디버그 모드 (API 호출, 도구 사용, 타이밍 로그)
--debug "<카테고리>"	카테고리 필터링해서 디버그 (예: "api,hooks")
--debug-file <path>	디버그 출력을 파일로 저장

2-3. 백그라운드 에이전트

명령어	기능
claude --bg "<작업내용>"	백그라운드 에이전트 실행, 세션 ID 즉시 반환
claude --bg --exec '<셸명령>'	세션이 아닌 단일 셸 명령을 백그라운드 잡으로 실행
claude --bg --agent <name> "<작업내용>"	특정 서브에이전트를 백그라운드로 실행
claude agents	Agent View 열기 (실행 중/대기/완료 세션 모니터링)
claude agents --cwd <path>	특정 디렉토리로 범위 한정된 Agent View
claude agents --json	백그라운드 세션 목록을 JSON으로 출력 (스크립팅용)

3. 슬래시 명령어 (세션 내부)

3-1. 프로젝트 설정 / 메모리

명령어	기능
/init	CLAUDE.md 초안 생성 (프로젝트 메모리 시작점)
/memory	저장된 프로젝트 메모리 확인/편집
/team-onboarding	CLAUDE.md, 스킬, 서브에이전트, 훅, 최근 작업 흐름을 분석해 팀 온보딩 문서 자동 생성

3-2. 컨텍스트 관리

명령어	기능
/compact [focus]	대화 내용을 요약해서 컨텍스트 절약. 특정 항목을 남기라고 지시 가능 (예: /compact 인증 모듈과 현재 테스트 실패만 유지)
/clear (별칭 /reset, /new)	대화 기록 전체 삭제 (CLAUDE.md, 스킬, 메모리는 유지). 이름을 붙여서 나중에 /resume으로 찾을 수 있음: /clear payment-refactor
/context	현재 컨텍스트 사용량 확인
/cd <path>	세션 중 작업 디렉토리 이동 (프롬프트 캐시 warmth 유지)

3-3. 계획 / 검토 / 되돌리기

명령어	기능
/plan <작업>	Plan 모드로 전환. 실행 전 계획부터 확인
/diff	지금까지의 변경 사항(diff) 확인
/rewind (단축키 Esc 두 번)	이전 체크포인트로 되돌리기. 코드만/대화만/둘 다 선택 복원 가능
/code-review [--fix] [effort]	별도 에이전트가 코드 리뷰. --fix는 발견한 문제를 바로 적용, effort로 /code-review high처럼 강도 지정 가능
/security-review	보안 관점 코드 리뷰
/simplify	정리/단순화 전용 리뷰 (버그 탐색은 안 하고 리팩터링/효율만)

3-4. 포커스 / 목표 지속

명령어	기능
/goal <완료조건>	여러 턴에 걸쳐 Claude가 향해 갈 완료 조건을 설정
/loop <간격> <작업|/명령어>	지정 간격으로 세션 내에서 반복 실행 (예: /loop 5m check if the deploy is complete). 각 반복은 독립된 컨텍스트라 대화가 비대해지지 않음
/btw <내용>	메인 스레드를 오염시키지 않고 곁가지 질문 처리

3-5. 탐색 / 세션 관리

명령어	기능
/resume [session]	세션 피커를 열거나, 이름/ID로 바로 재개
/rename	현재 세션 이름 다시 짓기 (인자 없으면 대화 맥락에서 자동 생성)
/branch [name] (별칭 /fork)	현재 지점에서 대화 분기, 원래 흐름은 그대로 보존
/background (별칭 /bg)	현재 세션 전체를 백그라운드로 분리
/tasks	현재 실행 중인 백그라운드 작업 목록 확인

3-6. 권한 / 모델 / 비용

명령어	기능
/permissions	승인 모드 변경 (plan / acceptEdits / auto / bypassPermissions / dontAsk / manual)
/model <alias>	모델 전환. 예: /model opus, /model sonnet, /model haiku, /model opusplan, /model fable
/effort <level>	추론 강도 조절 (모델에 따라 지원 레벨이 다름, 예: xhigh는 Opus 계열 전용인 경우가 많음)
/usage (구 /cost, /stats)	토큰 사용량, 요금제 한도, 비용 통합 대시보드
/status	현재 모델, 승인 정책, 연결된 MCP 서버, 도구 상태 확인
/doctor	환경을 실제로 점검하고 실패 원인을 구체적으로 리포트

/status와 /doctor의 차이: /status는 현재 설정값을 "읽어서 보여주기"만 하고, /doctor는 실제로 환경을 "테스트"해서 문제를 찾아냅니다. 뭔가 안 맞는데 원인을 모르겠으면 doctor부터 돌려보세요.

3-7. MCP / 플러그인 / 스킬 / 서브에이전트

명령어	기능
/mcp	연결된 MCP 서버 관리 및 도구 사용
/mcp__[server]__[prompt]	연결된 MCP 서버가 노출하는 프롬프트가 슬래시 명령어 형태로 자동 등록됨
/plugins	설치된 플러그인 확인/관리
/reload-skills	재시작 없이 스킬 다시 스캔
/hooks	등록된 훅 확인, HTTP 웹훅으로 외부 CI 트리거 설정 가능
/install-github-app	공식 Claude GitHub Actions 통합 설정

3-8. 기타 / 재미 요소

명령어	기능
/theme	테마 선택기 열기, 커스텀 테마 관리
/release-notes	최신 릴리즈 노트 확인
/buddy	터미널 펫 컴패니언 소환 (pet / card / mute / off)
/workflows	실행 중/완료된 dynamic workflow 확인

4. MCP 서버 관리 (터미널 명령)

# MCP 서버 추가 (명령 기반)
claude mcp add <name> <command> [args...]

# JSON 설정으로 추가
claude mcp add-json <name> '{"command": "npx", "args": ["-y", "@server/pkg"]}'

# SSE 전송 방식
claude mcp add --transport sse <name> <url>

# HTTP 전송 방식
claude mcp add --transport http <name> <url>

# 스코프 지정 + 환경변수 전달 (예: GitHub)
claude mcp add github -s user \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token \
  -- npx -y @modelcontextprotocol/server-github

# 설치된 서버 목록
claude mcp list

# 서버 제거
claude mcp remove <name>

# 설치 없이 테스트 실행
claude mcp run <name>

# 로그인/로그아웃 (인증 필요한 서버)
claude mcp login <name>
claude mcp logout <name>

Slack처럼 Dynamic Client Registration을 지원하지 않는 MCP 서버는 추가할 때 --client-id, --client-secret을 같이 지정해야 합니다.

5. 승인 모드 (Permission Modes) 상세

Shift+Tab으로 세션 중 바로 순환 전환할 수 있습니다.

Manual (default)

모든 행동마다 승인 요청. CLI 표기상 config 값은 default이며 manual이 별칭으로 쓰임.

Accept Edits

파일 생성/수정과 기본 파일시스템 명령(mkdir, mv, cp, rm 등)은 자동 승인. 워크스페이스 밖 경로나 그 외 명령은 여전히 확인.

Plan

읽기 전용. 계획만 세우고 승인 전까지 아무것도 실행하지 않음.

Auto

거의 다 자동 실행하되, 별도 안전 분류기(classifier)가 메인 브랜치 푸시, 프로덕션 배포, 외부 데이터 전송 같은 위험한 행동만 걸러서 차단.

Don't Ask

사전 승인된 도구만 실행하고, 목록에 없으면 조용히 거부. 잠긴 CI/스크립트 환경에 적합.

Bypass Permissions

사실상 전부 자동 승인. rm -rf / 같은 일부 안전장치만 남고, 프롬프트 인젝션에 대한 방어는 없음. 격리된 컨테이너/VM에서만 사용 권장.

보호 경로 (Protected Paths)

모드	보호 경로 쓰기 동작
default, acceptEdits, plan	승인 요청
auto	분류기로 라우팅
dontAsk	거부
bypassPermissions	허용

6. 설정 파일 (settings.json)

6-1. 설정 파일 우선순위

위치	범위
/Library/Application Support/ClaudeCode/managed-settings.json (macOS) / /etc/claude-code/managed-settings.json (Linux/WSL)	엔터프라이즈 설정 (최우선)
.claude/settings.local.json	로컬 프로젝트 설정 (git 무시, 개인 취향)
.claude/settings.json	프로젝트 설정 (버전관리 포함, 팀 공통)
~/.claude/settings.json	사용자 설정 (모든 프로젝트 적용)

6-2. 설정 예시

{
  "model": "claude-opus-4-8",
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Read", "Edit", "Write",
      "Bash(npm run *:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "Edit(.env*)"
    ]
  },
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\"" }
        ]
      }
    ]
  }
}

permissions.allow에 Tool(param:value) 형식으로 세밀하게 규칙을 걸 수 있습니다. 예: Bash(npm run test:*)는 npm run test로 시작하는 명령만 허용.

7. 훅 (Hooks)

훅은 JS 모듈이 아니라 settings.json 안의 JSON 설정 블록이며, 셸 명령/HTTP 호출/인라인 LLM 프롬프트로 실행됩니다.

이벤트	설명
PreToolUse / PostToolUse	도구 사용 전/후 실행
InstructionsLoaded	CLAUDE.md 로드 시점
ConfigChange	설정 파일이 세션 중 변경됨
WorktreeCreate / WorktreeRemove	워크트리 생성/제거
PreCompact / PostCompact	컨텍스트 압축 전/후
Elicitation / ElicitationResult	MCP가 구조화된 입력을 요청 / 사용자가 응답
StopFailure	API 오류로 턴이 종료됨
PermissionRequest / PermissionDenied	승인 다이얼로그 표시 / Auto 모드가 행동을 차단
CwdChanged	작업 디렉토리 변경
FileChanged	감시 중인 파일이 외부에서 수정됨
TaskCreated / TaskCompleted	작업 생성 / 완료
TeammateIdle	에이전트 팀 구성원이 유휴 상태

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "your-shell-command-here",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

훅에서 참조할 수 있는 환경변수: CLAUDE_FILE_PATH, CLAUDE_TOOL_NAME, CLAUDE_TOOL_INPUT, CLAUDE_SESSION_ID, CLAUDE_PROJECT_DIR

8. 모델 별칭 & effort 조합

별칭	동작
/model opus	Opus 계열로 전환 (배포 환경별로 실제 버전이 다를 수 있음)
/model sonnet	Sonnet 계열로 전환
/model haiku	Haiku 계열로 전환 (가볍고 반복적인 작업, 서브에이전트용)
/model opusplan	계획 단계는 Opus급 추론, 실제 코드 작성은 Sonnet 속도로 자동 전환
/model fable	Mythos 계열 상위 모델로 전환 (플랜/가용성에 따라 제공 여부 다름)

# 예시: 결제 모듈 전체를 Opus급으로 분석 후 Sonnet 속도로 수정
claude --model opusplan "결제 모듈 전체에서 race condition을 찾아서 고쳐줘"

판단 기준: 단순 탐색 → Haiku / 비용 민감한 일상 코딩 → Sonnet / 어려운 추론·설계·에이전틱 루프·보안 분석 → Opus. 복잡한 리팩터링에는 opusplan이 적합.

9. 키보드 단축키

단축키	기능
Shift + Tab	승인 모드 순환 전환
Esc 두 번	Rewind 메뉴 열기
Ctrl + O	일반/상세(verbose) 트랜스크립트 전환
Ctrl + C	진행 중인 작업 중단
Cmd/Ctrl + Enter (IDE 확장)	프롬프트 제출 (VS Code/JetBrains 기본 바인딩, ~/.claude/keybindings.json에서 재설정 가능)

10. @-멘션 (파일/디렉토리/URL 참조)

@README.md          # 특정 파일 포함
@src/components/    # 디렉토리 전체 포함
@https://example.com  # URL 가져오기 (읽기 전용)

파일을 그냥 붙여넣기보다 @-멘션을 쓰는 게 좋습니다. 도구를 통해 로드되면 토큰화가 더 잘 처리되고, 경로가 감사 로그(audit log)에도 남습니다.

11. 자동화 / CI 워크플로 예시

# 비대화형 실행
claude -p "테스트 실패 원인 정리해줘"

# 턴 수/비용 상한선 걸어서 자동화
claude -p --max-turns 3 --max-budget-usd 5.00 "빌드 로그 확인"

# 외부 MCP 설정 파일 로드 + 세션 영속화 생략 (CI 환경)
claude -p "open issues 확인" --mcp-config ./ci-mcp.json --no-session-persistence

# 스트리밍 JSON 출력 (SDK/자동화 연동)
claude -p "빌드 고쳐줘" --output-format stream-json --verbose

12. 커스텀 명령어 / 스킬

# 프로젝트 전체 공유용
mkdir -p .claude/commands
echo '작업 지시 내용' > .claude/commands/my-command.md

# 개인용
mkdir -p ~/.claude/commands
echo '작업 지시 내용' > ~/.claude/commands/my-command.md

같은 이름의 커맨드와 스킬이 동시에 존재하면 스킬이 우선 적용됩니다. 기존 .claude/commands/ 파일은 그대로 계속 동작하니 마이그레이션은 필수는 아닙니다.

13. 유용한 조합 정리

상황	추천 명령/설정
가볍고 반복적인 작업	/model haiku
비용 민감한 일상 코딩	/model sonnet
복잡한 설계·근본 원인 추적·보안 분석	/model opus
대규모 리팩터링 (계획은 깊게, 실행은 빠르게)	/model opusplan
신뢰하는 개인 프로젝트에서 승인 팝업 줄이기	--permission-mode acceptEdits
완전 격리된 컨테이너/VM 자동화	--dangerously-skip-permissions
세션이 길어져 응답 품질이 떨어질 때	/compact
완전히 다른 작업으로 전환	/clear
설정이 꼬였을 때	/status → /doctor 순으로 진단
정기적으로 상태 체크가 필요할 때	/loop 5m /test
커밋/푸시 전 품질 확인	/code-review --fix

마무리

Claude Code는 단순 채팅형 도구가 아니라 설정 계층, 권한, 훅, MCP, 서브에이전트까지 갖춘 하나의 에이전틱 런타임에 가깝습니다. 처음엔 /init → /permissions → /plan → /compact 정도의 기본 흐름만 익히고, 필요한 상황이 생길 때마다 이 글의 항목들을 하나씩 찾아 적용해보는 방식을 추천합니다.