CLI 참조 (CLI Reference)
기준일: 2026-06-07
난이도: 초급
공식 기준: CLI reference, Commands
Claude Code CLI는 claude 하나로 대화형 세션, 비대화형 실행, 세션 재개, 인증, 백그라운드 세션, MCP, 플러그인, 원격 제어를 다룹니다. Git, 테스트, 빌드 같은 작업은 별도 하위 명령이 아니라 Claude에게 요청하거나 Bash/tool 권한 안에서 실행합니다.
핵심 개념
| 영역 | 현재 공식 명령 | 언제 쓰는가 |
|---|---|---|
| 대화 시작 | claude, claude "query" |
대화형 세션 또는 첫 프롬프트와 함께 시작 |
| 비대화형 실행 | claude -p "query" |
스크립트, CI, 파이프 입력 처리 |
| 세션 이어가기 | claude -c, claude -r "<session>" |
최근 세션 계속 또는 ID/이름으로 재개 |
| 업데이트 | claude update, claude install stable |
Native binary 업데이트/재설치 |
| 인증 | claude auth login, claude auth status, claude setup-token |
사용자 로그인, CI용 long-lived token |
| 백그라운드 | claude agents, claude attach, claude logs, claude stop |
여러 세션을 모니터링하고 재접속 |
| 확장 | claude mcp, claude plugin |
MCP 서버와 플러그인 관리 |
| 프로젝트 정리 | claude project purge |
로컬 transcript/debug/file-edit 상태 삭제 |
| 원격/웹 | claude remote-control, claude --remote, claude --teleport |
Claude.ai/Web/Desktop과 로컬 세션 연결 |
선택 기준
| 상황 | 추천 |
|---|---|
| 처음 쓰는 로컬 세션 | claude |
| 단발성 요약/검사 | claude -p "..." |
| 로그나 diff를 파이프로 넣기 | `cat file |
| 방금 작업하던 세션 계속 | claude -c |
| 이름 붙인 세션 재개 | claude -r "auth-refactor" |
| CI에서 Claude 구독 토큰 사용 | claude setup-token 후 CLAUDE_CODE_OAUTH_TOKEN |
| 여러 백그라운드 작업 감시 | claude agents |
| 플러그인/스킬/MCP 확장 | claude plugin, claude mcp |
실습
기본 실행:
claude
claude "이 프로젝트 구조를 5줄로 설명해줘"
claude --version
비대화형 실행:
claude -p "현재 디렉터리의 테스트 전략을 제안해줘"
cat logs.txt | claude -p "이 로그에서 실패 원인을 요약해줘"
claude -c -p "방금 세션의 다음 작업을 이어서 정리해줘"
세션 재개와 백그라운드:
claude -c
claude -r "auth-refactor" "남은 테스트를 정리해줘"
claude agents --json
claude attach <session-id>
claude logs <session-id>
claude stop <session-id>
인증과 업데이트:
claude auth login
claude auth status --text
claude setup-token
claude update
claude install stable
확장과 프로젝트 정리:
claude mcp
claude plugin install code-review@claude-plugins-official
claude project purge ~/work/repo --dry-run
주요 플래그
| 플래그 | 용도 | 예시 |
|---|---|---|
-p, --print |
응답 출력 후 종료 | claude -p "query" |
-c, --continue |
현재 디렉터리의 최근 대화 계속 | claude -c |
-r, --resume |
특정 세션 재개 | claude -r "session-name" |
--model |
이번 세션 모델 override | claude --model sonnet |
--effort |
reasoning effort override | claude --effort high |
--permission-mode |
시작 권한 모드 지정 | claude --permission-mode plan |
--allowedTools / --disallowedTools |
도구 허용/차단 규칙 | claude --allowedTools "Bash(git log *)" |
--tools |
사용 가능한 도구 집합 제한 | claude --tools "Bash,Edit,Read" |
--add-dir |
추가 작업 디렉터리 접근 허용 | claude --add-dir ../lib |
--settings |
설정 파일 또는 inline JSON 지정 | claude --settings ./settings.json |
--mcp-config |
MCP 설정 로드 | claude --mcp-config ./mcp.json |
--bare |
hooks/skills/plugins/MCP/CLAUDE.md 자동 로딩 최소화 | claude --bare -p "query" |
--worktree, -w |
격리 worktree에서 시작 | claude -w feature-auth |
--tmux |
worktree 세션을 tmux로 표시 | claude -w feature-auth --tmux |
--system-prompt |
기본 system prompt 교체 | claude --system-prompt "You are a Python expert" |
--append-system-prompt |
기본 system prompt 뒤에 지침 추가 | claude --append-system-prompt "Use Korean" |
--output-format |
print mode 출력 형식 | claude -p "query" --output-format json |
--json-schema |
JSON Schema에 맞는 구조화 출력 | claude -p --json-schema '{"type":"object"}' "query" |
--max-turns |
agentic turn 제한 | claude -p --max-turns 3 "query" |
--max-budget-usd |
print mode 비용 상한 | claude -p --max-budget-usd 5 "query" |
--remote |
Claude.ai web 세션 생성 | claude --remote "Fix login bug" |
--teleport |
web 세션을 로컬 터미널로 가져오기 | claude --teleport |
도구에 입력할 프롬프트
내가 작성한 Claude Code 실행 명령을 검토해줘.
공식 CLI에 없는 하위 명령이 있는지,
대화형/비대화형/세션 재개/백그라운드 실행 중 어떤 형태가 맞는지,
권한과 비용 제한 플래그를 어떻게 추가하면 좋을지 표로 정리해줘.
체크리스트
- 파일 읽기, Git, 테스트, 빌드를 Claude 전용 하위 명령으로 오해하지 않는다.
- 스크립트 실행은
claude -p와 명시적 입력/출력 형식을 사용한다. - 세션을 이어갈 때
-c와-r의 차이를 구분한다. - CI 토큰은
claude setup-token과CLAUDE_CODE_OAUTH_TOKEN흐름을 따른다. - 위험 명령은
--permission-mode,--allowedTools,--disallowedTools,--tools로 제한한다. - 자동화에서
--max-turns와--max-budget-usd같은 중단 기준을 둔다. - 최신 플래그는
code.claude.com/docs/en/cli-reference에서 다시 확인한다.