Claude Code 공식문서 리뷰-참고자료(Reference)[1] : CLI 참고 자료(CLI reference)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> [참고자료(Reference)] 섹션의 내용 중 [CLI 참고 자료(CLI reference)]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/ko/cli-reference

CLI 참고 자료 - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

CLI를 알면 생산성이 달라진다

Claude Code는 터미널에서 바로 실행하는 명령줄 도구다. GUI 없이 터미널만으로 코드 작성, 분석, 리뷰를 할 수 있고, 자동화 스크립트나 CI/CD 파이프라인에 통합할 수 있다는 것이 큰 장점이다.

CLI (Command Line Interface)란?
터미널에서 텍스트 명령으로 프로그램을 제어하는 인터페이스다. GUI(그래픽 사용자 인터페이스)와 달리 마우스 클릭 대신 명령어 입력으로 모든 작업을 수행한다.

CLI 사용이 유리한 상황

• 터미널 작업 중 IDE를 열지 않고 빠르게 코드 질문
• CI/CD 파이프라인에서 자동 코드 리뷰
• SSH 원격 서버에서 코드 분석
• 여러 프로젝트를 오가며 작업할 때
• JSON 출력으로 다른 도구와 연동

출처: 공식 CLI Reference 문서

 

시작하기 전에 알아둘 것

CLI를 본격적으로 사용하기 전에 몇 가지 기본 개념을 이해하면 훨씬 수월하다.

필수 준비물

• Claude Code 설치 완료
  -> 터미널에서 claude --version 실행하면 확인 가능
• 인증 완료
  -> Anthropic 계정 로그인 또는 API 키/Vertex AI/Bedrock 설정

핵심 용어 정리

REPL	Read-Eval-Print Loop. 명령을 입력하면 바로 결과를 보여주는 대화형 환경. claude만 실행하면 REPL 모드로 진입한다.
Print 모드	-p 플래그를 사용하면 응답만 출력하고 바로 종료. 스크립트 자동화에 필수적이다.
세션	대화의 맥락이 저장되는 단위. 세션 ID로 이전 대화를 이어갈 수 있다.
서브에이전트	특정 작업에 특화된 보조 에이전트. 코드 리뷰, 디버깅 등 전문 역할을 맡길 수 있다.

 

상황별 사용 가이드 - 이럴 땐 이렇게

명령어가 많아서 뭘 써야 할지 모르겠다면?

자신의 상황에 맞는 명령어를 찾아보자. 대부분의 경우 2-3개 명령어만 알면 충분하다.

상황 1: "Claude Code를 처음 써봐요"

가장 기본적인 사용법. 터미널에서 바로 대화를 시작한다.

이렇게 시작하자

# 대화형 모드로 시작 (가장 기본)
claude

# 질문과 함께 시작
claude "이 프로젝트가 뭘 하는 건지 설명해줘"

-> 대화형 모드에서 /help를 입력하면 사용 가능한 명령어를 볼 수 있다.

상황 2: "빠르게 질문하고 끝내고 싶어요"

대화를 이어갈 필요 없이 한 번만 물어보고 싶을 때. Print 모드(-p)를 사용한다.

이렇게 사용하자

# 질문하고 응답만 받기
claude -p "Git에서 마지막 커밋 취소하는 방법"

# 파일 내용을 분석해달라고 하기
cat error.log | claude -p "이 에러 원인이 뭐야?"

# 코드 파일 설명 요청
cat src/main.py | claude -p "이 코드가 뭘 하는지 설명해줘"

상황 3: "아까 하던 대화를 이어가고 싶어요"

터미널을 닫았다가 다시 열어도 이전 대화를 계속할 수 있다.

이렇게 사용하자

# 가장 최근 대화 계속하기 (가장 많이 씀)
claude -c

# 특정 세션 이름으로 재개
claude -r "auth-refactor"

# 세션 재개하면서 질문 추가
claude -r "auth-refactor" "아까 그 함수에 에러 처리 추가해줘"

