Gemini CLI en Linux, macOS y Windows (configuración del Agente)

Gemini CLI es el agente de IA de código abierto de Google para la terminal. Incluye el modelo completo Gemini 3, una ventana de contexto de 1 millón de tokens y un generoso nivel gratuito (60 solicitudes por minuto, 1,000 por día) detrás de un único binario gemini. La versión estable actual llegó en abril de 2026, con lanzamientos de vista previa semanales los martes y compilaciones nocturnas a las 00:00 UTC.

Esta guía instala Gemini CLI en macOS, Linux y Windows, repasa los tres modos de autenticación, configura skills del agente, añade un servidor de Model Context Protocol (MCP), configura settings.json y ejecuta consultas reales en modo headless. Cada comando y cada fragmento de salida a continuación se ejecutó en una máquina real.

• Probado en abril de 2026 en macOS 26.3 (Apple Silicon) y Rocky Linux 10.1 (x86_64) con Gemini CLI 0.38.1 y Node.js 25.9.0.*

Cambios recientes dignos de mención

La línea de lanzamiento actual es donde Gemini CLI se graduó de ser un útil complemento de terminal a un competidor completo de Claude Code. Esta línea llegó en abril de 2026 e incluyó cuatro cambios que importan en el día a día:

• Modo TerminalBuffer, que finalmente elimina el parpadeo que tenían las versiones anteriores en los turnos largos del agente.
• Salida de herramientas compacta como renderizado predeterminado, para que los planes de múltiples herramientas no entierren tu prompt en JSON.
• Aprobaciones de políticas conscientes del contexto, permitiéndote aprobar una herramienta una vez para una carpeta en lugar de volver a preguntar por cada archivo.
• Servicio de memoria que extrae patrones reutilizables de las sesiones para skills posteriores.

Los lanzamientos de parches posteriores siguen la misma rama. Lo siguiente en la pista de vista previa es un comando /memory inbox para revisar skills extraídos, y una arquitectura de subagentes refactorizada que coincide con lo que Claude Code y OpenCode ofrecen ahora.

Prerrequisitos

Tres requisitos estrictos, uno flexible.

1. Node.js 20 o más nuevo. Gemini CLI se distribuye como un paquete npm, por lo que Node es el entorno de ejecución. Verifícalo con node --version.
2. Un sistema operativo compatible. macOS 15 Sequoia o posterior (Intel y Apple Silicon), Windows 11 24H2 o posterior, o Ubuntu 20.04 / Debian 12 / Rocky Linux 10 o posterior.
3. 4 GB de RAM para uso casual, 16 GB o más si planeas mantener múltiples sesiones y un contenedor sandbox en ejecución.
4. Una de tres credenciales: una Cuenta de Google personal (nivel gratuito), una clave API de Gemini de Google AI Studio, o credenciales de Vertex AI si estás en Google Cloud.

Paso 1: Establecer variables de shell reutilizables

La mayoría de los comandos a continuación toman un nombre de modelo, un modo de aprobación y (en algunas plataformas) una clave API. Expórtalas una vez para que los pasos posteriores se peguen tal cual.

export GEMINI_API_KEY="tu-clave-api-aqui"
export GEMINI_MODEL="gemini-2.5-pro"
export GEMINI_AGENT="claude-code"
export GEMINI_APPROVAL="auto_edit"

Confirma que los valores se cargaron antes de tocar cualquier cosa que gaste solicitudes:

echo "Key:     ${GEMINI_API_KEY:0:10}..."
echo "Model:   ${GEMINI_MODEL}"
echo "Agent:   ${GEMINI_AGENT}"
echo "Approve: ${GEMINI_APPROVAL}"

Los valores se mantienen solo en el shell actual. Vuelve a exportarlos después de reconectarte por SSH o abrir una nueva pestaña. Persístelos añadiendo las mismas líneas a ~/.zshrc, ~/.bashrc o al $PROFILE de Windows.

Paso 2: Instalar Gemini CLI en macOS

Tres rutas en Macs con Apple Silicon o Intel. Elige la que coincida con tu gestor de paquetes.

# Opción A: npm (recomendado para controlar el canal de lanzamiento)
npm install -g @google/gemini-cli

# Opción B: Homebrew
brew install gemini-cli

# Opción C: MacPorts
sudo port install gemini-cli

