OpenAI CLI — официальная консоль для OpenAI API

OpenAI выпустила официальный CLI для своего REST API. Инструмент называется openai-cli. Он написан на Go и закрывает почти всё, что доступно через API: модели, файлы, изображения и админ-эндпоинты организации. Это не кодинг-агент вроде Codex CLI. Это клиент для API: вы сами составляете команду, CLI отправляет запрос и печатает ответ.

Установка

Есть два способа.

Через Homebrew:

brew install openai/tools/openai

Через Go (нужна версия Go 1.26 или новее):

go install 'github.com/openai/openai-cli/cmd/openai@latest'

После go install бинарник кладётся в каталог Go-бинарников. Обычно это $HOME/go/bin, или $GOPATH/bin, если GOPATH задан. Проверить путь: go env GOPATH. Если команда openai не находится, добавьте этот каталог в PATH в профиле оболочки (.zshrc, .bashrc и так далее):

export PATH="$PATH:$(go env GOPATH)/bin"

Для запуска из исходников есть скрипт scripts/run: клонируйте репозиторий и вызывайте ./scripts/run с нужными аргументами.

Структура команд

CLI построен по ресурсам:

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

Обычные эндпоинты требуют API-ключ:

export OPENAI_API_KEY="sk-..."

openai responses create \
  --input "Say this is a test" \
  --model gpt-5.5

Админ-эндпоинты требуют отдельный админ-ключ:

export OPENAI_ADMIN_KEY="sk-admin-..."

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

Помощь работает без API-ключа и без сети:

openai help setup
openai images generate --help
openai --help

Старый формат через двоеточие (openai admin:organization:usage completions) по-прежнему работает. Tab-автодополнение поддерживает группу команд, темы справки и пути к файлам. После обновления перезагрузите автодополнение в оболочке — инструкция: https://github.com/openai/openai-cli/blob/main/docs/shell-completion.md

Есть режим command insertion: Ctrl+X, затем Tab подставляет в командную строку примеры и подсказки по настройке, ничего не запуская. Подробнее: https://github.com/openai/openai-cli/blob/main/docs/command-insertion.md

Формат вывода

Успешный JSON по умолчанию печатается как читаемый текст, в том числе в пайпах. Для скриптов переключите формат:

--format json
--format jsonl

Поддерживаются также yaml, raw, pretty, explore. --transform вырезает нужные поля по синтаксису GJSON. Ошибки идут в stderr кратким понятным описанием; --format-error json даёт полные детали ответа API. --transform-error обрабатывает ошибки отдельно от успешного вывода. Подробнее о читаемом выводе: https://github.com/openai/openai-cli/blob/main/docs/readable-output.md

Файлы

Загрузка локального файла, просмотр метаданных и скачивание:

openai files upload "upload space.txt" --purpose user_data
openai files get file-example
openai files download file-example --output "downloaded copy.txt"
openai files download file-example > copy.txt

Вместо file-example подставьте ID файла из ответа. Загрузка принимает обычный путь, без @.

В JSON-поля можно подставлять файл: @имя-файла читает локальный файл. Для бинарных загрузок используйте флаг --file с обычным путём. Строку, которая начинается с @, можно экранировать: --username '\@abe'. Явное кодирование: @file://имя.txt шлёт текст как есть, @data://имя.bin шлёт base64. Подробности: https://github.com/openai/openai-cli/blob/main/docs/files.md

Если JSON или YAML приходит из незнакомого источника, включите OPENAI_UNTRUSTED_STDIN=1. Тогда @ и @file:// внутри stdin не читают файлы. Для доверенного ввода (heredoc, свои скрипты) переменную не задавайте.

Изображения

Команда:

openai images generate --prompt "A tiny orange robot"

сохраняет картинки в ~/Downloads/gpt-images/ и печатает пути, в том числе в пайпах. Без явной модели используется gpt-image-2.5-sunburst. Своё имя файла задаётся флагом --name, каталог — --output-dir. Существующие файлы не перезаписываются.

images edit тоже сохраняет результат и не трогает исходники. Команды images create-variation больше нет — для вариантов используйте images edit с моделью GPT Image и промптом. openai images preview "path/to/image.png" показывает уже сохранённое изображение без запроса к API. Настройка автопоказа: openai images inline on или off, на команду — флаг --inline. Подробнее: https://github.com/openai/openai-cli/blob/main/docs/image-generation-saving.md

Переменные окружения

Глобальные флаги

• --api-key, --admin-api-key — ключи (или переменные окружения)
• --organization, --project — организация и проект
• --base-url — свой адрес API. По HTTPS, кроме localhost и loopback-адресов вроде 127.0.0.1 и ::1. То же касается OPENAI_BASE_URL
• --header, -H — свой заголовок запроса, можно повторять
• --format, --format-error, --transform, --transform-error — вывод и ошибки
• --debug — подробный лог HTTP-запросов и ответов; не выкладывайте такие логи публично
• --version, -v — версия CLI
• --help, -h — справка по любой команде

Заголовки запросов

openai --header 'X-Trace-ID: example-123' models list \
  -H 'X-Client-Label: local,manual'

Значения передаются как есть, без разбора @-префиксов. Если имя повторяется, побеждает последнее. Секреты в заголовках не стоит печатать в аргументах командной строки — они попадают в историю оболочки. Для этого есть OPENAI_CUSTOM_HEADERS: переменная принимает по одному Name: Value в строке.

mTLS (бета)

Mutual TLS сейчас в бете. Чтобы включить, нужно активировать CA-сертификат для организации или проекта по инструкции программы: https://help.openai.com/en/articles/10876024-openai-mutual-tls-beta-program

Два PEM-файла задаются вместе:

export OPENAI_MTLS_CLIENT_CERT_FILE=/run/secrets/openai/client-chain.pem
export OPENAI_MTLS_CLIENT_KEY_FILE=/run/secrets/openai/client.key
export OPENAI_BASE_URL=https://mtls.api.openai.com/v1

openai files list

Приватный ключ держите в файле с ограниченными правами. CLI сам не выбирает mTLS-эндпоинт — OPENAI_BASE_URL или --base-url задаётся явно. HTTP- и SOCKS-прокси работают, HTTPS-прокси отклоняются, чтобы клиентский сертификат не утек в TLS-рукопожатие прокси.

Проверка обновлений

Без аргументов openai проверяет свежие стабильные релизы, когда stdin, stdout и stderr — терминалы. Уведомление печатается под справкой не чаще раза в семь дней. Явные команды, автодополнение, CI и перенаправленные потоки проверку пропускают. CLI ничего не ставит сам: подставляет команду обновления или ссылку на инструкцию. Проверка использует публичные метаданные релизов GitHub, ждёт не больше 200 миллисекунд и молчит при сбое. Отключить: OPENAI_CLI_NO_UPDATE_CHECK=1.

Разработка и лицензия

Разные версии Go SDK можно подключить к CLI скриптом ./scripts/link — веткой, тегом или коммитом из репозитория, либо локальной копией SDK.

Баги и идеи — через GitHub issues. Pull request принимают только от коллабораторов; политика описана здесь: https://github.com/openai/openai-cli/blob/main/CONTRIBUTING.md. Уязвимости — по https://github.com/openai/openai-cli/blob/main/SECURITY.md. Лицензия Apache-2.0: https://github.com/openai/openai-cli/blob/main/LICENSE