CLI headless 실행과 claude -p¶

11/11(수)

한 줄 요약: claude -p는 Claude Code를 대화창 없이 한 번 실행하고 끝내는 방식이다. 사람이 없는 스크립트·예약 작업·CI에서 Claude에게 일을 시키는 창구이고, 물어볼 사람이 없으니 미리 허용한 것만 한다.

📍 만난 상황¶

2026-11-11 11:04 — 학습 일지 자동 정리 구조를 만들던 중이었다. 직전에 "HTML로 만들어 push하면 되지 않냐"고 물었고, GitHub가 HTML을 화면으로 보여 주지 않는다는 답을 들었다. md 방식(A)으로 가기로 정하면서, 자동 정리 스크립트에 계속 나오던 claude -p가 뭔지 물었다. 평소 쓰는 대화형 Claude Code와 무엇이 다른지 몰랐다. → 그날 일지

🧩 쉽게 말하면¶

평소 Claude Code는 전화 통화다. 말을 주고받고, 상대가 "이 파일 고쳐도 될까요?"라고 물으면 내가 답한다.

claude -p는 업무 지시 메모다. 메모 한 장을 책상에 두고 나간다. 받은 사람은 메모대로 처리하고 결과를 남긴 뒤 퇴근한다. 중간에 물어볼 사람이 없으니, 메모에 "여기까지는 해도 된다"고 미리 적어 둬야 한다.

이게 없으면 예약 작업이 Claude를 부를 방법이 없다. 대화창은 사람이 앞에 앉아 있어야 굴러가기 때문이다.

📖 제대로 알기¶

용어¶

CLI(Command Line Interface: 터미널에 명령을 쳐서 쓰는 프로그램): git, ls, claude 같은 것.
대화형(interactive) 실행: 프로그램이 켜진 채로 사람의 입력을 계속 기다린다. 평소의 claude.
비대화형·headless(headless: 화면·사람 없이 도는) 실행: 입력을 한 번에 받고, 처리하고, 끝난다.
표준입력(stdin: 프로그램이 읽어 들이는 기본 입력 통로)과 표준출력(stdout: 결과를 내보내는 기본 통로): 파이프(|)나 <, >로 파일·다른 명령과 이어 붙일 수 있다.
종료 코드(exit code: 끝날 때 남기는 숫자): 0이면 성공, 아니면 실패다. 스크립트는 이 숫자로 다음 단계를 정한다.

`-p`의 뜻¶

-p는 --print의 줄임말이다. "결과를 출력하고 종료하라"는 뜻이다.

대화형과 무엇이 다른가¶

항목	평소 `claude`	`claude -p`
실행 모습	대화창이 열려 계속 이어짐	처리 후 바로 종료
질문 전달	직접 타이핑	명령 인자나 파이프
권한 확인	그때마다 사람에게 물음	미리 허용한 것만 실행
주 용도	사람과 같이 작업	스크립트, 예약 작업, CI
모델·로그인·요금	같음	같음

핵심은 세 번째 줄이다. 대화형에서 "파일 고칠까요?"에 답하던 일을, headless에서는 실행 옵션으로 미리 정한다.

⚙️ 어떻게 동작하나¶

스크립트(또는 cron·launchd)가 claude -p를 프로세스(process: 실행 중인 프로그램 하나)로 띄운다.
Claude Code가 인자나 표준입력에서 프롬프트를 읽는다.
옵션대로 모델·도구·권한을 정한다. 허용 안 된 도구를 쓰려 하면 묻지 않고 거부한다.
필요하면 여러 턴 동안 도구를 쓰며 일을 한다. 이 과정은 화면에 대화로 보이지 않는다.
마지막 답을 표준출력에 쓴다. 옵션에 따라 글 또는 JSON이다.
종료 코드를 남기고 끝난다. 부른 스크립트가 결과와 종료 코드를 받아 다음 일을 한다.

sequenceDiagram
    participant L as launchd 18시
    participant S as 정리 스크립트
    participant C as claude -p
    L->>S: 실행
    S->>C: 프롬프트 + 대화 재료 (표준입력)
    C->>C: 허용된 도구만 써서 처리
    C-->>S: 결과 출력 + 종료 코드
    S->>S: commit 후 push

claude -p는 스크립트 입장에서 "글을 넣으면 글이 나오는 명령 하나"다. grep이나 sort처럼 다른 명령 사이에 끼울 수 있다.

🧪 예시¶

예시 1 · 일상에 빗대어: 저녁 6시, 비서(스크립트)가 메모 두 장을 들고 외주 작가(claude -p)를 부른다.
1번 메모: "세션 2개를 각각 요약해 줘. 파일은 건드리지 마." → 작가는 요약 2장을 건네고 돌아간다.
2번 메모: "요약으로 일지를 써서 이 폴더에 저장해. 파일 수정은 허락함." → 작가가 파일 13개를 쓰고 돌아간다.
작가가 "다른 폴더도 정리할까요?"라고 물을 상대는 없다. 허락 안 된 일은 그냥 안 한다.

예시 2 · 실제로는: 간단한 사용법부터.

claude -p "kustomize overlay가 뭔지 세 줄로 설명해"     # ① 인자로 질문
cat error.log | claude -p "이 로그에서 원인이 뭐야?"    # ② 파이프로 재료
claude -p "오늘 할 일 목록 만들어줘" > todo.md         # ③ 결과를 파일로

① 질문을 인자로 준다. 답을 출력하고 끝난다. ② 파일 내용을 표준입력으로 넘긴다. 질문과 재료가 합쳐진다. ③ 표준출력을 파일로 돌린다.

