Manual de la CLI

📚 Navegación de la serie: El artículo anterior 07 · Funciones de la aplicación de escritorio detalló las capacidades de la interfaz gráfica (revisión de diffs, concurrencia de tareas y permisos visuales). En este capítulo analizamos la terminal para dominar el ejecutable codex: estructura de la línea de comandos, interfaz de usuario en terminal (TUI) y parámetros de ejecución. El próximo artículo 09 · Extensión de IDE (VS Code y otros) te guiará para integrar el agente en tu editor de código.

Suele decirse que «la interfaz gráfica es la opción más sencilla para principiantes, por lo que conviene evitar la terminal». Sin embargo, en el caso de Codex, esta afirmación solo es parcialmente correcta.

Habiendo utilizado ambas interfaces durante meses, mi conclusión es la siguiente: la aplicación de escritorio destaca para «supervisar» y la CLI destaca para «ejecutar». Si necesitas revisar visualmente una larga lista de cambios o comparar cinco tareas concurrentes en paralelo, la aplicación de escritorio es muy cómoda. Pero si tu objetivo es integrar Codex en tus flujos de automatización diarios (como programar un script para revisar commits, ejecutar el agente en un servidor remoto en la nube sin interfaz gráfica o integrarlo en tus pipelines de CI/CD), la aplicación de escritorio no lo permite y debes recurrir a la CLI.

Un detalle que suele sorprender: la terminal de la CLI no es una ventana de consola estática convencional. Al arrancar la CLI de Codex, el sistema abre una interfaz de usuario interactiva a pantalla completa en la propia terminal, conocida como TUI (Terminal User Interface). La TUI organiza la visualización en una zona de chat, un cuadro de entrada y una barra de estado, ofreciendo una densidad de información similar a la aplicación de escritorio, controlada enteramente con el teclado. Al abrirla por primera vez, verás que funciona como una aplicación integrada dentro de tu terminal.

Por ello, en este capítulo analizaremos las capacidades de la línea de comandos: desglosaremos la estructura del comando codex para que aprendas a usarla con soltura en tus tareas de desarrollo.

Al leer este artículo, obtendrás:

• El desglose de la estructura del comando codex indicando la posición de los subcomandos, opciones y prompts.
• La distribución de las tres secciones de la TUI interactiva (zona de chat, cuadro de entrada y barra de estado) y sus controles.
• Una tabla de referencia rápida de las opciones más utilizadas (--model, --sandbox, --cd, --search, -i, etc.) contrastada con la referencia oficial de la CLI.
• Comandos de barra diagonal y atajos de teclado esenciales para tu flujo diario, con un ejercicio práctico de verificación.
• La diferencia de uso entre el modo interactivo estándar y la ejecución directa en una línea con exec.

⚠️ Los comandos, opciones y comportamientos predeterminados descritos en este artículo corresponden a la documentación oficial de Codex. Los nombres de los modelos y las cuotas de uso se adaptan con las sucesivas versiones de la plataforma.

---

01 Estructura de la línea de comandos de Codex

Para quienes no acostumbran a usar la terminal, una secuencia de comandos larga con múltiples parámetros (como codex exec --sandbox workspace-write --model xxx "tarea") puede parecer compleja a primera vista.

Sin embargo, su estructura es muy consistente. Como regla general: el comando codex se compone de hasta cuatro secciones: comando principal, subcomando, opciones y prompt. Aprender a identificar estas secciones te permitirá interpretar cualquier comando fácilmente.

Analogía: Realizar un pedido personalizado en una cafetería. El comando principal codex equivale a entrar al local y pedir «un café». Definir si pides un «café americano» o un «café latte» equivale al subcomando (exec, resume, cloud, etc.), que define el tipo de preparación. Los parámetros adicionales como «poca temperatura, doble shot y leche de avena» corresponden a las opciones (los parámetros precedidos por --). Y el encargo final que le haces a la herramienta (como «revisa este fragmento de código») equivale al prompt. El orden de las secciones es fijo, aunque algunos componentes son opcionales.

La distribución de los parámetros sigue este esquema:

codex   [subcomando]   [opciones...]   ["prompt"]
  │         │               │              │
Comando   Modo de        Ajustes de     Tarea a
principal ejecución      parámetros     realizar

Detalle de cada sección:

