한눈에 보기
- 이 글에서 클로드 코드(Claude Code)를 대화 창 없이 한 번 시키고 답만 받는 claude -p 를 처음부터 옮겼어요. 한 줄로 묻기, 잘 끝났는지 보기, 파일로 받기, 고치는 일 맡기기, json 으로 받기, 정해 둔 때 돌리기까지예요.
- 순서 작업할 폴더에서 claude -p “요청” 을 치면 답만 출력하고 끝나요. 끝난 뒤 $LASTEXITCODE 가 0 이면 성공이에요.
- 주의 권한 확인 창이 없어서 파일 고치기·명령 실행은 미리 허락해 둬야 해요. 윈도우 PowerShell 5.1 에서는 json 따옴표와 한글 파이프가 깨지니 아래 “막힐 때”를 보세요.
- 읽는 법 “처음이라면”만 따라 해도 한 줄로 묻고 답을 받을 수 있어요. “익숙해졌다면”은 파일·파이프·허락, “더 깊이”는 json·자동화예요.
이 글 순서
클로드 코드는 보통 터미널에 claude 를 쳐서 대화 창을 열고 주고받으며 써요. 그런데 “이 회의록을 세 줄로 줄여서 파일로 남겨 줘” 같은 일은 매번 창을 열고 기다릴 것 없이 명령 한 줄로 시키고 답만 받으면 편해요. 그 방식이 claude -p 예요. 공식 문서는 비대화형 모드(non-interactive mode), 흔히는 헤드리스(headless, 화면 없이 돌린다는 뜻)라고 불러요. 자판기에 돈을 넣고 버튼 하나 누르면 물건만 나오는 것과 비슷해요. 점원과 이야기하지 않아요.
클로드 코드 공식 문서의 “Claude Code를 프로그래밍 방식으로 실행하기”(headless)와 CLI 레퍼런스, 인증·예약 작업 쪽을 2026년 10월 8일에 읽고 옮겼어요. 캡처는 한국어 문서에서 했고, 옵션 이름과 버전 숫자는 영어 문서와 맞춰 봤어요. 터미널 그림은 클로드 코드 2.1.292 가 깔린 윈도우 PC 에서 같은 날 돌린 출력이에요. 이 PC 의 실제 설정과 계정을 건드리지 않으려고, 설정이 들어가는 폴더를 따로 만든 테스트 폴더로 돌려 놓고 로그인하지 않은 채로 돌렸어요. 그래서 그림 속 답은 모두 “로그인 안 됨”이고, 실제 답이 나오는 화면은 문서에 적힌 대로 옮겨요. 끝난 뒤 테스트 폴더는 지웠어요.
-p 가 뭔가요
클로드 코드는 내가 말로 요청한 일을 Claude 라는 AI 가 대신 하는 프로그램이에요. 파일을 읽고, 고치고, 명령을 돌려요. 대화 창으로 쓰면 Claude 가 파일을 고치려 할 때마다 “고쳐도 될까요?” 하고 물어보고, 내가 예·아니오를 눌러요.
claude 뒤에 -p 를 붙이면 그 창이 열리지 않아요. 따옴표 안의 요청을 한 번 받아서 혼자 일하고, 마지막 답만 화면에 출력하고 끝나요. -p 는 --print(출력)의 줄임말이에요. 명령 뒤에 붙이는 이런 단어를 옵션(또는 플래그)이라고 불러요.
그래서 이럴 때 써요.
- 비개발자: 폴더 속 회의록·메모를 요약해 파일로 남기기, 여러 CSV 파일의 머리줄이 같은지 확인시키기처럼 매번 같은 말로 시키는 일.
- 초급 개발자: 빌드가 깨졌을 때 오류 로그를 넘겨 원인을 한 줄로 듣기, 고친 내용(diff)에서 오타만 골라 달라기.
- 자동화: 다른 프로그램이 Claude 의 답을 받아 이어서 쓰게 하기. 문서는 스크립트와 CI(코드를 올릴 때마다 자동으로 도는 검사)에 쓰라고 적었어요.
대화 창과 하는 일은 같아요. 문서는 -p 도 대화 창과 같은 컨텍스트(Claude 가 일하며 읽어 두는 내용)를 불러온다고 적었어요. 그 폴더의 CLAUDE.md, 스킬, 훅, MCP 서버까지요. 다른 점은 권한 확인 창이 없다는 것 하나인데, 이게 꽤 커요. 아래에서 차례로 볼게요.
처음이라면: 한 줄로 묻기
준비물은 둘이에요.
- 클로드 코드가 깔려 있고 로그인돼 있을 것. 아직이라면 윈도우 설치 글부터 보세요. -p 는 대화 창에서 한 번 로그인해 둔 그 계정으로 돌아요.
- 터미널을 열 줄 알 것. 터미널은 마우스 대신 글자로 컴퓨터에 일을 시키는 까만 창이고, 윈도우에서는 PowerShell 이에요. 시작 버튼을 누르고 PowerShell 을 치면 나와요.
먼저 내 클로드 코드에 -p 가 있는지 봐요. 이 PC 에서 돌린 화면이에요.
claude --help클로드 코드가 받는 옵션 목록을 보여 달라는 줄이에요. 아무것도 바뀌지 않아요. 맨 위 설명에 “기본은 대화 세션을 열고, 비대화형 출력은 -p/--print 를 쓰라”고 적혀 있어요. -p 설명에는 “믿는 폴더인지 묻는 창을 건너뛰니 믿는 폴더에서만 쓰라”는 말도 붙어 있어요. 이 말은 뒤의 “남의 폴더에서” 절에서 다시 봐요.
이제 작업할 폴더로 가서 하나 시켜 봐요. cd 는 폴더를 옮기는 명령이에요.
cd C:\Users\사용자이름\Documents\연습폴더
claude -p "이 폴더에 있는 파일 이름을 한 줄에 하나씩 적어 줘"첫 줄은 연습폴더로 들어가는 줄, 둘째 줄은 그 폴더를 보고 파일 이름을 적어 달라는 요청이에요. 대화 창이 열리지 않고, 잠깐 뒤 답만 찍히고 다시 PS 로 시작하는 줄이 나오면 끝난 거예요. 그 폴더 안의 파일을 읽는 일은 따로 허락하지 않아도 돼요. 문서는 Manual(기본) 모드에서 작업 폴더 안 파일 읽기는 승인이 필요 없다고 적었어요.
요청은 큰따옴표로 감싸요. 띄어쓰기가 있는 글을 하나로 묶어 넘기려는 거예요. 한글로 써도 돼요. 처음엔 읽기만 하는 요청(요약해 줘, 찾아 줘, 설명해 줘)으로 시작하는 게 좋아요. 고치는 요청은 허락이 필요해서 그냥 치면 Claude 가 고치지 못하고 끝나요. 그 이야기는 “고치는 일 맡기기”에서 해요.
잘 끝났는지 보기
-p 는 끝날 때 종료 코드를 남겨요. 종료 코드는 프로그램이 끝나며 남기는 숫자로, 0 이면 잘 끝났고 0 이 아니면 어딘가 실패했다는 뜻이에요. PowerShell 에서는 $LASTEXITCODE 를 치면 보여요.
$LASTEXITCODE바로 앞에 돌린 프로그램의 종료 코드를 보여 달라는 줄이에요. 위 그림은 로그인하지 않은 테스트 폴더라서 답 대신 “로그인 안 됨, /login 을 하라”는 글이 나왔고 종료 코드는 1 이었어요. 실제로 로그인한 PC 라면 여기에 답이 나오고 0 이 찍혀요.
눈여겨볼 점이 하나 있어요. 문서는 옵션을 잘못 준 오류는 시작 전에 오류 통로(stderr)로 내보내지만, 로그인 같은 실행 중 오류는 답 자리(stdout)에 “결과”로 출력한다고 적었어요. 그래서 답을 파일로 받을 때는 파일 안 글만 보고 성공이라 믿지 말고 종료 코드를 같이 봐야 해요. 아래 “파일로 받기”에서 실제로 그렇게 되는 화면을 보여 드려요.
익숙해졌다면: 파일로 받기
답을 화면 대신 파일로 남기려면 끝에 > 파일이름 을 붙여요. > 는 리디렉션(화면에 나갈 글을 파일로 돌리기)이라고 불러요.
claude -p "회의록.txt 를 읽고 결정된 것만 세 줄로 적어 줘" > 요약.txt회의록.txt 를 읽게 하고, 화면에 나올 답을 요약.txt 파일에 담으라는 줄이에요. 회의록.txt 는 같은 폴더에 있어야 해요. 파일 이름을 요청 안에 적으면 Claude 가 직접 읽으니, 파일 내용을 따로 넘길 필요가 없어요.
| 는 파이프라는 기호로, 앞 명령의 출력을 뒤 명령에 넘겨요. 여기서는 Claude 의 답을 Out-File 에 넘겨 UTF-8 로 저장하라는 뜻이에요.
파이프로 넘기기
거꾸로 다른 명령의 출력을 Claude 에게 넘길 수도 있어요. 문서는 비대화형 모드가 표준 입력(stdin)을 읽으니 다른 명령줄 도구처럼 파이프로 넘기고 답을 파일로 돌릴 수 있다고 적었어요.
git diff | claude -p "이 변경에서 오타만 골라 파일이름:줄 꼴로 적어 줘"git diff(깃으로 관리하는 폴더에서 아직 저장 기록을 남기지 않은 고친 내용)를 Claude 에게 넘기고 오타만 골라 달라는 줄이에요. 문서의 빌드 스크립트 예와 같은 용도예요. 문서는 이렇게 파이프로 넘기면 Claude 가 그 내용을 읽으려고 명령을 돌릴 필요가 없어서 따로 허락이 필요 없다고 적었어요.
두 가지를 기억해 두세요.
- 파이프로 넘기는 양은 10MB 까지예요. 넘으면 오류로 끝나요. 문서는 큰 내용은 파일에 쓰고 요청 안에 파일 경로를 적으라고 권해요.
- 윈도우 PowerShell 5.1 에서 한글이 든 글을 파이프로 넘기면 물음표로 바뀔 수 있어요. 이 PC 에서 직접 확인한 것이라 “막힐 때”에 그림과 함께 적었어요. 처음에는 파이프보다 “회의록.txt 를 읽고”처럼 파일 이름을 요청에 적는 쪽이 탈이 적어요.
고치는 일 맡기기
대화 창에서는 Claude 가 파일을 고치기 전에 물어봐요. -p 에는 물어볼 창이 없어서, 미리 허락을 정해 두지 않으면 물어야 할 일은 거절되고 Claude 는 그 일을 못 한 채 이어 가요. 문서가 적은 허락 방법은 셋이에요.
첫째, 쓸 도구를 하나씩 적는 --allowedTools 예요. 도구는 Claude 가 일할 때 쓰는 손발로, 파일 읽기(Read)·고치기(Edit)·새로 쓰기(Write)·명령 돌리기(Bash) 같은 것이 있어요.
claude -p "회의록.txt 를 읽고 세 줄 요약을 요약.txt 로 저장해 줘" --allowedTools "Read,Write"읽기와 새 파일 쓰기만 묻지 않고 하게 하라는 줄이에요. 이번에는 > 없이 Claude 가 직접 요약.txt 를 만들어요.
둘째, 기본 태도를 정하는 --permission-mode 예요. 문서는 -p 에서 쓸 만한 것으로 셋을 들었어요.
- acceptEdits: 파일 고치기와 mkdir·mv·cp 같은 흔한 파일 명령은 묻지 않고 해요. 다른 명령과 인터넷 요청은 여전히 허락이 필요해요.
- dontAsk: 물어야 할 일은 전부 거절해요. 잠가 둔 자동 검사에 맞아요. 작업 폴더 안 파일 읽기처럼 원래 묻지 않는 일과, --allowedTools 로 허락한 일은 그대로 돼요.
- auto: 분류기(따로 도는 검사 모델)가 내 대신 대부분의 행동을 살펴요. auto 모드는 auto 모드 글에 따로 있어요.
claude -p "이 폴더의 CSV 파일 머리줄을 모두 같게 맞춰 줘" --permission-mode acceptEdits파일 고치기는 묻지 않고 하게 하는 줄이에요. 고치는 일을 맡길 때는 먼저 폴더를 복사해 두거나 깃에 저장 기록을 남겨 두세요. -p 는 고치는 동안 내가 지켜보며 멈출 수 없어서, 잘못 고쳤을 때 돌아갈 곳을 내가 마련해 둬야 해요.
셋째, 명령을 허락할 때는 좁게 적어요. Bash 라고만 적으면 모든 명령이 되니, Bash(git diff *) 처럼 앞부분을 정해 줘요. 문서는 * 앞의 띄어쓰기가 중요하다고 적었어요. Bash(git diff*) 로 붙여 쓰면 git diff-index 같은 다른 명령도 걸린다는 거예요. 규칙 적는 형식은 권한 설정 글에 있어요.
모든 검사를 끄는 --dangerously-skip-permissions 도 있어요. 이 PC 의 도움말에는 “인터넷이 없는 격리된 환경에서만 권한다”고 적혀 있어요. 평소 쓰는 폴더에서는 쓰지 않는 쪽이 맞아요.
이어서 시키기
-p 는 한 번 시키고 끝나지만, 앞 이야기를 이어 갈 수 있어요. --continue(줄여서 -c)는 가장 최근 대화를, --resume 은 세션 아이디로 고른 대화를 이어요. 세션은 대화 한 번을 말하고, 아이디는 그 대화의 식별자예요.
claude -p "이 폴더의 글에서 맞춤법이 틀린 곳을 찾아 줘"
claude -p "찾은 것 가운데 고칠 만한 것 다섯 개만 골라 줘" --continue첫 줄이 찾게 하고, 둘째 줄이 그 대화를 이어 골라 달라는 줄이에요. 헷갈리는 점이 하나 있어요. CLI 레퍼런스에 따르면 대화 창으로 켜는 claude --continue 는 -p 로 돌린 대화를 건너뛰고, claude -p --continue 는 -p 대화까지 포함해요. 그래서 -p 로 시작한 일은 -p 로 이어 가는 게 맞아요.
-p 로 돌린 대화도 기록으로 남아요. 위 “파일로 받기” 그림의 아랫부분이 그걸 센 거예요. 테스트 폴더의 대화 기록 파일(.jsonl)이 7 개였는데, -p 를 한 번 돌리니 8 개가 됐고, --no-session-persistence 를 붙여 돌리니 8 개 그대로였어요. 이 옵션은 “기록을 남기지 않아서 이어 갈 수 없게” 해요. 남이 보면 안 되는 내용을 한 번만 돌릴 때 쓸 만해요.
더 깊이: json 으로 받기
다른 프로그램이 Claude 의 답을 받아 쓰려면 글보다 정해진 형식이 편해요. --output-format 으로 형식을 고를 수 있어요.
- text: 기본값. 답 글만 나와요.
- json: 다 끝난 뒤 한 번에 묶여 나와요. 답(result), 세션 아이디(session_id), 비용 추정(total_cost_usd), 실패 여부(is_error) 같은 필드가 들어 있어요. JSON 은 “필드 이름: 값” 모양으로 적는 글 형식이에요.
- stream-json: 일하는 동안 일어난 일을 한 줄에 하나씩 바로바로 내보내요. 진행 상황을 화면에 그려 줄 프로그램을 만들 때 써요.
문서의 예는 jq 라는 별도 프로그램으로 json 을 읽지만, 윈도우 PowerShell 에는 ConvertFrom-Json 이 들어 있어서 따로 깔 것이 없어요. 이 PC 테스트 폴더에서 돌린 화면이에요.
$r = claude -p "README.md 를 세 줄로 줄여 줘" --output-format json | ConvertFrom-Json
$r.result
$r.session_id첫 줄은 json 으로 받은 답을 PowerShell 이 다루는 형식으로 바꿔 $r 에 담는 줄, 둘째 줄은 답 글만, 셋째 줄은 세션 아이디만 꺼내는 줄이에요. 세션 아이디는 나중에 --resume 에 넣어 그 대화를 이어 갈 때 써요.
그림에서 subtype 이 success 인데 is_error 가 True 인 것을 보세요. 로그인 실패도 “한 판을 끝냈다”는 뜻에서는 success 로 적혀요. 성공인지는 is_error 와 종료 코드로 보는 게 맞아요.
답을 아예 정해 둔 형식으로 받고 싶으면 --json-schema 에 JSON 스키마(받을 필드 이름과 종류를 적은 설계도)를 줘요. 답은 structured_output 필드에 들어가요. 윈도우 PowerShell 5.1 에서는 이 스키마를 넘기는 따옴표가 깨지는데, 이건 “막힐 때”에서 그림으로 볼게요.
--bare 와 남의 폴더
앞에서 -p 도 그 폴더의 설정을 다 읽는다고 했어요. 문서는 여기서 두 가지를 짚었어요.
- 남의 폴더: --bare 없이 돌린 -p 는 처음 여는 폴더라도 그 폴더 .claude\settings.json 의 훅(정해진 때 자동으로 도는 명령)을 돌리고 .mcp.json 의 서버를 연결해요. 대화 창이라면 “이 폴더를 믿나요?” 하고 물었을 텐데 -p 는 묻지 않아요. 그래서 남이 만든 저장소를 받자마자 -p 를 돌리지 말고, .claude 폴더와 .mcp.json 부터 열어 보세요. 훅이 무엇인지는 훅 글에 있어요.
- --bare: 훅·스킬·플러그인·MCP 서버·자동 메모리·CLAUDE.md 를 하나도 읽지 않고 빈손으로 시작해요. 어느 컴퓨터에서 돌려도 같은 결과가 필요한 자동 검사에 맞고, 문서는 앞으로 -p 의 기본이 --bare 가 될 거라고 적었어요.
--bare 에는 큰 차이가 하나 있어요. 구독 로그인(Pro·Max 계정)을 읽지 않아요. 문서는 --bare 로 돌리려면 ANTHROPIC_API_KEY 에 Claude Console 에서 만든 API 키를 넣으라고 적었어요. API 키는 요금제와 따로 쓴 만큼 돈이 나가는 키예요. 그러니 Pro·Max 로 쓰는 분은 평소에는 --bare 없이 쓰고, 남의 폴더에서는 위처럼 먼저 읽어 보는 쪽이 현실적이에요.
-p 에서 되는 명령
대화 창에서 쓰던 / 명령이 -p 에서도 되는지 헷갈려요. 문서의 안내를 캡처했어요.
- 내가 만든 스킬은 돼요. 요청 안에 /스킬이름 을 넣으면 펼쳐서 돌려요.
- /login 처럼 대화 창 안에서만 도는 명령은 안 돼요. 로그인은 대화 창에서 먼저 해 두세요.
- /model 은 값을 같이 줘요(예: /model sonnet). 다만 모델을 바꿀 거라면 claude -p “요청” --model sonnet 처럼 옵션으로 주는 쪽이 간단해요.
정해 둔 때 돌리기
-p 를 쓰는 큰 이유 하나가 “매일 아침 9시에 이 일을”처럼 사람이 없을 때 돌리는 거예요. 클로드 코드 문서에는 그 길이 따로 있어요. 윈도우 작업 스케줄러에 -p 를 거는 순서는 클로드 코드 문서에 없어서 이 글에서는 다루지 않아요.
- 데스크톱 앱의 예약 작업: 정한 때 새 세션을 자동으로 열어요. 내 컴퓨터에서 돌아 내 파일을 바로 쓰지만, 앱이 켜져 있고 컴퓨터가 깨어 있을 때만 돌아요. 데스크톱 앱은 데스크톱 앱 글에 있어요.
- routines: 클라우드에서 정한 때, 또는 깃허브 일이 생길 때 돌아요. 문서는 Pro·Max·Team·Enterprise 에서 된다고 적었어요.
- /loop: 열어 둔 대화 창 안에서 같은 요청을 일정한 간격으로 다시 돌려요. 창을 닫으면 멈춰요.
- 깃허브 Actions: 코드 저장소에 일이 생길 때 클로드 코드를 돌려요. 구독으로 돌리려면 내 PC 에서 claude setup-token 으로 1년짜리 토큰을 받아 CLAUDE_CODE_OAUTH_TOKEN 에 넣으라고 문서에 적혀 있어요(Pro·Max·Team·Enterprise). 이 토큰은 비밀번호처럼 다뤄야 하고, --bare 는 이 토큰도 읽지 않아요.
한도와 비용
-p 도 대화 창과 같은 로그인으로 돌아요(문서는 --bare 만 구독 로그인을 읽지 않는다고 적었어요). -p 를 따로 계산한다는 안내는 없어서, 같은 요금제 사용량에서 빠진다고 보면 돼요. 사람이 보지 않는 동안 오래 돌 수 있으니 상한을 걸어 두면 마음이 편해요.
- --max-turns 3: Claude 가 도구를 쓰며 일하는 차례를 3 번까지만. 넘으면 오류로 끝나요. 이 옵션은 CLI 레퍼런스에는 있는데 이 PC 의 claude --help 목록에는 없었어요.
- --max-budget-usd 1: 추정 비용이 1달러를 넘으면 멈춰요. 서브에이전트가 쓴 것도 들어가요. 자세한 용도는 사용량 확인 글에 있어요.
json 의 total_cost_usd 는 문서가 “클라이언트 측 추정치이고 실제 청구와 다를 수 있다”고 적은 값이에요. 비용 문서도 Pro·Max 구독자는 사용량이 요금제에 들어 있어서 세션 비용 숫자가 청구와 관계없다고 적었어요(이건 /usage 화면의 숫자 이야기예요). 요금제 안에서 얼마나 썼는지는 대화 창의 /usage 로 보는 게 맞아요.
막힐 때
문서에 적힌 것과, 이 PC 의 윈도우 PowerShell 5.1 에서 직접 걸려 본 것을 같이 적었어요.
| 이런 글이 나오면 | 이유 | 이렇게 |
|---|---|---|
| Not logged in · Please run /login | 로그인이 안 됨, 또는 --bare 로 돌림 | claude 로 대화 창을 열어 /login, --bare 는 API 키 |
| argument ‘xml’ is invalid | --output-format 에 없는 값 | text·json·stream-json 가운데 하나 |
| --bg and --print conflict | -p 와 --bg 를 같이 씀 | 둘 중 하나만 |
| --json-schema is not valid JSON | PowerShell 5.1 이 큰따옴표를 지움, 또는 파일 이름을 줌 | 큰따옴표 앞에 \ 를 붙임 |
| 한글이 ??? 로 바뀜 | PowerShell 5.1 파이프의 인코딩 | $OutputEncoding 을 UTF-8 로, 또는 파일 이름을 요청에 |
| 고치라 했는데 안 고침 | 허락할 창이 없어 거절됨 | --allowedTools 나 --permission-mode |
출처: 클로드 코드 문서 headless·cli-reference, 이 PC 에서 10월 8일 돌린 출력.
옵션을 잘못 주면 Claude 가 일을 시작하기도 전에 끝나요. 문서대로 이 오류는 오류 통로로 나가고 종료 코드는 1 이었어요.
가장 많이 걸릴 곳은 --json-schema 예요. 문서의 예처럼 작은따옴표 안에 JSON 을 그대로 넣으면 윈도우 PowerShell 5.1 에서는 안쪽 큰따옴표가 프로그램에 넘어가며 빠져서 “JSON 이 아니다”는 오류가 나요. 마이크로소프트 문서도 PowerShell 7 의 새 방식에서는 인수 속 큰따옴표가 그대로 넘어가고, 예전 방식(Legacy)은 그렇지 않다고 적었어요.
claude -p "이 폴더 파일 이름" --output-format json --json-schema '{\"type\":\"object\",\"properties\":{\"files\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"files\"]}'큰따옴표마다 앞에 백슬래시(\)을 붙인 줄이에요. 이 PC 에서는 이렇게 하니 스키마 검사를 지나 다음 단계(로그인 확인)까지 갔어요. 클로드 코드의 --json-schema 는 파일 이름을 받지 않았어요. schema.json 을 주니 그 글자를 JSON 으로 읽으려다 오류가 났어요. 길게 쓰기 번거로우면 PowerShell 7 을 따로 깔아 쓰는 방법도 있지만, 이 글에서는 테스트하지 않았어요.
한글 파이프도 이 PC 에서 확인했어요. 클로드 코드는 로그인 없이는 받은 글을 보여 주지 않아서, 받은 글자를 그대로 출력하는 node 로 PowerShell 이 무엇을 넘기는지 봤어요.
$OutputEncoding = New-Object System.Text.UTF8Encoding $falsePowerShell 이 바깥 프로그램에 글을 넘길 때 쓰는 인코딩을 UTF-8 로 바꾸는 줄이에요. 기본값(us-ascii)에서는 한글 “가나다”가 “???” 로 넘어갔고, 이 줄을 친 뒤에는 그대로 넘어갔어요. 이 설정은 그 PowerShell 창을 닫으면 사라져요. 마이크로소프트 문서도 $OutputEncoding 이 바깥 프로그램과 주고받는 인코딩을 정한다고 적었어요.
코덱스·안티그래비티는
다른 터미널 코딩 도구에도 같은 방식이 있어요. 한 번 시키고 끝내는 것은 같고, 처음 허락과 출력 형식이 달라요.
| 무엇 | 클로드 코드 | 코덱스 CLI | 안티그래비티 CLI |
|---|---|---|---|
| 명령 | claude -p “요청” | codex exec “요청” | agy -p “요청” |
| 처음 허락 | 시작 권한 모드, 물을 일은 거절 | 읽기 전용 샌드박스 | 폴더 안 읽기·쓰기 됨, 명령은 거절 |
| 고치게 하려면 | --allowedTools, --permission-mode | --sandbox workspace-write | settings.json 의 permissions.allow |
| 출력 형식 | text·json·stream-json | 글, --json(한 줄씩 이벤트) | text·json·stream-json |
| 정한 형식으로 받기 | --json-schema(글로만, 파일 안 됨) | --output-schema 파일 | --json-schema(글·파일·기본 종류) |
| 이어 하기 | --continue, --resume 아이디 | codex exec resume --last | -c, --conversation 아이디 |
| 기록 안 남기기 | --no-session-persistence | --ephemeral | 미확인 |
| 파이프로 자료 | 됨(10MB 까지) | 됨(요청 + 넘긴 글) | 미확인(stream-json 입력만 안내) |
| 깃 폴더 필요 | 안내 없음 | 필요(--skip-git-repo-check 로 끔) | 안내 없음 |
| 멈추는 상한 | --max-turns, --max-budget-usd | 미확인 | --print-timeout(문서 5분, 도움말 0s) |
출처: 클로드 코드 문서 headless·cli-reference, OpenAI 코덱스 문서 Non-interactive mode, 안티그래비티 문서 Headless mode, 안티그래비티 도움말은 안티그래비티 CLI 사용법 글에서 이 PC 로 확인한 것. 10월 8일 확인.
코덱스는 진행 상황을 오류 통로로, 마지막 답만 출력 통로로 내보내요. -o 파일이름 을 붙이면 마지막 답을 파일로도 남겨요. 자동화에는 API 키(CODEX_API_KEY)를 권하고, 그 키를 저장소 코드가 같이 도는 환경 전체에 깔아 두지 말라고 적었어요. 처음 쓰는 법은 코덱스 CLI 사용법 글에 있어요.
안티그래비티 CLI 는 한 번 로그인해 둔 계정을 그대로 쓰고, 로그인이 안 된 자동화 환경에서는 기다리지 않고 authentication required 오류로 끝난다고 적었어요. 허락이 필요한 명령은 조용히 거절되면서도 종료 코드는 0 이라서, 성공인지는 json 의 status 필드까지 봐야 해요. 없는 모델 이름을 주면 대화 창과 달리 다른 모델로 넘어가지 않고 오류로 끝난다고도 적혀 있어요.
제 생각에는 처음 자동화를 해 본다면 처음 허락이 가장 좁은 코덱스(읽기 전용)가 덜 무섭고, 이미 클로드 코드로 스킬·훅을 갖춰 둔 분은 그걸 그대로 쓰는 claude -p 가 편해요. 세 도구 모두 고치게 할 때는 폴더를 깃에 저장해 두고 돌리는 습관이 제일 중요해요. 세 도구를 한 번에 비교한 글은 클로드 코드·코덱스·제미나이 CLI 비교 글이에요.
한국에서 되나
| 질문 | 답 |
|---|---|
| 한국에서 되나 | 됨(Anthropic 지원 국가 목록에 South Korea) |
| 무슨 요금제 | 클로드 코드를 쓰는 요금제. -p 만 따로 막는 요금제 안내는 문서에 없음 |
| 한국어 문서 | 있음(code.claude.com/docs/ko/headless) |
| --bare | 구독 로그인을 안 읽음, API 키 필요(쓴 만큼 따로 청구) |
| 버전 숫자 | --permission-prompts 2.1.259, 윈도우 stdin 멈춤 수정 2.1.211 부터 |
출처: 클로드 코드 문서 headless·cli-reference·authentication, anthropic.com 지원 국가 목록. 10월 8일 확인.
회사 계정이라면 관리자가 정해 둔 설정이 -p 에도 그대로 걸려요. 쓰기 전에 회사 안내를 먼저 보세요.
다음에 볼 글
-p 에 같이 붙일 허락 규칙은 권한 설정 글, 남의 폴더에서 자동으로 도는 것은 훅 글, 폴더마다 지침을 남기는 법은 CLAUDE.md 글이에요. 클로드 코드를 아직 깔지 않았다면 윈도우 설치 글, 대화 창 쓰는 법은 클로드 코드 사용법 글부터 보면 돼요. 나머지 요령은 사용량 아끼는 법 모음에 차례로 있어요.
이 글의 내용은 2026년 10월 8일, 클로드 코드 2.1.292 기준이에요. 문서가 앞으로 -p 의 기본을 --bare 로 바꾼다고 예고했으니, 글과 다르게 움직이면 공식 문서의 지금 내용을 먼저 보세요.
같이 보면 좋은 글: 클로드 코드 사용량 확인하는 법: /usage 화면 읽기부터 상태 줄·팀 계정까지
같이 보면 좋은 글: 클로드 코드 사용량 아끼는 법: 대화·캐시·서브에이전트부터 스킬·훅·권한 설정까지
같이 보면 좋은 글: AI 비교 2026: 클로드·챗GPT·제미나이 요금제·한도·기능 표
같이 보면 좋은 글: 클로드 코드 깃 커밋·PR 맡기는 법: 연습 폴더부터 /diff·push 막기·서명 줄까지
같이 보면 좋은 글: 클로드 코드 agent view 사용법: claude agents 로 백그라운드 세션 여러 개 맡기기, /bg·attach 까지
같이 보면 좋은 글: 클로드 API 크레딧 받는 법: Max 매달 100·200달러, 쓰는 곳과 못 쓰는 곳
같이 보면 좋은 글: 클로드 코드 예약 작업 하는 법: /loop 반복·데스크톱 예약·루틴 차이와 7일 만료
같이 보면 좋은 글: 클로드 코드 대화 내보내기: /export 로 파일·클립보드에, 남에게 보여 주기 전 지울 것
같이 보면 좋은 글: 클로드 코드 GitHub Actions 사용법: /install-github-app 설치부터 @claude 로 이슈·PR 맡기기
참고한 자료
2026년 10월 8일에 확인했어요. 클로드 코드 문서는 영어 문서와 한국어 문서(/docs/ko/)를 같이 봤어요.
- Run Claude Code programmatically (클로드 코드 공식 문서, -p·--bare·파이프·출력 형식·허락·이어 하기)
- CLI reference (클로드 코드 공식 문서, --continue·--max-turns·--max-budget-usd·--no-session-persistence)
- Authentication (클로드 코드 공식 문서, claude setup-token·CLAUDE_CODE_OAUTH_TOKEN)
- Manage costs effectively (클로드 코드 공식 문서, 구독자에게 비용 숫자의 뜻)
- Schedule recurring tasks in Claude Code Desktop (클로드 코드 공식 문서, 데스크톱 예약 작업)
- Automate work with routines (클로드 코드 공식 문서, routines 요금제)
- Run prompts on a schedule (클로드 코드 공식 문서, /loop)
- Claude Code GitHub Actions (클로드 코드 공식 문서, 구독 토큰)
- Supported countries (Anthropic, South Korea)
- Non-interactive mode (OpenAI 코덱스 공식 문서, codex exec·샌드박스·--json·--output-schema·resume·깃 폴더)
- Headless mode (안티그래비티 공식 문서, agy -p·출력 형식·--json-schema·허락·--print-timeout)
- about_Character_Encoding (마이크로소프트 공식 문서, PowerShell 5.1 의 > 는 UTF-16LE, $OutputEncoding)
- about_Parsing (마이크로소프트 공식 문서, 바깥 프로그램에 넘기는 인수의 따옴표)
광고 · 쿠팡 추천 상품
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
