muaco Tech Note

Claude Codecode.claude.com

Claude Code 스크립트에서 부르기claude -p와 JSON 출력 사용법

Claude Code를 화면 없이 claude -p로 불러 답을 받고, JSON 출력과 셸 스크립트로 반복 작업에 끼워 넣는 법을 따라 합니다.

안녕하세요, muaco입니다.

이 글로 할 수 있는 일

이 글을 따라 하면 Claude Code를 대화창 없이 명령 한 줄로 부르고, 답을 파일로 받아 낼 수 있습니다. 마지막에는 폴더 안 메모 여러 개를 한꺼번에 요약하는 스크립트까지 만들어 자동화에 끼워 넣습니다.

평소처럼 마주 앉아 대화하는 대신 -p를 붙여 질문 하나에 답 하나를 받고 끝내는 방식입니다. 공식 문서는 이를 비대화형 모드(non-interactive mode)라고 부르고, 문서 주소에는 headless라는 이름을 씁니다.

시작 전에 갖출 준비물

여기서 하나라도 빠지면 아래 단계가 모두 막힙니다. 하나씩 짚고 넘어가겠습니다.

  • Claude Code를 쓸 수 있는 계정. Pro, Max, Team, Enterprise, Console 계정 가운데 하나가 있어야 합니다. 무료 claude.ai 요금제로는 Claude Code를 쓸 수 없습니다.
  • 지원하는 운영체제. macOS 13.0 이상, Windows 10 1809 이상, Ubuntu 20.04 이상 등을 지원합니다. 메모리는 4GB 이상이 필요합니다.
  • 터미널. 글자로 컴퓨터에 명령을 내리는 창입니다. 이 글의 예시는 macOS, Linux, WSL(Windows 안에서 도는 리눅스) 기준이라, Windows라면 WSL 창 안에서 설치하고 실행합니다.
  • jq(선택). JSON 결과에서 필요한 칸만 꺼내는 작은 프로그램입니다. 공식 문서가 예시에 쓰는 도구인데 설치법은 문서에 없어, 이 글에서도 다루지 않습니다. 없으면 3단계에 함께 적은 대안대로 하면 됩니다.

Claude Code가 아직 없다면 터미널에 아래 한 줄을 붙여 넣어 설치합니다. macOS, Linux, WSL에서 쓰는 공식 설치 명령입니다.

curl -fsSL https://claude.ai/install.sh | bash

설치 명령은 진행 표시 없이 내려받으니 끝날 때까지 기다리세요. 끝나면 새 터미널 창을 열고 claude를 실행해 브라우저 안내대로 로그인합니다. -p로 부를 때는 /login 같은 화면용 명령을 쓸 수 없으니, 이 로그인을 먼저 해 두세요.

이 글은 2026년 10월에 읽은 공식 문서를 따릅니다. 권한 관련 설명은 v2.1.302 이후 버전 기준입니다.

따라 하기: 쪽지 한 장으로 일 맡기기

1. 설치와 로그인 확인

따라 하기
  1. 터미널에 claude --version을 입력합니다. 숫자 뒤에 (Claude Code)가 붙은 버전 번호가 찍히면 설치된 상태입니다.
  2. claude auth status로 로그인 상태를 확인하세요. 결과의 authMethod 값이 none이면 로그인이 안 된 상태이니 claude를 실행해 다시 로그인합니다.

여기까지가 몸풀기.

2. 질문 한 줄 건네기

이번 묶음에서는 세로줄 |을 씁니다. 수도관처럼 앞 명령이 내놓은 글을 뒤 명령으로 흘려 보내는 기호로, 파이프라고 부릅니다. 파일 내용을 직접 건네므로 Claude에게 파일을 열 권한을 따로 주지 않아도 됩니다.

따라 하기
  1. 연습용 폴더를 만들고 그 안으로 들어갑니다. 
    mkdir notes-test
cd notes-test
    폴더를 따로 두면 연습 파일이 다른 파일과 섞이지 않습니다. 새 터미널은 홈 폴더에서 시작하니 이 폴더도 홈 폴더 안에 생깁니다. 터미널을 새로 열었다면 cd notes-test부터 입력하세요.
  2. 첫 쪽지를 건넵니다. 
    claude -p "자기소개를 한 문장으로 해 주세요"
    답이 한 덩어리로 찍힌 뒤 바로 명령 줄로 돌아오면 성공입니다.
  3. 회의 메모 파일을 터미널에서 바로 만듭니다. 아래 다섯 줄을 한 번에 붙여 넣고 Enter를 누르면, EOF 앞의 세 줄이 meeting.txt에 담깁니다. 
    cat > meeting.txt <<'EOF'
