CLI 참조 (CLI Reference)

기준일: 2026-07-26 (문서화 기준 CLI 2.1.220)
난이도: 초급
공식 기준: CLI reference, Commands, Manage sessions, Remote Control

Claude Code CLI는 claude 진입점 하나로 대화형 세션, 비대화형 실행, 세션 재개, 인증, 백그라운드 세션, MCP, 플러그인, Remote Control, cloud 세션 생성을 다룹니다. 문서에 없는 session, memory, config 하위 명령군을 만들지 않습니다.

핵심 개념

영역	공식 명령 또는 플래그	언제 쓰는가
대화 시작	claude, claude "query"	터미널에서 대화형 세션 시작
비대화형 실행	claude -p "query"	스크립트, 파이프 입력, 구조화 출력
세션 이어가기	claude --continue, claude --resume, claude --resume <name-or-id>	최근 세션, 세션 picker, 이름·ID 기반 재개
세션 이름	claude --name <name>, /rename <name>	여러 작업을 구분하고 찾기 쉽게 만들기
cloud 실행	claude --cloud "task"	claude.ai web 세션을 새로 만들어 맡기기
업데이트	claude update, claude install stable	Native binary 업데이트 또는 재설치
인증	claude auth login, claude auth logout, claude auth status, claude setup-token	로그인, 로그아웃, 인증 확인, CI용 long-lived token 생성
진단	claude doctor, claude --safe-mode, claude --debug	설치·설정 점검, 커스터마이징 배제, 디버그 로그
백그라운드	claude agents, claude attach <id>, claude logs <id>, claude stop <id>	병렬 세션 모니터링과 재접속
확장	claude mcp, claude mcp login <name>, claude plugin	MCP 서버와 플러그인 관리
프로젝트 정리	claude project purge [path]	로컬 Claude Code 상태를 확인 후 삭제
원격 제어	claude remote-control, claude --remote-control, /remote-control	로컬 세션을 claude.ai/code 또는 Claude 앱에서 이어가기

선택 기준

