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

O instálala con Go 1.25 o posterior:

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

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

Autenticación

La CLI lee tu clave de API de 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. La capa del SDK selecciona la clave de administración o la clave de API predeterminada según el punto de acceso al que se llame.

Para usar otro host de la API, configura OPENAI_BASE_URL.

Casos de uso

Usa la CLI cuando la terminal sea el lugar más adecuado para el trabajo:

• Genera artefactos locales, como imágenes o voz.
• Extrae datos estructurados en JSONL para los pasos posteriores en shell.
• Usa Responses con archivos, uso de la computadora y contexto web actualizado en la nube.
• Crea proyectos y claves de API con las API de administración.

Úsala directamente para solicitudes puntuales en la terminal, o desde scripts cuando los agentes necesiten realizar tareas repetibles por lotes con archivos y artefactos generados.

CLI frente a subagentes para Codex

Usa la CLI para tareas repetibles con la API que quieras inspeccionar y volver a ejecutar, como la extracción por lotes, la transformación de archivos, la generación de artefactos o la selección deliberada de modelos. Usa subagentes cuando el trabajo aún requiera criterio, como explorar código, comparar hipótesis, depurar o revisar cambios.

Flags globales

Estas opciones funcionan en todos los comandos:

Esta guía se centra en patrones de uso de la CLI. Para consultar los argumentos y las estructuras de respuesta más recientes de cualquier familia de API, usa la referencia de la API en línea.

También puedes cambiar la URL base cuando necesites que la CLI use otro punto de acceso compatible, como un despliegue que admita un conjunto diferente de modelos o solo un subconjunto de las funciones de la API.

Responses

Usa Responses para la generación de texto, la extracción estructurada, la búsqueda web, la comprensión de archivos y los scripts de procesamiento por lotes creados por Codex que puedas volver a ejecutar.

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 completo de respuesta de la API. Los ejemplos de esta página conservan campos representativos como id, status, model, output y usage, y omiten el resto.

La salida de Responses puede incluir elementos que no son mensajes, como elementos de razonamiento, antes del mensaje del asistente. Cuando necesites el texto del asistente, selecciona el elemento de mensaje por su tipo en lugar de suponer que siempre es output[0]:

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

Agrega un archivo local al prompt

Para un archivo local sencillo, construye el prompt en la misma línea mediante 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.

Pasar cuerpos de solicitud

Usa flags para entradas escalares cortas. Usa un heredoc de YAML para prompts de varias líneas, herramientas, archivos o cuerpos de solicitud anidados. El heredoc puede contener los mismos campos de solicitud que, de otro modo, pasarías como flags.

Ten cuidado con los valores de cadena que parezcan YAML, especialmente los prompts que contengan : o {}. En los flags, el analizador generado puede interpretar esos valores como YAML estructurado en lugar de texto sin formato. Si un prompt empieza a parecer una configuración, colócalo bajo input: | en un cuerpo 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.

Cuando necesites construir el propio prompt en shell, crea un cuerpo 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'

Escribe datos estructurados en JSON

Usa resultados estructurados cuando los scripts posteriores necesiten JSON con una estructura estable. Guarda los esquemas reutilizables en disco:

Guarda 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" }

Escribe registros estructurados en JSONL

Cuando una entrada pueda producir muchos registros, pídele al modelo un arreglo y conviértelo a JSONL para que los pasos posteriores en la shell puedan procesar un registro por línea:

Guarda 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

Esto mantiene estructurada la respuesta del modelo y produce un objeto JSON por línea para los pasos posteriores en la shell.

Búsqueda web

Responses puede llamar a 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 los archivos cargados, como los PDF, primero crea el archivo, 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.

Las compilaciones generadas más recientes envían los archivos locales especificados mediante flags como partes de archivo en solicitudes multipart, con metadatos de nombre de archivo y tipo de contenido. Si un comando de carga local falla con un error de tipo UploadFile, actualiza la CLI y vuelve a intentarlo.

Imágenes

Generar una imagen

Genera una imagen, extrae los datos en base64 y decodifícalos para obtener un archivo de recurso normal:

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

Limitación actual: los comandos de imágenes aún no admiten --output de forma nativa, por lo que la generación de imágenes todavía requiere que extraigas b64_json y lo decodifiques por tu cuenta.

Para 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. 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 con las restricciones de tamaño de la API de imágenes.

Editar una imagen

La edición de imágenes usa el mismo patrón de extracción de base64 una vez que la solicitud de edición se completa correctamente:

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 MP3 localmente 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 cualquier herramienta de audio local disponible en tu equipo. En macOS:

afplay speech.mp3

Usa --instructions para definir la forma de hablar y --input para las palabras que se deben pronunciar. Las instrucciones funcionan bien para indicar el ritmo, la energía, la calidez, la formalidad, el énfasis o el público al que se dirige:

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

Imprime la transcripción en texto sin formato para usarla en pipelines de shell:

Comando:

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

Salida:

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

Usa el formato de respuesta que corresponda al artefacto que necesitas:

Para obtener los tiempos de cada palabra, solicita el formato detallado de transcripción:

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. diarized_json es el formato que incluye segments[].speaker; con el mismo modelo de diarización y el formato json básico, la respuesta contiene el texto de la transcripción, pero no las etiquetas de hablante.

API de administración

Usa las API de administración para los flujos de trabajo de gestión de organizaciones, aprovisionamiento de credenciales, cumplimiento 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 devuelta.

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

Al crear una cuenta de servicio en ese proyecto, se devuelve una clave de API sin ocultar para esa 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-..."
  }
}

Esto escribe la respuesta del proyecto en project.json, extrae su ID para pasarlo al siguiente comando, escribe la respuesta de la cuenta de servicio en service-account.json y escribe la credencial devuelta 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 patrón en un repositorio.

Para conocer las demás funciones, consulta la guía de las API de administración y la referencia de la API de administración actual. Ten cuidado al dar acceso a las claves de administración a actores no verificados.