188 lines
6.0 KiB
Markdown
188 lines
6.0 KiB
Markdown
# CLI 플래그
|
|
|
|
> 터미널에서 Claude Code를 실행할 때 전달할 수 있는 모든 옵션.
|
|
|
|
```bash
|
|
claude [플래그] [프롬프트]
|
|
```
|
|
|
|
## 핵심 플래그
|
|
|
|
**`-p, --print`**
|
|
Claude를 비대화형으로 실행. Claude가 프롬프트를 처리하고 응답을 출력한 후 종료합니다. REPL이 시작되지 않습니다.
|
|
```bash
|
|
claude -p "src/index.ts의 메인 함수를 설명해줘"
|
|
echo "이게 뭐야?" | claude -p
|
|
```
|
|
> ⚠️ `--print` 모드에서는 작업 공간 신뢰 다이얼로그가 건너뜁니다. 신뢰하는 디렉토리에서만 사용하세요.
|
|
|
|
**`--output-format <형식>`** (`--print`와 함께만 작동)
|
|
| 값 | 설명 |
|
|
|----|------|
|
|
| `text` | 일반 텍스트 출력 (기본값) |
|
|
| `json` | 완전한 결과가 담긴 단일 JSON 객체 |
|
|
| `stream-json` | 실시간 이벤트를 담은 줄바꿈으로 구분된 JSON 스트림 |
|
|
|
|
**`--verbose`**
|
|
상세 출력 활성화.
|
|
|
|
**`-v, --version`**
|
|
버전 번호 출력 후 종료.
|
|
|
|
## 세션 계속 플래그
|
|
|
|
**`-c, --continue`**
|
|
현재 디렉토리의 가장 최근 대화를 재개합니다.
|
|
```bash
|
|
claude --continue
|
|
claude -c "이제 테스트 추가해줘"
|
|
```
|
|
|
|
**`-r, --resume [session-id]`**
|
|
세션 ID로 대화를 재개합니다. 값 없이 사용하면 지난 세션 목록에서 선택합니다.
|
|
```bash
|
|
claude --resume
|
|
claude --resume 550e8400-e29b-41d4-a716-446655440000
|
|
claude --resume "auth refactor"
|
|
```
|
|
|
|
**`--fork-session`**
|
|
`--continue` 또는 `--resume`과 함께 사용해 재개된 대화에서 분기된 새 세션을 만듭니다.
|
|
|
|
**`-n, --name <이름>`**
|
|
세션 표시 이름 설정.
|
|
|
|
**`--no-session-persistence`**
|
|
세션 영속성 비활성화. `--print`와 함께만 작동합니다.
|
|
|
|
## 모델 및 기능 플래그
|
|
|
|
**`--model <모델>`**
|
|
세션 모델 설정. 별칭(`sonnet`, `opus`, `haiku`) 또는 전체 모델 ID(`claude-sonnet-4-6`) 허용.
|
|
```bash
|
|
claude --model sonnet
|
|
claude --model opus
|
|
claude --model claude-sonnet-4-6
|
|
```
|
|
|
|
**`--effort <레벨>`**
|
|
세션의 effort 레벨 설정: `low`, `medium` (기본), `high`, `max`.
|
|
```bash
|
|
claude --effort high "이 아키텍처를 검토해줘"
|
|
```
|
|
|
|
**`--fallback-model <모델>`**
|
|
기본 모델이 과부하될 때 자동 대체 모델 활성화. `--print`와 함께만 작동합니다.
|
|
|
|
## 권한 및 보안 플래그
|
|
|
|
**`--permission-mode <모드>`**
|
|
세션의 권한 모드 설정:
|
|
| 모드 | 동작 |
|
|
|------|------|
|
|
| `default` | 커맨드 실행 및 편집 전에 확인 요청 |
|
|
| `acceptEdits` | 파일 편집 자동 적용; 셸 커맨드는 여전히 확인 필요 |
|
|
| `plan` | 계획을 제안하고 실행 전 승인 대기 |
|
|
| `bypassPermissions` | 프롬프트 없이 모든 작업 실행 — 격리된 샌드박스 환경 전용 |
|
|
|
|
**`--dangerously-skip-permissions`**
|
|
모든 권한 검사를 우회합니다. `--permission-mode bypassPermissions`와 동일.
|
|
> ⚠️ 인터넷 접근 없는 샌드박스 환경에서만 사용하세요.
|
|
|
|
**`--allowed-tools <도구...>`** (별칭: `--allowedTools`)
|
|
Claude가 사용할 수 있는 도구의 쉼표 또는 공백 구분 목록.
|
|
```bash
|
|
claude --allowed-tools "Bash(git:*) Edit Read"
|
|
```
|
|
|
|
**`--disallowed-tools <도구...>`**
|
|
Claude가 사용할 수 없는 도구 목록.
|
|
|
|
**`--tools <도구...>`**
|
|
세션에 사용 가능한 정확한 내장 도구 집합 지정. `""`는 모든 도구 비활성화.
|
|
|
|
## 컨텍스트 및 프롬프트 플래그
|
|
|
|
**`--add-dir <디렉토리...>`**
|
|
도구 접근 컨텍스트에 하나 이상의 디렉토리 추가.
|
|
```bash
|
|
claude --add-dir /shared/libs --add-dir /shared/config
|
|
```
|
|
|
|
**`--system-prompt <프롬프트>`**
|
|
기본 시스템 프롬프트를 커스텀 프롬프트로 교체.
|
|
|
|
**`--append-system-prompt <텍스트>`**
|
|
기본 시스템 프롬프트에 텍스트 추가. `--system-prompt`와 달리 내장 지시사항을 유지합니다.
|
|
|
|
**`--mcp-config <설정...>`**
|
|
하나 이상의 JSON 설정 파일 또는 인라인 JSON 문자열에서 MCP 서버 로드.
|
|
|
|
**`--strict-mcp-config`**
|
|
`--mcp-config`의 MCP 서버만 사용하고 다른 모든 MCP 설정 무시.
|
|
|
|
**`--settings <파일-또는-json>`**
|
|
JSON 파일 경로 또는 인라인 JSON 문자열에서 추가 설정 로드.
|
|
|
|
**`--agents <json>`**
|
|
JSON 객체로 커스텀 에이전트를 인라인으로 정의.
|
|
|
|
## 출력 제어 플래그
|
|
|
|
**`--max-turns <n>`**
|
|
비대화형 모드의 에이전틱 턴 수 제한. `--print`와 함께만 작동합니다.
|
|
|
|
**`--max-budget-usd <금액>`**
|
|
API 호출 최대 지출 금액 설정. `--print`와 함께만 작동합니다.
|
|
|
|
**`--json-schema <스키마>`**
|
|
구조화된 출력 검증을 위한 JSON 스키마 제공.
|
|
|
|
## Worktree 플래그
|
|
|
|
**`-w, --worktree [이름]`**
|
|
세션에 새 git worktree 생성. PR 번호나 GitHub PR URL 허용.
|
|
```bash
|
|
claude --worktree
|
|
claude --worktree feature-auth
|
|
claude --worktree "#142"
|
|
```
|
|
|
|
**`--tmux`**
|
|
worktree와 함께 tmux 세션 생성. `--worktree` 필요.
|
|
|
|
## 디버그 플래그
|
|
|
|
**`-d, --debug [필터]`**
|
|
디버그 모드 활성화.
|
|
```bash
|
|
claude --debug
|
|
claude --debug "api,hooks"
|
|
claude --debug "!file,!1p"
|
|
```
|
|
|
|
**`--debug-file <경로>`**
|
|
디버그 로그를 인라인 표시 대신 파일에 저장.
|
|
|
|
**`--bare`**
|
|
최소 모드. 훅, LSP, 플러그인 동기화, 어트리뷰션, 자동 메모리, 백그라운드 프리페치, 키체인 읽기, `CLAUDE.md` 자동 발견을 모두 건너뜁니다. 스타트업 지연이 중요하고 이러한 기능이 필요하지 않은 스크립트 파이프라인에 사용하세요.
|
|
|
|
## 일반적인 플래그 조합
|
|
|
|
```bash
|
|
# JSON 출력과 함께 비대화형
|
|
claude -p "모든 내보낸 타입 목록" --output-format json
|
|
|
|
# CI에서 권한 우회 (샌드박스 환경 전용)
|
|
claude -p "전체 테스트 스위트 실행하고 실패 수정해줘" --dangerously-skip-permissions
|
|
|
|
# 마지막 세션 재개 후 비대화형으로 계속
|
|
claude --continue -p "이제 그것에 대한 테스트 작성해줘"
|
|
|
|
# 커스텀 MCP 설정으로 엄격한 격리
|
|
claude --mcp-config ./ci-mcp.json --strict-mcp-config -p "스키마 분석해줘"
|
|
|
|
# 시스템 프롬프트를 교체하지 않고 추가
|
|
claude --append-system-prompt "항상 JavaScript가 아닌 TypeScript를 출력하세요."
|
|
```
|