En una Mac nueva con Node 25, la instalación por npm se completa en unos 23 segundos. Verifica que el binario aterrice en tu PATH:

gemini --version

Deberías ver una cadena de versión que coincida con el último lanzamiento estable. Si necesitas una ejecución puntual sin instalar, npx @google/gemini-cli descarga y ejecuta el paquete sin contaminar tu árbol global de npm.

Instalar Gemini CLI vía npm en macOS, establecer GEMINI_API_KEY y ejecutar un prompt headless.
Esos son los mismos tres pasos que ejecutarás en Linux y Windows, solo que con diferentes gestores de paquetes.

Paso 3: Instalar Gemini CLI en Linux

El mismo paquete npm funciona en Rocky Linux 10, Ubuntu 24.04, Debian 13 y Fedora 42. Homebrew en Linux también funciona si ya lo usas:

# Rocky Linux 10, AlmaLinux 10, Fedora 42
sudo dnf install -y nodejs
sudo npm install -g @google/gemini-cli

# Ubuntu 24.04, Debian 13
sudo apt install -y nodejs npm
sudo npm install -g @google/gemini-cli

# Homebrew en Linux
brew install gemini-cli

Si el Node distribuido por la distro es anterior a la versión 20, instala Node 20 o 22 desde NodeSource primero. Ese requisito de versión se aplica al iniciar, no al instalarse, por lo que npm install -g tendrá éxito pero la primera llamada a gemini fallará con un error de versión.

Para entornos restringidos donde Node no se puede instalar globalmente, Anaconda proporciona una ruta hermética:

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

Docker también es un objetivo de instalación válido. Google publica una imagen sandbox en us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1, que es la que la propia CLI usa cuando pasas --sandbox.

Paso 4: Instalar Gemini CLI en Windows

En Windows 11 24H2 o más nuevo, abre un prompt de PowerShell elevado y ejecuta:

npm install -g @google/gemini-cli
gemini --version

Windows no incluye Homebrew ni MacPorts, por lo que npm es la ruta principal. Si la política de tu empresa bloquea las instalaciones globales de npm, Docker Desktop junto con la imagen sandbox publicada es una alternativa soportada:

docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1

Establece la clave API vía PowerShell en lugar del simple export:

$env:GEMINI_API_KEY = "tu-clave-api-aqui"
gemini

Persiste la variable con [System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'tu-clave', 'User') si quieres que sobreviva a un reinicio.

Paso 5: Elegir un modo de autenticación

Gemini CLI soporta tres fuentes de credenciales, y tienen cuotas muy diferentes.

Para OAuth, simplemente lanza la CLI y sigue el flujo del navegador. Las credenciales se almacenan en caché localmente para que las ejecuciones posteriores omitan el aviso.

gemini

Para autenticación por clave API, exporta la clave y opcionalmente el modelo:

export GEMINI_API_KEY="tu-clave-api-aqui"
gemini -m "${GEMINI_MODEL}"

Si ya estableciste GOOGLE_API_KEY en tu entorno (por ejemplo, porque otro SDK de Google lo necesita), Gemini CLI lo recoge e imprime un aviso de una línea indicando que usó GOOGLE_API_KEY en lugar de GEMINI_API_KEY. Desactiva uno u otro si quieres forzar una fuente específica.

Para Vertex AI, la ruta ADC es la más limpia:

export GOOGLE_CLOUD_PROJECT="mi-proyecto-gcp"
export GOOGLE_CLOUD_LOCATION="us-central1"
gcloud auth application-default login
gemini

Desactiva cualquier GOOGLE_API_KEY o GEMINI_API_KEY persistente primero, porque la CLI prefiere una clave directa sobre ADC cuando ambas están presentes.

Paso 6: Ejecutar tu primera consulta

Dos modos. El interactivo es el predeterminado. El no interactivo es para scripts.

Inicia una sesión interactiva en tu directorio actual:

cd ~/code/mi-proyecto
gemini

La sesión lee cada archivo GEMINI.md que encuentra al subir desde el directorio actual, añade todo el espacio de trabajo al contexto (limitado por el .git más cercano por defecto), y te deja en un prompt.

Para una consulta de un solo uso desde un script de shell o un trabajo de CI, pasa -p:

gemini -p "Resume los últimos 10 commits en un párrafo"

