OpenAI가 공식 CLI를 공개해 터미널에서 API 전 기능을 다룬다

Hacker News10일 전조회 1

OpenAI가 자사 REST API를 터미널에서 직접 호출하는 공식 CLI를 GitHub에 올렸다. 서드파티 래퍼가 아니라 OpenAI가 직접 관리하는 도구라는 점이 핵심이다. 채팅·이미지·파일·관리자 엔드포인트를 하나의 실행 파일에서 다루며, 셸 스크립트나 CI 작업에 API 호출을 끼워 넣기 쉽게 설계됐다.

설치는 Homebrew 탭을 쓰거나 Go 툴체인으로 바이너리를 빌드하는 두 갈래다. 소스에서 설치하려면 Go 1.26 이상이 필요하고, `go install`로 받은 실행 파일은 기본적으로 `$HOME/go/bin`에 놓인다. 설치 후 명령이 잡히지 않으면 Go의 bin 디렉터리를 PATH에 추가하면 된다.

명령 체계는 리소스를 앞세우는 방식이다. `openai <리소스> [하위 리소스...] <명령> [플래그...]` 형태로, 예컨대 조직 사용량을 조회하려면 `openai admin organization usage completions`처럼 이어 붙인다. 기존의 콜론 표기(`openai admin:organization:usage`)도 계속 동작한다. 인자 없이 `openai`만 실행하면 작업별로 묶인 명령 그룹을 설명과 함께 훑어볼 수 있다.

도움말은 API 키나 네트워크 없이도 열린다. `openai help setup`, `openai images generate --help`, `openai --help` 같은 식으로 명령별 전체 옵션을 확인할 수 있고, 탭 완성도 같은 그룹 순서를 따르며 파일 경로 입력까지 지원한다. 예시나 복구 안내 문구를 명령줄에 바로 채워 넣는 기능도 있어 Ctrl+X 뒤 Tab으로 후보를 검색할 수 있다.

인증은 환경 변수로 처리한다. 일반 엔드포인트는 `OPENAI_API_KEY`, 관리자 엔드포인트는 `OPENAI_ADMIN_KEY`를 쓰고, 조직·프로젝트·웹훅 시크릿·mTLS 클라이언트 인증서도 각각 전용 환경 변수나 플래그로 지정할 수 있다. `--base-url`로 백엔드를 바꿀 때는 localhost나 루프백 주소가 아닌 한 HTTPS가 강제된다.

파일과 이미지 작업은 눈에 띄는 부분이다. `openai files upload`로 용도를 지정해 올리고, 메타데이터를 확인한 뒤 `openai files download`로 내려받는다. `openai images generate`는 별도 모델을 지정하지 않으면 `gpt-image-2.5-sunburst`를 사용해 `~/Downloads/gpt-images/`에 결과를 저장하고 경로를 출력한다. 저장된 이미지를 API 호출 없이 다시 보여주는 `images preview`도 있다. 반면 변형 이미지를 만들던 `images create-variation`은 폐기됐고, 같은 목적은 편집 명령으로 대체하도록 안내한다.

스크립트 사용을 염두에 둔 출력 정책도 분명하다. 성공한 JSON 응답은 파이프 안에서도 기본적으로 읽기 좋은 텍스트로 바뀌어 나오고, 데이터를 파싱해야 할 때는 `--format json`이나 `jsonl`을 명시해야 한다. 오류는 요약 형태로 stderr에 찍히며, 원본 API 오류 본문과 스트림 오류 이벤트까지 보려면 `--format-error json`을 쓴다. `--transform-error`로 오류 데이터만 따로 추출할 수도 있다.

업데이트 확인은 보수적으로 설계됐다. 표준 입출력이 모두 터미널일 때만 새 안정 버전을 살피고, 안내 문구는 7일에 한 번만 표시된다. 확인 자체도 하루 최대 한 번, 200밀리초 안에 끝나며 실패하면 조용히 넘어간다. CLI가 스스로 업데이트를 설치하는 일은 없고, Homebrew로 설치한 것이 확인된 경우에만 `brew upgrade` 명령을 안내한다. `OPENAI_CLI_NO_UPDATE_CHECK=1`로 이 동작을 끌 수 있다.

배경에는 API 표면이 넓어졌다는 사실이 있다. 채팅 completions부터 이미지, 파일, 조직 관리까지 엔드포인트가 늘면서 간단한 호출마다 코드를 작성하는 대신 셸에서 바로 실행하려는 수요가 커졌다. 공식 CLI는 그 요구를 OpenAI가 직접 흡수하겠다는 선언에 가깝다.

개발자 입장에서 가장 즉각적인 변화는 반복 작업의 위치다. 파일 업로드와 이미지 생성, 사용량 조회를 스크립트 몇 줄로 처리하고 결과를 파이프로 넘길 수 있어, 배치 작업이나 사내 자동화에 붙이기 쉬워졌다. 반대로 기본 출력이 사람이 읽기 좋은 텍스트라는 점은 주의할 부분이다. 파싱을 전제로 한 스크립트라면 `--format`을 습관처럼 지정해야 하고, `--debug` 로그에는 요청·응답 본문이 그대로 담길 수 있으므로 민감한 페이로드가 섞이지 않도록 관리해야 한다.