월요일 회의: 신제품 출시일은 다음 달 둘째 주로 정함
김 대리가 금요일까지 보도자료 초안 작성
다음 회의는 목요일 오후
EOF
    cat meeting.txt로 세 줄이 보이면 됩니다. 메모장 같은 편집기로 만들면 4단계에서 막힐 수 있어, 이 글은 파일을 모두 터미널에서 만듭니다.
  4. 메모를 파이프로 Claude에게 넘깁니다. 
    cat meeting.txt | claude -p "이 메모를 세 줄로 요약해 주세요"
    요약 세 줄이 화면에 나오면 됩니다.
  5. 같은 이름의 파일이 이미 있다면 다른 이름을 쓰세요. 끝에 붙은 >는 결과를 파일에 쓰면서 원래 내용을 지웁니다. 
    cat meeting.txt | claude -p "이 메모를 세 줄로 요약해 주세요" > summary.txt
    화면은 조용하고, summary.txt를 열어 요약이 들어 있으면 성공입니다.

3. 답의 모양 정하기

기본 출력은 사람이 읽는 줄글(text)입니다. 다른 프로그램에 넘기려면 JSON이 편합니다. 이름표 붙은 상자 묶음이라 필요한 상자만 골라 꺼낼 수 있습니다.

따라 하기
  1. 출력 형식을 JSON으로 바꿉니다. 
    cat meeting.txt | claude -p "이 메모를 세 줄로 요약해 주세요" --output-format json
    중괄호 안에 result(답), session_id(대화 번호), total_cost_usd(예상 비용)가 보이면 맞습니다.
  2. jq로 답 상자만 꺼냅니다. 
    cat meeting.txt | claude -p "이 메모를 세 줄로 요약해 주세요" --output-format json | jq -r '.result'
    -r은 따옴표를 떼라는 뜻이라, 요약 글만 깔끔하게 남으면 성공입니다. jq가 없다면 이 단계는 건너뛰고 1번 결과의 result 칸을 읽으세요.
  3. 답의 칸까지 정하려면 --json-schema로 빈칸이 정해진 양식을 건넵니다. 아래는 메모에서 할 일만 골라 목록으로 받아 todos.json에 저장한 뒤 꺼내는 예입니다. 
    cat meeting.txt | claude -p "이 메모에서 할 일만 골라 주세요" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"todos":{"type":"array","items":{"type":"string"}}},"required":["todos"]}' \
  > todos.json
jq '.structured_output' todos.json
    todos 아래 할 일이 하나씩 나오면 성공입니다. jq가 없다면 마지막 줄 대신 cat todos.json으로 전체를 열어 structured_output 칸을 찾으세요. 양식에 맞춘 답은 result가 아니라 structured_output에 담깁니다.

4. 스크립트로 묶기

스크립트는 명령을 순서대로 적어 둔 레시피입니다. 한 번 적어 두면 컴퓨터가 위에서부터 차례로 따라 합니다.

따라 하기
  1. notes-test 안에 notes 폴더를 만들고, 앞의 메모를 복사해 연습용 파일 두 개를 넣습니다. 
    mkdir notes
cp meeting.txt notes/memo1.txt
cp meeting.txt notes/memo2.txt
    파일 하나에 한 번씩 Claude를 부르니 처음에는 적게 시험하는 편이 좋습니다.
  2. 이번에도 터미널에서 바로 summarize.sh를 만듭니다. 첫 줄부터 마지막 EOF까지 한 번에 붙여 넣고 Enter를 누르세요. 
    cat > summarize.sh <<'EOF'
