Gemini CLI: el agente de terminal de Google con 1M de contexto y capa gratuita generosa

El 25 de marzo de 2026, Google lanzó Gemini CLI en preview: un agente de terminal open source (Apache 2.0) con 1 millón de tokens de contexto, Google Search integrado de serie, soporte MCP y la capa gratuita más generosa de todos los agentes de terminal del mercado. 1.000 peticiones al día sin tarjeta de crédito, solo con una cuenta de Google.

No es una herramienta de juguete. Comparte tecnología con Gemini Code Assist, el producto empresarial de Google para codificación asistida. Lo que tienes en el CLI gratuito es una versión del mismo agente que las empresas pagan por usar, con un límite de uso diario razonable.

Esta guía cubre lo que necesitas saber para empezar y sacarle partido desde el primer día.

Instalación: tres formas#

# Opción 1: npx sin instalación (para probarlo)
npx @google/gemini-cli

# Opción 2: instalación global con npm (recomendado)
npm install -g @google/gemini-cli

# Verificar versión
gemini --version

# Actualizar a la última versión
npm update -g @google/gemini-cli

También funciona directamente en Google Cloud Shell, sin ninguna configuración adicional.

Autenticación:

# Con cuenta personal de Google (capa gratuita — 1000 req/día)
gemini auth login
# Abre el navegador, autentica con tu cuenta de Google

# Con API key de Google AI Studio (para pago por uso)
export GOOGLE_API_KEY=AIza...
gemini

# Con Google Cloud / Vertex AI para empresas
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

Qué puedes hacer con la capa gratuita#

La capa gratuita de Gemini CLI con cuenta de Google personal incluye:

• Acceso a Gemini 2.5 Pro (el modelo más capaz de Google)
• 1.000 peticiones al día — suficiente para un día de trabajo intensivo
• 1 millón de tokens de contexto — el mismo límite que los planes de pago
• Google Search integrado — sin cargo adicional
• Todas las herramientas del agente (edición de archivos, shell, web fetch)

Para comparar: Claude Code requiere suscripción de 20$/mes mínimo para uso básico. Codex CLI necesita ChatGPT Plus (20$/mes). Gemini CLI es gratis con tu cuenta de Google.

GEMINI.md: el equivalente al CLAUDE.md#

Gemini CLI lee el archivo GEMINI.md en el directorio del proyecto al iniciar una sesión. Funciona exactamente igual que el CLAUDE.md de Claude Code:

# Mi Portfolio — luismibriz.dev

## Stack tecnológico
- Next.js 15, React 18, TypeScript 5.7 (modo strict)
- Tailwind CSS 3.4, SCSS para módulos de componentes
- Supabase como base de datos (REST API + GraphQL legacy)
- Deploy automático en Vercel desde la rama master

## Comandos del proyecto
- `npm run dev` — servidor de desarrollo en puerto 3000
- `npm run build` — build de producción
- `npm test` — Jest + React Testing Library
- `npm run typecheck` — verificar TypeScript sin emitir

## Convenciones de código
- Componentes React: PascalCase, funcionales, named exports
- Hooks personalizados: prefijo use, en src/hooks/
- Tests: en __tests__/ junto al código que testean
- Imports de Supabase: siempre content_md || content para posts
- Sin `any` excepto en mappers de datos de Supabase

## Restricciones importantes
- No modificar .env.local (nunca committear)
- No tocar src/graphql/apollo-client.ts (deuda técnica pendiente)
- master → Vercel producción automática. No pushear directamente.

Guarda el GEMINI.md en el repositorio junto al código para que todos los miembros del equipo partan del mismo contexto.

Google Search integrado: la ventaja diferencial#

Gemini CLI es el único agente de terminal con Google Search integrado de forma nativa. No es una búsqueda genérica: es Google, con el índice más completo del mundo y actualización en tiempo real.

# La búsqueda se activa automáticamente cuando hace falta
gemini "¿cuál es la forma correcta de configurar headers de caché en Next.js 15?"
# Gemini busca en Google si su conocimiento no es suficiente

# También puedes forzar una búsqueda explícita
gemini "busca las novedades de Next.js publicadas esta semana"

# O combinar búsqueda y análisis de código local
gemini "compara cómo gestiona la caché este proyecto con las recomendaciones oficiales de Next.js 15"
# Busca la documentación oficial y la compara con tu código

Esto es especialmente útil para proyectos que usan librerías que se actualizan frecuentemente, donde el conocimiento de entrenamiento del modelo puede estar desactualizado.

Plan mode: lee antes de escribir#

Gemini CLI tiene un plan mode que funciona en modo solo lectura. El agente analiza el código y propone un plan sin modificar nada hasta que apruebes:

# Activar plan mode
gemini
> /plan migrar el sistema de posts de GraphQL a REST de Supabase