-> 세션 목록은 대화형 모드에서 /sessions로 확인 가능

상황 4: "CI/CD나 스크립트에서 자동으로 돌리고 싶어요"

JSON 출력과 Print 모드를 조합하면 자동화가 가능하다.

이렇게 사용하자

# JSON 형식으로 출력 (파싱하기 좋음)
claude -p "코드 분석해줘" --output-format json

# 권한 프롬프트 건너뛰기 (자동화 환경용)
claude -p --dangerously-skip-permissions "테스트 실행해줘"

# 특정 도구만 사용하도록 제한
claude -p --tools "Read,Grep,Glob" "이 코드에서 TODO 찾아줘"

# 턴 수 제한 (무한 루프 방지)
claude -p --max-turns 5 "버그 찾아서 고쳐줘"

상황 5: "더 똑똑한 모델을 쓰고 싶어요"

복잡한 추론이 필요하면 Opus, 빠른 응답이 필요하면 Haiku를 선택할 수 있다.

이렇게 사용하자

# Opus 모델 사용 (가장 강력, 비용 높음)
claude --model opus

# 별칭으로 간단히
claude --model sonnet  # 기본값

# 폴백 모델 지정 (기본 모델 과부하 시)
claude -p --fallback-model sonnet "복잡한 분석"

 

기본 명령어 레퍼런스

이것만 알면 80%는 커버된다

아래 표에서 자주 쓰는 명령어 위주로 익혀두자.

명령어	설명	예시
claude	대화형 REPL 시작	claude
claude "질문"	초기 프롬프트와 함께 REPL 시작	claude "이 프로젝트 설명해줘"
claude -p "질문"	Print 모드: 응답 출력 후 종료	claude -p "함수 설명해줘"
cat file | claude -p	파이프된 콘텐츠 처리	cat logs.txt | claude -p "설명해줘"
claude -c	가장 최근 대화 계속하기	claude -c
claude -r "세션"	ID나 이름으로 세션 재개	claude -r "auth-refactor"
claude update	최신 버전으로 업데이트	claude update
claude mcp	MCP 서버 설정	MCP 문서 참조

 

핵심 플래그 상세

세션 관리 플래그

세션이란?

Claude Code는 대화 내용을 세션 단위로 저장한다. 터미널을 닫아도 세션은 유지되며, 나중에 -c나 -r로 다시 이어갈 수 있다.

플래그	설명
--continue, -c	현재 디렉토리에서 가장 최근 대화 불러오기
--resume, -r	ID나 이름으로 특정 세션 재개
--session-id	특정 세션 ID 사용 (유효한 UUID 필요)
--fork-session	원본 세션 유지하면서 새 세션으로 분기 (--resume/--continue와 함께)

# 세션 재개 기본 예시
claude --resume auth-refactor

# 세션 재개하면서 질문 추가
claude --resume auth-refactor "타입 에러 고쳐줘"

# 대화를 새 세션으로 분기 (원본은 그대로 유지)
claude --resume abc123 --fork-session

초보자 팁

--fork-session은 "이 시점에서 다른 방향으로 시도해보고 싶을 때" 유용하다. 원본 대화는 그대로 남아있어서 나중에 비교할 수 있다.

모델 설정 플래그

플래그	설명
--model	세션용 모델 설정 (별칭: sonnet, opus, 또는 전체 모델명)
--fallback-model	기본 모델 과부하 시 자동 폴백 (print 모드 전용)

# Opus 모델 사용 (가장 강력)
claude --model opus

# 전체 모델명으로 지정
claude --model claude-sonnet-4-5-20250929

# 폴백 모델 지정 (print 모드)
claude -p --fallback-model sonnet "복잡한 분석 수행"

언제 어떤 모델을 쓸까?

