Claude Code CLI

예시

# macOS/Linux/WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Homebrew / WinGet
brew install --cask claude-code
winget install Anthropic.ClaudeCode

로그인

인증 상태 확인

로그아웃

설정 진단·문제 해결

대화형 세션 시작

프롬프트와 함께 시작

프린트 모드: 실행 후 종료

파이프 콘텐츠 처리

최근 대화 이어가기

세션 ID·이름으로 재개

세션 표시 이름 지정

PR 연결 세션 재개

최신 버전 업데이트

네이티브 바이너리 설치

장기 OAuth 토큰 생성

MCP 서버 구성

세션 모델 지정

추론 강도 설정

파일 접근용 작업 디렉토리 추가

확인 없이 도구 허용

특정 도구 금지

출력 형식 지정

입력 형식 지정

에이전트 턴 수 제한

상세 로그 활성화

세션 이어가기 / 재개

PR 연결 세션 재개

세션을 복사해 분기 후 재개

모든 권한 확인 생략

도움말 표시

코드베이스 분석해 CLAUDE.md 생성/개선

→ 처음 깔았다, 무엇부터 해야 하나 · → 처음 보는 코드베이스를 파악해야 한다

CLI 종료(별칭 /quit · 백그라운드는 분리)

새 대화 시작

대화 요약, 컨텍스트 확보

컨텍스트 사용량 표시

설정 패널 열기

세션 상태·진행 작업 표시

설정 진단 및 문제 해결

토큰 사용량·비용 표시

세션 내 모델 변경

추론 강도 조정

다른 대화로 돌아가기

현재 세션 이름 변경

현재 지점에서 대화 분기

대화를 텍스트로 내보내기

변경사항 대화형 뷰어

IDE 연동 관리·상태 표시

MCP 서버 연결 관리

중단 (2회=종료)

Claude Code 종료

트랜스크립트 뷰어 토글

명령어 히스토리 역검색

작업(task) 목록 토글

실행 중 작업을 백그라운드로 (tmux는 2회)

백그라운드 서브에이전트 전부 중단 (3초 내 2회)

프롬프트 보관 · 빈 입력에서 다시 누르면 복원

클립보드 이미지 붙여넣기

화면 다시 그리기 (풀스크린에서 2회=/clear)

프로세스 일시 중지 (Unix, fg 로 복귀)

프롬프트/응답을 기본 편집기로 열기

응답·도구 호출 중단, 대화상자 닫기

초안 삭제, 비어있으면 되돌리기

권한 모드 순환 전환

모델 전환

확장 사고 토글

패스트 모드 토글

파일 경로 언급 자동완성

셸 모드 진입

