💡 Gemini CLI — Cheatsheet (Guía rápida)

El CLI de Gemini es una herramienta de código abierto que trae el poder de Gemini directamente a tu terminal, permitiéndote realizar una amplia gama de tareas —como programar, resolver problemas y gestionar tareas— usando lenguaje natural. Esta chuleta es un resumen rápido para instalar, configurar y usar Gemini CLI, con foco en usuarios que se autentican mediante una clave de API de Gemini. (Referencia: philschmid/gemini-samples).

In Questo Articolo

🚀 Comenzando

Instalación

Instalar globalmente:

npm install -g @google/gemini-cli

Ejecutar sin instalar:

npx @google/gemini-cli

Autenticación con una clave API de Gemini

Autentícate con una clave API antes del primer uso. Consulta la guía de autenticación en el repositorio oficial para más detalles.

Obtén tu clave: Consigue una clave API en Google AI Studio.
Configura la clave: Hazla accesible para el CLI de una de estas maneras: Método 1 — Variable de entorno del shell
Añade en tu perfil de shell (por ejemplo ~/.bashrc, ~/.zshrc): export GEMINI_API_KEY="TU_GEMINI_API_KEY" Método 2 — Archivo .env
Crea un archivo .env en ~/.gemini/ para uso global o en ./.gemini/ para un proyecto específico. El CLI lo cargará automáticamente: # En .gemini/.env GEMINI_API_KEY="TU_GEMINI_API_KEY"

📖 Invocación básica

Modo interactivo (REPL):
Inicia una sesión conversacional:

gemini

Modo no interactivo:
Pasa un prompt y obtén una sola respuesta:

gemini -p "Resume los puntos principales del archivo adjunto. @./summary.txt"

Piping hacia el CLI:

echo "Cuenta hasta 10" | gemini

Modo sandbox:
Ejecuta herramientas en un entorno seguro (requiere Docker o Podman):

gemini --sandbox -p "tu prompt"

Otros flags:

-m, --model <model>: Usar un modelo específico.
-i, --prompt-interactive <prompt>: Iniciar sesión interactiva con un prompt inicial.
-d, --debug: Activar salida de depuración.
--yolo: Auto-aprobar todas las llamadas a herramientas.
--checkpointing: Guardar snapshot del proyecto antes de modificar archivos. Usa /restore para revertir cambios.

(Consulta el listado completo de flags en la documentación oficial.)

⚙️ Configuración

Archivos de settings (`settings.json`)

Personaliza el CLI creando un settings.json. El orden de precedencia es:

Proyecto: .gemini/settings.json (sobrescribe usuario y sistema).
Usuario: ~/.gemini/settings.json (sobrescribe sistema).
Sistema: /etc/gemini-cli/settings.json (prioridad más baja).

Ejemplo settings.json:

{
  "theme": "GitHub",
  "autoAccept": false,
  "sandbox": "docker",
  "vimMode": true,
  "checkpointing": { "enabled": true },
  "fileFiltering": { "respectGitIgnore": true },
  "usageStatisticsEnabled": true,
  "includeDirectories": ["../shared-library", "~/common-utils"],
  "chatCompression": { "contextPercentageThreshold": 0.6 },
  "customThemes": {
    "MyCustomTheme": {
      "name": "MyCustomTheme",
      "type": "custom",
      "Background": "#181818",
      "Foreground": "#F8F8F2",
      "LightBlue": "#82AAFF",
      "AccentBlue": "#61AFEF",
      "AccentPurple": "#C678DD",
      "AccentCyan": "#56B6C2",
      "AccentGreen": "#98C379",
      "AccentYellow": "#E5C07B",
      "AccentRed": "#E06C75",
      "Comment": "#5C6370",
      "Gray": "#ABB2BF"
    }
  }
}

Opciones destacadas:

autoAccept: Auto-aprobar llamadas a herramientas de solo lectura seguras.
sandbox: Aislar ejecución de herramientas (true, "docker", "podman").
vimMode: Habilitar edición estilo Vim para el prompt.
checkpointing: Habilitar /restore para deshacer cambios en archivos.
includeDirectories: Definir workspace multi-directorio.
chatCompression: Configurar compresión automática del historial de chat.
customThemes: Definir temas personalizados.
usageStatisticsEnabled: Poner false para desactivar estadísticas de uso.

