OpenAI가 자사 REST API를 위한 공식 명령행 도구(CLI)를 깃허브에 공개했다. Go로 작성돼 있으며 로컬에서 빌드하거나 설치하려면 Go 1.26 이상이 필요하다. go install을 실행하면 바이너리가 Go의 bin 디렉터리에 놓이고, 설치 후 명령을 찾지 못하면 해당 디렉터리를 PATH에 추가해야 한다. 저장소를 클론한 경우에는 scripts/run 스크립트로 바로 실행해 볼 수 있다. 겉보기에는 흔한 API 래퍼처럼 보이지만, 실제 명세를 뜯어보면 스크립트 환경과 보안 운영을 상당히 의식한 설계가 드러난다.
리소스 기반 구조와 오프라인 도움말
명령 체계는 리소스 중심으로 짜여 있다. 일반 API 엔드포인트는 OPENAI_API_KEY로, 관리자 엔드포인트는 OPENAI_ADMIN_KEY로 각각 인증한다. openai admin --help처럼 그룹별로 --help를 붙여 탐색할 수 있고, openai admin:organization:usage 같은 기존 콜론 방식 명령도 계속 동작한다. 눈여겨볼 점은 도움말이 API 키나 네트워크 연결 없이 작동한다는 것이다. 그냥 openai만 입력하면 작업 단위로 명령 그룹을 설명과 함께 보여주고, 각 명령 페이지에는 전역 옵션이 함께 나열된다. 탭 자동완성은 그룹 순서를 따르고 도움말 토픽과 파일 입력 경로까지 지원하는데, 업그레이드 후에는 셸 자동완성을 다시 불러와야 새 파일 경로 동작이 활성화된다.
도구는 사용자가 눈치채기 어려운 동작도 일부 수행한다. 아무 인자 없이 openai를 실행하고 표준 입출력이 모두 터미널일 때, CLI는 공개된 깃허브 릴리스 메타데이터를 통해 새 안정 버전을 하루 한 번 이내로 확인하고 도움말 아래에 7일에 한 번꼴로 평문 알림을 덧붙인다. 이 확인은 API 자격 증명 없이 이뤄지고 HTTPS_PROXY·NO_PROXY를 존중하며 최대 200밀리초만 대기하고, 실패하면 조용히 넘어간다. 명시적 help, 파이프로 리다이렉트된 스트림, CI 환경에서는 아예 건너뛴다. CLI는 절대 업데이트를 자동 설치하지 않으며, OPENAI_CLI_NO_UPDATE_CHECK=1로 알림 자체를 끌 수 있다. 사내 자동화 파이프라인에서 예기치 않은 네트워크 호출을 꺼리는 팀이라면 기억해 둘 만한 환경 변수다.
파이프라인에서의 출력과 파일 처리
스크립트 작성자에게 중요한 특징은 출력 기본값이다. 성공한 JSON 응답은 파이프 안에서도 기본적으로 사람이 읽기 좋은 텍스트로 출력된다. 따라서 API 데이터를 프로그램으로 파싱하려면 --format json이나 --format jsonl을 명시해야 한다. 이 기본 동작을 모르고 파이프 출력을 그대로 파싱하면 예상과 다른 결과를 얻을 수 있으니, 자동화 스크립트에서는 포맷 플래그를 습관적으로 붙이는 편이 안전하다. 파일 업로드는 목적(purpose)을 지정해 올리고 메타데이터를 조회한 뒤 내용을 내려받는 흐름이며, 업로드 시 경로 앞에 @를 붙이지 않는 점이 JSON 입력 규칙과 구분된다.
이미지 생성은 별도의 편의 계층을 갖췄다. openai images generate --prompt는 결과를 ~/Downloads/gpt-images/에 저장하고 경로를 출력하며, 모델이나 레거시 응답 형식을 지정하지 않으면 gpt-image-2.5-sunburst를 사용한다. --model, --name, --output-dir로 세부 조정이 가능하고 기존 파일은 덮어쓰지 않고 보존한다. 다만 --format json을 쓰면 저장 없이 API 데이터만 반환한다는 점을 알아둬야 한다. images create-variation은 폐기됐고, 대신 GPT Image 모델과 프롬프트를 쓴 images edit로 변형을 만들어야 한다. 오류 역시 기본적으로 표준 오류로 실행 가능한 요약만 출력하고, 원본 API 오류 상세는 --format-error json으로 따로 요청해야 한다. 요약은 거부된 값이나 요청 URL을 생략하는데, 이는 서버가 돌려준 민감 정보가 로그에 남지 않게 하려는 의도다.
자격 증명과 신뢰 경계를 다루는 방식
이 CLI에서 가장 실무적으로 의미 있는 부분은 보안 경계 처리다. 커스텀 헤더는 --header/-H로 넣되 값은 문자열 그대로 취급돼 @ 접두사가 파일을 읽지 않으며, 입력한 헤더 값은 도움말에서 숨겨지고 디버그 로그에서 가려진다. 자격 증명이 담긴 헤더라면 명령 인자가 아니라 OPENAI_CUSTOM_HEADERS 환경 변수에 비밀 관리자나 신뢰된 실행기가 직접 넣도록 권고한다. 비밀이 셸 히스토리에 남지 않게 하려는 조치다. 상호 TLS(mTLS)는 베타로 제공되며, 클라이언트 인증서와 개인 키를 별도 PEM 파일로 지정하고 개인 키는 권한이 제한된 파일에 두도록 한다. 프록시의 TLS 핸드셰이크 과정에서 클라이언트 인증서가 노출되는 것을 막기 위해 HTTPS 프록시는 거부되고 HTTP·SOCKS만 허용된다.
신뢰할 수 없는 입력을 다루는 장치도 눈에 띈다. JSON 입력에서 @myfile은 로컬 파일 내용을 읽고, @file://은 문자열로 @data://는 base64로 인코딩하도록 명시할 수 있다. 문제는 외부에서 받은 JSON·YAML을 파이프로 넘길 때다. 이 경우 OPENAI_UNTRUSTED_STDIN을 켜면 stdin으로 들어온 값의 @·@file://·@data:// 참조가 파일을 읽지 않고 리터럴로만 처리돼, 신뢰할 수 없는 데이터가 로컬 파일을 끌어오는 경로 공격을 차단한다. 파일 업로드는 이 모드에서 반드시 명령행 플래그로 명시해야 한다. 신뢰된 heredoc처럼 의도적으로 로컬 파일을 참조하는 입력에서는 이 변수를 비워 둬야 한다는 점에서, 신뢰 경계를 운영자가 직접 선언하도록 설계한 셈이다.
종합하면 이 도구는 단순한 API 호출 래퍼를 넘어 파이프라인 기본 출력, 암묵적 업데이트 확인, 자격 증명 격리, 신뢰할 수 없는 stdin 처리 같은 운영상의 세부를 상당히 신경 쓴 결과물이다. 다만 라이선스는 Apache 2.0이지만 풀 리퀘스트는 저장소 협업자로 제한되고 외부 기여는 받지 않으며, 버그 리포트와 기능 요청은 깃허브 이슈로만 받는다는 점에서 커뮤니티 기여 폭은 좁다. Go 1.26 이상이라는 비교적 최신 요구 사항도 도입 시 확인해야 할 전제다. 반대로 말하면, 기본값과 환경 변수의 동작을 미리 숙지한 팀일수록 이 CLI의 보안 지향적 설계를 온전히 활용할 수 있다.