• Comando principal codex: llama al ejecutable en tu sistema. Ejecutar codex a secas en la terminal abre la interfaz interactiva TUI.
• Subcomando: define la modalidad de ejecución. Por ejemplo, codex exec inicia una ejecución directa (aplica la instrucción y finaliza sin abrir la interfaz de chat), codex resume recupera la última sesión activa y codex login gestiona el inicio de sesión. Si se omite el subcomando, se inicia la TUI por defecto.
• Opciones (flags): parámetros con prefijos -- o - para modificar la ejecución. Por ejemplo, --model cambia el modelo activo, --sandbox altera las restricciones de permisos y --cd define el directorio de trabajo. La mayoría de las opciones cuenta con formato largo y abreviado (por ejemplo, -m es equivalente a --model).
• Prompt: la instrucción entre comillas con la tarea que deseas encomendar al agente. Es un parámetro opcional; si se omite, se abre la interfaz para introducir las instrucciones interactivamente; si se incluye, el agente procesará la instrucción al arrancar.

Ejemplos de uso comunes:

# Iniciar la interfaz interactiva TUI sin instrucciones previas
codex

# Iniciar la interfaz ejecutando una instrucción inicial
codex "Explica la estructura de este proyecto"

# Iniciar especificando el modelo y el directorio de trabajo
codex --model gpt-5.5 --cd ~/my-project "Completa la sección de instalación del README"

⚠️ El nombre del modelo gpt-5.5 se muestra como ejemplo. Los modelos recomendados y disponibles en tu cuenta cambian frecuentemente; ejecuta el comando /model en la interfaz interactiva para ver el listado actualizado.

Cualquier comando complejo que encuentres en la documentación se construye combinando estas cuatro secciones básicas.

💡 Resumen en una frase: La línea de comandos se organiza en: comando principal + subcomando (modalidad) + opciones (parámetros) + prompt (instrucción); identificar esta estructura facilita la interpretación de cualquier comando.

---

02 Distribución de la interfaz de usuario en terminal (TUI)

Al ejecutar codex en la terminal se abre la TUI a pantalla completa. A primera vista, la distribución de información puede desconcertar.

El espacio se organiza en tres áreas básicas: la zona de chat, el cuadro de entrada y la barra de estado. Las líneas de texto que se desplazan representan el informe de actividad del agente.

Analogía: Seguir una transmisión en streaming. La zona central es la pantalla del creador de contenido (la zona de chat, donde Codex muestra su plan de acción, fragmentos de código y el diff de cambios); la zona inferior es el chat de texto donde escribes tus comentarios (el cuadro de entrada, donde introduces tus instrucciones); y las líneas pequeñas de la barra inferior muestran los datos de la transmisión (la barra de estado, que indica el modelo activo, tokens consumidos y ruta de archivos).

Detalle de las tres áreas:

• Zona de chat (sección central principal): el área de trabajo del agente. Aquí Codex muestra la lógica que va a aplicar, los bloques de código editados y el Git diff de cambios, aplicando resaltado de colores en el código y en las diferencias para facilitar su lectura. Es la zona donde supervisas las modificaciones del agente.
• Cuadro de entrada (línea inferior): el canal de comunicación con Codex. Desde aquí escribes tus instrucciones, adjuntas rutas de archivos, referencias de imágenes o comandos de barra diagonal.
• Barra de estado (líneas de texto al pie del cuadro de entrada): detalla la información técnica de la sesión activa: modelo en uso, tokens de contexto consumidos, directorio de trabajo activo y la rama de Git del repositorio. El formato y la información de esta barra se pueden configurar con el comando /statusline.

Un error común de visualización que suele ocurrir a los principiantes: la pantalla de la terminal se desorganiza o muestra áreas vacías. Esto puede ocurrir al reanudar sesiones en gestores de terminales como tmux o tras microcortes de red en conexiones SSH, dando la impresión de que el proceso ha fallado. No cierres la sesión; pulsa Ctrl + L para forzar el redibujado de la interfaz gráfica; la sesión se actualizará sin perder el contexto acumulado de la conversación.

En conexiones SSH remotas propensas a la latencia de red, la interfaz puede desalinearse ocasionalmente; pulsar Ctrl + L reajustará el buffer de la terminal inmediatamente.

