Gemini CLI: MCP nativo, modo headless y su ruta hacia Antigravity CLI

Gemini CLI es el agente de código abierto (licencia Apache 2.0) que Google publicó para trabajar desde la terminal con un bucle ReAct, hasta 1 millón de tokens de contexto y soporte nativo para MCP (Model Context Protocol). Esa definición sigue siendo exacta en agosto de 2026, pero conviven con ella dos hechos que conviene conocer antes de instalarlo: el repositorio sigue publicando builds nightly a diario (la más reciente en el momento de escribir esto, v0.56.0-nightly.20260810), y Google ya anunció en mayo que lo sustituye por Antigravity CLI. La documentación oficial de cuotas, con fecha de última actualización el propio 18 de junio de 2026 (el día en que se cumplía el plazo del anuncio), sigue publicando límites de tier gratuito activos. Esta referencia parte de esa tensión: qué sigue funcionando hoy, cómo configurarlo y qué vigilar si tu flujo depende de que siga vivo.

Qué es Gemini CLI y qué cambia con la llegada de Antigravity CLI

Gemini CLI ejecuta un bucle de razonar-actuar: recibe un objetivo, decide qué herramienta usar (archivos, shell, búsqueda web, servidores MCP), ejecuta la acción y evalúa el resultado antes de continuar, de forma autónoma y sobre tu entorno local, no solo como un chat. El repositorio acumulaba más de 100.000 estrellas en GitHub y 6.000 pull requests fusionados cuando Google anunció, el 19 de mayo de 2026, que iba a concentrar su desarrollo de agentes de terminal en un único producto: Antigravity CLI, un binario cerrado escrito en Go (comando agy) que comparte el mismo motor que la aplicación de escritorio Antigravity 2.0.

El propio anuncio fija una fecha de corte concreta: a partir del 18 de junio de 2026, Gemini CLI y las extensiones de Gemini Code Assist para IDE dejarían de dar servicio a las cuentas de Google AI Pro, Google AI Ultra y a quienes lo usaban gratis vía "Gemini Code Assist para particulares". Las licencias Gemini Code Assist Standard o Enterprise de una organización quedan explícitamente fuera del corte. Dicho esto, la página de planes sigue mostrando hoy el aviso ("Unpaid tier and Google One users: Gemini CLI will be replaced by Antigravity CLI on June 18th") junto a una tabla de planes que sigue incluyendo la opción gratuita, y la página de cuotas fechada exactamente ese 18 de junio detalla límites que siguen activos. En la práctica, quién puede seguir usando gemini hoy depende de cómo te autentiques:

Si vas a depender de Gemini CLI en un flujo que no puedes revisar cada semana, la recomendación honesta es comprobar la página de cuotas antes de cada actualización de dependencias: es la fuente que cambia más rápido que cualquier artículo.

Instalación y primeros pasos

La instalación no ha cambiado: requiere Node.js y admite varios gestores de paquetes.

# Ejecutar sin instalación permanente
npx @google/gemini-cli

# Instalación global con npm
npm install -g @google/gemini-cli

# macOS/Linux con Homebrew
brew install gemini-cli

# Entornos restringidos, vía conda
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

Al arrancar con gemini, el CLI pide autenticarte. Si tienes una API key de Google AI Studio, sáltate el flujo OAuth:

export GEMINI_API_KEY="tu-api-key-de-ai-studio"
gemini

# Elegir modelo explícitamente
gemini -m gemini-2.5-flash

Con 1 millón de tokens de contexto, el CLI puede cargar proyectos de cientos de archivos sin truncar el historial, lo que es una ventaja real frente a agentes con ventanas de 200K tokens cuando la tarea es analizar un repositorio completo en lugar de escribir código nuevo.

GEMINI.md: contexto persistente y jerárquico

Gemini CLI carga contexto de proyecto desde archivos GEMINI.md, el equivalente directo al CLAUDE.md de Claude Code. La carga es jerárquica en tres niveles, no solo en el directorio desde el que lanzas el CLI: primero ~/.gemini/GEMINI.md (contexto global para todos tus proyectos), después los archivos que encuentra en el directorio de trabajo configurado y en sus directorios padre (contexto de proyecto), y por último archivos GEMINI.md específicos de un subdirectorio cuando una herramienta accede a rutas dentro de él (contexto de componente). El CLI concatena todo lo que encuentra y lo antepone a cada prompt.