Sonnet (기본)	대부분의 코딩 작업에 적합. 속도와 품질의 균형이 좋다. -> 일상적인 개발 작업, 코드 작성, 리팩토링
Opus	복잡한 추론과 분석에 강하다. 비용이 더 높다. -> 아키텍처 설계, 복잡한 버그 분석, 대규모 리팩토링
Haiku	가장 빠르고 저렴하다. 간단한 작업에 적합. -> 파일 탐색, 간단한 검색, 빠른 응답 필요 시

출력 모드 플래그

플래그	설명
--print, -p	대화형 모드 없이 응답 출력 후 종료
--output-format	출력 형식: text, json, stream-json
--input-format	입력 형식: text, stream-json
--verbose	상세 로깅 및 턴별 출력 활성화
--include-partial-messages	부분 스트리밍 이벤트 포함 (stream-json과 함께)

# 텍스트 출력 (기본)
claude -p "질문"

# JSON 출력 (스크립트 파싱용)
claude -p "query" --output-format json

# 스트리밍 JSON + 부분 메시지
claude -p "query" --output-format stream-json --include-partial-messages

 

도구 및 권한 플래그

도구(Tool)란?

Claude Code가 파일을 읽고(Read), 수정하고(Edit), 명령을 실행(Bash)하는 등의 기능을 "도구"라고 한다. 보안을 위해 도구 사용을 제한하거나 허용할 수 있다.

도구 제어 플래그

플래그	설명
--tools	사용 가능한 도구 지정: "" (없음), "default" (전체), 또는 도구명
--allowedTools	권한 프롬프트 없이 실행할 도구 (자동 허용)
--disallowedTools	완전히 비활성화할 도구 (컨텍스트에서 제거)

# 읽기 전용으로 제한 (안전한 탐색)
claude -p --tools "Read,Grep,Glob" "이 코드 분석해줘"

# 특정 git 명령만 자동 허용
claude --allowedTools "Bash(git log:*)" "Bash(git diff:*)" "Read"

# 위험한 명령 비활성화
claude --disallowedTools "Bash(rm:*)" "Bash(sudo:*)"

자주 쓰는 도구 목록

• Read - 파일 읽기
• Edit - 파일 수정
• Write - 파일 생성
• Bash - 셸 명령 실행
• Grep - 패턴 검색
• Glob - 파일 찾기

권한 모드 플래그

플래그	설명
--permission-mode	지정된 권한 모드로 시작 (예: plan)
--dangerously-skip-permissions	모든 권한 프롬프트 건너뛰기
--permission-prompt-tool	비대화형 모드에서 권한 처리할 MCP 도구

경고: --dangerously-skip-permissions

이 플래그는 모든 권한 확인을 건너뛴다. 신뢰할 수 있는 환경(샌드박스, CI/CD)에서만 사용하고, 중요한 시스템에서는 절대 사용하지 말자.

 

시스템 프롬프트 플래그

시스템 프롬프트란?

Claude의 기본 동작 방식을 정의하는 지침이다. "항상 TypeScript를 사용해라", "코드에 주석을 꼭 달아라" 같은 규칙을 설정할 수 있다.

플래그	동작	모드	사용 사례
--append-system-prompt	기본에 추가	대화형 + Print	기능 유지하며 지침 추가 (권장)
--system-prompt	기본 전체 교체	대화형 + Print	완전한 제어가 필요할 때
--system-prompt-file	파일로 교체	Print 전용	재현성 있는 자동화

# 가장 많이 쓰는 방법: 기존 기능 유지하면서 지침 추가
claude --append-system-prompt "항상 TypeScript를 사용하고 JSDoc 주석을 포함해"

# 완전히 새로운 페르소나로
claude --system-prompt "당신은 Python 전문가입니다. 타입 힌트를 항상 사용합니다."

# 파일에서 로드 (CI/CD에서 유용)
claude -p --system-prompt-file ./prompts/code-review.txt "이 PR 리뷰해줘"

권장 사항

대부분의 경우: --append-system-prompt 사용
-> Claude Code의 기본 기능(파일 읽기, 코드 분석 등)이 유지되면서 추가 지침만 적용된다.

