CLI de OpenAI

Interactúa con la API de OpenAI directamente desde tu terminal con la herramienta de línea de comandos openai.

Instalación

Instala la CLI con Homebrew:

brew install openai/tools/openai

También puedes instalarla con Go 1.25 o una versión posterior:

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

Las versiones anteriores del SDK de Python también instalaban una versión antigua del comando openai. Si ya tenías ese paquete instalado y el comando que ves no coincide con el de esta guía, es posible que el shell siga usando el ejecutable anterior. Esto no afecta a las instalaciones nuevas de la CLI.

Explorar comandos

Ejecuta openai explore en tu terminal para explorar los comandos antes de configurar una clave de API. Escribe una tarea como count tokens offline para encontrar openai tokenizer count. Usa las teclas de flecha para resaltar un resultado. Presiona Enter para seleccionarlo o Escape para cancelar.

Explore muestra el comando seleccionado sin ejecutarlo. Si usas la integración con el shell, puedes editar el comando seleccionado en la línea de comandos. Ejecuta openai explore --help para consultar los shells compatibles y los atajos de teclado.

Autenticación

La CLI lee tu clave de API de la variable OPENAI_API_KEY:

Comando:

export OPENAI_API_KEY="sk-..."

Si aún no tienes una clave de API, crea una en el panel.

Para los puntos de acceso de la API de administración, configura OPENAI_ADMIN_KEY en su lugar. El SDK selecciona la clave de administración o la clave de API predeterminada según el punto de acceso que se invoque.

Para usar otro host de la API, configura OPENAI_BASE_URL.

Casos de uso

Usa la CLI para tareas que se prestan al trabajo en la terminal:

• Genera artefactos locales, como imágenes o archivos de voz.
• Extrae datos estructurados en formato JSONL para procesarlos después en el shell.
• Usa Responses en la nube para trabajar con archivos, usar la computadora y obtener contexto actualizado de la web.
• Crea proyectos y claves de API con las API de administración.

Usa la CLI directamente para hacer solicitudes puntuales desde la terminal o invócala desde scripts cuando los agentes necesiten repetir tareas por lotes con archivos y artefactos generados.

Cuándo usar la CLI o los subagentes en Codex

Usa la CLI para tareas repetibles de la API que quieras inspeccionar y volver a ejecutar, como extraer datos por lotes, transformar archivos, generar artefactos o seleccionar un modelo específico. Usa subagentes cuando la tarea aún requiera criterio, por ejemplo, para explorar código, comparar hipótesis, depurar o revisar cambios.

Opciones globales

Estas opciones se pueden usar con distintos comandos:

Esta guía se centra en las formas de usar la CLI. Para conocer los argumentos y la estructura de las respuestas más recientes de cualquier familia de API, consulta la referencia actualizada de la API.

También puedes cambiar la URL base si necesitas dirigir la CLI a otro punto de acceso compatible, como un despliegue que admita un conjunto distinto de modelos o solo algunas funciones de la API.

Responses

Usa Responses para generar texto, extraer datos estructurados, hacer búsquedas web, interpretar archivos y ejecutar de forma repetida scripts por lotes escritos por Codex.

Envía tu primera solicitud

Comando:

1
2
3openai responses create \
  --model gpt-6-astra \
  --input "Say hello in one sentence."

Salida:

123456789101112131415161718192021222324{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5-...",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6,
    "total_tokens": 18
  },
  "...": "additional response fields omitted"
}

De forma predeterminada, la CLI muestra el objeto de respuesta completo de la API. Los ejemplos de esta página incluyen campos representativos como id, status, model, output y usage, y omiten el resto.

La salida de Responses puede incluir elementos de otros tipos, como los de razonamiento, antes del mensaje del asistente. Si necesitas el texto del asistente, selecciona el elemento de tipo mensaje en lugar de dar por hecho que siempre está en output[0]:

--transform 'output.#(type=="message").content.0.text'

Agrega un archivo local al prompt

Para incluir un archivo local, construye el prompt en el propio comando mediante la sustitución de comandos:

1
2
3
4
5
6
7
8
9openai responses create \
  --model gpt-6-astra \
  --input "Summarize this note in one sentence.

<note>
$(cat ./note.md)
</note>" \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text'

Salida:

The note says the launch checklist is ready except for final support ownership.

Cómo pasar el cuerpo de una solicitud

Usa opciones de línea de comandos para valores escalares cortos. Usa un here-document en YAML para prompts de varias líneas, herramientas, archivos o cuerpos de solicitud con estructuras anidadas. El here-document puede contener los mismos campos de solicitud que pasarías como opciones.

Ten cuidado con las cadenas que parecen YAML, en especial los prompts que contienen : o {}. Si pasas esos valores como opciones, el analizador generado puede interpretarlos como YAML estructurado en lugar de texto plano. Si un prompt empieza a parecerse a una configuración, colócalo bajo input: | en el cuerpo de la solicitud en YAML:

Comando:

1
2
3
4
5
6
7
8
9
10
11
12
13openai responses create \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text' <<'YAML'
model: gpt-5.5
instructions: Return exactly one sentence.
max_output_tokens: 120
input: |
  Summarize this release note in one sentence.

  <release_note>
  Fixed the image generation example and added CLI installation guidance.
  </release_note>
YAML

Salida:

The release note updates the CLI docs with corrected image generation and installation guidance.

Si necesitas construir el prompt en el shell, prepara el cuerpo de la solicitud en YAML y pásalo al comando mediante una tubería:

1
2
3
4
5
6
7
8
9
10{
  printf 'input: |\n'
  printf '  Summarize this note in one sentence.\n\n'
  printf '  <note>\n'
  sed 's/^/  /' ./note.md
  printf '  </note>\n'
} | openai responses create \
  --model gpt-6-astra \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text'

Guarda datos estructurados en JSON

Usa resultados estructurados cuando los scripts que procesan la respuesta necesiten JSON con una estructura estable. Guarda en disco los esquemas que quieras reutilizar:

Guarda el esquema como schema.json:

1234567891011121314{
  "type": "json_schema",
  "name": "fact",
  "strict": true,
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "person": { "type": "string" },
      "topic": { "type": "string" }
    },
    "required": ["person", "topic"]
  }
}

Comando:

1
2
3
4
5
6
7openai responses create \
  --model gpt-6-astra \
  --instructions "Extract the person and topic from the input." \
  --input "Ada Lovelace wrote notes about the Analytical Engine." \
  --text.format "$(cat ./schema.json)" \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text'

Salida:

{ "person": "Ada Lovelace", "topic": "notes about the Analytical Engine" }

Guarda registros estructurados en JSONL

Si una sola entrada puede generar varios registros, pídele al modelo un arreglo y conviértelo a JSONL para que los pasos posteriores del shell puedan procesar un registro por línea:

Guarda el esquema como records-schema.json:

12345678910111213141516171819202122232425{
  "type": "json_schema",
  "name": "items",
  "strict": true,
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "title": { "type": "string" },
            "summary": { "type": "string" },
            "evidence": { "type": "string" }
          },
          "required": ["title", "summary", "evidence"]
        }
      }
    },
    "required": ["items"]
  }
}

Comando:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20: > records.jsonl