학습 일지 정리 스크립트(run_claude())가 붙이는 옵션이다.

claude -p \
  --model sonnet \
  --no-session-persistence \
  --settings '{"disableAllHooks":true}' \
  --strict-mcp-config \
  --tools "" \
  --permission-mode acceptEdits \
  < prompt_and_material.txt

① --model: 세션별 정리는 가벼워서 Sonnet, 하루 종합은 깊어서 Opus를 쓴다. ② --no-session-persistence: 이 실행을 대화 기록으로 남기지 않는다. 안 그러면 다음 날 "정리 작업을 정리하는" 꼬리 물기가 생긴다. ③ disableAllHooks: 평소 걸어 둔 hook(특정 시점에 자동으로 도는 스크립트)이 정리 작업에서 돌지 않게 한다. ④ --strict-mcp-config: 외부 연결(MCP: 외부 도구를 붙이는 규약)을 설정에 적은 것만 쓴다. 여기선 아무것도 안 붙인다. ⑤ --tools "": 쓸 수 있는 도구를 비운다. 1단계처럼 글만 쓰면 되는 작업용이다. ⑥ --permission-mode acceptEdits: 파일 수정을 묻지 않고 허용한다. 파일을 써야 하는 2단계에만 붙인다. ⑦ <: 프롬프트와 재료를 표준입력으로 넣는다. 인자로 넣기엔 너무 길기 때문이다.

⚖️ 비교 · 흔한 오해¶

방식	무엇을 부르나	언제 쓰나
`claude` (대화형)	Claude Code	사람이 같이 작업
`claude -p`	Claude Code	스크립트·예약·CI
API·SDK 직접 호출	모델 API	내 앱에 Claude를 넣을 때

오해 1. "-p는 다른 프로그램이다" 같은 Claude Code다. 같은 모델, 같은 로그인, 같은 요금제를 쓴다. 다른 건 사람과 주고받는 창이 없다는 것뿐이다.

오해 2. "headless면 권한 확인 없이 다 한다" 반대다. 물어볼 사람이 없으니 허용되지 않은 건 거부한다. 그래서 필요한 권한은 옵션으로 미리 열어 줘야 한다. 무엇이든 허용하는 옵션도 있지만, 자동화에서는 위험하니 범위를 좁힌다.

왜 헷갈리기 쉬운가: 평소엔 Claude가 "고칠까요?"를 묻고 내가 "응"을 누르는 게 자연스럽다. 그래서 그 확인 단계가 사람이 있을 때만 존재하는 장치라는 걸 의식하지 않게 된다.

🛠️ 실무에서는¶

언제 쓰나: 매일 도는 정리·보고, CI에서 코드 리뷰 의견 달기, 로그 요약을 다른 명령과 잇기.
언제 피하나: 판단이 자주 필요한 작업. 중간에 사람이 고를 일이 많으면 대화형이 낫다.
체크리스트
필요한 도구·권한만 열었나? (--tools, --permission-mode, 허용 도구 목록)
대화 기록을 남길지 정했나? (--no-session-persistence)
평소 hook·MCP가 자동 작업에 끼어들지 않나?
사람이 없는 환경에서 로그인은 어떻게 하나? 예약 작업은 브라우저 로그인을 못 하니 장기 토큰(claude setup-token)을 Keychain·Secrets에 둔다.
시간 제한과 실패 시 재시도가 있나?
문제가 생기면 먼저 볼 것: 종료 코드, 표준오류(stderr: 오류 메시지가 나오는 통로) 로그, "권한 거부"로 멈춘 도구가 있는지.

❓ 자주 묻는 질문¶

Q. claude -p도 여러 턴 동안 일하나? A. 한다. 도구를 쓰고 결과를 보고 다시 도구를 쓰는 과정을 안에서 반복한다. 사람에게 보여 주지 않을 뿐이다.
Q. 결과를 프로그램에서 다루기 쉽게 받을 수 있나? A. 출력 형식 옵션(--output-format json)으로 JSON을 받을 수 있다. 비용·턴 수 같은 정보도 함께 온다.
Q. 구독 로그인으로 claude -p를 돌려도 되나? A. 된다. 본인 구독으로 Claude Code CLI를 돌리는 건 허용된 용도다. 다만 그 토큰으로 직접 만든 앱에서 API를 부르는 건 별개다.

🔭 더 깊이 보기¶

자동화에서 권한을 얼마나 좁혀야 안전한가 — headless는 사람의 마지막 확인이 없어서, 허용 범위가 곧 안전장치라서.
긴 재료를 한 번에 넣으면 무엇이 문제인가 — 정리 작업의 품질과 시간이 여기서 갈려서.
관련 주제: cron 예약 실행과 클라우드 실행, LLM 컨텍스트 길이와 긴 입력 처리

📚 참고 자료¶

Run Claude Code programmatically (Headless mode) (Claude Code 공식 문서, 영문) — -p 사용법과 출력 형식 · 링크
CLI reference (Claude Code 공식 문서, 영문) — --model, --permission-mode 등 옵션 전체 목록 · 링크
Authentication (Claude Code 공식 문서, 영문) — 사람 없는 환경에서 setup-token으로 로그인하는 방법 · 링크

🗓️ 이력¶

2026-11-11: 예약 작업이 부르는 claude -p가 뭔지, 평소 대화형과 무엇이 다른지 물었다 → 일지

🕸️ 연결된 주제¶

바로 이어진 주제 4개전체 지도에서 보기 →

다른 주제 랜덤으로 보기