Image for post Gemini CLI: Guía Práctica del Agente de Terminal de Google

Gemini CLI: Guía Práctica del Agente de Terminal de Google

Escrito por Sergio Márquez

Gemini CLI es el agente IA open source de Google que funciona directamente en tu terminal. Soporta MCP (Model Context Protocol) de forma nativa, ofrece un contexto de 1 millón de tokens y permite 1.000 peticiones diarias gratis con una cuenta de Google. Esta guía cubre la instalación, configuración de MCP, modo headless para CI/CD y una comparativa con Claude Code y Codex CLI para que sepas dónde encaja en tu flujo de trabajo.

¿Qué es Gemini CLI?

Gemini CLI es un agente IA open source (Apache 2.0) de Google que se ejecuta en tu terminal y utiliza un bucle ReAct (reason and act) para completar tareas de desarrollo: editar archivos, ejecutar comandos, buscar en la web y conectarse a servicios externos mediante MCP. No es solo un chat con un modelo, es un agente con herramientas que opera sobre tu entorno local.

Si vienes del mundo de los agentes IA y su diferencia con un prompt simple, Gemini CLI es un ejemplo concreto: recibe un objetivo, razona sobre los pasos necesarios, ejecuta acciones con herramientas y ajusta su plan en función del resultado.

El repositorio acumula 98.000 estrellas en GitHub en menos de un año, con releases estables cada martes y un ciclo de preview y nightly para quien quiera probar las novedades antes.

Instalación y Primeros Pasos

La instalación se hace con npm. Si no quieres instalarlo globalmente, puedes ejecutarlo directamente con npx:

# Ejecución directa (sin instalación global)
npx @google/gemini-cli

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

# Alternativa con Homebrew (macOS/Linux)
brew install gemini-cli

La primera vez que lo ejecutes, se abrirá un flujo de autenticación con tu cuenta de Google. Con una cuenta personal ya tienes acceso al tier gratuito: 60 peticiones por minuto y 1.000 al día usando Gemini 3 Pro. Si necesitas más capacidad, puedes configurar una API key de Google AI Studio o Vertex AI.

# Autenticación con API key (alternativa a OAuth)
export GOOGLE_API_KEY="tu-api-key-de-ai-studio"
gemini

Una vez dentro, el agente puede leer tus archivos, ejecutar comandos de shell (con tu aprobación) y navegar por tu proyecto. El contexto de 1 millón de tokens significa que puede cargar proyectos de 200+ archivos sin perder el hilo.

GEMINI.md: Contexto Persistente por Proyecto

Igual que Claude Code usa CLAUDE.md para instrucciones persistentes, Gemini CLI carga archivos GEMINI.md de forma jerárquica. Si has trabajado con Cursor Rules para configurar el agente según tu codebase, el concepto es el mismo: definir contexto que el modelo recibe en cada interacción sin tener que repetirlo.

Los archivos se cargan en tres niveles:

  • Global: ~/.gemini/GEMINI.md aplica a todos los proyectos.
  • Proyecto: GEMINI.md en la raíz del repositorio (y directorios padre hasta .git).
  • Componente: archivos GEMINI.md en subdirectorios, hasta 200 directorios por defecto.
# 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 @path/to/file.md. En sesión, los comandos /memory show y /memory reload permiten inspeccionar y recargar el contexto sin reiniciar.

Configurar MCP en Gemini CLI

MCP (Model Context Protocol) es lo que convierte a Gemini CLI de un agente local a un agente conectado a servicios externos. La configuración vive en ~/.gemini/settings.json (global) o .gemini/settings.json (proyecto).

Gemini CLI soporta tres tipos de transporte para MCP:

PropiedadTransporteCaso de uso
commandStdioServidores locales, scripts Python/Node
urlSSEServidores remotos con Server-Sent Events
httpUrlHTTP StreamingAPIs REST con streaming

Ejemplo: conectar el servidor MCP de GitHub

Un caso de uso frecuente es conectar Gemini CLI a GitHub para gestionar issues y PRs directamente desde la terminal:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      },
      "timeout": 30000
    }
  }
}

Una vez configurado, puedes hablar con GitHub desde Gemini CLI:

# Dentro de una sesión de Gemini CLI
> @github Lista los PRs abiertos del repositorio mi-proyecto
> @github Crea un issue con el título "Refactorizar módulo auth"

También puedes añadir servidores MCP sin editar JSON directamente:

# Añadir servidor MCP via CLI
gemini mcp add github docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server \
  --scope project

# Listar servidores configurados
gemini mcp list

Seguridad en MCP

Gemini CLI sanitiza las variables de entorno antes de pasarlas a los servidores MCP. Por defecto, redacta cualquier variable que coincida con patrones como *TOKEN*, *SECRET*, *PASSWORD* o *KEY*. Esto evita que un servidor MCP de terceros tenga acceso accidental a tus credenciales. Si necesitas pasar una variable específica, la declaras en el campo env del servidor.

Si estás combinando Gemini CLI con otros agentes de terminal, en Multi-CLI MCP cubrimos cómo orquestar Claude, Codex y Gemini compartiendo servidores MCP.

Modo Headless: Gemini CLI en CI/CD

El modo headless permite ejecutar Gemini CLI de forma no interactiva, lo que lo hace apto para scripts y pipelines de CI/CD. Se activa con el flag -p:

# Ejecución no interactiva básica
gemini -p "Analiza los tests que fallan en test_auth.py y sugiere un fix"

# Con formato JSON para parsear el resultado
gemini -p "Resume los cambios del último commit" \
  --non-interactive \
  --output-format json

# En un pipeline de CI, con auto-aprobación de herramientas
# (SOLO en entornos aislados y de confianza)
gemini -p "Ejecuta pytest y analiza los fallos" \
  --non-interactive \
  --yolo \
  --output-format json

La autenticación en CI/CD se hace con variables de entorno en lugar de OAuth interactivo:

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

El flag --session-summary genera un JSON con métricas de ejecución (tokens consumidos, coste estimado, tiempo de respuesta), lo que permite monitorizar el uso en pipelines automatizados.

Gemini CLI vs Claude Code vs Codex CLI

Si ya has leído la guía para elegir entre Claude Code, Cursor y Copilot, esta comparativa se centra en los tres agentes que operan exclusivamente en terminal.

CaracterísticaGemini CLIClaude CodeCodex CLI
ModeloGemini 3 ProClaude Opus 4.6GPT-5.3 Codex
Contexto1M tokens200K tokens192K tokens
Tier gratuito1.000 req/díaNoCon ChatGPT Plus
Precio mínimo0 (gratis)20 $/mes (Pro)20 $/mes (Plus)
LicenciaApache 2.0PropietariaOpen source (Rust)
MCPNativo (3 transportes)NativoNativo
SandboxConfigurablePermisos por nivelSandbox OS por defecto
Modo headlessSí (JSON/JSONL)Sí (JSON)Sí
Contexto proyectoGEMINI.mdCLAUDE.mdAGENTS.md

La ventaja principal de Gemini CLI es la combinación de tier gratuito generoso y contexto de 1M tokens. Para proyectos con bases de código grandes donde necesitas que el agente entienda la estructura completa, esa ventana de contexto marca diferencia. Claude Code sigue siendo el referente en calidad de código generado y en tareas agénticas complejas de múltiples pasos. Codex CLI destaca en seguridad con su sandbox a nivel de sistema operativo.

En la práctica, el consumo de tokens en agentes de terminal es un factor que condiciona la elección. El caching automático de Gemini CLI ayuda, pero en sesiones largas con código denso, los tokens se acumulan igual.

En Producción

