CLI 사용법과 제어

시작하기

Claude Code는 두 가지 주요 상호작용 방식을 제공합니다:

대화형 모드: claude를 실행하여 REPL 세션 시작
단일 실행 모드: 빠른 명령을 위해 claude -p "쿼리"를 사용

# 대화형 모드 시작
claude

# 초기 쿼리와 함께 시작
claude "이 프로젝트를 설명해주세요"

# 단일 명령 실행 후 종료
claude -p "이 함수는 무엇을 하나요?"

# 파이프된 내용 처리
cat logs.txt | claude -p "이 오류들을 분석해주세요"

CLI 명령어

명령어	설명	예시
`claude`	대화형 REPL 시작	`claude`
`claude "쿼리"`	초기 프롬프트와 함께 REPL 시작	`claude "이 프로젝트를 설명해주세요"`
`claude -p "쿼리"`	일회성 쿼리 실행 후 종료	`claude -p "이 함수를 설명해주세요"`
`cat file \| claude -p "쿼리"`	파이프된 내용 처리	`cat logs.txt \| claude -p "설명해주세요"`
`claude -c`	가장 최근 대화 계속하기	`claude -c`
`claude -c -p "쿼리"`	출력 모드로 계속하기	`claude -c -p "타입 오류를 확인해주세요"`
`claude -r "<session-id>" "쿼리"`	ID로 세션 재개	`claude -r "abc123" "이 PR을 완성해주세요"`
`claude config`	설정 구성	`claude config set --global theme dark`
`claude update`	최신 버전으로 업데이트	`claude update`
`claude mcp`	Model Context Protocol 서버 구성	튜토리얼의 MCP 섹션 참조

CLI 플래그

다음 명령줄 플래그로 Claude Code의 동작을 사용자 지정할 수 있습니다:

플래그	설명	예시
`--print`, `-p`	대화형 모드 없이 응답 출력 (아래 자세한 출력 모드 설명 참조)	`claude -p "쿼리"`
`--output-format`	출력 모드의 출력 형식 지정 (옵션: `text`, `json`, `stream-json`)	`claude -p "쿼리" --output-format json`
`--verbose`	상세 로깅 활성화, 전체 턴별 출력 표시 (출력 및 대화형 모드 모두에서 디버깅에 유용)	`claude --verbose`
`--max-turns`	비대화형 모드에서 에이전트 턴 수 제한	`claude -p --max-turns 3 "쿼리"`
`--permission-prompt-tool`	비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구 지정	`claude -p --permission-prompt-tool mcp_auth_tool "쿼리"`
`--resume`	ID로 또는 대화형 모드에서 선택하여 특정 세션 재개	`claude --resume abc123 "쿼리"`
`--continue`	현재 디렉토리에서 가장 최근 대화 불러오기	`claude --continue`
`--dangerously-skip-permissions`	권한 프롬프트 건너뛰기 (주의해서 사용)	`claude --dangerously-skip-permissions`

--output-format json 플래그는 특히 스크립팅과 자동화에 유용하며, Claude의 응답을 프로그래밍 방식으로 파싱할 수 있게 해줍니다.

출력 모드 상세 설명

-p (또는 --print) 플래그는 Claude Code에서 비대화형 모드를 활성화하여 프로그래밍 방식으로 입력과 출력을 파이프할 수 있게 합니다. 이 플래그는 다양한 사용 사례에 대한 여러 출력 형식을 지원합니다.

기본 사용법

# 기본 출력 모드 - 최종 응답 텍스트만 출력
claude -p "출력 플래그 사용 방법을 설명해주세요"

# stdin 입력과 함께
echo "2+2는 얼마인가요?" | claude -p

# 프롬프트와 함께 세션을 출력 모드로 재개
claude -p --resume <session-id> "이 프롬프트로 세션 재개"

출력 형식

--output-format 옵션(-p와 함께 사용)은 세 가지 형식을 지원합니다:

1. 텍스트 출력 (기본값)

claude -p "출력 형식을 설명해주세요"
# 응답 텍스트만 출력

2. JSON 출력

claude -p --output-format json "JSON 출력 사용 방법을 설명해주세요"

구조화된 JSON 객체 출력:

{
  "cost_usd": 0.003,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "result": "응답 텍스트가 여기에...",
  "session_id": "abc123"
}

3. 스트리밍 JSON 출력

claude -p --output-format stream-json "Python 스크립트를 만들어주세요"

스트리밍 모드에서는 각 메시지가 수신될 때마다 별도의 JSON 객체로 출력됩니다:

도구 사용 메시지
어시스턴트 텍스트 메시지
도구 결과 메시지
통계가 포함된 최종 시스템 메시지

출력 모드와 함께 상세 출력 사용

-p와 함께 --verbose를 사용할 때는 반드시 --output-format json 또는 --output-format stream-json과 함께 사용해야 합니다:

claude -p --verbose --output-format json "이 코드를 디버그해주세요"

상세 JSON 모드에서는 전체 대화 기록이 출력에 포함됩니다:

[
  {
    "role": "user",
    "content": "이 코드를 디버그해주세요"
  },
  {
    "role": "assistant",
    "content": "그 코드를 디버그하는 것을 도와드리겠습니다..."
  },
  {
    "role": "system",
    "cost_usd": 0.003,
    "duration_ms": 1234,
    "duration_api_ms": 800,
    "result": "응답 텍스트가 여기에...",
    "session_id": "abc123"
  }
]

출력 모드를 위한 추가 옵션

최대 턴 수

claude -p --max-turns 3 "이 코드를 수정해주세요" < file.py

비대화형 모드에서 에이전트 턴 수를 제한합니다.

권한 프롬프트 도구

claude -p --permission-prompt-tool mcp_auth_tool "파일을 만들어주세요"

비대화형 모드에서 권한 프롬프트를 처리할 MCP 도구를 지정합니다.

세션 재개

claude -p --resume abc123 "이 프롬프트로 세션 재개"

출력 모드에서 새 프롬프트와 함께 특정 세션을 ID로 재개합니다.

세션 계속하기

claude -c -p "이 다음 작업을 계속하세요"

이 프로젝트에서 마지막 대화를 계속합니다.

슬래시 명령어

대화형 세션 중 Claude의 동작을 제어합니다:

명령어	목적
`/bug`	버그 보고 (대화를 Anthropic에 전송)
`/clear`	대화 기록 지우기
`/compact [instructions]`	선택적 집중 지침과 함께 대화 압축
`/config`	설정 보기/수정
`/cost`	토큰 사용 통계 표시
`/doctor`	Claude Code 설치 상태 확인
`/help`	사용법 도움말 보기
`/init`	CLAUDE.md 가이드로 프로젝트 초기화
`/login`	Anthropic 계정 전환
`/logout`	Anthropic 계정에서 로그아웃
`/memory`	CLAUDE.md 메모리 파일 편집
`/pr_comments`	풀 리퀘스트 댓글 보기
`/review`	코드 리뷰 요청
`/status`	계정 및 시스템 상태 보기
`/terminal-setup`	줄바꿈을 위한 Shift+Enter 키 바인딩 설치 (iTerm2와 VSCode만 해당)
`/vim`	삽입 모드와 명령 모드를 번갈아 사용하는 vim 모드 진입

특수 단축키

`#`으로 빠른 메모리

입력을 #으로 시작하여 즉시 메모리를 추가합니다:

# 항상 설명적인 변수 이름 사용하기

이를 저장할 메모리 파일을 선택하라는 메시지가 표시됩니다.

터미널에서 줄바꿈

다음 방법으로 여러 줄 명령어를 입력합니다:

빠른 이스케이프: \ 입력 후 Enter
키보드 단축키: Option+Enter (또는 구성된 경우 Shift+Enter)

터미널에서 Option+Enter 설정하기:

Mac Terminal.app의 경우:

설정 → 프로필 → 키보드 열기
“Option을 Meta 키로 사용” 체크

iTerm2와 VSCode 터미널의 경우:

설정 → 프로필 → 키 열기
일반에서 왼쪽/오른쪽 Option 키를 “Esc+“로 설정

iTerm2와 VSCode 사용자를 위한 팁: Claude Code 내에서 /terminal-setup을 실행하여 더 직관적인 대안으로 Shift+Enter를 자동 구성할 수 있습니다.

자세한 구성은 설정의 터미널 설정을 참조하세요.

Vim 모드

Claude Code는 /vim 또는 /config를 통해 활성화할 수 있는 Vim 키바인딩의 일부를 지원합니다.

지원되는 기능은 다음과 같습니다:

모드 전환: Esc (NORMAL로), i/I, a/A, o/O (INSERT로)
이동: h/j/k/l, w/e/b, 0/$/^, gg/G
편집: x, dw/de/db/dd/D, cw/ce/cb/cc/C, . (반복)

Claude 코드

​시작하기

​CLI 명령어

​CLI 플래그

​출력 모드 상세 설명

​기본 사용법

​출력 형식