(Ver la guía de configuración para todos los detalles.)

Archivos de contexto (`GEMINI.md`)

Usa GEMINI.md para dar instrucciones al modelo y adaptar el comportamiento al proyecto. Usa /init para generar un GEMINI.md inicial.

Carga jerárquica:
El CLI combina GEMINI.md desde varias ubicaciones; archivos más específicos sobreescriben los generales. Orden de carga:

Contexto global: ~/.gemini/GEMINI.md (instrucciones aplicables a todos tus proyectos).
Contexto del proyecto/ancestros: El CLI busca desde tu directorio actual hacia la raíz del proyecto GEMINI.md.
Contexto de subdirectorios: También escanea subdirectorios para instrucciones específicas de componentes.

Usa /memory show para ver el contexto combinado final que se envía al modelo.

Modularizar contexto con imports:
Puedes organizar GEMINI.md importando otros archivos Markdown con la sintaxis @file.md. Solo soporta .md.

Ejemplo GEMINI.md con imports:

# Contexto principal del proyecto: Mi App Asombrosa

## Instrucciones generales
- Todo código Python debe cumplir PEP 8.
- Usa indentación de 2 espacios para archivos nuevos.

## Guías por componente
@./src/frontend/react-style-guide.md
@./src/backend/fastapi-style-guide.md

(Ver la guía completa de archivos de contexto.)

Ignorar archivos con `.geminiignore`

Crea .geminiignore en la raíz del proyecto para excluir archivos y carpetas de las herramientas de Gemini, similar a .gitignore.

Ejemplo .geminiignore:

/backups/
*.log
secret-config.json

🛠️ Trabajando con herramientas

Algunas herramientas incorporadas

Herramientas de sistema de ficheros: interactuar con archivos y directorios — list_directory(path="/src"), glob(pattern="src/**/*.ts"), read_file(path="/path/to/file.txt"), write_file(file_path="/path/to/new_file.js", content="console.log('hello');"), replace(file_path="...", old_string="...", new_string="..."), search_file_content(pattern="myFunction", include="*.js").
Shell Tool: ejecutar comandos shell. Usar con precaución. Para restringir, usa excludeTools en settings.json, por ejemplo: "excludeTools": ["run_shell_command(rm)"].
Web Tools: recuperar contenido y buscar en línea — google_web_search(query="Gemini API rate limits"), web_fetch(prompt="Summarize https://my-blog.com/article").
Memory Tool: guardar y recordar información entre sesiones — save_memory(fact="Mi framework CSS preferido es Tailwind CSS.").

Herramientas personalizadas vía servidores MCP

Extiende el CLI con tus propias herramientas ejecutando servidores MCP (Model Context Protocol). Administra servidores vía settings.json o gemini mcp <add|list|remove>.

Capacidades:

Soporte OAuth 2.0 para conectar servidores remotos de forma segura.
Retornos con contenido multimodal (texto, imágenes).
Exponer prompts predefinidos como comandos slash en el CLI.

Ejemplo de configuración mcpServers:

"mcpServers": {
  "myPythonServer": {
    "command": "python",
    "args": ["-m", "my_mcp_server", "--port", "8080"],
    "cwd": "./mcp_tools/python",
    "env": {
      "DATABASE_URL": "$DB_URL_FROM_ENV"
    },
    "timeout": 15000,
    "trust": false,
    "includeTools": ["safe_tool_1", "safe_tool_2"],
    "excludeTools": ["dangerous_tool"]
  }
}

Transporte (elige uno):