완전한 제어 필요시: --system-prompt 또는 --system-prompt-file
-> 기본 프롬프트가 완전히 대체되므로 필요한 모든 지침을 직접 작성해야 한다.

 

커스텀 에이전트 (서브에이전트)

서브에이전트란?

특정 작업에 전문화된 보조 에이전트다. 예를 들어 "코드 리뷰 전문가", "디버깅 전문가" 같은 역할을 정의해서 사용할 수 있다. 반복적인 작업에 일관된 품질을 유지하는 데 유용하다.

--agents 플래그는 커스텀 서브에이전트를 정의하는 JSON 객체를 받는다:

{
  "code-reviewer": {
    "description": "코드 리뷰 전문가. 코드 변경 후 사전에 사용.",
    "prompt": "당신은 시니어 코드 리뷰어입니다. 코드 품질, 보안, 모범 사례에 집중하세요.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "에러 및 테스트 실패 전문 디버거.",
    "prompt": "당신은 전문 디버거입니다. 에러를 분석하고 근본 원인을 파악해 해결책을 제시하세요."
  }
}

필드 설명

필드	필수	설명
description	필수	서브에이전트를 언제 호출할지 설명
prompt	필수	동작을 안내하는 시스템 프롬프트
tools	선택	사용할 도구 배열 (생략 시 모든 도구 상속)
model	선택	모델 별칭: sonnet, opus, haiku

실전 활용 예시

• 코드 리뷰어: PR 전에 자동으로 코드 품질 체크
• 테스트 작성자: 새 함수에 대한 테스트 케이스 생성
• 문서 작성자: 코드에 JSDoc/docstring 추가
• 보안 감사자: 보안 취약점 스캔

 

기타 유용한 플래그

MCP 설정

플래그	설명
--mcp-config	JSON 파일에서 MCP 서버 로드
--strict-mcp-config	--mcp-config의 MCP 서버만 사용

환경 및 연결

플래그	설명
--add-dir	추가 작업 디렉토리 추가 (다중 프로젝트 작업 시)
--chrome / --no-chrome	Chrome 브라우저 연동 활성화/비활성화
--ide	유효한 IDE가 있으면 시작 시 자동 연결
--settings	설정 JSON 파일 경로
--plugin-dir	플러그인 디렉토리 로드 (반복 가능)

디버그 및 고급

플래그	설명
--debug	디버그 모드 (카테고리 필터링 가능: "api,mcp")
--enable-lsp-logging	상세 LSP 로깅 (~/.claude/debug/에 저장)
--max-turns	에이전트 턴 수 제한 (무한 루프 방지)
--json-schema	JSON 스키마에 맞는 구조화 출력 (print 모드)
--betas	베타 기능 헤더 (API 키 사용자용)
-v, --version	버전 번호 출력

# 카테고리별 디버그
claude --debug "api,hooks"

# 특정 카테고리 제외
claude --debug "!statsig,!file"

# 여러 디렉토리에서 작업
claude --add-dir ../apps ../lib

# JSON 스키마로 구조화된 출력
claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' "버그 목록 추출"

 

실전 워크플로우 예시

실제 개발에서 이렇게 쓴다

CLI 플래그를 조합해서 실제 개발 워크플로우에 활용하는 예시들이다.

워크플로우 1: 코드 리뷰 자동화

# Git diff를 Claude에게 전달해서 리뷰
git diff main | claude -p "이 변경사항을 리뷰해줘. 버그, 보안 이슈, 개선점을 찾아줘"

# JSON 출력으로 CI/CD 파이프라인에서 파싱
git diff main | claude -p \
  --output-format json \
  --max-turns 5 \
  "코드 리뷰하고 issues 배열로 반환해"

워크플로우 2: 에러 로그 분석

# 에러 로그 분석
cat error.log | claude -p "이 에러의 원인과 해결책을 알려줘"

# 최근 100줄만 분석
tail -100 app.log | claude -p "에러 패턴을 찾아서 요약해줘"

