Cómo usar Gemini CLI: guía paso a paso

Para usar Gemini CLI, instálalo con npm o Homebrew, ejecuta gemini dentro de la carpeta de un proyecto, elige cómo iniciar sesión y describe en lenguaje natural lo que quieres. Gemini lee tus archivos, propone ediciones y comandos de shell y, por defecto, pregunta antes de ejecutar cada uno.

Antes de empezar, una advertencia importante. Desde el 18 de junio de 2026, Gemini CLI ya no da servicio a los usuarios del nivel gratuito ni de Google One. Google los trasladó a Antigravity CLI. Gemini CLI sigue funcionando con una API key de Gemini de pago, Vertex AI o una licencia de Gemini Code Assist Standard o Enterprise. Esta guía cubre la instalación, el inicio de sesión, GEMINI.md, los ajustes, MCP, los modos de aprobación, los comandos slash, checkpointing y cómo retomar sesiones. Todo sigue la documentación oficial de Gemini CLI de Google a octubre de 2026.

Qué es Gemini CLI

Gemini CLI es el agente de programación de código abierto de Google para la terminal. Ejecuta modelos Gemini, lee y edita archivos en la carpeta desde la que lo lanzas, ejecuta comandos de shell, busca en la web, se conecta a servidores MCP y toma las instrucciones del proyecto de GEMINI.md. Es un agente de programación, no un autocompletado: le das una tarea y la resuelve paso a paso. Para compararlo con otros agentes, mira Gemini CLI vs Claude Code y Codex vs Gemini CLI.

Paso 1: instala Gemini CLI

Gemini CLI necesita Node.js. Elige la instalación que encaje con tu entorno:

En npm hay tres canales de versiones: @latest (estable, semanal), @preview (semanal, por delante de la estable) y @nightly. Lo normal es quedarse en la estable. Para actualizar más adelante, ejecuta gemini update o reinstala con tu gestor de paquetes. Comprueba la instalación:

gemini --version

Paso 2: elige cómo iniciar sesión

Entra en un proyecto y arráncalo:

cd mi-proyecto
gemini

La primera vez, Gemini CLI te pregunta cómo quieres autenticarte. Hay tres opciones:

• Sign in with Google: abre el navegador. Tras el cambio de junio de 2026, es para organizaciones con una licencia de Gemini Code Assist Standard o Enterprise; antes de empezar, pon en GOOGLE_CLOUD_PROJECT el ID de tu proyecto de Google Cloud.
• API key de Gemini: crea una key en Google AI Studio y define GEMINI_API_KEY. Con una key de pago, el uso se factura por token.
• Vertex AI: para equipos en Google Cloud. Define GOOGLE_API_KEY y GOOGLE_GENAI_USE_VERTEXAI=true, o usa tus credenciales de Cloud.

export GEMINI_API_KEY="tu-key"
gemini

Puedes cambiar de método más tarde con /auth. Si usabas Gemini CLI con una cuenta personal gratuita, el aviso de Google te remite a Antigravity CLI; Gemini CLI vs Claude Code explica el cambio en detalle. Antes de lanzar sesiones largas con una key, consulta los precios de la API de Gemini para ver las tarifas actuales.

Paso 3: tu primera tarea

Empieza con algo pequeño y real:

Explica cómo está estructurado el módulo de pagos, luego añade validación
de entrada al endpoint de reembolsos y ejecuta los tests.

Gemini lee los archivos que necesita, te muestra cada edición y cada comando y espera tu visto bueno. Algunos atajos ayudan desde el primer día:

• @ruta/al/archivo añade un archivo (o una carpeta entera) al prompt.
• !git status ejecuta directamente un comando de shell. Un ! solo activa y desactiva el modo shell.
• gemini -p "resume README.md" ejecuta un único prompt sin la interfaz interactiva e imprime la respuesta. Añade --output-format json cuando un script tenga que leer el resultado.
• /copy copia la última respuesta al portapapeles.

Paso 4: escribe un GEMINI.md

GEMINI.md es un archivo Markdown con instrucciones que Gemini CLI carga y envía con cada prompt: cómo compilar y probar, el estilo de código, qué no tocar. Ejecuta /init y Gemini genera una primera versión a partir de tu proyecto. Mantenlo corto y concreto:

# Proyecto: billing-service