Diferencia importante entre comandos de limpieza en la CLI:

La tecla Ctrl + L redibuja el buffer visual de la terminal manteniendo el contexto de la conversación activo; por el contrario, el comando de barra diagonal /clear limpia la pantalla de la terminal y reinicia la sesión de chat por completo, vaciando el historial de contexto acumulado. Distingue ambos controles para no perder tu historial de forma accidental.

💡 Resumen en una frase: La TUI se organiza en zona de chat, cuadro de entrada de instrucciones y barra de estado de la sesión; si la interfaz se descompone visualmente, pulsa Ctrl + L para redibujarla sin perder tu historial de conversación.

---

03 Opciones indispensables para el uso diario

Las opciones (flags) permiten modificar el comportamiento de la CLI. De la lista de parámetros detallada en la referencia de la CLI (cli/reference), seleccionamos las ocho opciones recomendadas para tus tareas de desarrollo diario:

Opción (Largo / Corto)	Propósito técnico	Ejemplo de uso
--model / -m	Define el modelo de ejecución para la sesión activa	codex -m gpt-5.5 "Refactoriza el módulo"
--sandbox / -s	Define los límites del sandbox (read-only, workspace-write, danger-full-access)	codex -s read-only "Analiza este archivo"
--ask-for-approval / -a	Define la política de aprobación (untrusted, on-request, never)	codex -a on-request "Depura este test"
--cd / -C	Define el directorio de trabajo del agente	codex --cd ~/proyecto "Resume el estado"
--add-dir	Autoriza un directorio adicional para el sandbox (permite duplicar parámetro)	codex --cd app --add-dir ../shared
--image / -i	Adjunta una imagen o captura de pantalla al contexto de la instrucción	codex -i error.png "Corrige la interfaz"
--search	Fuerza la consulta de búsqueda web a tiempo real (omitiendo la caché de OpenAI)	codex --search "Usa la sintaxis de la versión reciente"
--oss	Desvía las consultas a modelos de código abierto locales (requiere instancia de Ollama)	codex --oss "Genera el script de pruebas"

Detalle sobre las opciones seleccionadas:

El parámetro --cd simplifica el acceso a tus directorios de trabajo. Te permite inicializar Codex apuntando directamente a la ruta del proyecto con codex --cd ~/ruta/proyecto "instrucción", sin necesidad de navegar previamente con cd en tu terminal. La barra de estado de la TUI confirmará la ruta activa al arrancar.

Los parámetros --sandbox y --ask-for-approval configuran el nivel de seguridad de la sesión. Como vimos en el capítulo 02, controlan respectivamente las restricciones del sistema de archivos y las confirmaciones previas del agente. La combinación recomendada por defecto es --sandbox workspace-write y --ask-for-approval on-request, que limita los cambios del agente a la carpeta de trabajo y solicita tu confirmación si intenta conectarse a internet o modificar archivos externos. Las particularidades de estas políticas se detallan en el capítulo 15.

El parámetro --search modifica el comportamiento de búsqueda en internet. Codex activa búsquedas web de forma predeterminada consultando un índice seguro mantenido por OpenAI para evitar inyecciones de código; incluir la opción --search desactiva este filtro de seguridad y realiza consultas en la web abierta en tiempo real. Trata la información recuperada de internet con precaución.

Parámetro de seguridad avanzado:

⚠️ La opción --dangerously-bypass-approvals-and-sandbox (abreviada como --yolo) desactiva por completo los límites del sandbox y las solicitudes de aprobación, permitiendo que Codex aplique cualquier cambio e invoque comandos directamente en tu máquina local sin pedir confirmación. Se aconseja utilizarla únicamente en entornos de desarrollo aislados (como contenedores). Evita su uso en tu sistema principal.

💡 Resumen en una frase: Familiarízate con las opciones más comunes: -m para cambiar de modelo, -s y -a para ajustar la seguridad, --cd para definir el directorio de trabajo, -i para adjuntar capturas y --search para búsquedas en tiempo real; evita el uso del parámetro --yolo por seguridad.

---

04 Comandos de barra diagonal en la terminal

Si necesitas realizar modificaciones de parámetros o consultas técnicas durante la sesión interactiva, puedes usar los comandos de barra diagonal (slash commands) escribiendo / en el cuadro de entrada de texto para desplegar el listado de opciones.

