OpenAI CLI v1.40.0: 새 도구가 아니라 API 작업을 셸에 고정하는 방법

“OpenAI CLI가 공개됐다”는 문장은 절반만 맞습니다. 2026년 10월 21일 GitHub에 v1.40.0이 올라온 것은 사실이지만, CLI 자체는 그날 처음 나온 제품이 아닙니다. 첫 릴리스 v1.0.0은 2026년 5월 5일에 있었고, v1.40.0은 그 연속선상의 포인트 릴리스입니다.

릴리스 노트도 작습니다. api: add custom voice consent management와 api: clarify cache-write token totals 두 가지입니다. 새 도구의 등장을 기다렸다면 실망할 수 있습니다. 반대로 API 작업을 셸에서 반복하고 싶은 개발자라면, 이 릴리스는 “이제 CLI를 스크립트에 넣어도 된다”는 신호로 읽을 수 있습니다.

v1.40.0에서 실제로 바뀐 것

중요한 점은 이 CLI가 “OpenAI API를 호출하는 공식 도구”라는 범위를 꽤 오래 유지해 왔다는 것입니다. v1.40.0은 API 표면에 voice consent 관련 명령을 더하고, 토큰 집계 설명을 고친 릴리스입니다. 새로운 에이전트 제품이나 모델 출시가 아닙니다.

OpenAI CLI와 Codex CLI는 다른 도구다

공식 README는 두 도구의 역할을 분명히 나눕니다.

둘 다 터미널에서 쓰지만 같은 계층이 아닙니다. OpenAI CLI는 “API를 호출하는 어댑터”에 가깝고, Codex CLI는 “작업을 수행하는 에이전트”입니다. 이 구분이 중요한 이유는 권한과 실패 모드가 다르기 때문입니다. API CLI는 입력과 출력이 비교적 명확하지만, 코딩 에이전트는 파일과 명령에 접근합니다.

CLI가 제공하는 것

README 기준으로 OpenAI CLI는 API의 리소스 구조를 그대로 명령에 옮깁니다.

openai <resource> [subresource...] <command> [flags...]

openai images generate --prompt "..."
openai files upload report.txt --purpose user_data
openai files get file-example
openai files download file-example --output downloaded-report.txt
openai batches create --input-file-id file-example --endpoint /v1/responses --completion-window 24h
openai batches wait batch_example --output-dir ./results
openai models list --format jsonl
openai responses create --model "$MODEL" --input @prompt.txt

설치 경로는 세 가지입니다. GitHub Releases의 사전 빌드 바이너리, Homebrew(brew install openai/tools/openai), Go 설치(go install github.com/openai/openai-cli/cmd/openai@latest)입니다. 인증은 openai help setup으로 안전하게 입력하거나, 스크립트에서는 OPENAI_API_KEY 환경 변수를 사용합니다. 관리자 엔드포인트는 별도의 OPENAI_ADMIN_KEY를 씁니다.

출력은 기본적으로 사람이 읽기 쉬운 텍스트입니다. 파이프에서도 기본값이 텍스트라는 점이 중요합니다. 스크립트에서 구조화된 값을 원하면 --format json, jsonl, raw, yaml을 명시해야 합니다. --transform으로 GJSON 경로를 추출할 수도 있습니다.

왜 셸에 고정하는가

API를 호출하는 가장 빠른 방법은 대화형 도구나 SDK입니다. 하지만 반복 작업에는 다른 기준이 필요합니다. “같은 입력으로 같은 절차를 다시 실행할 수 있는가”, “실패했을 때 멈추는가”, “결과 파일이 어디에 남는가”가 중요해집니다.

OpenAI CLI의 가치는 모델 호출 자체보다 이 절차를 셸에 고정한다는 데 있습니다. 예를 들어 배치 작업은 다음 순서로 재현할 수 있습니다.

1. JSONL 요청 파일을 만든다.
2. openai files upload로 업로드하고 파일 ID를 받는다.
3. openai batches create로 배치를 만들고 배치 ID를 받는다.
4. openai batches wait로 완료를 기다리고 결과를 내려받는다.
5. 결과 JSON을 검증하고 실패한 요청만 재처리한다.

이 흐름은 대화형 클릭보다 느려 보이지만, CI나 정기 작업에서는 훨씬 예측 가능합니다.

안전한 배치 스크립트 예시

아래 스크립트는 이 글에서 실행하지 않은 예시입니다. 실제 API 키와 유료 호출을 사용하지 않았고, 응답 필드 이름은 사용하는 CLI 버전의 --help로 확인해야 합니다. 핵심은 “키를 명령행에 넣지 않는다”, “실패하면 멈춘다”, “결과 파일 권한을 좁힌다”입니다.

#!/usr/bin/env bash
set -euo pipefail
umask 077

: "${OPENAI_API_KEY:?set OPENAI_API_KEY in the environment}"
: "${MODEL:?set MODEL to a model returned by: openai models list}"

export OPENAI_CLI_NO_UPDATE_CHECK=1

# 1) 입력 파일 업로드
file_id="$(
  openai files upload requests.jsonl \
    --purpose batch \
    --format json | jq -r '.id'
)"

# 2) 배치 생성
batch_id="$(
  openai batches create \
    --input-file-id "$file_id" \
    --endpoint /v1/responses \
    --completion-window 24h \
    --format json | jq -r '.id'
)"

# 3) 완료 대기 및 결과 다운로드
openai batches wait "$batch_id" --output-dir ./results

