메인 콘텐츠로 건너뛰기
Agent SDK는 Claude Code를 구동하는 동일한 도구, 에이전트 루프 및 컨텍스트 관리를 제공합니다. 스크립트 및 CI/CD용 CLI로 사용하거나 완전한 프로그래밍 방식 제어를 위한 Python 및 TypeScript 패키지로 사용할 수 있습니다.
CLI는 이전에 “헤드리스 모드”라고 불렸습니다. -p 플래그 및 모든 CLI 옵션은 동일한 방식으로 작동합니다.
CLI에서 Claude Code를 프로그래밍 방식으로 실행하려면 프롬프트와 함께 -p를 전달하고 CLI 옵션을 사용합니다: 
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
이 페이지는 CLI(claude -p)를 통한 Agent SDK 사용을 다룹니다. 구조화된 출력, 도구 승인 콜백 및 기본 메시지 객체가 있는 Python 및 TypeScript SDK 패키지의 경우 전체 Agent SDK 문서를 참조하십시오.

​
기본 사용법

-p(또는 --print) 플래그를 모든 claude 명령에 추가하여 비대화형으로 실행합니다. 모든 CLI 옵션은 -p와 함께 작동합니다: 이 예제는 코드베이스에 대해 Claude에 질문하고 응답을 출력합니다: 
claude -p "What does the auth module do?"

​
예제

이 예제들은 일반적인 CLI 패턴을 강조합니다.

​
구조화된 출력 가져오기

--output-format을 사용하여 응답이 반환되는 방식을 제어합니다:
  • text(기본값): 일반 텍스트 출력
  • json: 결과, 세션 ID 및 메타데이터가 포함된 구조화된 JSON
  • stream-json: 실시간 스트리밍을 위한 줄 구분 JSON
이 예제는 세션 메타데이터와 함께 프로젝트 요약을 JSON으로 반환하며, 텍스트 결과는 result 필드에 있습니다: 
claude -p "Summarize this project" --output-format json
특정 스키마를 준수하는 출력을 얻으려면 --output-format json을 --json-schema 및 JSON Schema 정의와 함께 사용합니다. 응답에는 요청에 대한 메타데이터(세션 ID, 사용량 등)가 포함되며 구조화된 출력은 structured_output 필드에 있습니다. 이 예제는 함수 이름을 추출하고 문자열 배열로 반환합니다: 
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
jq와 같은 도구를 사용하여 응답을 구문 분석하고 특정 필드를 추출합니다:
# 텍스트 결과 추출
claude -p "Summarize this project" --output-format json | jq -r '.result'

# 구조화된 출력 추출
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

​
응답 스트리밍

--output-format stream-json을 --verbose 및 --include-partial-messages와 함께 사용하여 생성되는 토큰을 수신합니다. 각 줄은 이벤트를 나타내는 JSON 객체입니다: 
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
다음 예제는 jq를 사용하여 텍스트 델타를 필터링하고 스트리밍 텍스트만 표시합니다. -r 플래그는 원본 문자열(따옴표 없음)을 출력하고 -j는 줄 바꿈 없이 조인하므로 토큰이 계속 스트리밍됩니다: 
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
콜백 및 메시지 객체를 사용한 프로그래밍 방식 스트리밍의 경우 Agent SDK 문서의 실시간 응답 스트리밍을 참조하십시오.

​
도구 자동 승인

--allowedTools를 사용하여 Claude가 프롬프트 없이 특정 도구를 사용하도록 합니다. 이 예제는 테스트 스위트를 실행하고 실패를 수정하며, Claude가 권한을 요청하지 않고 Bash 명령을 실행하고 파일을 읽고 편집할 수 있도록 합니다: 
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

​
커밋 생성

이 예제는 스테이징된 변경 사항을 검토하고 적절한 메시지로 커밋을 생성합니다: 
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
--allowedTools 플래그는 권한 규칙 구문을 사용합니다. 뒤의 *는 접두사 일치를 활성화하므로 Bash(git diff *)는 git diff로 시작하는 모든 명령을 허용합니다. 공백이 중요합니다: 없으면 Bash(git diff*)도 git diff-index와 일치합니다.
사용자가 호출한 skills(/commit 등) 및 기본 제공 명령은 대화형 모드에서만 사용할 수 있습니다. -p 모드에서는 대신 수행하려는 작업을 설명합니다.

​
시스템 프롬프트 사용자 정의

--append-system-prompt를 사용하여 Claude Code의 기본 동작을 유지하면서 지침을 추가합니다. 이 예제는 PR diff를 Claude에 파이프하고 보안 취약점을 검토하도록 지시합니다: 
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
기본 프롬프트를 완전히 바꾸는 --system-prompt를 포함한 더 많은 옵션은 시스템 프롬프트 플래그를 참조하십시오.

​
대화 계속하기

--continue를 사용하여 가장 최근 대화를 계속하거나 --resume을 세션 ID와 함께 사용하여 특정 대화를 계속합니다. 이 예제는 검토를 실행한 다음 후속 프롬프트를 보냅니다: 
# 첫 번째 요청
claude -p "Review this codebase for performance issues"

# 가장 최근 대화 계속
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
여러 대화를 실행 중인 경우 세션 ID를 캡처하여 특정 대화를 재개합니다: 
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

​
다음 단계