Analogía: Ajustar la configuración desde el menú del dispositivo. En lugar de reiniciar el terminal para cambiar un ajuste de la sesión, utilizas los comandos de barra diagonal para aplicar cambios sobre la conversación activa.

Selección de comandos de barra diagonal recomendados (puedes ver la lista completa en el menú de ayuda de la aplicación):

Comando	Propósito	Escenario de uso
/model	Muestra y permite cambiar el modelo activo de la sesión	Para alternar a modelos ligeros en tareas sencillas
/permissions	Permite alternar entre los perfiles de permisos (Auto, Read Only, Full Access)	Para bloquear la edición al analizar código
/status	Detalla la configuración activa y el consumo de tokens de la sesión	Para supervisar la cuota disponible en tareas grandes
/diff	Muestra las diferencias de Git de la sesión (incluyendo archivos sin seguimiento)	Para auditar las modificaciones antes de cerrar el chat
/compact	Resume el histórico de la conversación para liberar espacio en el contexto	Si el chat es muy extenso y consume muchos tokens
/review	Llama a un agente secundario para auditar los cambios propuestos	Para validar la calidad del código antes de integrarlo
/init	Genera la plantilla básica del archivo AGENTS.md en el directorio de trabajo	Para estructurar las directivas del proyecto
/clear	Limpia la pantalla y vacía el contexto acumulado para iniciar una sesión limpia	Para cambiar a una tarea diferente

Al ejecutar procesos extensos en segundo plano, puedes escribir la siguiente instrucción o comando de barra diagonal en el cuadro de entrada y pulsar la tecla Tab para añadirla a la cola de ejecución; Codex procesará la instrucción en cola automáticamente al finalizar la tarea activa.

Los detalles sobre los atajos avanzados, las configuraciones del archivo de comandos y el registro de comandos personalizados se describen en el capítulo 12.

💡 Resumen en una frase: Utiliza los comandos de barra diagonal en el chat para interactuar con la sesión: /model para alternar modelos, /permissions para ajustar la seguridad, /status para monitorizar la cuota de uso y /diff para revisar las modificaciones aplicadas.

---

05 Interacciones de teclado en la TUI

Además de los comandos /, la interfaz interactiva expone combinaciones de teclas para agilizar la interacción. Detallamos a continuación los atajos más habituales según la documentación de Codex:

Atajo de teclado	Acción en el sistema
Ctrl+C	Cancela la ejecución del proceso activo o cierra la sesión interactiva (equivalente a /exit)
Ctrl+L	Redibuja la interfaz visual de la TUI (conservando la sesión de chat activa)
↑ / ↓ (Flechas de dirección)	Permite navegar por el historial de instrucciones enviadas en la sesión
Ctrl+R	Abre el buscador del historial de instrucciones anteriores (Intro para confirmar, Esc para cancelar)
Ctrl+O	Copia la última respuesta de Codex al portapapeles (equivalente al comando /copy)
Tab	Añade la instrucción escrita a la cola de ejecución del agente
Pulsar dos veces Esc	Recupera el texto de la última instrucción en el cuadro de entrada para editarlo y volver a enviarlo
Ctrl+G	Abre el editor de texto del sistema para redactar prompts extensos y volcarlos en el chat

Herramientas útiles del cuadro de entrada:

El prefijo ! permite ejecutar comandos de terminal locales sin la intervención de Codex. Escribir el símbolo ! al inicio del cuadro de entrada (por ejemplo, !git status o !ls) ejecuta el comando directamente en tu terminal. El resultado de la ejecución se añade al contexto de la conversación de forma transparente, permitiendo que el agente interprete los datos resultantes; esta acción respeta las limitaciones del sandbox y las políticas de aprobación de la sesión.

!git status

El atajo Ctrl+G abre el editor de texto de tu sistema para redactar prompts complejos. Si necesitas describir instrucciones estructuradas en varias líneas, pulsa Ctrl+G para abrir el editor configurado en tu variable de entorno VISUAL o EDITOR (como vim o nano); escribe la instrucción, guarda y cierra el archivo, y el contenido se volcará directamente en el cuadro de entrada de la TUI.