# GEMINI.md (raíz del proyecto)

## Stack
- Backend: FastAPI 0.115 + Python 3.12
- Base de datos: PostgreSQL 16 con pgvector
- Tests: pytest con fixtures async

## Convenciones
- Imports: stdlib > third-party > local
- Commits: Conventional Commits en inglés
- Docstrings: Google style, solo en funciones públicas

## Restricciones
- No generar código sin type hints
- Usar variables de entorno para configuración sensible

Puedes modularizar el contexto importando otros archivos con la sintaxis @ruta/al/archivo.md, e inspeccionar exactamente qué se cargó (útil cuando algo no se comporta como esperas) con /memory show; /memory reload lo recarga sin reiniciar la sesión. El pie del CLI muestra cuántos archivos de contexto están activos, una señal visual rápida de que el archivo se cargó de verdad.

Configurar servidores MCP: transportes, sanitización y un ejemplo real

MCP es lo que convierte a Gemini CLI de un agente que solo ve tu disco local a un agente conectado a servicios externos. La configuración vive en ~/.gemini/settings.json (global) o .gemini/settings.json (proyecto), y Gemini CLI soporta tres mecanismos de transporte: Stdio (arranca un subproceso y habla por stdin/stdout, el más común para servidores locales), SSE (Server-Sent Events, para servidores remotos) y Streamable HTTP (streaming sobre HTTP).

Un ejemplo con el servidor MCP oficial de GitHub, usando exactamente la forma que documenta Google hoy:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

Con eso activo, puedes invocar el servidor por nombre dentro de una sesión:

> @github Lista los PRs abiertos del repositorio mi-org/mi-api
> @github Crea un issue con el título "Refactorizar módulo auth"

Tres detalles de seguridad que evitan errores silenciosos al configurar MCP:

• El CLI expande variables de entorno con sintaxis POSIX ($VAR o ${VAR}, en cualquier plataforma) o con sintaxis Windows (%VAR%, solo en Windows) dentro del bloque env, así que nunca hace falta escribir un secreto en claro en settings.json.
• Por defecto, el CLI redacta del entorno base cualquier variable que coincida con los patrones *TOKEN*, *SECRET*, *PASSWORD*, *KEY*, *AUTH* o *CREDENTIAL*, además de claves propias como GEMINI_API_KEY o GOOGLE_API_KEY, antes de lanzar el proceso del servidor MCP. Esto evita que un servidor de terceros lea por accidente credenciales de tu shell.
• Si el servidor necesita una de esas variables, tienes que declararla explícitamente en su bloque env: una vez declarada así, se considera consentimiento informado y no se redacta. Para servidores remotos por SSE o HTTP, el CLI soporta además OAuth 2.0.

Para verificar qué servidores están conectados y qué herramientas exponen, usa /mcp dentro de una sesión; en caso de conflicto de nombres entre dos servidores, la herramienta duplicada recibe el prefijo nombreServidor__nombreHerramienta.

Hooks: interceptar el bucle agéntico sin tocar el código del CLI

Los hooks son scripts que Gemini CLI ejecuta en puntos concretos del bucle agéntico, y corren de forma síncrona: cuando se dispara un evento, el CLI espera a que terminen todos los hooks que aplican antes de seguir. Sirven para inyectar contexto, bloquear una acción peligrosa antes de que se ejecute, forzar reintentos o registrar cada interacción para auditoría. Los eventos más usados:

Se configuran en settings.json, con precedencia de proyecto (.gemini/settings.json) sobre usuario (~/.gemini/settings.json) sobre sistema:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

