# Claude CLI 완전 가이드 v2: 커맨드라인 모드 (One-Shot Mode)

## 커맨드라인 모드란?

커맨드라인 모드(One-Shot Mode)는 Interactive 세션 없이 단일 명령으로 Claude를 실행하는 방식입니다. 스크립트, 자동화, CI/CD 파이프라인에 이상적입니다.

핵심 플래그: **`-p`** 또는 **`--print`**

---

## 기본 사용법

### 단순 쿼리

```bash
claude -p "JavaScript에서 배열을 역순으로 정렬하는 방법"
```

### 파일 내용과 함께 쿼리

```bash
cat app.js | claude -p "이 코드에서 버그를 찾아줘"
```

### 특정 파일 참조

```bash
claude -p "이 함수를 최적화해줘" @src/utils.js
```

### 디렉토리 컨텍스트 추가

```bash
claude -p "프로젝트 구조를 분석해줘" --add-dir /path/to/project
```

---

## 주요 플래그 및 옵션

### 출력 제어

| 플래그 | 설명 | 예시 |
|--------|------|------|
| `--output-format` | 출력 형식 지정 | `text`, `json`, `stream-json` |
| `--input-format` | 입력 형식 지정 | `text`, `stream-json` |
| `--json-schema` | JSON 스키마 검증 | 스키마에 맞는 구조화된 출력 |
| `--include-partial-messages` | 스트리밍 이벤트 포함 | 부분 메시지 수신 |

**JSON 출력 예시:**

```bash
claude -p "코드 분석 결과를 JSON으로" --output-format json
```

**스키마 검증 출력:**

```bash
claude -p "사용자 데이터 추출" --json-schema '{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "email": {"type": "string"}
  }
}'
```

---

### 실행 제어

| 플래그 | 설명 | 기본값 |
|--------|------|--------|
| `--max-turns` | 에이전트 반복 횟수 제한 | 무제한 |
| `--model` | 사용할 모델 지정 | default |
| `--verbose` | 상세 로깅 활성화 | false |
| `--timeout` | 실행 시간 제한 (초) | - |

**모델 지정:**

```bash
# 별칭 사용
claude -p "복잡한 분석" --model opus

# 사용 가능한 별칭: sonnet, opus, haiku, default
```

**반복 횟수 제한:**

```bash
claude -p "단계별로 리팩토링해줘" --max-turns 5
```

---

### 시스템 프롬프트 커스터마이징

| 플래그 | 설명 |
|--------|------|
| `--system-prompt` | 기본 시스템 프롬프트 완전 교체 |
| `--system-prompt-file` | 파일에서 프롬프트 로드 |
| `--append-system-prompt` | 기본 프롬프트에 추가 |

**추가 지시사항:**

```bash
claude -p "코드 리뷰" --append-system-prompt "보안 취약점에 집중해줘"
```

**완전 교체:**

```bash
claude -p "분석해줘" --system-prompt "너는 시니어 보안 전문가야"
```

**파일에서 로드:**

```bash
claude -p "검토해줘" --system-prompt-file ./prompts/security-review.txt
```

---

### 권한 및 도구 제어

| 플래그 | 설명 |
|--------|------|
| `--permission-mode` | 권한 모드 설정 |
| `--allowedTools` | 허용할 도구 지정 |
| `--disallowedTools` | 차단할 도구 지정 |
| `--dangerously-skip-permissions` | 모든 권한 프롬프트 건너뛰기 (주의) |

**Permission Mode 옵션:**

| 모드 | 동작 |
|------|------|
| `auto` | 모든 권한 자동 승인 |
| `plan` | 분석만 (파일 수정/명령 실행 안함) |
| `ask` | 매번 승인 요청 (기본값) |

```bash
# 읽기 전용 분석 모드
claude -p "보안 취약점 스캔" --permission-mode plan

# 자동 승인 (신뢰할 수 있는 환경에서만)
claude -p "테스트 실행" --permission-mode auto
```

**도구 제한:**

```bash
# 특정 도구만 허용
claude -p "파일 분석만 해줘" --allowedTools "Read,Glob,Grep"

# 특정 도구 차단
claude -p "코드 수정해줘" --disallowedTools "Bash"
```

---

## 실전 활용 예제

