La OpenAI CLI es la herramienta oficial de línea de comandos de OpenAI para la API REST de OpenAI. Instalas un único binario openai, configuras OPENAI_API_KEY y llamas a la API desde tu terminal o un script de shell: openai responses create, openai files upload, openai batches create, openai images generate. No es Codex CLI. Codex es un agente de programación; openai envía una solicitud a la API por comando.
Esta guía cubre la instalación, la autenticación, los primeros comandos que vale la pena ejecutar y cómo se compara con Codex CLI y con el antiguo comando openai que el SDK de Python colocaba en tu PATH. Todos los comandos y resultados a continuación provienen de la versión 1.44.1, instalada y ejecutada el 28 de octubre de 2026.
¿Qué es la OpenAI CLI?
La OpenAI CLI es un binario de Go de código abierto, publicado por OpenAI en github.com/openai/openai-cli bajo la licencia Apache 2.0. Sus comandos reflejan los recursos de la API (responses, files, batches, images, audio, vector-stores, admin), así que cualquier cosa que enviarías con curl o un SDK se convierte en un solo comando de terminal con flags.
No es completamente nueva. La versión 1.0.0 se publicó el 5 de mayo de 2026, y el proyecto ha sacado 99 versiones desde entonces; la 1.44.1 llegó el 27 de octubre de 2026. Así que trátala como una herramienta madura que quizá te perdiste, no como un lanzamiento.
Esto es lo que obtienes en una primera ejecución:
La ayuda agrupa los comandos por tarea: generar contenido (responses, chat, images, audio, videos), datos y recuperación (files, uploads, vector-stores, embeddings), modelos y trabajos, administración, y un conjunto de herramientas locales que nunca tocan la red. La ayuda en sí no necesita clave de API ni conexión, lo que convierte a openai <command> --help en la forma más rápida de aprender los flags.
Les viene bien a los desarrolladores que prueban un prompt sin escribir un script, al personal de operaciones que quiere subidas de archivos y lotes en un trabajo de cron, y a los agentes de programación que necesitan una interfaz documentada en lugar de curl hecho a mano.
Cómo instalar la OpenAI CLI
Tienes tres rutas de instalación, todas listadas en el README del proyecto:
- Binario precompilado. Descarga el archivo para tu sistema operativo y arquitectura desde GitHub Releases (se publican compilaciones para macOS, Linux y Windows), extráelo y coloca
openaien tu PATH. - Homebrew.
brew install openai/tools/openai
- Go. Requiere Go 1.26 o posterior.
go install 'github.com/openai/openai-cli/cmd/openai@latest'
export PATH="$PATH:$(go env GOPATH)/bin"
Las instalaciones de versiones autogestionadas pueden actualizarse a sí mismas durante las ejecuciones interactivas. Si fijas versiones en CI, establece OPENAI_CLI_NO_AUTO_UPDATE=1 para detener las instalaciones automáticas, o OPENAI_CLI_NO_UPDATE_CHECK=1 para desactivar por completo las comprobaciones de actualización. Las instalaciones de Homebrew y Go conservan sus avisos de actualización pero dejan las actualizaciones al gestor de paquetes.
Cómo funciona la autenticación de la OpenAI CLI
La CLI lee una clave de API estándar de OPENAI_API_KEY (o del flag --api-key, que deberías evitar porque acaba en el historial del shell). Si aún no tienes una, nuestra guía para obtener una clave de API de OpenAI lo explica paso a paso.
La configuración más rápida es la guía integrada:
openai help setup
Te dirige a la página de claves de API y te da una línea read -rs OPENAI_API_KEY para Bash o zsh, de modo que la clave se escribe oculta y nunca se muestra.
Olvida la clave y obtendrás un fallo claro y apto para scripts. Esta es la salida real sin ninguna clave configurada:
Sale con estado 1 y te dice exactamente de dónde puede venir una clave. Añade --format-error json cuando un script necesite el cuerpo sin procesar del error.
Los demás ajustes de autenticación:
| Ajuste | Flag | Variable de entorno | Úsalo para |
|---|---|---|---|
| Clave de API | --api-key |
OPENAI_API_KEY |
Toda llamada normal a la API |
| Clave de administrador | --admin-api-key |
OPENAI_ADMIN_KEY |
openai admin ... (uso, proyectos); una clave de proyecto no puede sustituirla |
| URL base | --base-url |
OPENAI_BASE_URL |
Apuntar la CLI a otro host o a una pasarela |
| Certificado y clave mTLS | --mtls-client-cert-file, --mtls-client-key-file |
OPENAI_MTLS_CLIENT_CERT_FILE, OPENAI_MTLS_CLIENT_KEY_FILE |
TLS mutuo, que necesita una URL base HTTPS explícita |
Primeros comandos de la OpenAI CLI que ejecutar
La forma del comando sigue a la de la API: openai <resource> [subresource...] <command> [flags...]. Estos son los comandos que se ganan su lugar en una caja de herramientas.
Hacer una llamada a la API de Responses
openai responses create \
--model gpt-5.5 \
--input "Say this is a test"
Los prompts largos no necesitan escape. Los flags de entrada JSON se leen desde un archivo con @path:
openai responses create --model gpt-5.5 --input @prompt.txt
Si canalizas JSON o YAML desde una fuente en la que no confías, establece OPENAI_UNTRUSTED_STDIN=1 para que esa entrada no pueda desencadenar lecturas de archivos locales.
Subir y obtener archivos
openai files upload report.txt --purpose user_data
openai files get file-example
openai files download file-example --output downloaded-report.txt
Ejecutar un lote
Coloca una solicitud por línea en requests.jsonl, cada una con un custom_id único, y luego:
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 sondea hasta que el lote termina y guarda los archivos de resultados, lo que elimina el bucle de sondeo que, de otro modo, tendrías que escribir. La guía de lotes del proyecto indica que los límites actuales son 50.000 solicitudes y 200 MB por archivo de entrada, con una ventana de finalización de 24h. El precio de los lotes difiere del de las llamadas síncronas; consulta nuestro desglose de precios de la API de OpenAI antes de poner en cola un trabajo grande.
Contar tokens localmente, sin clave
El comando tokenizer se ejecuta totalmente sin conexión: sin credenciales, sin red, sin entrada guardada.
La codificación predeterminada es o200k_base, y openai tokenizer encodings lista las demás (cl100k_base, más dos heredadas). La ayuda es sincera sobre los límites: un recuento de texto plano excluye la estructura de la solicitud y las entradas multimodales, por lo que no es una cifra de facturación. Para un recuento del lado del servidor, usa openai responses input-tokens count.
Obtener una salida que un script pueda analizar
La salida predeterminada es texto legible, incluso cuando se canaliza. Pide datos explícitamente:
openai models list --format jsonl | jq '.id'
openai files list --format json > files.json
openai files get file-example --transform filename --raw-output
--format acepta auto, text, json, jsonl, yaml, explore (un visor JSON interactivo) y pretty. --transform extrae campos con sintaxis de GJSON, y jq se encarga de cualquier cosa más elaborada. Comprueba siempre el estado de salida antes de fiarte de un archivo redirigido: una solicitud fallida puede dejar uno parcial.
Cuando una llamada se comporta mal, --debug añade tiempos HTTP por intento; limpia sus registros antes de compartirlos. Si te encuentras con 429, nuestra guía de límites de velocidad de la API de OpenAI explica los niveles.
OpenAI CLI vs Codex CLI vs el antiguo comando openai
Tres herramientas comparten proveedor y dos comparten nombre. Esta es la versión corta:
| OpenAI CLI | Codex CLI | Python openai heredado |
|
|---|---|---|---|
| Comando | openai |
codex |
openai |
| Qué es | Un cliente para la API REST | Un agente de programación que lee, edita y ejecuta código en tu proyecto | Una CLI incluida con el paquete Python openai |
| Instalación | Binario, Homebrew o Go | npm install -g @openai/codex o brew install --cask codex |
pip install openai |
| Autenticación | OPENAI_API_KEY |
Gestiona su propio inicio de sesión | Clave de API |
| Úsalo cuando | Quieras una llamada específica a la API, o pasos de API en un script | Quieras que un agente implemente o depure un cambio | Mantengas scripts antiguos construidos sobre ella |
Ejecuta openai codex y la propia OpenAI CLI imprime los comandos de instalación de Codex, señalando que es una herramienta aparte con su propio inicio de sesión. Nuestra guía de Codex CLI cubre el lado del agente, y el código fuente está en github.com/openai/codex.
Ojo con el conflicto de PATH
El paquete Python openai también instala un binario llamado openai. Si alguna vez has ejecutado pip install openai, puede que tengas dos:
En este Mac, el de Python informa openai 2.30.0 y ofrece los subcomandos api, tools, migrate y grit; el de Go informa openai version 1.44.1. El directorio que aparezca primero en tu PATH es el que gana. Ejecuta which -a openai y openai --version después de instalar. Si la salida dice openai version 1.44.1 (o una posterior), tienes el correcto. Si imprime un número de versión simple como openai 2.30.0, reordena tu PATH o llama al nuevo binario por su ruta completa.
Dónde encaja Apidog CLI junto a la OpenAI CLI
La OpenAI CLI hace llamadas a OpenAI. No sabe nada de tu propia API: los endpoints que tu aplicación expone sobre OpenAI, los entornos en los que despliegas o las aserciones que demuestran que una versión no rompió nada. Eso es otro trabajo, y ahí es donde entra Apidog CLI. No eliges una en lugar de la otra; la mayoría de los equipos que lanzan una función de IA quieren ambas.
Mejor aún, deja que tu agente de programación ejecute las dos. Configura Apidog CLI una vez:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Luego dale a tu agente un único prompt:
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.
El agente comprueba la clave con openai y luego trabaja a través de Apidog CLI. Lee el esquema antes de escribir cualquier carga útil, valida el archivo y solo entonces crea y ejecuta el caso:
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
Dos detalles de apidog test-case create --help te ahorran un viaje de ida y vuelta: el caso necesita un categoryId válido (lístalos con apidog test-case category --project <id>), y las cargas útiles deben venir de cli-schema, nunca de memoria. La misma línea de apidog run con -r junit se integra en CI, como muestra nuestra guía de Apidog CLI en CI/CD. Si Codex es tu agente, empieza por Apidog CLI en Codex.
El plan gratuito de Apidog cubre hasta 4 usuarios, así que un equipo pequeño puede probarlo sin tener que tomar una decisión de compra.
Preguntas frecuentes
¿Es gratuita la OpenAI CLI? La herramienta es gratuita y de código abierto bajo Apache 2.0. Las llamadas a la API que realiza se facturan a tu cuenta de OpenAI a las tarifas normales de la API. Los comandos locales como openai tokenizer y todas las páginas de --help no cuestan nada y no necesitan clave.
¿Es la OpenAI CLI lo mismo que Codex CLI? No. openai envía solicitudes directas a la API, una por comando. codex es un agente de programación que lee y edita tu proyecto y ejecuta comandos. Se instalan por separado y se autentican por separado.
¿Cómo instalo la OpenAI CLI en un Mac? Ejecuta brew install openai/tools/openai, o descarga el zip macos_arm64 (Apple Silicon) o macos_amd64 (Intel) desde GitHub Releases y coloca el binario en tu PATH. Luego ejecuta openai --version para confirmar que no estás usando el comando openai antiguo de Python.
¿Funciona la OpenAI CLI en scripts de shell y CI? Sí, ese es su principal objetivo de diseño. Usa --format json o jsonl para obtener una salida analizable, comprueba el estado de salida, mantén la clave en OPENAI_API_KEY desde tu gestor de secretos y establece OPENAI_CLI_NO_AUTO_UPDATE=1 para mantener la versión fijada.
¿Cuándo se publicó la OpenAI CLI? La versión 1.0.0 se publicó en GitHub el 5 de mayo de 2026. A fecha del 28 de octubre de 2026, la última versión es la 1.44.1, del 27 de octubre.