for file in notes/*.md; do
  extracted="$(
    openai responses create \
      --model gpt-5.5 \
      --text.format "$(cat ./records-schema.json)" \
      --raw-output \
      --transform 'output.#(type=="message").content.0.text' <<YAML
input: |
  <note path="$file">
$(sed 's/^/  /' "$file")
  </note>
YAML
  )"

  jq -r --arg source "$file" \
    '.items[]? + {source: $source} | @json' \
    <<<"$extracted" >> records.jsonl
done

Así se conserva la estructura de la respuesta del modelo y se genera un objeto JSON por línea para los pasos posteriores del shell.

Búsqueda web

Responses puede invocar herramientas alojadas desde el mismo cuerpo de solicitud en YAML:

Comando:

1
2
3
4
5
6
7
8
9
10openai responses create \
  --model gpt-6-astra \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text' <<'YAML'
tools:
  - type: web_search
input: |
  Research the latest material news for AAPL.
  Return three concise bullets and cite sources in the text.
YAML

Salida:

- Apple announced ...
- Analysts highlighted ...
- The company said ...

Archivos de entrada

Para usar un archivo que se carga en la API, como un PDF, primero crea el archivo en la API, obtén su ID y pásalo como input_file.file_id:

Comando:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20FILE_ID=$(
  openai files create \
    --file ./brief.pdf \
    --purpose user_data \
    --format yaml \
    --transform id
)

openai responses create \
  --model gpt-5.5 \
  --format yaml \
  --transform 'output.#(type=="message").content.0.text' <<YAML
input:
  - role: user
    content:
      - type: input_text
        text: Summarize this brief and list three risks.
      - type: input_file
        file_id: ${FILE_ID}
YAML

Salida:

- The brief proposes ...
- Risks: migration timing, unclear rollback criteria, and unresolved support ownership.

En las compilaciones generadas más recientes, los archivos locales que indicas mediante opciones se envían como partes de una solicitud multipart, con el nombre del archivo y el tipo de contenido como metadatos. Si el comando para cargar un archivo local falla con un error de tipo UploadFile, actualiza la CLI y vuelve a intentarlo.

Imágenes

Genera una imagen

Genera una imagen, extrae los datos en base64 y decodifícalos para guardarlos como un archivo de imagen:

Comando:

1
2
3
4
5
6openai images generate \
  --model gpt-image-2 \
  --prompt "A simple product-style render of a translucent green cube on a neutral background." \
  --format yaml \
  --transform 'data.0.b64_json' | base64 --decode > hero.png
printf 'wrote hero.png\n'

Salida:

wrote hero.png

Por el momento, los comandos de imágenes no admiten --output de forma nativa. Por eso, para la generación de imágenes todavía necesitas extraer b64_json y decodificar su contenido por tu cuenta.

Con gpt-image-2, omite --input-fidelity. Las imágenes de entrada siempre se procesan con alta fidelidad. Los fondos transparentes están disponibles en versión preliminar. Usa --background transparent con png (el formato predeterminado) o webp. El formato jpeg no admite fondos transparentes. El modelo también admite una gama más amplia de valores de --size que los modelos GPT Image anteriores, siempre que la resolución solicitada cumpla los requisitos de tamaño de la API de imágenes.

Edita una imagen

Cuando se completa correctamente la solicitud de edición, usa el mismo procedimiento para extraer los datos en base64:

Comando:

1
2
3
4
5
6
7openai images edit \
  --model gpt-image-2 \
  --image ./hero.png \
  --prompt "Turn the cube bright green." \
  --format yaml \
  --transform 'data.0.b64_json' | base64 --decode > hero-edited.png
printf 'wrote hero-edited.png\n'

Salida:

wrote hero-edited.png

Si la carga de una imagen local para editarla falla con un error de tipo UploadFile, actualiza la CLI y vuelve a intentarlo.

Voz

Crea un archivo MP3 local con la API de voz:

Comando:

1
2
3
4
5openai audio:speech create \
  --model gpt-4o-mini-tts \
  --voice marin \
  --input "The OpenAI CLI can call the API from ordinary shell scripts." \
  --output speech.mp3

Salida:

Wrote output to: speech.mp3

Reprodúcelo con la herramienta de audio que tengas disponible en tu equipo. En macOS:

afplay speech.mp3

Usa --instructions para indicar cómo debe sonar la voz y --input para especificar el texto que debe pronunciar. Puedes dar indicaciones sobre el ritmo, la energía, la calidez, el grado de formalidad, el énfasis o el público al que va dirigido el mensaje:

1
2
3
4
5
6openai audio:speech create \
  --model gpt-4o-mini-tts \
  --voice marin \
  --instructions "Whisper very quickly, like a hurried stage cue, while staying clear and intelligible." \
  --input "The launch checklist is ready. Please send final feedback by Friday at noon." \
  --output reminder.mp3

Transcripción

Obtén la transcripción en texto plano para usarla en tuberías del shell:

Comando:

1
2
3
4
5openai audio:transcriptions create \
  --model gpt-transcribe \
  --file ./speech.mp3 \
  --transform text \
  --raw-output

Salida:

The OpenAI CLI can call the API from ordinary shell scripts.

El ejemplo anterior usa el modelo recomendado para la transcripción de archivos. Los siguientes ejemplos especializados siguen disponibles para las integraciones existentes:

Para obtener las marcas de tiempo de cada palabra, solicita el formato de transcripción detallado:

Comando:

1
2
3
4
5
6openai audio:transcriptions create \
  --model whisper-1 \
  --file ./speech.mp3 \
  --response-format verbose_json \
  --timestamp-granularity word \
  --format json

Salida:

1234567891011{
  "task": "transcribe",
  "language": "english",
  "duration": 6,
  "text": "The OpenAI CLI can call the API from ordinary shell scripts.",
  "words": [
    { "word": "The", "start": 0, "end": 0.42 },
    { "word": "OpenAI", "start": 0.42, "end": 1.22 }
  ],
  "...": "additional response fields omitted"
}

Para obtener una salida con etiquetas de hablante, usa el modelo de diarización y solicita diarized_json:

Comando:

1
2
3
4
5openai audio:transcriptions create \
  --model gpt-4o-transcribe-diarize \
  --file ./speech.mp3 \
  --response-format diarized_json \
  --format json

Salida:

1234567891011121314{
  "text": "The OpenAI CLI can call the API from ordinary shell scripts.",
  "segments": [
    {
      "type": "transcript.text.segment",
      "id": "seg_0",
      "start": 0.05,
      "end": 5.25,
      "text": " The OpenAI CLI can call the API from ordinary shell scripts.",
      "speaker": "A"
    }
  ],
  "...": "additional response fields omitted"
}

whisper-1 admite json, text, srt, verbose_json y vtt. El formato diarized_json incluye el campo segments[].speaker. Si usas el mismo modelo de diarización con el formato json simple, la respuesta contiene el texto de la transcripción sin etiquetas de hablante.

API de administración

Usa las API de administración en flujos de trabajo de gestión de organizaciones, aprovisionamiento de credenciales, cumplimiento normativo y monitoreo del uso. Configura OPENAI_ADMIN_KEY y luego ejecuta los comandos admin:organization:* generados.

Para aprovisionar una nueva credencial de máquina, crea un proyecto, crea una cuenta de servicio dentro de ese proyecto y usa la clave de API que recibas.

Crea un proyecto, una cuenta de servicio y una clave de API

Al crear una cuenta de servicio en ese proyecto, recibes la clave de API completa de la cuenta.

Comando:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15# Create the project that will own this app or agent and save the response.
openai admin:organization:projects create \
  --name "automation project" \
  --format json > project.json
PROJECT_ID="$(jq -r '.id' project.json)"

# Create a service account inside the project and save the full response.
openai admin:organization:projects:service-accounts create \
  --project-id "$PROJECT_ID" \
  --name "automation bot" \
  --format json > service-account.json

# Extract the returned API key into an env file for the workload to use.
jq -r '.api_key.value | "OPENAI_API_KEY=\(.)"' \
  service-account.json > .env

Salida:

12345678910{
  "object": "organization.project.service_account",
  "id": "svc_acct_...",
  "name": "automation bot",
  "role": "member",
  "api_key": {
    "id": "key_...",
    "value": "sk-..."
  }
}

El ejemplo guarda la respuesta de creación del proyecto en project.json, extrae el ID para pasarlo al siguiente comando, guarda la respuesta de creación de la cuenta de servicio en service-account.json y escribe la credencial recibida en .env como OPENAI_API_KEY=.... Trata ambos archivos JSON como secretos y agrega project.json, service-account.json y .env a .gitignore antes de usar este procedimiento en un repositorio.

Para conocer las demás funciones, consulta la guía de las API de administración y la referencia actualizada de la API de administración. Ten cuidado al dar acceso a las claves de administración a personas o sistemas cuya confiabilidad no hayas verificado.