​
개요

헤드리스 모드를 사용하면 대화형 UI 없이 명령줄 스크립트와 자동화 도구에서 Claude Code를 프로그래밍 방식으로 실행할 수 있습니다.

​
기본 사용법

Claude Code의 주요 명령줄 인터페이스는 claude 명령입니다. --print (또는 -p) 플래그를 사용하여 비대화형 모드로 실행하고 최종 결과를 출력합니다:

claude -p "내 변경사항을 스테이징하고 이에 대한 커밋 세트를 작성해줘" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

​
구성 옵션

SDK는 Claude Code에서 사용 가능한 모든 CLI 옵션을 활용합니다. SDK 사용을 위한 주요 옵션들은 다음과 같습니다:

플래그설명예시
--print, -p비대화형 모드로 실행claude -p "쿼리"
--output-format출력 형식 지정 (text, json, stream-json)claude -p --output-format json
--resume, -r세션 ID로 대화 재개claude --resume abc123
--continue, -c가장 최근 대화 계속claude --continue
--verbose상세 로깅 활성화claude --verbose
--append-system-prompt시스템 프롬프트에 추가 (--print와 함께만 사용)claude --append-system-prompt "사용자 지정 지시사항"
--allowedTools허용된 도구의 공백으로 구분된 목록, 또는

쉼표로 구분된 허용 도구 목록 문자열		claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedTools거부된 도구의 공백으로 구분된 목록, 또는

쉼표로 구분된 거부 도구 목록 문자열		claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configJSON 파일에서 MCP 서버 로드claude --mcp-config servers.json
--permission-prompt-tool권한 프롬프트 처리를 위한 MCP 도구 (--print와 함께만 사용)claude --permission-prompt-tool mcp__auth__prompt

CLI 옵션과 기능의 전체 목록은 CLI 참조 문서를 참조하세요.

​
다중 턴 대화

다중 턴 대화의 경우, 대화를 재개하거나 가장 최근 세션에서 계속할 수 있습니다:

# 가장 최근 대화 계속
claude --continue "이제 더 나은 성능을 위해 리팩토링해줘"

# 세션 ID로 특정 대화 재개
claude --resume 550e8400-e29b-41d4-a716-446655440000 "테스트를 업데이트해줘"

# 비대화형 모드로 재개
claude --resume 550e8400-e29b-41d4-a716-446655440000 "모든 린팅 문제를 수정해줘" --no-interactive

​
출력 형식

​
텍스트 출력 (기본값)

claude -p "src/components/Header.tsx 파일을 설명해줘"
# 출력: 이것은 다음을 보여주는 React 컴포넌트입니다...

​
JSON 출력

메타데이터를 포함한 구조화된 데이터를 반환합니다:

claude -p "데이터 레이어는 어떻게 작동하나요?" --output-format json

응답 형식:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "여기에 응답 텍스트...",
  "session_id": "abc123"
}

​
스트리밍 JSON 출력

수신되는 각 메시지를 스트리밍합니다:

claude -p "애플리케이션을 구축해줘" --output-format stream-json

각 대화는 초기 init 시스템 메시지로 시작하고, 사용자와 어시스턴트 메시지 목록이 이어지며, 통계가 포함된 최종 result 시스템 메시지로 끝납니다. 각 메시지는 별도의 JSON 객체로 방출됩니다.

​
입력 형식

​
텍스트 입력 (기본값)

# 직접 인수
claude -p "이 코드를 설명해줘"

# stdin에서
echo "이 코드를 설명해줘" | claude -p

​
스트리밍 JSON 입력

각 메시지가 사용자 턴을 나타내는 stdin을 통해 제공되는 메시지 스트림입니다. 이를 통해 claude 바이너리를 다시 실행하지 않고도 대화의 여러 턴을 수행할 수 있으며, 모델이 요청을 처리하는 동안 지침을 제공할 수 있습니다.

각 메시지는 출력 메시지 스키마와 동일한 형식을 따르는 JSON ‘사용자 메시지’ 객체입니다. 메시지는 입력의 각 줄이 완전한 JSON 객체인 jsonl 형식을 사용하여 포맷됩니다. 스트리밍 JSON 입력에는 -p와 --output-format stream-json이 필요합니다.

echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"이 코드를 설명해줘"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

​
에이전트 통합 예시

​
SRE 인시던트 대응 봇

#!/bin/bash

# 자동화된 인시던트 대응 에이전트
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "인시던트: $incident_description (심각도: $severity)" \
      --append-system-prompt "당신은 SRE 전문가입니다. 문제를 진단하고, 영향을 평가하며, 즉각적인 조치 항목을 제공하세요." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# 사용법
investigate_incident "결제 API가 500 오류를 반환함" "high"

​
자동화된 보안 검토

# 풀 리퀘스트를 위한 보안 감사 에이전트
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "당신은 보안 엔지니어입니다. 이 PR을 취약점, 안전하지 않은 패턴, 규정 준수 문제에 대해 검토하세요." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# 사용법 및 파일에 저장
audit_pr 123 > security-report.json

​
다중 턴 법무 어시스턴트

# 세션 지속성을 가진 법적 문서 검토
session_id=$(claude -p "법적 검토 세션 시작" --output-format json | jq -r '.session_id')

# 여러 단계로 계약서 검토
claude -p --resume "$session_id" "contract.pdf에서 책임 조항을 검토해줘"
claude -p --resume "$session_id" "GDPR 요구사항 준수를 확인해줘"
claude -p --resume "$session_id" "위험에 대한 경영진 요약을 생성해줘"

​
모범 사례

  • 응답의 프로그래밍 방식 파싱을 위해 JSON 출력 형식 사용:

    # jq로 JSON 응답 파싱
result=$(claude -p "코드 생성" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')

  • 오류를 우아하게 처리 - 종료 코드와 stderr 확인:

    if ! claude -p "$prompt" 2>error.log; then
    echo "오류가 발생했습니다:" >&2
    cat error.log >&2
    exit 1
fi

  • 다중 턴 대화에서 컨텍스트 유지를 위한 세션 관리 사용

  • 장시간 실행되는 작업에 대한 타임아웃 고려:

    timeout 300 claude -p "$complex_prompt" || echo "5분 후 타임아웃됨"

  • 여러 요청을 할 때 호출 간 지연을 추가하여 속도 제한 준수

​
관련 리소스