워크플로우 3: 커스텀 에이전트로 보안 감사

# 보안 감사 에이전트 정의
claude \
  --agents '{"security":{"description":"보안 취약점 탐지","prompt":"OWASP Top 10 기준으로 취약점을 찾아라","tools":["Read","Grep","Glob"]}}' \
  "src/ 디렉토리 보안 점검해줘"

워크플로우 4: 프로젝트별 환경 설정

# 프로젝트별 설정 파일 사용
claude \
  --settings ./project-settings.json \
  --mcp-config ./mcp-servers.json \
  --append-system-prompt "이 프로젝트는 React + TypeScript 스택이다" \
  "개발 시작"

워크플로우 5: 셸 스크립트로 래핑

#!/bin/bash
# review.sh - 코드 리뷰 자동화

echo "코드 리뷰를 시작합니다..."

git diff main | claude -p \
  --model sonnet \
  --output-format text \
  --tools "Read,Grep,Glob" \
  "변경된 코드를 리뷰하고, 문제점과 개선 제안을 해줘"

 

문제 해결 - 자주 겪는 문제

CLI 사용 중 막혔을 때

아래 체크리스트를 순서대로 확인해보자.

문제 1: "command not found: claude"

증상

claude 명령어를 찾을 수 없다는 에러

해결 방법

1. 설치 확인

   npm list -g @anthropic-ai/claude-code

2. PATH 확인

   echo $PATH | tr ':' '\n' | grep npm

3. 재설치

   npm install -g @anthropic-ai/claude-code

문제 2: "Permission denied" 에러가 계속 뜸

증상

매번 권한 확인 프롬프트가 뜨거나, 자동화 스크립트가 멈춤

해결 방법

1. 신뢰할 수 있는 도구 허용

   claude --allowedTools "Read" "Grep" "Glob" "질문"

2. 자동화 환경에서 (주의해서 사용)

   claude -p --dangerously-skip-permissions "질문"

문제 3: 세션을 찾을 수 없음

증상

-c나 -r로 세션 재개가 안 됨

해결 방법

1. 세션 목록 확인

   # 대화형 모드에서
   /sessions

2. 작업 디렉토리 확인
   -> 세션은 디렉토리별로 저장된다. 같은 디렉토리에서 실행하는지 확인

문제 4: JSON 출력이 파싱이 안 됨

증상

--output-format json으로 받은 결과가 올바른 JSON이 아님

해결 방법

1. JSON 스키마로 출력 강제

   claude -p --json-schema '{"type":"object","properties":{"result":{"type":"string"}}}' "질문"

2. jq로 필터링

   claude -p "질문" --output-format json | jq '.result'

 

핵심 요약 - 빠른 참조 체크리스트

가장 많이 쓰는 명령어 TOP 5

1. claude - 대화 시작
2. claude -p "질문" - 빠른 질문
3. claude -c - 이전 대화 계속
4. cat file | claude -p "분석해줘" - 파일 분석
5. claude update - 업데이트

목적	명령어
대화 시작	claude 또는 claude "질문"
빠른 질문 (종료)	claude -p "질문"
이전 대화 계속	claude -c
특정 세션 재개	claude -r "세션이름"
파일 분석	cat file | claude -p "분석해줘"
JSON 출력	claude -p "질문" --output-format json
모델 변경	claude --model opus
읽기 전용 모드	claude -p --tools "Read,Grep,Glob" "분석해줘"
지침 추가	claude --append-system-prompt "항상 TypeScript 사용"
자동화 (권한 스킵)	claude -p --dangerously-skip-permissions "질문"

 

관련 문서

문서	설명
대화형 모드	키보드 단축키, 슬래시 명령어, UI 기능
슬래시 명령	/help, /clear, /sessions 등 세션 내 명령어
Settings	설정 파일 구조 및 옵션
MCP	Model Context Protocol 서버 설정
서브에이전트	커스텀 에이전트 시스템 상세