Gemini CLI: guía práctica del agente de IA en la terminal

Gemini CLI es el agente de IA open source de Google que vive en tu terminal: abres tu proyecto, corres gemini y le describes la tarea en lenguaje natural. El agente lee y edita archivos, ejecuta comandos de shell, consulta la web con grounding de Google Search y se extiende con servidores MCP. Está escrito en TypeScript, se distribuye por npm bajo licencia Apache 2.0 y corre sobre Node.js.

Si llegaste aquí después de leer la noticia de la migración hacia Antigravity CLI, el dato práctico es este: a septiembre de 2026 el repositorio google-gemini/gemini-cli sigue recibiendo commits diarios (v0.59.0-preview publicada a inicios de septiembre) y la documentación oficial sigue en línea. La transición existe, pero la herramienta no ha desaparecido, y miles de scripts y flujos de automatización siguen corriendo sobre ella. Esta guía cubre el flujo completo del hub Construir agentes: instalación, autenticación, uso interactivo y headless, configuración de proyecto, sandbox y un checklist para decidir si sigue siendo tu herramienta o toca evaluar la migración. Si ya usas otro agente de terminal, compáralo con Kimi Code CLI; y para que cualquier CLI respete las reglas de tu repo, combínalo con AGENTS.md.

Instalación: tres caminos

La vía rápida, sin instalar nada de forma permanente:

npx @google/gemini-cli

Para uso diario conviene una instalación global. Con npm:

npm install -g @google/gemini-cli

En macOS o Linux también existe por Homebrew:

brew install gemini-cli

El proyecto publica tres canales de release con cadencia semanal:

Canal	Tag	Cadencia	Para quién
Stable	@latest	Martes 20:00 UTC	Uso diario
Preview	@preview	Martes 23:59 UTC	Probar novedades antes que nadie
Nightly	@nightly	Diario 00:00 UTC	Validar regresiones, no producción

Para instalar un canal específico: npm install -g @google/gemini-cli@preview. El canal nightly asume validaciones pendientes: úsalo solo si reportas bugs o necesitas un fix que aún no salió.

Primer arranque y autenticación

Corre gemini dentro de tu proyecto y el asistente de primera vez te pedirá elegir método de autenticación. Hay tres, y la elección define tus límites:

Opción	Variable / acción	Free tier	Cuándo usarla
Sign in with Google	OAuth en el navegador	60 req/min y 1,000 req/día	Individual, sin gestionar API keys
Gemini API key	export GEMINI_API_KEY=...	1,000 req/día con Gemini 3	Control de modelo específico, scripts
Vertex AI	GOOGLE_API_KEY + GOOGLE_GENAI_USE_VERTEXAI=true	Según facturación	Empresas con Google Cloud

Con OAuth, el flujo abre el navegador, autorizas tu cuenta de Google y listo: sin llaves que rotar ni variables que exportar. Si tu organización tiene licencia paga de Gemini Code Assist, exporta además GOOGLE_CLOUD_PROJECT con el ID de proyecto antes de arrancar.

La vía por API key se saca de aistudio.google.com/apikey y es la indicada cuando necesitas fijar el modelo con -m o cuando el agente corre en un servidor donde no hay navegador para OAuth. La vía Vertex reutiliza la infraestructura y los límites de tu cuenta de Google Cloud existente.

Uso diario: interactivo vs headless

En modo interactivo, gemini abre una sesión de chat en la terminal. Los comandos con / controlan la sesión (/help, /chat, entre otros), @servidor invoca servidores MCP configurados, y puedes abarcar varios directorios con --include-directories ../lib,../docs. Para fijar un modelo concreto: gemini -m gemini-2.5-flash.

El segundo modo es el que convierte al CLI en pieza de automatización: headless. Se activa con -p (o --prompt), y también cuando el CLI detecta un entorno sin TTY:

gemini -p "Explica la arquitectura de este codebase"

Para scripts, el flag --output-format da salida estructurada. Con json recibes un único objeto con response, stats (tokens y latencia) y error opcional. Con stream-json recibes eventos JSONL línea por línea — init, message, tool_use, tool_result, error y result — ideal para monitorear operaciones largas mientras ocurren.

Los códigos de salida estándar son el contrato para tu CI o cron:

Exit code	Significado
0	Éxito
1	Error general o fallo de API
42	Error de entrada (prompt o argumentos inválidos)
53	Límite de turnos excedido