La regla de oro de los hooks es estricta: el script se comunica por stdin/stdout, y stdout no puede contener nada que no sea el JSON final; un simple echo de depuración antes del JSON rompe el parseo y el CLI cae por defecto a "permitir" tratando toda la salida como un mensaje de sistema. Para depurar, usa stderr (echo "debug" >&2), que el CLI captura pero nunca intenta parsear como JSON. El código de salida 0 es el correcto incluso para bloqueos intencionados (con {"decision": "deny"} en el JSON); el código 2 fuerza un bloqueo crítico usando stderr como motivo. Gestiona los hooks activos con /hooks dentro de una sesión, sin editar JSON a mano.

Modo headless para scripts y CI/CD

El modo headless se activa automáticamente cuando el CLI corre en un entorno sin TTY, o de forma explícita con el flag -p (o --prompt):

# Respuesta de texto simple
gemini -p "Explica la arquitectura de este repositorio"

# Salida estructurada para parsear en un script
gemini -p "Resume los cambios del último commit" --output-format json

# Streaming de eventos NDJSON para monitorizar tareas largas
gemini -p "Ejecuta los tests y despliega" --output-format stream-json

En modo json, la respuesta trae el texto final más estadísticas de uso; en stream-json obtienes eventos init, message, tool_use, tool_result, error y un result final con el desglose de tokens por modelo. Los códigos de salida son explícitos: 0 éxito, 1 error general o fallo de API, 42 prompt o argumentos inválidos, 53 límite de turnos superado. En CI, la autenticación se hace con variables de entorno en vez de OAuth interactivo (que necesita un navegador que no existe en el runner):

# GitHub Actions
- name: Analizar tests con Gemini CLI
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
  run: |
    npx @google/gemini-cli -p "Revisa los tests fallidos y sugiere correcciones"       --output-format json > analysis.json

Gemini CLI, Claude Code y Antigravity CLI: cuándo usar cada uno

Con Antigravity CLI ya disponible para todo el mundo desde el anuncio de mayo, la pregunta ya no es solo "Gemini CLI o Claude Code", sino cuál de los tres conviene según el flujo:

Si ya tienes servidores MCP configurados para Claude Code, son interoperables sin cambios: el protocolo es el mismo, solo cambia la ruta del archivo de settings. Si tu prioridad es que el flujo siga funcionando sin sorpresas en los próximos meses y no dependes de una licencia Code Assist de empresa, Antigravity CLI es la vía que Google sostiene activamente; Gemini CLI, con nightly builds a diario pero con su tier de consumo bajo aviso de cierre, es razonable para probar hoy pero no para construir una dependencia de producción nueva sobre él.

Casos borde y errores que vas a encontrar

El servidor MCP no responde al iniciar sesión. Causa: el binario no está instalado o no está en el PATH. Verifica con which npx o which uvx según el transporte, y ejecuta /mcp para ver el estado real de la conexión; /mcp reload fuerza una reconexión.

Una variable de entorno no llega al servidor MCP. Causa: el CLI la redactó por coincidir con un patrón sensible. Declárala explícitamente en el bloque env del servidor con la sintaxis "MI_VAR": "$MI_VAR"; las variables declaradas así no se filtran.

HTTP 429 (rate limit) usando la cuenta personal. Causa: el tier gratuito vía Code Assist individual tiene un límite diario que, según el momento del anuncio de Antigravity, puede reducirse o retirarse sin previo aviso adicional. Revisa la página de cuotas antes de asumir que el límite de hoy seguirá vigente el mes que viene; si necesitas continuidad, pasa a una API key de pago o a Vertex AI.

GEMINI.md no se carga. Causa habitual: el archivo no está en ninguno de los tres niveles jerárquicos (global, proyecto o componente) desde donde el CLI resuelve rutas. Ejecuta /memory show para ver exactamente qué se concatenó; en Linux el nombre del archivo es sensible a mayúsculas.

Un hook no hace nada, o el CLI ignora el bloqueo esperado. Causa casi siempre: el script imprimió algo en stdout antes del JSON de respuesta. Mueve cualquier echo de depuración a stderr y confirma que el hook está habilitado con /hooks.

"Authentication required" en modo headless. Causa: el flujo OAuth necesita un navegador que no existe en un runner de CI o un contenedor sin interfaz. Usa GEMINI_API_KEY como variable de entorno; no intentes autenticación interactiva en un entorno sin pantalla.