El prefijo @ despliega un buscador de los archivos del espacio de trabajo; selecciona la ruta del archivo mediante las flechas de dirección y pulsa Tab para insertarla directamente en el chat, evitando errores de transcripción de nombres de archivos.

Si requieres personalizar los atajos de teclado de la TUI, puedes ejecutar el comando /keymap para consultar e importar nuevas asignaciones de teclas.

💡 Resumen en una frase: Optimiza tu interacción con el teclado: ejecuta comandos directos con !, añade archivos con @, redacta instrucciones extensas abriendo el editor con Ctrl+G y recupera el último mensaje pulsando dos veces la tecla Esc.

---

06 Ejercicio práctico con la CLI

A continuación se detalla un ejercicio práctico paso a paso para familiarizarse con los controles de la TUI en un directorio de pruebas vacío:

Requisitos previos: tener instalada la CLI de Codex y la sesión iniciada (ver proceso en el capítulo 03).

Paso 1: Crear la carpeta de pruebas y arrancar el agente

Ejecuta en tu terminal (en Windows con PowerShell, reemplaza mkdir -p por mkdir):

mkdir -p ~/codex-cli-demo && cd ~/codex-cli-demo
codex

Resultado esperado: se inicia la interfaz de la TUI en la terminal, mostrando el cuadro de entrada inferior y la información de estado de la sesión.

Paso 2: Consultar la configuración activa

En el cuadro de entrada, escribe y pulsa Intro:

/status

Resultado esperado: la TUI muestra el informe de la sesión, detallando el modelo asignado, la política de permisos activa, las carpetas con permisos de escritura y el consumo de tokens de contexto.

Para supervisar esta información, puedes integrar herramientas comunitarias de monitorización de tokens (como se muestra en el gráfico), que muestran el nombre del proyecto, el saldo de cuota de tokens restante en periodos de 5 horas y semanales, el porcentaje de contexto ocupado y el modelo en uso.

Paso 3: Ejecutar un comando local con el prefijo !

Escribe en el cuadro de entrada:

!echo prueba-de-consola

Resultado esperado: la terminal ejecuta el comando e imprime directamente el texto prueba-de-consola en la pantalla de chat, incorporando la salida al contexto del hilo.

Paso 4: Recuperar el comando del historial

Con el cuadro de entrada vacío, pulsa la flecha de dirección hacia arriba ↑.

Resultado esperado: el comando !echo prueba-de-consola se muestra en el cuadro de entrada para que puedas editarlo o volver a ejecutarlo. Borra el comando de la línea de entrada.

Paso 5: Modificar archivos y verificar el diff

Escribe en el chat la siguiente instrucción:

Crea un archivo llamado hi.txt que contenga la línea "hello from codex cli"

Si la política de permisos solicita confirmación, autorízala. A continuación, escribe:

/diff

Resultado esperado: Codex muestra el diff de cambios de Git correspondiente a la creación del archivo hi.txt en el espacio de trabajo.

Paso 6: Finalizar la sesión

/exit

Resultado esperado: se cierra la interfaz de la TUI y regresas a la terminal ordinaria de tu sistema. También puedes utilizar el atajo Ctrl+C para forzar el cierre.

Completar estos pasos te ayudará a asimilar las interacciones básicas en la interfaz en terminal.

💡 Resumen en una frase: Completa este flujo de prueba para asimilar el uso de la terminal interactiva: iniciar el agente → /status → comando local con ! → historial con ↑ → crear archivo y verificar con /diff → cerrar sesión con /exit.

---

07 Ejecución interactiva frente a la llamada directa con exec

Para finalizar, analizamos una de las características más importantes de la CLI: la ejecución directa de instrucciones sin abrir la interfaz de chat, utilizando el comando codex exec (abreviado como codex e).

La ejecución interactiva estándar (codex) es la adecuada para procesos de desarrollo y depuración que requieran interactuar y evaluar propuestas de cambios en el chat. Por el contrario, la ejecución directa con exec está pensada para automatizaciones y tareas repetitivas desatendidas (como programar tareas de revisión, analizar logs o generar documentación de forma periódica), donde pasas la instrucción como parámetro y la CLI procesa el cambio y finaliza la ejecución retornando los datos.