La salida estructurada está disponible vía --output-format json (un documento JSON al final) o --output-format stream-json (eventos delimitados por nuevas líneas durante la ejecución, útil para barras de progreso). Añade --include-directories ../lib,../docs cuando el contexto relevante viva fuera del árbol actual.

Paso 7: Aprender los comandos slash

Dentro de una sesión interactiva, los comandos slash controlan el estado. Escribe /help o /? para la lista completa. Los que realmente usarás:

Dos prefijos especiales importan tanto como los comandos slash. Inicia cualquier línea con @ para inyectar un archivo o directorio en el prompt (@src/main.ts fix the race condition), y con ! para salir al shell sin dejar la sesión (!git log --oneline -5).

Para la referencia completa que cubre cada bandera de la CLI, todos los comandos slash, atajos de teclado, comandos TOML personalizados, la matriz de banderas de servidores MCP, sandbox y checkpointing, más capturas de sesiones reales, consulta la hoja de trucos de Gemini CLI.

Paso 8: Gestionar skills del agente desde la CLI

Los Skills son paquetes de capacidades basados en markdown que siguen el estándar abierto Agent Skills. Gemini CLI los descubre en cinco ubicaciones, en orden de precedencia:

1. Espacio de trabajo: .agents/skills/ luego .gemini/skills/
2. Usuario: ~/.agents/skills/ luego ~/.gemini/skills/
3. Extensiones incluidas con las extensiones de CLI instaladas

El ciclo de vida completo del skill se expone como subcomandos de gemini skills:

gemini skills list
gemini skills list --all
gemini skills install https://github.com/google-gemini/gemini-skills
gemini skills install ./ruta/al/skill/local
gemini skills link ./ruta/al/skill-en-desarrollo
gemini skills enable <nombre>
gemini skills disable <nombre> --scope user
gemini skills uninstall <nombre> --scope user

Si ya instalaste la CLI de Android, android init dejó un skill android-cli en ~/.agents/skills/, y Gemini CLI lo recoge automáticamente. En la Mac de prueba usada para esta guía, esto se ve así:

Lista de skills de Gemini CLI y ayuda del subcomando skills en macOS.

Un aviso de conflicto de skill no es un error. Solo significa que Gemini recogió el mismo skill de dos rutas de descubrimiento y está usando el de mayor precedencia. Desinstala el duplicado o habilita solo la versión que quieres con gemini skills enable <nombre> --scope user.

Dentro de una sesión interactiva, las mismas operaciones están disponibles vía /skills list, /skills enable <nombre> y /skills reload.

Paso 9: Añadir servidores MCP para extender capacidades

Model Context Protocol (MCP) es donde Gemini CLI obtiene la mayor parte de su poder. Un servidor MCP es cualquier proceso que hable el protocolo MCP (stdio, SSE o HTTP streaming) y exponga un conjunto de herramientas. Gemini CLI viene con herramientas integradas de archivos, shell y web-fetch; MCP es como añades todo lo demás (Context7, GitHub, Slack, bases de datos, herramientas internas personalizadas).

El comando mcp add escribe la configuración en settings.json por ti. Para instalar el servidor MCP Context7 a nivel de usuario:

gemini mcp add --scope user context7 npx -y @upstash/context7-mcp

El ~/.gemini/settings.json resultante se ve así:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Verifica que el servidor se registre y la autenticación headless siga funcionando:

Añadir servidor MCP Context7 a settings.json de Gemini CLI y ejecutar un prompt headless.

Cada bandera de servidor MCP tiene una forma completa para cuando necesitas más control:

# Servidor SSE remoto con encabezado de autenticación
gemini mcp add --transport sse my-api https://api.example.com/sse \
  -H "Authorization: Bearer ${MY_TOKEN}" \
  --timeout 10000

# Servidor HTTP streaming con una variable de entorno
gemini mcp add --transport http my-db http://localhost:3000/mcp \
  -e DATABASE_URL=postgres://localhost/mydb \
  --trust

# Servidor filtrado (permitir solo herramientas específicas)
gemini mcp add --scope user safe-fs npx -y @modelcontextprotocol/server-filesystem \
  --include-tools read_file,list_directory

Una vez que los servidores están registrados, referéncialos con @ dentro de un prompt interactivo: @context7 fetch the latest nextjs 16 docs, @github list my open PRs, @my-db run select count(*) from users.

Paso 10: Configurar settings.json