# 4) 결과 파일을 확인한 뒤에만 다음 단계로 진행
test -s "./results/${batch_id}/output.jsonl"

이 예시에서 set -euo pipefail은 명령 실패를 조기에 드러내고, umask 077은 결과 파일을 소유자만 읽을 수 있게 합니다. OPENAI_CLI_NO_UPDATE_CHECK=1은 CI에서 업데이트 확인이 네트워크 작업에 끼어들지 않게 합니다. --format json과 jq는 파일 ID와 배치 ID를 스크립트 변수로 받기 위한 것입니다.

주의할 점도 있습니다. CLI는 성공한 JSON 응답을 기본적으로 읽기 쉬운 텍스트로 보여주고, 오류는 stderr로 보냅니다. 리다이렉션으로 결과를 저장할 때는 종료 상태를 먼저 확인해야 합니다. 실패한 요청이 불완전한 출력 파일을 남길 수 있기 때문입니다. --debug와 API 오류 상세에는 민감한 데이터가 포함될 수 있으므로 로그에 그대로 남기지 마세요.

비용과 운영의 경계

공식 README에는 “이 작업이 얼마나 비용이 드는가”를 미리 계산하는 기능이 설명돼 있지 않습니다. 배치의 completion window, 모델 선택, 입력 크기, 재시도 횟수를 운영자가 관리해야 합니다. 비용을 통제하려면 다음을 스크립트 밖의 정책으로 두는 편이 좋습니다.

관리자 사용량 조회는 별도 권한이 필요합니다. 예를 들어 organization usage를 하루 단위로 보는 명령은 README에 다음과 같이 나옵니다.

openai admin organization usage completions \
  --start-time 1735689600 \
  --end-time 1735776000 \
  --bucket-width 1d

이 숫자를 비용 최적화의 유일한 근거로 삼지는 마세요. API 가격과 청구 단위는 별도로 확인해야 하고, CLI가 보여주는 토큰 합계가 청구서와 항상 같은 수준으로 맞는다고 가정하면 안 됩니다.

자격증명이 새는 경로

CLI를 쓰면 API 키가 셸 환경에 들어옵니다. 편리하지만 노출 경로도 늘어납니다.

• 명령행 인자에 키를 직접 넣으면 셸 기록과 프로세스 목록에 남을 수 있습니다.
• set -x나 디버그 로그가 환경 변수를 출력할 수 있습니다.
• --debug와 상세 오류는 요청 본문이나 헤더를 포함할 수 있습니다.
• CI 로그에 env를 출력하면 키가 그대로 남습니다.
• 결과 파일에 고객 데이터나 모델 응답이 포함될 수 있습니다.

가장 안전한 방법은 키를 명령행에 넣지 않고, 비밀 관리 도구에서 프로세스 환경으로 주입하는 것입니다. 스크립트에서는 set +x를 명시하고, 키를 출력하는 디버그 문을 만들지 마세요. CI에서는 해당 작업에만 키를 주입하고, 작업이 끝나면 환경과 임시 파일을 정리합니다.

이 CLI가 하지 않는 일

OpenAI CLI는 만능 도구가 아닙니다. 공식 README도 Codex CLI와의 차이를 설명합니다. 이 CLI에는 코드 편집, 파일 시스템 탐색, 테스트 실행을 스스로 판단하는 에이전트 루프가 없습니다. 그런 작업은 Codex CLI나 별도 애플리케이션의 몫입니다. 또한 CLI는 API 호출을 쉽게 만들 뿐, 결과의 정확성을 검증하지 않습니다. 배치 결과를 그대로 신뢰하지 말고 스키마 검증과 표본 검토를 붙여야 합니다.

이번 조사에서는 실제 API 호출, 유료 배치, 이미지 생성, 파일 업로드를 실행하지 않았습니다. 명령과 옵션은 공식 README와 v1.40.0 릴리스 노트를 기준으로 정리했으며, 예시 스크립트는 실행 전에 각자의 환경에서 검증해야 합니다.

결론: 릴리스보다 명령 표면을 보라

v1.40.0은 화제가 될 만한 대형 릴리스가 아닙니다. 하지만 CLI의 가치는 버전 번호가 아니라 “API 작업을 반복 가능한 명령으로 고정한다”는 성질에 있습니다. 배치, 파일, 모델 목록, 사용량 조회를 셸에 두면 사람이 매번 콘솔을 클릭하지 않아도 됩니다.

도입한다면 세 가지부터 정하세요. 사용할 모델과 배치 창을 코드가 아닌 설정으로 둘 것인가, 키를 환경과 로그에서 어떻게 분리할 것인가, 결과 파일의 스키마와 보관 기간을 어떻게 검증할 것인가. 이 세 가지가 없으면 CLI는 편리한 호출 도구일 뿐 운영 가능한 파이프라인이 되지 않습니다.

함께 읽으면 좋은 글

• Codex CLI 0.161.0: 터미널에서 MCP 로그인이 된다
• OpenAI Agents API란? Codex 하네스를 API로 쓰는 시대

참고 자료

• GitHub: openai/openai-cli
• GitHub: OpenAI CLI v1.40.0 release
• GitHub: OpenAI CLI v1.0.0 release

이 주제를 직접 따라가며 배우고 싶다면

도구는 달라도 터미널에서 AI 작업을 반복 가능한 흐름으로 묶는 원리는 비슷합니다. 명령과 권한, 검증 지점을 프로젝트 규칙으로 정리하는 연습을 하고 싶다면 이 강의가 도움이 됩니다.

• Claude Code·하네스 엔지니어링 강의 보기