Analogía: Almorzar en el restaurante frente a pedir comida para llevar. El modo interactivo es como comer en el restaurante: te sientas en la mesa, te sirven los platos uno a uno e interactúas con el personal sobre el punto de la comida. El comando exec funciona como pedir comida para llevar: introduces tu requerimiento, el sistema cocina y empaqueta el pedido en segundo plano, y lo recibes directamente en la puerta (retorno de salida en la consola) sin haber entrado en la interfaz.

Ejemplo de ejecución directa con exec:

codex exec "Revisa las modificaciones recientes del proyecto e identifica posibles fallos"

El agente analizará el espacio de trabajo local, procesará la tarea y volcará el resultado directamente en la terminal como flujo de salida (stdout), finalizando el proceso sin abrir la interfaz interactiva.

Opciones comunes para el comando exec (detalladas en la referencia de la CLI):

Parámetro en exec	Propósito técnico
--model / -m	Especifica el modelo a utilizar para la ejecución de la tarea
--json	Muestra el log de ejecución y resultados en formato estructurado JSON
--output-last-message / -o	Guarda el contenido de la última respuesta del agente en el archivo indicado
--skip-git-repo-check	Permite ejecutar la instrucción en directorios locales que no estén inicializados en Git
--ephemeral	Evita almacenar el historial y los logs de la sesión en el registro de Codex

Diferencias entre ambas modalidades:

Criterio de uso	Ejecución interactiva (codex)	Ejecución directa (codex exec)
Comportamiento al finalizar	Mantiene abierta la interfaz TUI esperando nuevas instrucciones	Finaliza el proceso y regresa al prompt de la terminal
Escenario recomendado	Tareas de desarrollo de lógica complejas y depuración colaborativa	Integración en scripts locales, tareas de CI/CD y automatizaciones
Intervención del usuario	Requiere supervisar los pasos del agente de forma interactiva	Ejecución desatendida; el agente procesa el cambio de forma autónoma
Flujo de salida	Representación visual interactiva en la pantalla TUI	Redirección de datos a la salida estándar (stdout) o a archivos JSON
Caso típico	«Refactoricemos esta función y verifiquemos los cambios paso a paso»	«Genera la documentación de cambios del repositorio de esta semana»

Dado que el comando exec está diseñado para ejecuciones automatizadas desatendidas, se aconseja configurar la aprobación de seguridad en modo never (para evitar bloqueos interactivos) y definir con precisión las políticas del sandbox para proteger el sistema de archivos local. Las particularidades de la automatización e integración en CI/CD se detallan en los capítulos de integración avanzada.

💡 Resumen en una frase: La ejecución interactiva es adecuada para desarrollo interactivo y depuración colaborativa, mientras que la llamada directa con exec facilita automatizaciones y ejecuciones en scripts desatendidos al retornar la salida directamente en la consola.

---

08 Resumen

En este capítulo hemos analizado las capacidades de la CLI de Codex:

Acción	Comando / Control
Llamar al agente interactivo	Ejecutar codex en la terminal (puedes adjuntar la instrucción al arrancar)
Ajustar parámetros de inicio	Usar --model para el modelo, --sandbox para permisos y --cd para la ruta del proyecto
Adjuntar capturas de pantalla	Utilizar la opción --image / -i al iniciar
Menú de la sesión activa	Usar comandos de barra diagonal como /model, /status y /diff
Ejecutar comandos locales	Escribir el prefijo ! en el cuadro de entrada de la TUI
Visualización inestable	Pulsar Ctrl+L para redibujar la terminal sin perder la conversación
Redactar prompts complejos	Pulsar Ctrl+G para abrir el editor de texto del sistema
Ejecuciones en scripts	Utilizar el subcomando codex exec "instrucción" para retornos directos

Dominar el uso de la CLI de Codex te permitirá integrar el agente en tus flujos de trabajo de terminal habituales y diseñar automatizaciones de código complejas en entornos locales o servidores remotos.

El próximo capítulo 09 · Extensión de IDE (VS Code y otros) detallará el proceso para integrar a Codex directamente en tus editores de código y entornos de desarrollo (IDE) habituales como VS Code, facilitando la programación asistida sin necesidad de alternar ventanas de consola.

---

Lecturas recomendadas

• Uso de la terminal en Windows: configuración de terminal nativa o WSL
• Tabla de referencia rápida de comandos de Codex
• Instalación de dependencias y login