La configuración vive en dos archivos. ~/.gemini/settings.json es para todo el usuario. .gemini/settings.json en la raíz de un proyecto es específico del espacio de trabajo y gana sobre la configuración del usuario. Un punto de partida sensato y anotado:

{
  "general": {
    "preferredEditor": "code",
    "defaultApprovalMode": "auto_edit",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 100
    }
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    },
    "disableYoloMode": false
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "footer": {
      "items": ["model", "context"]
    }
  },
  "model": {
    "name": "gemini-2.5-pro",
    "maxSessionTurns": 50
  },
  "tools": {
    "allowed": ["run_shell_command(git)", "read_file"],
    "exclude": [],
    "sandbox": "docker"
  },
  "context": {
    "fileName": ["GEMINI.md"],
    "includeDirectories": ["./docs"],
    "memoryBoundaryMarkers": [".git"]
  },
  "telemetry": {
    "enabled": false
  }
}

Cuatro campos ganan su lugar para el uso diario. general.defaultApprovalMode establece la política inicial: default pregunta por cada herramienta, auto_edit aprueba ediciones silenciosamente pero sigue preguntando por comandos de shell, yolo aprueba todo, y plan es de solo lectura. model.name fija el modelo predeterminado para que no tengas que escribir -m cada vez. tools.allowed es una lista blanca que omite la confirmación para las llamadas a herramientas específicas listadas, por lo que run_shell_command(git) permite a Gemini ejecutar cualquier comando git pero sigue preguntando antes de cualquier otro comando de shell. mcpServers contiene las entradas que gemini mcp add escribió.

Los valores de cadena soportan interpolación de variables de entorno usando tres sintaxis: "$VAR", "${VAR}" y "${VAR:-default}". Útil para configuraciones de equipo compartidas que extraen secretos de un archivo env común.

Paso 11: Escribir un archivo de contexto GEMINI.md

Los Skills son bajo demanda. GEMINI.md es contexto siempre activo. Pon uno en la raíz del proyecto para decirle a Gemini sobre convenciones, arquitectura, librerías preferidas, o cualquier otra cosa que deba tratar como conocimiento de fondo en cada turno.

Genera uno inicial desde dentro de una sesión:

cd ~/code/mi-proyecto
gemini
> /init

O escribe uno a mano. Mantenlo corto. Un GEMINI.md de 50 líneas que realmente coincide con la realidad vence a uno de 500 líneas que se desvía la primera vez que alguien refactoriza. Secciones típicas:

# Project context

## Stack
Node.js 20 + TypeScript 5.5 + Fastify 5. Tests via Vitest.

## Conventions
- Absolute imports from `src/`, no default exports.
- Every public function has a JSDoc @example.
- Commit messages follow Conventional Commits.

## Commands
- `npm run dev` - local dev server on port 3000
- `npm run test` - full test suite
- `npm run lint` - eslint + prettier --check

## Do not touch
- `src/generated/` is autogenerated from OpenAPI; edit the spec instead.

Gemini CLI atraviesa hacia arriba desde el directorio actual recopilando cada GEMINI.md que encuentra, deteniéndose en la primera entrada de memoryBoundaryMarkers (por defecto: .git). Eso permite que los monorepos tengan un GEMINI.md raíz más archivos GEMINI.md por paquete sin que nada se filtre entre proyectos.

Paso 12: Usar el modo no interactivo en scripts

El modo headless es el mismo binario, diferentes banderas. Tres formas de salida dependiendo de qué consuma el resultado.

# Texto plano (predeterminado)
gemini -p "Summarise the README in two sentences"

# JSON estructurado (un solo blob al final)
gemini -p "Count the TypeScript files in src/" --output-format json

# Eventos delimitados por nuevas líneas durante la ejecución
gemini -p "Run the test suite and explain any failures" --output-format stream-json

El modo stream es ideal para trabajos de CI porque puedes hacer tail a los eventos con jq y reaccionar a otros específicos (por ejemplo, publicar un mensaje en Slack la primera vez que una llamada a herramienta se bloquea esperando aprobación).

Otras dos banderas que vale la pena conocer para automatización. --yolo aprueba cada llamada a herramienta sin preguntar (peligroso fuera de un sandbox). --sandbox ejecuta toda la sesión en el contenedor Docker oficial. Combínalos dentro de un ejecutor de CI y Gemini CLI hará trabajo destructivo sin tocar nunca el sistema de archivos del host.