상황	추천
처음 쓰는 로컬 세션	claude
단발성 요약·검사	claude -p "..."
로그나 diff를 파이프로 넣기	`cat file
방금 작업하던 세션 계속	claude --continue
세션 picker에서 고르기	claude --resume 또는 /resume
이름 붙인 세션 재개	claude --resume "auth-refactor"
기존 세션을 복사해 다른 방향으로 시도	claude --continue --fork-session 또는 /branch
웹/cloud 세션을 새로 만들기	claude --cloud "Fix the login bug"
로컬 세션을 다른 기기에서 제어	claude remote-control 또는 claude --remote-control
설정·hooks·MCP가 의심될 때	claude doctor, claude --safe-mode
실행 중 문제를 로그로 진단	claude --debug "api,mcp" 또는 /debug

--remote는 --cloud의 deprecated alias입니다. 새 문서와 스크립트에는 --cloud를 씁니다.

실습

기본 실행:

claude
claude "이 프로젝트 구조를 5줄로 설명해줘"
claude --version

비대화형 실행:

claude -p "현재 디렉터리의 테스트 전략을 제안해줘"
cat logs.txt | claude -p "이 로그에서 실패 원인을 요약해줘"
claude -p --output-format json "작업 요약을 JSON으로 출력해줘"

세션 재개:

claude --continue
claude --resume
claude --resume "auth-refactor" "남은 테스트를 정리해줘"
claude --continue --fork-session

인증과 업데이트:

claude auth login
claude auth status --text
claude setup-token
claude update
claude install stable

진단:

claude doctor
claude --safe-mode
claude --debug "api,mcp"
claude --debug-file /tmp/claude-debug.log

백그라운드와 확장:

claude agents --json
claude attach <session-id>
claude logs <session-id>
claude stop <session-id>
claude mcp
claude mcp login sentry
claude plugin install code-review@claude-plugins-official

cloud와 Remote Control:

claude --cloud "Fix the login bug"
claude remote-control --name "My Project"
claude --remote-control "My Project"

프로젝트 로컬 상태 정리 전 미리보기:

claude project purge ~/work/repo --dry-run

주요 플래그

플래그	용도	예시
-p, --print	응답 출력 후 종료	claude -p "query"
--continue, -c	현재 디렉터리의 최근 대화 계속	claude --continue
--resume, -r	특정 세션 재개 또는 picker 열기	claude --resume auth-refactor
--name, -n	세션 표시 이름 지정	claude -n "my-feature-work"
--fork-session	재개 시 원본 대신 분기 세션 생성	claude --resume abc123 --fork-session
--cloud	claude.ai web 세션 생성	claude --cloud "Fix the login bug"
--remote-control, --rc	대화형 세션을 Remote Control에 연결	claude --remote-control "My Project"
--safe-mode	CLAUDE.md, skills, plugins, hooks, MCP 등 커스터마이징 없이 시작	claude --safe-mode
--debug	디버그 로그 활성화	claude --debug "api,mcp"
--bare	스크립트용 최소 로딩 모드	claude --bare -p "query"
--add-dir	추가 작업 디렉터리 접근 허용	claude --add-dir ../shared
--worktree, -w	격리된 git worktree에서 시작	claude --worktree feature-auth
--permission-mode	시작 권한 모드 지정	claude --permission-mode plan
--dangerously-skip-permissions	--permission-mode bypassPermissions 와 동등 (시작부터 권한 프롬프트 생략; 위험)	claude --dangerously-skip-permissions -p "…"
--allow-dangerously-skip-permissions	Shift+Tab 모드 사이클에 bypassPermissions 를 추가 (시작 모드는 그대로; 세션 중 전환 가능)	claude --permission-mode plan --allow-dangerously-skip-permissions
--bg, --background	백그라운드 세션으로 시작 (-p 와 동시 사용 불가)	claude --bg "task"
--effort	모델 effort 힌트 (지원 모델; low/medium/high 등)	claude --effort high -p "…"
--forward-subagent-text	서브에이전트 텍스트를 스트림에 포함 (≥2.1.211; -p + --output-format stream-json 필요)	claude -p --output-format stream-json --verbose --forward-subagent-text "query"
--model	현재 세션 모델 지정	claude --model sonnet
--output-format	print mode 출력 형식	claude -p --output-format json "query"
--system-prompt	기본 system prompt를 현재 실행에서 교체	claude --system-prompt "You are a Python expert"
--append-system-prompt	기본 system prompt 뒤에 지침 추가	claude --append-system-prompt "Always cite files"

참고: --remote 는 --cloud 의 deprecated alias 입니다. 신규 자동화는 --cloud 을 쓰세요. 전체 플래그 목록은 공식 CLI reference를 따릅니다.

세션 관련 slash command

명령	용도
/resume [session]	세션 picker 또는 ID·이름 기반 재개
/rename [name]	현재 세션 이름 변경
/branch [name]	현재 대화에서 분기 생성
/clear [name]	새 컨텍스트로 시작하고 이전 대화는 재개 가능하게 보존
/compact [instructions]	대화를 요약해 컨텍스트 확보
/context	컨텍스트 사용량 확인
/export [filename]	현재 대화를 읽기 쉬운 텍스트로 내보내기

도구에 입력할 프롬프트

현재 작업에 맞는 Claude Code 실행 방식을 골라줘.
로컬 대화형, claude -p, --continue/--resume, --cloud, remote-control 중에서
권한, 데이터 위치, 재개 가능성, 디버깅 방법을 비교하고
공식 CLI reference에 없는 하위 명령은 제안하지 마.

체크리스트

• claude --version으로 설치 버전을 확인했다.
• 세션 재개에는 --continue, --resume, /resume을 사용한다.
• 새 cloud 작업에는 --cloud를 사용하고 deprecated alias를 기본값으로 쓰지 않는다.
• 설정 변경은 세션 안 /config 또는 settings 문서를 기준으로 한다.
• 메모리는 /memory, CLAUDE.md, auto memory로 관리한다.
• 문제 재현 전 claude doctor와 --safe-mode를 먼저 시도한다.

다음 단계

• 메모리 시스템에서 CLAUDE.md와 auto memory를 정리합니다.
• 문제 해결에서 doctor, safe mode, debug 절차를 확인합니다.
• Remote Control에서 로컬 세션을 다른 기기에서 이어가는 흐름을 봅니다.