command, args, cwd: lanzar proceso local vía stdio.
url: endpoint SSE (ej. http://localhost:8080/sse).
httpUrl: endpoint HTTP streaming (ej. http://localhost:8080/mcp).

Opcional:

env: variables de entorno (usa $VAR_NAME para referenciar).
headers: cabeceras HTTP para url/httpUrl.
timeout: tiempo de espera en ms (por defecto: 10 min).
trust: omitir confirmaciones de herramientas para este servidor.
includeTools/excludeTools: whitelist/blacklist de herramientas (exclude prevalece).

(Toma en cuenta el documento de soporte OAuth para MCP servers si usas OAuth.)

⚡ Comandos principales

Comandos slash útiles (`/`)

Comando	Descripción
`/compress`	Reemplaza todo el contexto del chat por un resumen para ahorrar tokens.
`/copy`	Copiar la última respuesta al portapapeles.
`/mcp`	Listar servidores MCP configurados y sus herramientas.
`/clear`	Limpiar la pantalla y el contexto (`Ctrl+L` también funciona).
`/tools`	Listar herramientas disponibles.
`/extensions`	Listar extensiones activas.
`/stats`	Mostrar uso de tokens y ahorros.
`/memory show`	Mostrar el contexto combinado de todos los `GEMINI.md`.
`/memory refresh`	Recargar todos los `GEMINI.md`.
`/chat save <tag>`	Guardar la conversación actual con una etiqueta.
`/chat resume <tag>`	Reanudar una conversación guardada.
`/chat list`	Listar etiquetas de conversaciones guardadas.
`/restore`	Listar o restaurar un checkpoint del proyecto.
`/auth`	Cambiar método de autenticación actual.
`/bug`	Reportar un bug del Gemini CLI.
`/help`	Mostrar ayuda y comandos.
`/theme`	Cambiar tema visual del CLI.
`/quit`	Salir del Gemini CLI.
`/ide`	Gestionar integración con tu IDE (ej. `install`, `enable`).
`/settings`	Abrir editor para `settings.json`.
`/vim`	Alternar modo Vim para edición de input.
`/init`	Generar `GEMINI.md` inicial para un proyecto.
`/directory`	Gestionar directorios en un workspace multi-directorio (por ejemplo `add`, `show`).

Comandos de contexto (`@`)

Referencia archivos o directorios en tu prompt. El CLI respeta .gitignore y .geminiignore. También puedes referenciar imágenes, PDFs, audio y vídeo.

Incluir un solo archivo: > Explícame este código. @./src/main.js
Incluir una imagen: > Describe lo que ves en esta captura. @./ux-mockup.png
Incluir un directorio entero (recursivo): > Refactoriza el código en este directorio a async/await. @./src/

Comandos de Shell (`!`)

Ejecuta comandos shell directamente desde el CLI.

Ejecutar un comando único: > !git status
Alternar modo Shell persistente:
Escribe ! solo para entrar en modo shell persistente; escribe ! otra vez para salir.

Atajos de teclado

Atajo	Descripción
`Ctrl+L`	Limpiar pantalla.
`Ctrl+V`	Pegar texto o imagen desde el portapapeles.
`Ctrl+Y`	Alternar modo YOLO (auto-aprobar todas las llamadas a herramientas).
`Ctrl+X`	Abrir el prompt actual en un editor externo.

✨ Funciones avanzadas

Integración IDE (VS Code)

Contexto del workspace: obtiene tus archivos recientes, posición del cursor y texto seleccionado.
Diff nativo: ver y aprobar cambios directamente en el diff del editor.
Comandos: /ide install para instalar integración, /ide enable para habilitarla.

Comandos personalizados

Crea comandos personalizados usando archivos TOML. Guárdalos en ~/.gemini/commands/ (global) o <proyecto>/.gemini/commands/ (por proyecto). Pueden usarse para exponer prompts reutilizables.

Ejemplo ~/.gemini/commands/test/gen.toml:

# Invocado como: /test:gen "Crea un test para el botón de login"
description = "Genera un unit-test basado en la descripción."
prompt = """
Eres un ingeniero de pruebas experto. Basado en el siguiente requisito, escribe un unit-test completo usando Jest.

Requisito: {{args}}
"""

Extensiones

Crea extensiones para añadir funcionalidad. Colócalas en <workspace>/.gemini/extensions/ o ~/.gemini/extensions/. Cada extensión es un directorio con gemini-extension.json que puede configurar MCP servers, herramientas y archivos de contexto.

Ejemplo gemini-extension.json:

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node my-server.js"
    }
  },
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command"]
}

(Ver la guía de extensiones para más detalles.)

Checkpointing & Restore

Con checkpointing activado, el CLI guarda un snapshot del proyecto antes de que las herramientas modifiquen archivos.

Activar con flag o en settings.json:

gemini --checkpointing

Restaurar a un estado anterior:

# Listar checkpoints disponibles
/restore

# Restaurar un checkpoint específico
/restore <checkpoint_file_name>

Si quieres, puedo convertir esta traducción en un archivo Markdown listo para subir al repositorio o al blog. ¿Lo dejo en Markdown y te lo muestro?