Task 도구로 호출: subagent_type=이름 · .claude/agents/*.md frontmatter(name/description/tools/model)로 정의 · --agent/--agents 플래그로도 지정 가능

결과는 요약이라 근거가 잘려 있다. 중요한 판정은 파일 경로와 재현 명령을 같이 요구하고, 받은 뒤 직접 확인할 것.

→ 작업이 커서 하나의 대화로는 안 될 것 같다 · /agents · --agent / --agents

UI/컴포넌트/스타일링

서버, API, 아키텍처

API 설계·문서화·통합

iOS/Android 앱

javascript-developer · typescript-developer

wordpress-developer · ios-developer

설계·최적화·모델링

code-debugger · code-documenter

code-security-auditor

스타일/일관성

위 17종은 원본 프로젝트에서 온 개발직군 롤 템플릿이다 (legacy/subagents/)

→ 작업이 커서 하나의 대화로는 안 될 것 같다

읽기만 자동 승인. 쓰기·실행은 매번 물어본다.

claude --permission-mode default

누적된 allow 규칙은 .claude/settings.local.json 에 남고 여기엔 내 로컬 경로가 섞인다. 리포를 공개할 거면 이 파일이 .gitignore 에 있는지 먼저 볼 것.

→ 처음 깔았다, 무엇부터 해야 하나 · → 승인 창이 너무 자주 떠서 흐름이 끊긴다 · dontAsk · /permissions

파일 편집·기본 파일시스템 명령을 자동 승인한다.

→ 승인 창이 너무 자주 떠서 흐름이 끊긴다 · auto

읽기 전용 탐색만 하고, 편집 전에 계획을 먼저 내놓는다.

→ 처음 보는 코드베이스를 파악해야 한다 · /plan · Ctrl+G

분류기가 위험도를 판정해 대부분의 도구 호출을 자동 승인한다.

"대부분 자동 승인"이지 "전부"가 아니다. CI 처럼 사람이 없는 환경에서 쓰면 카드가 뜨는 순간 그 자리에서 사람을 기다리며 멈춘다. 무인 실행은 dontAsk 다.

→ 승인 창이 너무 자주 떠서 흐름이 끊긴다 · → CI나 스크립트에서 사람 없이 돌리고 싶다 · dontAsk · /sandbox

사전 승인된 도구만 실행하고 나머지는 그냥 실패시킨다. CI용.

claude -p "커버리지 분석" --permission-mode dontAsk --max-turns 3

→ CI나 스크립트에서 사람 없이 돌리고 싶다 · auto · --permission-mode <mode>

모든 검사를 생략한다. 격리 환경 전용.

이 모드를 쓰기 전에 되돌릴 수 있는 상태인지 먼저 볼 것 — 커밋했는지, 브랜치를 팠는지. /rewind 는 Claude 가 추적하는 변경만 되돌린다.

→ 건드리면 안 되는 걸 건드릴까 봐 불안하다 · --allowedTools "Bash(git log:*)" \ · /sandbox

2026-08-14부터 Pro/Max/Team 신규 세션 기본값이 auto 모드로 전환

settings.json의 hooks.<Event>[] (PreToolUse/PostToolUse/SessionStart/Stop 등), /hooks로 확인

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash(git commit:*)",
      "hooks": [{ "type": "command", "command": "npm test --silent" }]
    }]
  }
}

훅은 매 도구 호출마다 돈다. 전체 테스트를 PreToolUse 에 걸면 파일 하나 고칠 때마다 몇 분씩 멈춘다. matcher 를 좁히거나 빠른 검사만 걸 것. 설정에 썼는데 /hooks 목록에 안 보이면 JSON 문법 오류이거나 파일 위치가 틀린 것이다.

→ 커밋 전에 자동으로 뭔가 돌리고 싶다 · → 건드리면 안 되는 걸 건드릴까 봐 불안하다 · .claude/commands/*.md · 설명

.claude-plugin/plugin.json 매니페스트, claude plugin install <name>@<marketplace>, /plugin

→ 같은 지시를 매번 치기 싫다 · → 외부 서비스나 내 도구를 붙이고 싶다 · Project · --mcp-config / --plugin-dir

로드 순서: managed policy → ~/.claude/CLAUDE.md → ./CLAUDE.md → CLAUDE.local.md

CLAUDE.local.md 는 .gitignore 에 넣을 것. 로컬 경로나 개인 메모가 그대로 커밋된다.

→ 처음 깔았다, 무엇부터 해야 하나 · → 처음 보는 코드베이스를 파악해야 한다 · 설명

@path/to/file 로 다른 문서 import(최대 4단계)

→ 토큰이 빨리 닳고 대화가 무거워진다

/memory 로 편집 · Auto Memory: 학습 내용을 스스로 기록

→ 처음 보는 코드베이스를 파악해야 한다 · /clear [name]

/sandbox, settings.json의 sandbox.enabled / filesystem.* / network.allowedDomains

// .claude/settings.json
{
  "sandbox": {
    "enabled": true,
    "network": { "allowedDomains": ["registry.npmjs.org", "github.com"] }
  }
}

→ 건드리면 안 되는 걸 건드릴까 봐 불안하다 · bypassPermissions · sandbox.network.allowedDomains

macOS=Seatbelt, Linux/WSL2=bubblewrap

→ Windows에서 쓰는데 문서대로 안 된다

네이티브 Windows 미지원 — WSL2 필요

백그라운드·클라우드 세션 명령 모음

claude --bg "작업 지시"        # 백그라운드 실행
claude agents                  # 목록/대시보드
claude attach|logs|stop <id>   # 연결/로그/중지
claude respawn <id>            # 재시작
claude --cloud "작업"          # 웹 세션 생성
claude --teleport              # 웹 세션→로컬 이동

백그라운드 작업도 토큰을 쓴다. 여러 개를 걸어두면 사용량이 눈에 안 보이는 채로 늘어난다. 일회성 작업에는 --max-turns 를 걸고 /usage 로 주기적으로 확인할 것.

→ 오래 걸리는 작업을 걸어두고 다른 걸 하고 싶다 · /tasks · -p --max-turns 3

/background(/bg), /tasks 로 세션 내 관리

→ 오래 걸리는 작업을 걸어두고 다른 걸 하고 싶다 · → 작업이 커서 하나의 대화로는 안 될 것 같다 · /fork · Ctrl+T

시작 권한 모드 지정

세션 에이전트 지정/JSON 정의

커스터마이제이션 전체 비활성화

훅·스킬·플러그인·MCP 생략

설정 파일/인라인 JSON 지정

자동 컴팩트 기준 설정

과부하 시 폴백 모델

지출 상한 (프린트 모드)

시스템 프롬프트 교체/추가

MCP·플러그인 로컬 로드

코드+대화 체크포인트 롤백

서브에이전트 관리

격리 환경에서 실행

도구 권한 규칙 관리

계획 모드 진입

현재 diff·PR 검토

diff 보안 취약점 검사

세션을 백그라운드로 분리

백그라운드 작업 목록

대화를 새 백그라운드 세션으로 복사

프롬프트 반복 실행

완료 조건 설정 후 자동 진행

세션 한 줄 요약

세션 사용 패턴 분석

별칭 전체: default, best, fable, sonnet, opus, haiku, sonnet[1m], opus[1m], opusplan

특정 모델 버전 지정

low, medium, high, xhigh, max — 기본 high, max 는 세션 한정

어드바이저 모델 활성화

세션 내 변경

추가 작업 디렉토리 등록

디렉토리 경로 유효성 확인

여러 디렉토리 동시 접근

JSON 출력 (스크립팅용)

→ CI나 스크립트에서 사람 없이 돌리고 싶다 · SID=$(claude -p "start" --output-format json \

실시간 처리용 스트림

→ CI나 스크립트에서 사람 없이 돌리고 싶다

프린트 모드 입력 형식

스키마 검증된 JSON 출력

→ CI나 스크립트에서 사람 없이 돌리고 싶다

배치/1회성 처리

우선순위: managed → CLI 인자 → .claude/settings.local.json → .claude/settings.json → ~/.claude/settings.json

→ 처음 깔았다, 무엇부터 해야 하나

세션 시작 권한 모드 (default/acceptEdits/plan/auto/dontAsk)

"auto" 값은 프로젝트·local 설정 파일에서는 무시된다 — auto 시작은 내장 기본값이나 user 설정으로만. 우선 규칙은 --permission-mode 플래그가 항상 이긴다.

auto

도구별 사전 승인·차단·확인 규칙

{ "permissions": { "allow": ["Bash(npm run lint)"], "deny": ["Read(./.env)"] } }

→ 승인 창이 너무 자주 떠서 흐름이 끊긴다

세션에 주입할 환경변수 묶음

기본 모델 지정 · 선택 가능한 모델 제한

--model sonnet/opus/haiku/fable

Bash 샌드박스를 설정으로 상시 켜기

/sandbox

자동 컴팩트 토글 · 발동 기준 컨텍스트 크기(100k~1M)

→ 토큰이 빨리 닳고 대화가 무거워진다

응답 스타일 지정 (/clear 후에도 유지)

explanatory-output-style

자동 메모리 토글 · 저장 위치 변경

/memory

모노리포에서 남의 CLAUDE.md 를 글롭으로 제외

→ 건드리면 안 되는 걸 건드릴까 봐 불안하다

대화 기록 보존 기간 (기본 30일)

프로젝트에 플러그인·마켓플레이스를 고정해 팀과 공유

Project

터미널 하단 상태줄을 명령 출력으로 커스텀

커밋·PR 에 붙는 서명 문구 변경

→ 머지 전에 변경사항을 검토받고 싶다

! 셸 모드의 셸 선택 (bash / powershell)

→ Windows에서 쓰는데 문서대로 안 된다

프린트 모드 턴 수 제한

지출 상한 설정

상세 로그 출력

토큰 사용량·비용 표시

도구 허용·금지 규칙을 명령줄에서 지정한다

--allowedTools "Bash(git log:*)" \
  "Bash(git diff:*)" "Write"

--disallowedTools "Bash(rm:*)" "Bash(sudo:*)"

--permission-prompt-tool mcp_auth_tool

--dangerously-skip-permissions   # 위험, 지양

--dangerously-skip-permissions 는 마지막 수단이다. 승인 창이 잦은 게 문제라면 allow 규칙을 쌓거나 샌드박스를 켜는 쪽이 맞다. 쓰기 전에 되돌릴 수 있는 상태인지 — 커밋했는지, 브랜치를 팠는지 — 먼저 볼 것.

→ 승인 창이 너무 자주 떠서 흐름이 끊긴다 · → 건드리면 안 되는 걸 건드릴까 봐 불안하다 · bypassPermissions · /sandbox

MCP 서버 설정

MCP 서버가 돌려주는 내용은 데이터지 지시가 아니다. 외부 도구가 반환한 텍스트에 "이렇게 해라"가 섞여 있어도 그건 실행 근거가 아니다. 쓰기 권한이 있는 커넥터를 붙일 때는 샌드박스의 network.allowedDomains 로 나가는 곳을 제한하는 편이 안전하다.

→ 외부 서비스나 내 도구를 붙이고 싶다 · /sandbox · --mcp-config / --plugin-dir

MCP OAuth 로그인/해제

MCP 기능 접근

→ 외부 서비스나 내 도구를 붙이고 싶다

예시

git log --oneline | claude -p "요약해줘"
cat error.log | claude -p "원인 찾아줘"

.claude/commands/*.md에 정의, frontmatter(name/description/aliases), 본문에 $ARGUMENTS 사용

Claude Code 는 frontmatter 키 20개를 받지만 claude.ai 업로드·Skills API 경로는 name, description, license, compatibility, metadata, allowed-tools 6개만 받고 그 외 키가 있으면 무시가 아니라 실패한다. 밖으로 내보낼 파일이면 6개로 제한할 것.

→ 같은 지시를 매번 치기 싫다 · 예: .claude/commands/deploy.md → /deploy 로 호출

파일명이 그대로 명령 이름이 된다

/debug     # .claude/commands/debug.md
/test      # .claude/commands/test.md
/deploy    # .claude/commands/deploy.md

→ 같은 지시를 매번 치기 싫다

예시

#!/bin/bash
claude -p "analyze codebase" \
  --output-format json > analysis.json
claude -p "generate tests" --max-turns 3 \
  --output-format text > tests.txt

예시

SID=$(claude -p "start" --output-format json \
  | jq -r '.session_id')
claude -r "$SID" "continue analysis"

claude -p "구조 분석" | claude -p "개선안 제안" \
  | claude -p "구현 계획 작성"

예시

git diff HEAD~1 | claude -p "보안 이슈 리뷰" > security.md
git diff HEAD~1 | claude -p "성능 이슈 확인" > perf.md
git diff HEAD~1 | claude -p "개선안 제안" > improve.md

예시

claude -p "커버리지 분석" --output-format json \
  | jq '.coverage_percentage'
claude -p "커밋 기반 릴리스 노트 생성" \
  --max-turns 2 > RELEASE_NOTES.md
find . -name "*.js" -exec claude -p "버그 분석: {}" \; \
  > bug_report.txt

예시

/ide                # IDE 연동 상태 표시/관리
claude --ide          # 사용 가능한 IDE 자동 연결
claude --chrome        # Chrome 브라우저 연동 켜기
claude --no-chrome     # 이 세션만 Chrome 연동 끄기

예시

git log --oneline -10 | claude -p "체인지로그 작성"
git diff --name-only | claude -p "변경사항 설명"
mysql -e "SHOW TABLES" | claude -p "DB 구조 분석"
docker logs c | claude -p "로그에서 에러 찾기"

예시

claude -p --max-turns 1 "빠른 분석"     # 단일 턴
claude --autocompact auto                # 자동 컨텍스트 압축
/usage                # 세션 비용·한도 확인
/doctor                # 설정 진단

예시

claude -c -p "이전 분석 이어가기"   # 컨텍스트 재사용
claude -p "task1" & claude -p "task2" & wait  # 병렬
claude --fallback-model sonnet,haiku "질의"

예시

claude --settings team-config.json "표준 분석"
claude -r "team-session-id" "팀 논의 이어가기"

claude --permission-mode dontAsk   # CI·락다운 환경

설정 우선순위: managed-settings.json > CLI 인자 > .claude/settings.local.json > .claude/settings.json > ~/.claude/settings.json

설명

auto 모드는 프로덕션 배포·강제 푸시·시크릿 유출 등을 기본 차단

sandbox.network.allowedDomains 로 아웃바운드 도메인 제한

→ 건드리면 안 되는 걸 건드릴까 봐 불안하다 · /sandbox

작업 전환마다 /clear로 컨텍스트 초기화

--max-turns로 무한 반복 방지

장기 대화는 /compact로 압축

--dangerously-skip-permissions 사용 지양

위험 명령은 --disallowedTools로 상시 차단

도구 권한 주기적 점검, 항상 최신 버전 유지

반복 작업 → .claude/commands/ 커스텀 명령어화

자동화 스크립트 → --output-format json

복합 작업 → 파이프로 단계별 연결

장시간 작업 → 세션 ID로 관리, 에러 처리 구현

팀 공유용 워크플로우는 문서화

기본 명령어부터 → /help 자주 활용 → 간단한 질의로 연습 → 작업 간 /clear

권한 모드·도구 권한 마스터 → JSON 출력 자동화 → MCP 연동 → 커스텀 명령어화

Hooks·플러그인·샌드박싱 활용 → 백그라운드/클라우드 세션 → 팀 협업·엔터프라이즈 정책 준수

예시

claude --version && claude auth status && claude doctor
claude install stable         # 네이티브 재설치
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code   # npm 재설치

예시

/clear                          # 컨텍스트 비우기
claude -p --max-turns 3 "포커스 질의"
/compact "핵심만 유지"

/permissions                    # 권한 규칙 확인·관리

공식 문서: code.claude.com/docs/en/overview

CLI 레퍼런스: code.claude.com/docs/en/cli-reference

명령어 레퍼런스: code.claude.com/docs/en/commands

권한 모드: code.claude.com/docs/en/permission-modes

Hooks: code.claude.com/docs/en/hooks

GitHub: github.com/anthropics/claude-code