Para GitHub Actions, Google publica una acción lista para usar en google-github-actions/run-gemini-cli que maneja revisiones de PR, triaje de issues y menciones @gemini-cli bajo demanda. Envuelve exactamente el mismo binario detrás de una interfaz de acción familiar. Si ya ejecutas Aider o la CLI de OpenAI Codex para el mismo trabajo, la forma de las banderas te resultará familiar.

Paso 13: Elegir un canal de lanzamiento

Tres canales, tres cadencias. Instala el que coincida con tu tolerancia al riesgo.

# Estable (Martes 20:00 UTC) - lo que producción debería usar
npm install -g @google/gemini-cli@latest

# Vista previa (Martes 23:59 UTC) - el estable de la próxima semana, ayuda a probar
npm install -g @google/gemini-cli@preview

# Nocturno (diario 00:00 UTC) - rama principal tal cual, bordes ásperos
npm install -g @google/gemini-cli@nightly

El canal estable es el predeterminado cuando ejecutas npm install -g @google/gemini-cli sin una etiqueta. Preview está una semana por delante de stable, por lo que ejecutarlo ayuda a surface regresiones antes de que se lancen. Nightly refleja la rama principal a la medianoche UTC e incluye todo lo que pasó el CI ese día, lo cual es genial para el propio equipo de Google y menos genial para servidores de producción. Si quieres comparar Gemini CLI contra las otras CLI de agentes antes de comprometerte, Cursor vs Windsurf vs Kiro cubre el lado del IDE del ecosistema y Ollama es la elección correcta cuando necesitas mantenerte completamente local.

Solución de problemas comunes

Cinco errores reales que encontré o registré durante la redacción. Soluciones a continuación.

“Both GOOGLE_API_KEY and GEMINI_API_KEY are set. Using GOOGLE_API_KEY.”
No es un error. Cuando ambas variables de entorno están establecidas, Gemini CLI prefiere GOOGLE_API_KEY. Si la clave que quieres está en GEMINI_API_KEY, desactiva GOOGLE_API_KEY antes de ejecutar, o almacena el mismo valor en ambas variables (que es lo que ~/.gemini/.env típicamente hace).

“Skill conflict detected” durante el inicio
Significa que el mismo skill existe en dos rutas de descubrimiento (típicamente ~/.agents/skills/ y ~/.gemini/skills/). Gemini usa el de mayor precedencia. Es seguro ignorarlo, pero es más limpio eliminar el duplicado:

gemini skills uninstall android-cli --scope user
android init --agent=gemini    # reinstalar en la ubicación canónica

Reinicia la CLI después de la desinstalación para que la caché de skills se reconstruya.

“Error executing tool activate_skill: Tool not found” en modo headless
La activación de skills se basa en una herramienta que solo existe en modo interactivo. En ejecuciones headless (gemini -p), el modelo aún ve los nombres y descripciones de los skills en el prompt del sistema y puede inferir comportamiento a partir de ellos, pero no puede cargar dinámicamente el SKILL.md completo. Ejecuta interactivamente, o pre-expande el skill en el prompt vía @~/.agents/skills/android-cli/SKILL.md.

“gemini mcp list” se cuelga
El comando list se conecta a cada servidor configurado para enumerar sus herramientas. Si un servidor tarda demasiado en iniciar (por ejemplo, npx iniciando en frío un paquete de Context7), todo el comando se detiene hasta el tiempo de espera predeterminado de 600 segundos. Acorta la espera añadiendo --timeout 5000 a la llamada mcp add, o elimina servidores que ya no uses con gemini mcp remove <nombre>.

Advertencia “prebuild-install is no longer maintained” en npm install
Una dependencia transitiva (herramientas de complementos nativos) imprime una advertencia de obsolescencia. Es cosmético. La instalación aún se completa y el binario aún se ejecuta. El equipo de Google rastrea esto contra el rastreador de issues de la CLI; no se necesita acción de tu parte hasta que una futura versión elimine la dependencia.

Para cualquier cosa no cubierta aquí, el comando /bug "<short description>" en la CLI abre un issue de GitHub pre-rellenado contra google-gemini/gemini-cli con los metadatos de tu sesión adjuntos. Úsalo. El ciclo de retroalimentación es cómo la vista previa 0.39 llegó un mes después del estable 0.38.