### 1. 코드 리뷰 자동화

```bash
#!/bin/bash
# review.sh - 변경된 파일 자동 리뷰

git diff --name-only HEAD~1 | while read file; do
  echo "=== Reviewing: $file ==="
  claude -p "이 파일의 변경사항을 리뷰해줘. 버그, 보안 이슈, 개선점을 찾아줘" @"$file"
  echo ""
done
```

### 2. 배치 처리

```bash
#!/bin/bash
# batch-analyze.sh - 여러 파일 분석

for file in src/*.js; do
  echo "Analyzing: $file"
  claude -p "이 코드의 복잡도와 개선점을 분석해줘" @"$file" \
    --output-format json >> analysis-results.json
  sleep 2  # Rate limit 고려
done
```

### 3. CI/CD 파이프라인 통합

```yaml
# .github/workflows/code-review.yml
name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Claude CLI
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Code Review
        run: |
          git diff origin/main...HEAD > changes.diff
          cat changes.diff | claude -p "이 PR의 변경사항을 리뷰하고 문제점을 지적해줘" \
            --output-format json > review.json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

### 4. 구조화된 데이터 추출

```bash
claude -p "이 로그에서 에러 정보를 추출해줘" @error.log \
  --json-schema '{
    "type": "object",
    "properties": {
      "errors": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "timestamp": {"type": "string"},
            "level": {"type": "string"},
            "message": {"type": "string"},
            "file": {"type": "string"},
            "line": {"type": "number"}
          }
        }
      },
      "summary": {"type": "string"},
      "total_count": {"type": "number"}
    }
  }' --output-format json
```

### 5. 문서 생성 자동화

```bash
#!/bin/bash
# generate-docs.sh - API 문서 자동 생성

claude -p "이 Express 라우터 파일들을 분석해서 API 문서를 생성해줘.
각 엔드포인트의 HTTP 메서드, 경로, 파라미터, 응답 형식을 정리해줘" \
  --add-dir ./src/routes \
  --output-format text > API_DOCUMENTATION.md
```

---

## 세션 관리 플래그

| 플래그 | 설명 |
|--------|------|
| `-c`, `--continue` | 가장 최근 세션 이어서 진행 |
| `-r`, `--resume` | 특정 세션 ID로 재개 |

```bash
# 최근 세션 이어가기
claude -c "아까 말한 함수를 수정해줘"

# 특정 세션 재개
claude -r "session-abc123" "추가 수정 요청"
```

---

## 디버깅 및 문제 해결

### Verbose 모드

```bash
claude -p "분석해줘" --verbose
```

각 턴마다 상세 로그를 출력하여 Claude의 동작을 추적할 수 있습니다.

### Exit Code 활용

| Exit Code | 의미 |
|-----------|------|
| 0 | 성공 |
| 1 | 일반 오류 |
| 2 | 권한 거부 |

```bash
claude -p "테스트 실행" --permission-mode auto
if [ $? -eq 0 ]; then
  echo "성공"
else
  echo "실패"
fi
```

---

## 주의사항

1. **Rate Limit**: 배치 처리 시 요청 간 딜레이 추가 권장 (2-5초)
2. **비용 관리**: `--max-turns`로 반복 횟수 제한
3. **보안**: `--dangerously-skip-permissions`는 신뢰할 수 있는 환경에서만 사용
4. **API Key**: 환경 변수 `ANTHROPIC_API_KEY` 설정 필요 (Console 계정 사용 시)

---

## 다음 단계

v2에서는 커맨드라인 모드의 자동화 활용법을 다뤘습니다.

**다음 v3에서는**:
- Interactive 모드 상세 사용법
- 키보드 단축키
- 멀티라인 입력
- Vim 모드

를 알아봅니다.

---

## 빠른 참조

```bash
# 기본 사용
claude -p "쿼리"

# JSON 출력
claude -p "쿼리" --output-format json

# 모델 지정
claude -p "쿼리" --model opus

# 읽기 전용 모드
claude -p "쿼리" --permission-mode plan

# 파일과 함께
cat file.txt | claude -p "분석해줘"
claude -p "분석해줘" @file.txt

# 세션 이어가기
claude -c "추가 질문"
```

---

*Claude CLI 완전 가이드 시리즈 v2/10*