## Comandos
- Instalar: npm ci
- Test: npm test (ejecútalo antes de dar una tarea por terminada)

## Estilo
- TypeScript, sangría de 2 espacios, solo igualdad estricta.
- Los endpoints nuevos van en src/routes y necesitan un test.

## No hagas
- No edites archivos en src/generated.

Gemini CLI carga los archivos de contexto por capas y los une:

1. Global: ~/.gemini/GEMINI.md, tus valores por defecto personales para todos los proyectos.
2. Workspace: los archivos GEMINI.md de la carpeta del proyecto y de sus carpetas superiores.
3. Sobre la marcha: cuando una herramienta toca un archivo de una subcarpeta, Gemini recoge también cualquier GEMINI.md de esa carpeta y de sus superiores.

Puedes dividir un archivo largo con importaciones, por ejemplo con una línea @./docs/style-guide.md. Para ver lo que recibe realmente el modelo, ejecuta /memory show; /memory list muestra qué archivos se cargaron. Si editas un archivo a mitad de sesión, recárgalo con /memory reload.

Si tu repositorio ya tiene un AGENTS.md, no hace falta duplicarlo. Pon context.fileName en los ajustes como ["AGENTS.md", "GEMINI.md"]. CLAUDE.md vs AGENTS.md explica cómo mantener un único conjunto de reglas para varios agentes.

Paso 5: settings.json

Gemini CLI lee los ajustes de archivos JSON:

• ~/.gemini/settings.json para tus ajustes de usuario;
• .gemini/settings.json dentro de un proyecto para los ajustes del workspace.

Ejecuta /settings para cambiar la mayoría de las opciones en un editor dentro de la CLI en lugar de editar el JSON a mano. Un ejemplo pequeño:

{
  "general": {
    "defaultApprovalMode": "auto_edit",
    "checkpointing": { "enabled": true }
  },
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

El modelo se puede elegir por ejecución con -m / --model. Los alias auto (el predeterminado), pro, flash y flash-lite te permiten elegir por velocidad y profundidad sin recordar nombres exactos de modelos; /model lo cambia dentro de una sesión.

Paso 6: modos de aprobación y sandbox

Gemini CLI pregunta antes de ejecutar herramientas salvo que le digas lo contrario. El flag --approval-mode define el comportamiento:

El antiguo flag --yolo sigue existiendo, pero está obsoleto en favor de --approval-mode=yolo. Puedes hacer que auto_edit o plan sea el modo predeterminado en los ajustes; yolo solo se puede activar desde la línea de comandos.

El sandbox está desactivado por defecto. Arranca con --sandbox (o -s) para ejecutar las herramientas en un entorno aislado: Seatbelt en macOS, o un contenedor de Docker o Podman. Si vas a usar auto_edit o yolo con frecuencia, activa antes el sandbox. Seguridad de los agentes de programación con IA explica por qué las aprobaciones por sí solas no bastan.

Paso 7: conecta servidores MCP

Los servidores MCP dan a Gemini herramientas extra: búsqueda en documentación, un navegador, GitHub, tu base de datos. Añade uno desde la shell:

gemini mcp add github npx -y @modelcontextprotocol/server-github

Para un servidor HTTP, añade --transport http y una URL en lugar de un comando. --env CLAVE=valor pasa variables de entorno, y --scope user hace que el servidor esté disponible en todos los proyectos y no solo en este. gemini mcp list muestra lo que tienes configurado y gemini mcp remove <nombre> elimina un servidor.

Por debajo, todo esto se guarda en la sección mcpServers de settings.json, así que también puedes editarlo ahí. Dentro de una sesión, /mcp lista los servidores y sus herramientas, /mcp auth inicia sesión en los servidores que usan OAuth y /mcp reload los reinicia. ¿El concepto es nuevo para ti? Lee qué es un servidor MCP. Cada servidor añade descripciones de herramientas a la ventana de contexto, así que quédate solo con los que uses.

Paso 8: los comandos slash que conviene conocer

También puedes escribir tus propios comandos. Un archivo .toml en ~/.gemini/commands/ se convierte en un comando slash personal, y uno en .gemini/commands/ dentro de un proyecto se comparte con todos los que usan el repositorio. /commands list los muestra.

Paso 9: checkpointing y deshacer

Checkpointing es la red de seguridad de Gemini CLI y está desactivado por defecto. Actívalo en settings.json:

{
  "general": {
    "checkpointing": { "enabled": true }
  }
}

A partir de ahí, cada vez que apruebas una herramienta que cambia archivos, Gemini guarda primero una instantánea de tu proyecto en un repositorio git paralelo, separado, dentro de ~/.gemini/history/. No toca tu propio historial de git. Ejecuta /restore para ver la lista de checkpoints y /restore <id> para devolver tus archivos y la conversación a ese punto. Después, Gemini vuelve a ofrecerte la llamada a la herramienta original, para que la repitas, la cambies o la descartes.

Incluso sin checkpointing, /rewind (o Esc dos veces) te permite volver a un prompt anterior y elegir si deshaces la conversación, los cambios de código o ambos.

Paso 10: retoma sesiones

Gemini CLI guarda tus sesiones por proyecto:

• gemini --resume latest (o -r latest) continúa la sesión más reciente.
• gemini --list-sessions muestra las sesiones guardadas con números; gemini --resume 3 abre una de ellas.
• Dentro de una sesión, /resume te permite explorar, guardar y reabrir conversaciones.

También puedes pasar un prompt nuevo directamente: gemini -r latest "revisa los errores de tipos".

Consejos para obtener mejores resultados

• Haz commit antes de las tareas grandes. Los checkpoints están bien; un commit de git es mejor y funciona con cualquier herramienta.
• Di cómo verificarlo. “Ejecuta npm test y corrige los fallos” da mejores resultados que “haz que funcione”.
• Usa el modo plan para los cambios grandes. Deja que Gemini explore y proponga un plan antes de editar nada.
• Señala archivos con @. Es más rápido que esperar a que Gemini los encuentre y mantiene el contexto centrado.
• Comprime o limpia entre tareas. /compress conserva un resumen; /clear empieza de cero. Las dos cosas ahorran tokens.
• Un agente por worktree. Si ejecutas más de un agente, dale a cada uno su propio git worktree para que no se pisen.

Cuando una terminal no basta

Gemini CLI suele ser uno de varios agentes que usa un equipo. En cuanto quieres a Gemini en una tarea y a Codex o Claude Code en otra, o que un agente revise el trabajo de otro, una sola terminal se queda pequeña.

AgentVera es una app de escritorio para macOS, Windows y Linux que ejecuta Gemini CLI (y otros agentes CLI) en terminales reales, una al lado de otra. Cada agente de Gemini usa su propio inicio de sesión de Google o GEMINI_API_KEY; la terminal te pregunta cuál la primera vez. Consulta la página de Gemini CLI en AgentVera para más detalles.

• Workspace: una cuadrícula de agentes por proyecto, de 1×1 a 5×4. Cada agente de Gemini empieza con su propia sesión y la vuelve a abrir tras reiniciar.
• Permisos por agente: en el diálogo “New agent”, elige Ask, Auto o Full access.
• Instrucciones: Gemini CLI no tiene un flag para instrucciones extra, así que el campo “Role and instructions” de AgentVera no le llega. Pon las reglas en GEMINI.md o AGENTS.md.
• Gestor de MCP: los servidores que configuras en AgentVera se conectan a Gemini al arrancar, combinados por nombre con tus propios ajustes de Gemini.
• Flujos: pasa el resultado de un agente al siguiente; por ejemplo, Gemini escribe y otro agente revisa.
• Revisión de código: revisa automáticamente los cambios de un agente al final de cada turno.
• Worktrees: crea uno desde el panel Git e inicia un agente en él.

La cuadrícula, los worktrees, la revisión de código y el gestor de MCP están en el plan gratuito; los flujos están en Pro y Team. Descarga AgentVera y pruébalo en tu propio repositorio. Si usas una cuenta gratuita de Google, AgentVera también es compatible con Antigravity.

Conclusión

Instala Gemini CLI, ejecuta gemini y elige un inicio de sesión que siga funcionando después de junio de 2026: una API key de pago, Vertex AI o una licencia de Code Assist. Ejecuta /init y mantén corto tu GEMINI.md, fija tus valores por defecto con /settings y añade servidores MCP solo cuando los necesites. Quédate en el modo de aprobación predeterminado hasta que confíes en tu configuración, activa checkpointing para que /restore pueda deshacer ediciones y usa --resume latest para seguir donde lo dejaste. Para compararlo con el agente de OpenAI, lee cómo usar Codex CLI.