# Cómo usar Gemini CLI: guía paso a paso URL: https://agentvera.dev/es/blog/how-to-use-gemini-cli/ · Publicado: 2026-10-25 Cómo usar Gemini CLI: instálalo, elige el inicio de sesión tras el cambio de junio de 2026, escribe GEMINI.md, ajusta settings.json, añade MCP y deshaz con checkpoints. **En resumen:** - Instala Gemini CLI con npm, Homebrew o MacPorts, o pruébalo con npx; después ejecuta gemini en la carpeta de un proyecto y elige un método de inicio de sesión. - Desde el 18 de junio de 2026, los usuarios del nivel gratuito y de Google One pasaron a Antigravity CLI; Gemini CLI funciona ahora con API keys de pago, Vertex AI y Code Assist Standard o Enterprise. - Las reglas del proyecto van en GEMINI.md, los ajustes en .gemini/settings.json, los servidores MCP se añaden con gemini mcp add, y checkpointing con /restore deshace ediciones. 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](/es/glossary/coding-agent/ "Qué 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](/es/blog/gemini-cli-vs-claude-code/ "Gemini CLI vs Claude Code") y [Codex vs Gemini CLI](/es/blog/codex-vs-gemini-cli/ "Codex vs Gemini CLI"). ## Paso 1: instala Gemini CLI Gemini CLI necesita Node.js. Elige la instalación que encaje con tu entorno: | Método | Comando | | --- | --- | | Probarlo sin instalar | `npx @google/gemini-cli` | | npm (cualquier plataforma) | `npm install -g @google/gemini-cli` | | macOS, Linux (Homebrew) | `brew install gemini-cli` | | macOS (MacPorts) | `sudo port install gemini-cli` | 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: ```bash gemini --version ``` ## Paso 2: elige cómo iniciar sesión Entra en un proyecto y arráncalo: ```bash 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. ```bash 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](/es/blog/gemini-cli-vs-claude-code/ "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](https://ai.google.dev/gemini-api/docs/pricing "Precios de la API de Gemini") para ver las tarifas actuales. ## Paso 3: tu primera tarea Empieza con algo pequeño y real: ```text 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: ```markdown # 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](/es/blog/claude-md-agents-md/ "CLAUDE.md y 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: ```json { "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: | Modo | Qué pasa | | --- | --- | | `default` | Pregunta antes de cada llamada a una herramienta | | `auto_edit` | Aprueba automáticamente las ediciones de archivos, pero sigue preguntando antes de otras herramientas, como los comandos de shell | | `plan` | Solo lectura: Gemini puede mirar y planificar, pero no cambiar nada | | `yolo` | Aprueba todas las llamadas a herramientas; solo para un entorno aislado | 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](/es/blog/ai-coding-agent-security/ "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](/es/glossary/mcp/ "Qué es MCP") dan a Gemini herramientas extra: búsqueda en documentación, un navegador, GitHub, tu base de datos. Añade uno desde la shell: ```bash 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 ` 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](/es/blog/what-is-mcp-server/ "Qué es un servidor MCP"). Cada servidor añade descripciones de herramientas a la [ventana de contexto](/es/glossary/context-window/ "Qué es la ventana de contexto"), así que quédate solo con los que uses. ## Paso 8: los comandos slash que conviene conocer | Comando | Qué hace | | --- | --- | | `/init` | Genera un `GEMINI.md` para el proyecto | | `/memory show` | Muestra las instrucciones que recibe el modelo | | `/settings` | Abre el editor de ajustes | | `/model` | Cambia el modelo | | `/auth` | Cambia el método de inicio de sesión | | `/mcp` | Lista los servidores MCP y sus herramientas | | `/tools` | Lista las herramientas que Gemini puede usar | | `/stats` | Uso de la sesión, del modelo y de las herramientas | | `/compress` | Sustituye la conversación por un resumen para ahorrar tokens | | `/clear` | Limpia la pantalla y empieza de cero | | `/resume` | Explora y retoma sesiones guardadas | | `/rewind` | Retrocede en la conversación (también Esc dos veces) | | `/restore` | Restaura archivos desde un checkpoint | | `/directory` | Añade más carpetas al workspace | | `/help` | Lista todos los comandos | 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`: ```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 ` 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](/es/blog/git-worktree-parallel-agents/ "Git worktrees para agentes en paralelo") 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](/es/agents/gemini-cli/ "Gemini CLI en AgentVera") para más detalles. - **[Workspace](/es/features/workspace/ "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](/es/features/mcp-manager/ "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](/es/features/flows/ "Flujos"):** pasa el resultado de un agente al siguiente; por ejemplo, Gemini escribe y otro agente revisa. - **[Revisión de código](/es/features/code-review/ "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](/es/features/git-and-github/ "Git y GitHub") 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](/es/download/ "Descargar AgentVera") y pruébalo en tu propio repositorio. Si usas una cuenta gratuita de Google, AgentVera también es compatible con [Antigravity](/es/agents/antigravity/ "Antigravity en AgentVera"). ## 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](/es/blog/how-to-use-codex-cli/ "Cómo usar Codex CLI"). ## Preguntas frecuentes **¿Gemini CLI sigue siendo gratis?** No para cuentas personales. Según el aviso de Google, el 18 de junio de 2026 los usuarios del nivel gratuito y de Google One pasaron a Antigravity CLI. Gemini CLI sigue funcionando con API keys de Gemini de pago, Vertex AI y licencias de Gemini Code Assist Standard o Enterprise. **¿Qué diferencia hay entre GEMINI.md y AGENTS.md?** Los dos son archivos Markdown con instrucciones del proyecto. Gemini CLI lee GEMINI.md por defecto. Si tu equipo ya guarda las reglas en AGENTS.md, pon context.fileName en settings.json como una lista, por ejemplo ["AGENTS.md", "GEMINI.md"], y Gemini CLI leerá ambos. **¿Cómo evito que Gemini CLI ejecute comandos sin preguntar?** Quédate en el modo de aprobación predeterminado, que pregunta antes de cada llamada a una herramienta. auto_edit aprueba las ediciones de archivos pero sigue preguntando antes de otras herramientas, y yolo lo aprueba todo, así que úsalo solo dentro de un sandbox de confianza. **¿Cómo deshago un cambio que hizo Gemini CLI?** Activa checkpointing en settings.json. Gemini CLI guardará entonces una instantánea antes de cada edición de archivos, y /restore devuelve tus archivos a su estado. Sin checkpointing, /rewind (o Esc dos veces) aún te deja retroceder por la conversación y sus cambios de archivos. **¿Cómo continúo una sesión anterior de Gemini CLI?** Arranca Gemini CLI con --resume latest para continuar la sesión más reciente, o ejecuta gemini --list-sessions y retoma una por su número. Dentro de una sesión, /resume te deja explorar y elegir una conversación guardada. --- **Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/