Regla práctica: en scripts, ramifica por exit code y parsea el JSON con tu lenguaje, nunca por la presencia de texto en stdout. Un 53 recurrente en tareas grandes es señal de que la tarea debe dividirse, no de que el modelo "falló".

Configura el proyecto: GEMINI.md, settings.json y MCP

Dos archivos definen el comportamiento del agente en tu repo. GEMINI.md (en la raíz o en subdirectorios) funciona como archivo de contexto persistente: convenciones del proyecto, comandos de build, qué no tocar. Es el equivalente directo de AGENTS.md en otros CLIs, y los dos pueden coexistir.

~/.gemini/settings.json guarda la configuración global: modelo por defecto, sandbox, y los servidores MCP que amplían las herramientas del agente. Configurado un servidor MCP (por ejemplo GitHub), lo invocas desde la sesión así:

> @github Lista mis pull requests abiertos
> @database Encuentra usuarios inactivos

Las extensiones empaquetan comandos y servidores MCP reutilizables para compartirlos con tu equipo o publicarlos.

Sandbox y permisos: dónde sí toca el shell

El agente ejecuta comandos de shell, y ahí vive el riesgo.

El flag -s (o --sandbox) activa aislamiento del sistema operativo; la variable GEMINI_SANDBOX hace lo mismo por sesión, y "tools": {"sandbox": true} en settings.json lo vuelve permanente:

export GEMINI_SANDBOX=docker
gemini -p "build the project"

Los métodos disponibles: Seatbelt (sandbox-exec, nativo de macOS), Docker o Podman (aislamiento completo multiplataforma: tu directorio actual se monta dentro del contenedor), Windows Native Sandbox, y en Linux runsc (gVisor) o LXC como opciones experimentales. Para scripts nocturnos sin supervisión, Docker es el método por defecto recomendable: el daño potencial queda encerrado en un contenedor desechable.

Complementa con la política de carpetas de confianza: el CLI pregunta antes de operar en un directorio nuevo y tú decides si ese repo merece ejecución con permisos completos.

Gemini CLI vs Antigravity CLI: qué hacer ahora

Con el anuncio de transición sobre la mesa, la decisión no es "migrar sí o no" a ciegas. Es un checklist corto:

1. Inventario: lista dónde usas Gemini CLI hoy — sesiones manuales, scripts con -p, GitHub Actions, cron jobs.
2. Valida cada caso: "el comando abre" no es validación. Corre tus flujos reales y compara salida y exit codes.
3. No migres scripts por pánico: el repo sigue activo y mantenido; un script con --output-format json que funciona hoy no se rompe solo.
4. Prueba el reemplazo en paralelo: si la transición avanza, valida Antigravity CLI con el mismo checklist antes de cortar.

Si el CLI solo te sirve para explorar código y responder dudas, la migración será tolerable. Si sostiene automatización de negocio, trata el cambio como una migración de dependencia más: con backlog, ventana y rollback.

FAQ

¿Gemini CLI sigue gratis? El README oficial documenta el free tier con cuenta personal de Google: 60 solicitudes por minuto y 1,000 por día, con acceso a los modelos Gemini 3 y ventana de contexto de 1M tokens. Los niveles pagos vía API key o Vertex levantan esos techos según facturación.

¿Necesito Node.js? Para las rutas npm y npx, sí (Node 18 o superior). Homebrew instala el binario y sus dependencias sin que gestiones Node; en entornos restringidos existe la vía con Anaconda.

¿Cómo lo uso en CI? Autenticación por API key (OAuth no cabe en un runner sin navegador), -p con prompt cerrado, --output-format json para parsear el resultado y manejo explícito de exit codes 1, 42 y 53. Añade timeout en el job: un agente que cuelga no debe tumbar tu pipeline completo.

Checklist final

• Instalación global con @latest (o @preview si reportas bugs upstream).
• OAuth para uso personal; API key para scripts y CI; Vertex si ya vives en Google Cloud.
• GEMINI.md con las reglas del repo antes del primer prompt serio.
• Sandbox activo (GEMINI_SANDBOX=docker) para ejecuciones no supervisadas.
• Scripts con --output-format json y ramificación por exit code.
• Inventario de flujos que dependen del CLI, por si la migración a Antigravity avanza.