OpenAI CLI는 OpenAI REST API를 위한 OpenAI의 공식 명령줄 도구입니다. openai 바이너리 하나를 설치하고 OPENAI_API_KEY를 설정한 뒤 터미널이나 셸 스크립트에서 API를 호출하면 됩니다. openai responses create, openai files upload, openai batches create, openai images generate 같은 식입니다. 이것은 Codex CLI가 아닙니다. Codex는 코딩 에이전트이고, openai는 명령 하나당 API 요청 하나를 보냅니다.
이 가이드는 설치, 인증, 가장 먼저 실행해볼 만한 명령, 그리고 Codex CLI 및 Python SDK가 PATH에 남겨둔 예전 openai 명령과의 비교를 다룹니다. 아래의 모든 명령과 출력은 2026년 10월 28일에 설치하고 실행한 버전 1.44.1에서 가져온 것입니다.
OpenAI CLI란 무엇인가?
OpenAI CLI는 OpenAI가 github.com/openai/openai-cli에서 Apache 2.0 라이선스로 공개한 오픈소스 Go 바이너리입니다. 명령이 API의 리소스(responses, files, batches, images, audio, vector-stores, admin)를 그대로 반영하기 때문에, curl이나 SDK로 보내던 모든 것이 플래그를 붙인 터미널 명령 하나가 됩니다.
완전히 새로운 것은 아닙니다. 버전 1.0.0이 2026년 5월 5일에 출시되었고, 그 이후 프로젝트는 99개의 릴리스를 배포했습니다. 1.44.1은 2026년 10월 27일에 나왔습니다. 그러니 출시 소식이 아니라, 놓치고 있었을 수도 있는 성숙한 도구로 보시면 됩니다.
처음 실행했을 때 보게 되는 것은 다음과 같습니다:
도움말은 명령을 용도별로 묶어 보여줍니다: 콘텐츠 생성(responses, chat, images, audio, videos), 데이터 및 검색(files, uploads, vector-stores, embeddings), 모델과 작업, 관리, 그리고 네트워크를 전혀 사용하지 않는 로컬 도구 모음입니다. 도움말 자체는 API 키도, 연결도 필요 없으므로 openai <command> --help가 플래그를 익히는 가장 빠른 방법입니다.
스크립트를 작성하지 않고 프롬프트를 테스트하려는 개발자, 파일 업로드와 배치를 cron 작업에 넣고 싶은 운영 담당자, 직접 짠 curl 대신 문서화된 인터페이스가 필요한 코딩 에이전트에게 잘 맞습니다.
OpenAI CLI 설치 방법
설치 경로는 세 가지이며, 모두 프로젝트 README에 나와 있습니다:
- 미리 빌드된 바이너리. GitHub Releases에서 사용 중인 OS와 아키텍처에 맞는 아카이브를 내려받아(macOS, Linux, Windows 빌드가 게시됩니다) 압축을 풀고
openai를 PATH에 넣습니다. - Homebrew.
brew install openai/tools/openai
- Go. Go 1.26 이상이 필요합니다.
go install 'github.com/openai/openai-cli/cmd/openai@latest'
export PATH="$PATH:$(go env GOPATH)/bin"
직접 관리하는 릴리스 설치본은 대화형 실행 중에 스스로 업데이트할 수 있습니다. CI에서 버전을 고정한다면 OPENAI_CLI_NO_AUTO_UPDATE=1로 자동 설치를 막거나, OPENAI_CLI_NO_UPDATE_CHECK=1로 업데이트 확인 자체를 끄면 됩니다. Homebrew와 Go 설치는 업데이트 알림은 유지하되 업그레이드는 패키지 관리자에 맡깁니다.
OpenAI CLI 인증 방식
CLI는 OPENAI_API_KEY에서 표준 API 키를 읽습니다(또는 --api-key 플래그인데, 셸 히스토리에 남기 때문에 피하는 게 좋습니다). 아직 키가 없다면, OpenAI API 키 발급받기 가이드에서 자세히 다룹니다.
가장 빠른 설정 방법은 내장 가이드입니다:
openai help setup
API 키 페이지로 안내하고, Bash나 zsh용 read -rs OPENAI_API_KEY 줄을 알려주므로 키가 숨겨진 채로 입력되고 절대 화면에 표시되지 않습니다.
키를 빠뜨리면 명확하고 스크립트에서 처리 가능한 실패를 만납니다. 다음은 키를 설정하지 않았을 때의 실제 출력입니다:
상태 코드 1로 종료하면서 키가 어디서 올 수 있는지 정확히 알려줍니다. 스크립트가 원시 오류 본문을 필요로 한다면 --format-error json을 추가하세요.
나머지 인증 설정은 다음과 같습니다:
| 설정 | 플래그 | 환경 변수 | 사용 용도 |
|---|---|---|---|
| API 키 | --api-key |
OPENAI_API_KEY |
모든 일반 API 호출 |
| 관리자 키 | --admin-api-key |
OPENAI_ADMIN_KEY |
openai admin ...(사용량, 프로젝트). 프로젝트 키로는 대체할 수 없습니다 |
| Base URL | --base-url |
OPENAI_BASE_URL |
CLI를 다른 호스트나 게이트웨이로 지정 |
| mTLS 인증서 및 키 | --mtls-client-cert-file, --mtls-client-key-file |
OPENAI_MTLS_CLIENT_CERT_FILE, OPENAI_MTLS_CLIENT_KEY_FILE |
상호 TLS. 명시적인 HTTPS base URL이 필요합니다 |
먼저 실행해볼 OpenAI CLI 명령
명령 형태는 API를 따릅니다: openai <resource> [subresource...] <command> [flags...]. 다음은 도구함에 자리할 만한 명령들입니다.
Responses API 호출하기
openai responses create \
--model gpt-5.5 \
--input "Say this is a test"
긴 프롬프트도 이스케이프할 필요가 없습니다. JSON 입력 플래그는 @path로 파일에서 읽습니다:
openai responses create --model gpt-5.5 --input @prompt.txt
신뢰할 수 없는 출처에서 JSON이나 YAML을 파이프로 넘긴다면, 그 입력이 로컬 파일 읽기를 유발할 수 없도록 OPENAI_UNTRUSTED_STDIN=1을 설정하세요.
파일 업로드 및 가져오기
openai files upload report.txt --purpose user_data
openai files get file-example
openai files download file-example --output downloaded-report.txt
배치 실행하기
requests.jsonl에 요청을 한 줄에 하나씩, 각각 고유한 custom_id와 함께 넣은 다음:
openai files upload requests.jsonl --purpose batch
openai batches create --input-file-id file-example \
--endpoint /v1/responses --completion-window 24h
openai batches wait batch_example --output-dir ./results
batches wait은 배치가 끝날 때까지 폴링하고 결과 파일을 저장하므로, 따로 작성해야 했을 폴링 루프를 없애줍니다. 프로젝트의 배치 가이드에 따르면 현재 한도는 입력 파일당 50,000건 요청과 200 MB이며, 완료 기한은 24h입니다. 배치 가격은 동기 호출과 다르므로, 대규모 작업을 큐에 넣기 전에 OpenAI API 가격 정리를 확인하세요.
키 없이 로컬에서 토큰 세기
tokenizer 명령은 완전히 오프라인으로 동작합니다: 자격 증명도, 네트워크도, 저장되는 입력도 없습니다.
기본 인코딩은 o200k_base이고, openai tokenizer encodings는 나머지(cl100k_base와 두 개의 레거시 인코딩)를 나열합니다. 도움말은 한계를 솔직하게 밝히고 있습니다. 순수 텍스트 개수는 요청 구조와 멀티모달 입력을 제외하므로 청구 금액이 아닙니다. 서버 측 개수는 openai responses input-tokens count를 사용하세요.
스크립트가 파싱할 수 있는 출력 얻기
기본 출력은 파이프로 넘겨도 사람이 읽을 수 있는 텍스트입니다. 데이터를 명시적으로 요청하세요:
openai models list --format jsonl | jq '.id'
openai files list --format json > files.json
openai files get file-example --transform filename --raw-output
--format은 auto, text, json, jsonl, yaml, explore(대화형 JSON 뷰어), pretty를 받습니다. --transform은 GJSON 문법으로 필드를 뽑아내고, 더 복잡한 것은 jq가 처리합니다. 리다이렉트된 파일을 신뢰하기 전에 항상 종료 상태를 확인하세요. 실패한 요청은 불완전한 파일을 남길 수 있습니다.
호출이 이상하게 동작하면 --debug가 시도별 HTTP 타이밍을 추가합니다. 로그를 공유하기 전에 민감 정보를 지우세요. 429를 맞고 있다면 OpenAI 속도 제한 가이드에서 티어를 설명합니다.
OpenAI CLI vs Codex CLI vs 예전 openai 명령
세 도구가 같은 벤더를 공유하고, 그중 둘은 이름까지 공유합니다. 짧게 정리하면 다음과 같습니다:
| OpenAI CLI | Codex CLI | 레거시 Python openai |
|
|---|---|---|---|
| 명령 | openai |
codex |
openai |
| 정체 | REST API용 클라이언트 | 프로젝트의 코드를 읽고, 수정하고, 실행하는 코딩 에이전트 | openai Python 패키지에 포함된 CLI |
| 설치 | 바이너리, Homebrew 또는 Go | npm install -g @openai/codex 또는 brew install --cask codex |
pip install openai |
| 인증 | OPENAI_API_KEY |
자체 로그인 처리 | API 키 |
| 사용 시점 | 특정 API 호출 하나가 필요하거나, 스크립트에 API 단계를 넣고 싶을 때 | 에이전트가 변경 사항을 구현하거나 디버깅하길 원할 때 | 이를 기반으로 만든 오래된 스크립트를 유지보수할 때 |
openai codex를 실행하면 OpenAI CLI가 Codex 설치 명령을 직접 출력하면서, 이것이 자체 로그인을 가진 별도 도구라고 알려줍니다. Codex CLI 가이드가 에이전트 쪽을 다루며, 소스는 github.com/openai/codex에 있습니다.
PATH 충돌 주의하기
openai Python 패키지도 openai라는 이름의 바이너리를 설치합니다. pip install openai를 실행한 적이 있다면 두 개를 갖고 있을 수 있습니다:
이 Mac에서는 Python 쪽이 openai 2.30.0을 보고하고 api, tools, migrate, grit 하위 명령을 제공하며, Go 쪽은 openai version 1.44.1을 보고합니다. PATH에서 어느 디렉터리가 먼저 오는지가 승자를 정합니다. 설치 후 which -a openai와 openai --version을 실행해 보세요. 출력이 openai version 1.44.1(또는 그 이상)이면 올바른 것을 사용 중입니다. openai 2.30.0처럼 버전 숫자만 출력한다면 PATH 순서를 바꾸거나 새 바이너리를 전체 경로로 호출하세요.
OpenAI CLI 옆에서 Apidog CLI가 하는 역할
OpenAI CLI는 OpenAI로 호출을 보냅니다. 여러분 자신의 API는 알지 못합니다. OpenAI 위에 여러분의 앱이 노출하는 엔드포인트, 배포하는 환경, 릴리스가 아무것도 망가뜨리지 않았음을 증명하는 검증 같은 것은 다루지 않습니다. 그것은 다른 일이고, 바로 그 지점에서 Apidog CLI가 등장합니다. 둘 중 하나를 고르는 것이 아니라, AI 기능을 출시하는 대부분의 팀은 둘 다 원합니다.
더 나아가, 코딩 에이전트가 둘 다 실행하게 할 수도 있습니다. Apidog CLI를 한 번 설정하세요:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
그런 다음 에이전트에게 프롬프트 하나를 주세요:
Use the openai CLI to confirm my key works with one responses create call on gpt-5.5.
Then import ./openapi.yaml into Apidog project <id>, create a test case for
POST /v1/summarize that asserts a 200 and a non-empty "summary" field, run it
against the staging environment and summarize any failures.
에이전트는 openai로 키를 확인한 다음 Apidog CLI로 작업을 진행합니다. 페이로드를 작성하기 전에 스키마를 읽고, 파일을 검증한 뒤에야 테스트 케이스를 만들고 실행합니다:
apidog import --project <id> --format openapi --file ./openapi.yaml
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> -r cli,json
apidog test-case create --help에서 얻는 두 가지 세부 사항이 시행착오를 줄여줍니다. 케이스에는 유효한 categoryId가 필요하고(apidog test-case category --project <id>로 목록을 확인하세요), 페이로드는 기억에 의존하지 말고 반드시 cli-schema에서 가져와야 합니다. 같은 apidog run 줄에 -r junit을 붙이면 CI에 바로 들어가며, Apidog CLI CI/CD 가이드에서 확인할 수 있습니다. 에이전트로 Codex를 쓴다면 Codex에서의 Apidog CLI부터 시작하세요.
Apidog의 무료 플랜은 최대 4명까지 지원하므로, 소규모 팀이라면 구매 결정 없이 시도해볼 수 있습니다.
자주 묻는 질문
OpenAI CLI는 무료인가요? 이 도구는 Apache 2.0에 따라 무료이고 오픈소스입니다. 도구가 보내는 API 호출은 일반 API 요금으로 여러분의 OpenAI 계정에 청구됩니다. openai tokenizer 같은 로컬 명령과 모든 --help 페이지는 비용이 들지 않고 키도 필요 없습니다.
OpenAI CLI는 Codex CLI와 같은 건가요? 아닙니다. openai는 명령 하나당 하나씩, 직접 API 요청을 보냅니다. codex는 프로젝트를 읽고 수정하며 명령을 실행하는 코딩 에이전트입니다. 둘은 따로 설치되고 따로 인증합니다.
Mac에서 OpenAI CLI를 설치하려면 어떻게 하나요? brew install openai/tools/openai를 실행하거나, GitHub Releases에서 macos_arm64(Apple Silicon) 또는 macos_amd64(Intel) zip을 내려받아 바이너리를 PATH에 넣으세요. 그런 다음 openai --version을 실행해 예전 Python openai 명령을 실행하고 있지 않은지 확인하세요.
OpenAI CLI는 셸 스크립트와 CI에서 동작하나요? 네, 그게 주된 설계 목표입니다. 파싱 가능한 출력을 위해 --format json 또는 jsonl을 사용하고, 종료 상태를 확인하고, 키는 시크릿 관리자에서 OPENAI_API_KEY로 가져오고, 버전을 고정하려면 OPENAI_CLI_NO_AUTO_UPDATE=1을 설정하세요.
OpenAI CLI는 언제 출시되었나요? 버전 1.0.0이 2026년 5월 5일 GitHub에 게시되었습니다. 2026년 10월 28일 기준 최신 릴리스는 10월 27일에 나온 1.44.1입니다.