Gemini API CLI y Gemini CLI son herramientas diferentes. La primera, ejecutada mediante gemini-api, es un cliente de terminal sin estado de sesión local oculto. Google la lanzó en beta el 27 de octubre de 2026 para llamar a modelos y agentes gestionados de la API Gemini desde scripts, procesos de integración continua (CI) y otros agentes. La segunda, ejecutada mediante gemini, es un agente de programación que conversa con el usuario y puede trabajar con archivos y comandos de un proyecto. Para desarrollar de forma interactiva, Gemini CLI suele ser el punto de partida; para integrar llamadas concretas a la API en un flujo existente, conviene evaluar gemini-api.
CLI significa interfaz de línea de comandos: un programa controlado desde la terminal. Una API es una interfaz mediante la cual un software solicita funciones a otro. La similitud de los nombres no convierte la herramienta nueva en una actualización ni en un reemplazo directo de la anterior. Esta comparación es documental y se basa en fuentes oficiales consultadas el 29 de octubre de 2026; no se ejecutaron pruebas propias de las herramientas.
¿Qué se lanzó el 27 de octubre?
Las notas de cambios de la API Gemini identifican expresamente la beta de gemini-api en esa fecha. El cliente utiliza la Interactions API para generar texto y contenido multimedia, analizar documentos, transcribir archivos e iniciar agentes gestionados. Google lo describe como un binario independiente que no requiere añadir un SDK al proyecto. Un SDK es un conjunto de bibliotecas de desarrollo que se incorporan al código de una aplicación.
La expresión técnica clave es sin estado: una ejecución de gemini-api no conserva implícitamente una sesión local para el siguiente comando. Para enlazar tareas, quien crea el script debe pasar referencias como el identificador de una interacción anterior, una ruta de archivo o el identificador de un trabajo en segundo plano. Esto no significa que el servicio remoto nunca almacene datos. La Interactions API permite mantener estado en el servidor y, según su documentación, guarda solicitudes de forma predeterminada, con la opción store=false en los casos documentados.
Comparación práctica de las dos herramientas
| Criterio | Gemini API CLI (gemini-api) | Gemini CLI (gemini) |
|---|---|---|
| Función principal | Cliente para llamadas explícitas a modelos y agentes gestionados mediante API. | Agente de terminal para explorar, explicar y modificar proyectos con supervisión del usuario. |
| Uso habitual | Comandos independientes, archivos de salida y formatos estructurados para automatización. | Sesiones conversacionales con herramientas, permisos y contexto del proyecto. |
| Automatización | Diseñada para scripts y CI, con salida JSON, vista previa sin llamada de red y códigos de salida. | También incluye modo headless con -p y salida JSON; no se limita a sesiones interactivas. |
| Autenticación | La guía inicial se basa en una clave de la API Gemini mediante GEMINI_API_KEY o configuración de credenciales. | Admite inicio de sesión con Cuenta de Google, claves de la API Gemini y opciones Vertex AI según el caso. |
| Instalación documentada | Binarios para macOS, Linux y Windows; scripts de instalación y opción mediante Go. | Paquete @google/gemini-cli mediante npm y otros métodos documentados. |
| Estado de publicación | Beta, con advertencia oficial sobre posibles cambios incompatibles entre versiones menores. | Proyecto independiente con canales stable, preview y nightly. |
La diferencia, por tanto, no consiste en que una herramienta automatice y la otra no. Gemini CLI dispone de un modo no interactivo y puede ejecutarse en CI. gemini-api se distingue por ofrecer una interfaz ligera para operaciones específicas de la Interactions API que otros agentes y programas pueden controlar.
¿Cuándo conviene utilizar cada comando?
Para revisar un repositorio y acompañar cambios propuestos: la documentación de Gemini CLI muestra la instalación con npm install -g @google/gemini-cli y el inicio con gemini. El agente puede analizar código, proponer modificaciones y solicitar permisos para determinadas acciones. Para una tarea puntual sin interfaz interactiva, la documentación también muestra gemini -p "Explica este error".
Para llamar a la API desde otro agente o script: después de instalar el binario y configurar una clave de API con los permisos adecuados, la guía de la herramienta nueva muestra gemini-api generate "Resume este texto" y gemini-api analyze -i ./informe.pdf "Enumera los hallazgos". Son ejemplos de sintaxis basados en documentación, no resultados comprobados por DTech. El comando gemini-api generate "Prueba" --dry-run permite previsualizar y validar la solicitud localmente sin enviarla a la API.
Google documenta la salida estructurada con -o json, códigos de retorno para los errores y --stream=false cuando un proceso de generación debe devolver un único objeto JSON. Estas opciones resultan útiles cuando un programa necesita procesar la respuesta sin interpretar una conversación de terminal.
Autenticación, costes y migración: qué revisar
- Credenciales: gemini-api puede leer GEMINI_API_KEY del entorno o guardar la clave en el almacén seguro del sistema operativo. Nunca publiques claves en el código, registros o repositorios. Iniciar sesión con una Cuenta de Google en Gemini CLI no implica condiciones comerciales equivalentes a una clave de API.
- No hay sustitución directa de comandos: cambiar gemini por gemini-api en un script puede modificar argumentos, formatos de respuesta, tratamiento de errores, sesiones, permisos y facturación. Comprueba la compatibilidad en un entorno controlado antes de modificar procesos de producción. En CI, fija una versión de la beta en vez de depender automáticamente de la más reciente.
- Estado y privacidad: la ausencia de estado local oculto no excluye el almacenamiento en el servicio. Revisa la retención de la Interactions API, las políticas de datos aplicables y los archivos enviados, sobre todo si contienen información confidencial.
- Disponibilidad y límites: Google documenta instaladores o binarios para macOS, Linux y Windows, pero eso no equivale a pruebas propias en todas las versiones de esos sistemas. El cliente nuevo no ofrece conexiones WebSocket bidireccionales para voz y vídeo en directo; Google indica los SDK y la Live API para ese uso.
¿Funciona en Brasil y es gratuito?
Brasil figura en la lista oficial de regiones compatibles con la API Gemini y Google AI Studio. Esto confirma la elegibilidad regional de los servicios enumerados, no que la beta funcione en cualquier cuenta, equipo o configuración. El acceso efectivo también depende de la credencial, el proyecto, la función solicitada y los límites de la cuenta.
Instalar una CLI y pagar las solicitudes de API son cuestiones distintas. Google ofrece niveles gratuitos y de pago para determinados modelos y funciones de la API, sujetos a límites y precios cambiantes; no hay motivo para afirmar que todo uso de gemini-api sea gratuito. Gemini CLI también tiene cuotas, precios y condiciones de privacidad que dependen del método de autenticación. Una suscripción a una aplicación no implica que todas las llamadas mediante una clave de API estén incluidas.
Decisión práctica: elige Gemini CLI si quieres un agente que trabaje directamente en la terminal y en tu proyecto, incluso en modo headless. Elige Gemini API CLI cuando necesites llamadas explícitas a modelos, análisis de archivos, generación multimedia o agentes gestionados dentro de scripts y otros agentes. Como gemini-api sigue en beta, verifica comandos, formatos y acceso real antes de considerarla sustituta de un flujo existente.