# Gemini analiza todo el código relacionado (archivos GraphQL,
# consultas, tipos, componentes que las usan)
# Propone un plan de migración con pasos ordenados
# Hace preguntas si necesita clarificación
# Solo ejecuta cuando le das el OK

El plan mode también soporta herramientas MCP en modo solo lectura. Puede consultar issues de GitHub o el schema de tu base de datos para que el plan esté informado por datos reales, no solo por lo que hay en el código local.

Herramientas disponibles#

Gemini CLI incluye un conjunto de herramientas que puede invocar:

Código y archivos:
- ReadFile          — leer cualquier archivo
- WriteFile         — crear o sobreescribir archivos
- Edit              — editar fragmentos de archivos
- FindFiles         — buscar archivos por patrón glob
- SearchText        — buscar texto en el contenido de archivos
- ReadFolder        — listar el contenido de un directorio

Shell y sistema:
- Shell             — ejecutar comandos del sistema
- WriteTodos        — gestionar una lista de tareas de la sesión

Internet:
- GoogleSearch      — búsqueda en Google
- WebFetch          — obtener el contenido de una URL

Agentes:
- SaveMemory        — guardar información entre sesiones
- CodebaseInvestigator — análisis profundo de la base de código

Las herramientas que modifican el sistema (Shell, WriteFile, Edit) piden confirmación antes de ejecutarse por defecto.

MCP: extensión con herramientas externas#

// ~/.gemini/settings.json
{
  "mcpServers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    {
      "name": "supabase",
      "command": "npx",
      "args": ["@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}"
      }
    }
  ]
}

Con el servidor MCP de GitHub configurado:

gemini "@github lista mis PRs abiertos y dime cuáles llevan más de 48h sin revisión"
gemini "@github crea un issue con este título y esta descripción: ..."
gemini "@supabase muéstrame el schema de la tabla posts y compáralo con el tipo Post de TypeScript"

Extensiones y el modo --yolo#

Gemini CLI tiene un sistema de extensiones que se instalan desde el Extensions Gallery:

# Listar extensiones instaladas
gemini extensions list

# Instalar una extensión (ejemplo: GitHub MCP)
gemini extensions install github

# Desinstalar
gemini extensions uninstall github

El modo --yolo desactiva todas las confirmaciones de herramientas y ejecuta todo automáticamente:

# Solo para proyectos donde confíes completamente en el agente
gemini --yolo "refactoriza los componentes de formulario para usar react-hook-form"

No se recomienda en proyectos de producción. Úsalo solo en sandboxes o ramas de experimentos.

Errores comunes al empezar con Gemini CLI#

No crear el GEMINI.md. Sin contexto de proyecto, Gemini empieza desde cero en cada sesión. El GEMINI.md es lo que más impacta en la calidad de los resultados con el mínimo esfuerzo.

Llegar al límite de 1.000 peticiones diarias con tareas triviales. El límite es generoso, pero se consume rápido si cada cambio pequeño genera 10 peticiones. Agrupa las tareas en prompts más completos en lugar de hacer muchas preguntas pequeñas.

Activar --yolo en proyectos importantes. Gemini ejecuta comandos de shell. Un rm -rf accidental en modo --yolo sin confirmación puede ser catastrófico. Mantén el modo de confirmación activo para proyectos con datos reales.

Ignorar el modo plan para migraciones. Cualquier cambio que afecte a más de cinco archivos merece un plan previo. El plan mode de Gemini hace buenas preguntas antes de proponer cambios y el resultado final es significativamente mejor.

Buenas prácticas#

Usa el historial de sesiones. Gemini CLI puede continuar sesiones anteriores con gemini --continue. Para proyectos en los que trabajas durante varios días, esto evita perder el contexto acumulado.

Combina Google Search con el código local. La mayor ventaja de Gemini sobre otros agentes es poder buscar en Google y aplicar lo encontrado a tu código en el mismo prompt. Aprovéchalo para migrar a versiones nuevas de dependencias o implementar patterns recientes.

Configura el MCP de GitHub desde el primer día. Con un token de acceso personal de GitHub y el servidor MCP configurado en ~/.gemini/settings.json, Gemini puede gestionar issues y PRs directamente sin salir del terminal.

Conclusión#

Gemini CLI es la apuesta de Google por el ecosistema de agentes de terminal: open source, gratuito para uso personal con límites generosos, con el contexto de 1 millón de tokens que hasta hace poco era exclusivo de planes de pago, y con la ventaja única de Google Search integrado de serie.

Para desarrolladores que quieren probar un agente de terminal sin comprometer presupuesto, Gemini CLI es el punto de entrada más accesible del mercado. Para los que ya usan Claude Code o Codex CLI, es una alternativa real para tareas donde la búsqueda en tiempo real de documentación actualizada marca la diferencia.