헤드리스 모드 (-p)

기본 사용

아무 claude 명령에 -p(또는 --print)를 붙이면 비대화형으로 실행됩니다. 성공하면 종료 코드 0, 실패하면 0이 아닌 값으로 끝나서 스크립트가 분기할 수 있습니다.

표준 입력을 읽기 때문에 다른 명령의 출력을 파이프로 넘길 수 있습니다. 파이프 입력은 10MB까지입니다.

claude -p "auth 모듈이 하는 일을 설명해줘"

cat build-error.txt | claude -p "빌드 오류의 근본 원인을 간단히 설명해줘" > output.txt

출력 형식

• text(기본): 일반 텍스트.
• json: 결과, 세션 ID, 메타데이터가 든 JSON. 텍스트 결과는 result 필드에 있고 total_cost_usd로 비용 추정치도 나옵니다(청구액과 다를 수 있음).
• stream-json: 줄 단위 JSON. 실시간 처리용이며 --verbose, --include-partial-messages와 함께 씁니다.
• --json-schema를 함께 주면 스키마에 맞는 결과가 structured_output 필드에 담깁니다. 쓰기 전에 필드가 있는지 확인하세요.

claude -p "이 프로젝트를 요약해줘" --output-format json | jq -r ".result"

권한과 이어가기

비대화형이라 승인 질문에 답할 사람이 없습니다. --allowedTools로 미리 허용할 도구를 정합니다. Bash(git diff *)처럼 뒤에 공백과 *를 붙이면 그 접두어로 시작하는 명령만 허용합니다. 공백이 없으면 git diff-index까지 맞으니 주의하세요.

--permission-mode로 기본 방식(auto, dontAsk, acceptEdits)을 정할 수도 있습니다. 문서에 따르면 v2.1.302부터는 아무 설정이 없을 때 -p가 Manual 모드로 시작하고, 승인이 필요한 호출은 거부됩니다.

이전 대화는 --continue로 이어가거나, JSON 출력에서 session_id를 얻어 --resume으로 지정해 이어갑니다.

claude -p "테스트를 돌리고 실패를 고쳐줘" --allowedTools "Bash,Read,Edit"

claude -p "성능 문제를 점검해줘"
claude -p "DB 쿼리에 집중해줘" --continue

CI에서는 --bare

--bare를 붙이면 훅, 스킬, 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 탐색을 건너뜁니다. 시작이 빨라지고 어느 컴퓨터에서나 같은 결과를 내기 쉽습니다. 이 모드는 구독 로그인을 쓰지 않으므로 ANTHROPIC_API_KEY가 필요합니다. 공식 문서는 스크립트용으로 --bare를 권장하며 앞으로 -p의 기본값이 될 예정이라고 합니다.

--bare 없이 실행하면 프로젝트의 .claude/settings.json 훅과 .mcp.json 서버가 신뢰 확인 없이 로드됩니다. 모르는 저장소에서 쓸 때는 특히 조심하세요.

/schedule, /loop과의 차이

-p는 지금 한 번 실행하는 방법이고, 언제 실행할지는 정하지 않습니다. 정해진 시각에 돌리려면 cron이나 GitHub Actions에서 -p를 호출하거나 클라우드 예약 작업(/schedule)을 씁니다. 대화형 터미널 전용 명령(/login 등)은 -p에서 쓸 수 없습니다.

실제 예시

git diff main | claude -p "오타 린터로 동작해. 오타마다 파일:줄 한 줄과 문제 한 줄만 출력해. 다른 말은 하지 마."

claude -p "auth.py의 주요 함수 이름을 뽑아줘" --output-format json --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' | jq ".structured_output"

흔한 실수와 쓰지 말아야 할 때

• --allowedTools 없이 Bash나 편집이 필요한 작업을 시키면 승인이 없어 호출이 거부된 채 끝날 수 있습니다.
• --allowedTools에 Bash 전체를 허용하면 어떤 셸 명령이든 실행됩니다. 가능한 한 Bash(git diff *)처럼 좁게 적으세요.
• --bare는 구독 로그인을 쓰지 않으므로, 키가 없으면 인증 실패로 끝납니다.
• --bare 없이 CI에서 돌리면 호스트의 훅과 플러그인 때문에 결과가 환경마다 달라질 수 있습니다.
• SIGTERM으로 멈추면 종료 코드 143이고 그 턴의 결과는 기록되지 않습니다.

자주 묻는 질문