El tier gratuito de Gemini CLI es viable para uso personal y prototipos, pero tiene limitaciones que importan en producción:

  • Límites de rate: 60 req/min y 1.000 req/día con cuenta personal. Para equipos de 5+ personas o pipelines de CI con ejecuciones frecuentes, necesitas API keys de Google AI Studio (pago por uso) o Vertex AI.
  • Coste real: con la API de Gemini 3 Pro, el coste por millón de tokens de entrada ronda los 1,25 $ y 5 $ por millón de tokens de salida. Para un desarrollador individual con uso moderado (10-20 sesiones largas al mes), el coste mensual se sitúa entre 5 y 15 euros.
  • Token caching: en modo headless, las instrucciones de sistema y el contexto estable se cachean entre invocaciones, lo que reduce costes en ejecuciones repetitivas. El campo stats.tokens.cached en el session summary indica la tasa de acierto de caché.
  • OAuth en headless: la autenticación OAuth requiere un navegador. En entornos SSH, Docker o CI/CD, usa exclusivamente GOOGLE_API_KEY o GOOGLE_APPLICATION_CREDENTIALS con una service account.
  • MCP en remoto: los servidores MCP via SSE/HTTP soportan OAuth 2.0 con tres modos (dynamic_discovery, google_credentials, service_account_impersonation). Para servicios protegidos por IAP en Cloud Run, el modo service_account_impersonation es el recomendado.
  • Calidad del código: en benchmarks comparativos, Gemini CLI genera código correcto en el primer intento entre un 85% y un 88% de las veces. Eso es bueno, pero por debajo del 95% de Claude Code. Para tareas críticas, revisa siempre la salida.

Errores Comunes y Depuración

Error: "No tools found" al conectar un servidor MCP.
Causa: el servidor MCP no expone herramientas o el timeout es demasiado corto.
Solución: aumenta el timeout en la configuración del servidor y ejecuta /mcp en sesión para verificar el estado de las conexiones. Usa /mcp reload para forzar una reconexión.

Error: conflicto de nombres de herramientas entre servidores MCP.
Causa: dos servidores registran una herramienta con el mismo nombre.
Solución: Gemini CLI asigna el nombre al primer servidor que lo registre. Los duplicados reciben el prefijo serverName__toolName. Usa includeTools o excludeTools para controlar qué herramientas expone cada servidor.

Error: "Authentication required" en modo headless.
Causa: el flujo OAuth necesita un navegador que no existe en el entorno.
Solución: configura GOOGLE_API_KEY como variable de entorno. No intentes autenticación OAuth en entornos sin interfaz gráfica.

Error: el agente ignora las instrucciones de GEMINI.md.
Causa: el archivo no está en la ruta esperada o el nombre no coincide con context.fileName en settings.
Solución: ejecuta /memory show para verificar qué contexto se ha cargado. Comprueba que el archivo se llama exactamente GEMINI.md (sensible a mayúsculas en Linux).

Preguntas Frecuentes

¿Gemini CLI es gratuito?

Sí. Con una cuenta personal de Google tienes 1.000 peticiones diarias y 60 por minuto usando Gemini 3 Pro. Para uso profesional intensivo o equipos, necesitas una API key de pago de Google AI Studio o Vertex AI, donde pagas por tokens consumidos.

¿Puedo usar Gemini CLI dentro de VS Code?

Gemini CLI tiene una extensión companion para VS Code que permite ejecutar el agente de terminal integrado en el editor. Dicho esto, Gemini CLI está diseñado como herramienta de terminal. Si tu flujo es IDE-first, Gemini Code Assist (integrado en VS Code) comparte el mismo modelo pero está optimizado para esa experiencia.

¿Qué diferencia hay entre Gemini CLI y Gemini Code Assist?

Gemini Code Assist vive dentro del IDE y se enfoca en autocompletado, chat inline y refactoring interactivo. Gemini CLI es un agente de terminal para tareas autónomas: scripts, análisis de proyectos completos, integración con MCP y automatización en CI/CD. Ambos usan modelos Gemini 3 por debajo. En la práctica, son complementarios.

Cierre

Gemini CLI ocupa un espacio propio en el ecosistema de agentes de terminal. La combinación de tier gratuito generoso, contexto de 1 millón de tokens y soporte MCP nativo con tres transportes lo convierte en una opción que merece un hueco en tu arsenal, especialmente si trabajas con proyectos grandes o necesitas conectar el agente a servicios externos sin coste inicial. No reemplaza a Claude Code en calidad de razonamiento ni a Codex en seguridad de ejecución, pero para exploración de código, prototipos rápidos y automatización en CI/CD es una herramienta que conviene tener configurada.

Si ya lo usas junto a otros agentes de terminal, en el análisis de alternativas a Cursor puedes ver cómo encaja en el panorama general de herramientas de coding asistido por IA en 2026. ¿Has probado Gemini CLI en tu flujo de trabajo? Cuéntamelo en Twitter @sergiomarquezp_.

Volver al blog