mkdir -p summaries
for f in notes/*.txt; do
  name=$(basename "$f" .txt)
  if cat "$f" | claude -p "이 문서를 세 줄로 요약해 주세요" > "summaries/$name.txt"; then
    echo "완료: $f"
  else
    echo "실패: $f"
  fi
done
EOF
    파일마다 Claude를 한 번 부르고, 결과를 summaries 폴더에 같은 이름으로 남깁니다.
  3. bash summarize.sh로 실행합니다. 파일마다 완료: 줄이 찍히고 summaries 폴더에 요약 파일이 생기면 끝입니다.

성공과 실패는 종료 코드로 가립니다. 명령이 끝나며 남기는 성적표 같은 숫자인데, Claude Code는 성공하면 0, 실패하면 0이 아닌 값을 남깁니다. 스크립트의 if가 이 숫자를 보고 완료와 실패로 나눕니다.

막히기 쉬운 곳

명령이 생각대로 돌지 않을 때는 어디부터 봐야 할까요? 자주 걸리는 다섯 곳을 모았습니다.

스크립트가 오류만 내고 멈춥니다

bash summarize.sh가 syntax error near unexpected token 같은 오류를 내고 파일을 하나도 처리하지 못합니다. 편집기로 스크립트를 만들었다면 먼저 의심할 곳입니다. Windows 메모장은 줄마다 보이지 않는 기호(\r)를 붙이고, macOS 텍스트 편집기는 기본 설정이 서식 있는 문서(RTF)라 서식 코드가 섞입니다.

4단계 2번 명령을 다시 붙여 넣으세요. 같은 이름으로 덮어써 깨끗한 파일이 됩니다.

파일을 고쳐 달라고 했는데 그대로입니다

claude -p로 파일 수정을 맡겼는데 내용이 바뀌지 않습니다. v2.1.302 이후 -p 실행은 권한 모드를 정하지 않으면 수동(Manual) 모드로 시작합니다. 이 모드에서는 허락이 필요한 동작을 물어볼 사람이 없어 거절로 끝납니다.

고칠 때 쓸 도구를 --allowedTools "Read,Edit"처럼 미리 적어 주면 됩니다. 중요한 파일이 든 폴더에서는 복사본부터 만들어 두세요. 허락을 미리 주면 Claude가 묻지 않고 바로 고쳐 씁니다.

요약 파일에 요약 대신 오류 문장이 있습니다

summaries 폴더의 파일을 열었더니 요약이 아니라 오류 안내가 적혀 있습니다. 로그인이 빠진 경우처럼 실행 도중 생긴 실패를 Claude Code는 결과 자리에 그대로 찍습니다. >로 받은 파일에 그 문장이 담긴 셈입니다.

먼저 claude auth status로 로그인을 확인하세요. 스크립트에서는 파일 내용보다 종료 코드를 믿어야 합니다. 앞의 스크립트가 if로 갈라 둔 까닭입니다.

structured_output이 null로 나옵니다

jq '.structured_output'를 실행했는데 null만 찍힙니다. 문서에 따르면 Claude가 요청을 거절하는 등 양식에 맞는 답 없이 끝난 실행에는 이 칸이 아예 없습니다. 없는 칸을 꺼내려 했으니 빈 값이 돌아온 셈입니다.

cat todos.json으로 result에 어떤 답이 왔는지 먼저 보세요. 그다음 질문을 양식에 맞게 다듬어 다시 돌려 봅니다.

bare 모드를 켰더니 로그인이 안 됩니다

문서가 스크립트용으로 권하는 --bare를 붙이자 인증 오류가 납니다. bare 모드는 빨리 시작하려고 설정을 덜 읽는데, 구독 로그인 정보와 시스템 키체인도 읽지 않습니다.

구독 계정으로 쓴다면 --bare를 빼고 돌리세요. 꼭 써야 한다면 Claude Console에서 만든 API 키를 ANTHROPIC_API_KEY 환경 변수(프로그램이 읽어 가는 이름 붙은 설정값)에 넣습니다. 실행할 터미널 창에서 아래처럼 입력하면 되고, 창을 닫으면 이 값도 사라집니다.

export ANTHROPIC_API_KEY="발급받은 키"

API 키로 쓰면 구독과 별도로 사용량 요금이 붙습니다.

문서는 이 모드가 앞으로 -p의 기본값이 된다고 예고합니다. 업데이트 뒤 갑자기 로그인 오류가 난다면 여기부터 의심해 볼 만합니다.

여기서 더 나아가려면

이어서 물을 일이 있다면 --continue로 방금 대화를 잇거나, JSON의 session_id를 --resume에 넘겨 특정 대화로 돌아갑니다. 사람 없이 오래 돌릴 작업에는 --max-budget-usd로 비용 상한을 걸어 두세요.

상한과 JSON의 비용 칸은 모두 추정치라 실제 청구액과 다를 수 있고, 상한을 조금 넘기기도 합니다.

이상으로 글 마치겠습니다.

출처

#Claude Code#headless#claude -p#자동화#스크립트#JSON#터미널

같은 분류의 글