Curso de Gemini CLI

Este es un curso de Hazla con Datos. ¡Bienvenido al taller de Gemini CLI! En este curso, aprenderás a instalar, configurar y utilizar la interfaz de línea de comandos (CLI) de Gemini para potenciar tu flujo de trabajo de desarrollo.

Videos complementarios

Gemini CLI no es solo un chat; es un agente colaborativo que vive en tu terminal, entiende tu código y puede ejecutar tareas complejas utilizando herramientas del sistema.

TÚ ERES EL PILOTO, LA IA ES TU COPILOTO

Antes de empezar, hay algo fundamental que debes entender: un agente de IA no reemplaza tu criterio como desarrollador. Lo amplifica.

Gemini CLI es una herramienta extraordinariamente capaz, pero necesita dirección. Puede generar código, refactorizar módulos enteros y automatizar tareas repetitivas — pero no sabe cuál es la arquitectura correcta para tu proyecto, qué trade-offs son aceptables para tu equipo, ni qué convenciones sigue tu organización.

Tu rol como desarrollador es supervisar, guiar y validar. Esto significa:

• Revisar siempre lo que genera. No aceptes código que no entiendas. Si no puedes explicar lo que hace, no debería estar en tu proyecto.
• Dar contexto claro. La calidad de la respuesta es directamente proporcional a la calidad de tu prompt. Un agente bien dirigido produce resultados profesionales; uno sin dirección produce código genérico.
• Saber cuándo decir no. Si la propuesta del agente no tiene sentido, recházala. Tienes el poder de aprobar, modificar o cancelar cualquier acción.
• Mantener tus fundamentos afilados. Cuanto más sepas de programación, terminal y arquitectura, mejor podrás supervisar y corregir al agente. La IA no es un atajo para evitar aprender.

La combinación más poderosa es un desarrollador con criterio técnico sólido + un agente de IA bien configurado. Este curso te enseña a construir exactamente eso.

LO QUE APRENDERÁS

• Cómo instalar y autenticar Gemini CLI
• Cómo interactuar con el modelo Gemini desde tu terminal
• Cómo dar contexto de tus archivos y organizar tu proyecto
• Cómo planificar antes de ejecutar (Plan Mode) y usar subagents
• Cómo utilizar herramientas integradas para navegar por internet
• Integración avanzada con MCP (Model Context Protocol)
• Qué son las Extensiones y cómo instalarlas
• Cómo crear tus propias Skills y subagents personalizados
• Cómo utilizar la memoria persistente (GEMINI.md) de forma iterativa

El primer paso es instalar la herramienta en tu sistema.

OPCIÓN 1: NPM (RECOMENDADO)

npm install -g @google/gemini-cli

OPCIÓN 2: HOMEBREW (macOS/Linux)

brew install gemini-cli

OPCIÓN 3: SIN INSTALAR (npx)

Si solo quieres probar sin instalar globalmente:

npx @google/gemini-cli

VERIFICAR INSTALACIÓN

gemini --version

CANALES DE ACTUALIZACIÓN

Gemini CLI ofrece tres canales de release:

• Stable (recomendado): npm install -g @google/gemini-cli@latest
• Preview (semanal, sin garantía): npm install -g @google/gemini-cli@preview
• Nightly (diario, experimental): npm install -g @google/gemini-cli@nightly

Ahora que estás dentro, ¡probemos lo básico!

CHAT BÁSICO

Escribe cualquier pregunta o instrucción directamente en el prompt.

• Intenta esto: Explica brevemente qué es la arquitectura MVC.

COMANDOS DE BARRA (/)

Gemini CLI tiene comandos especiales que empiezan con /. Estos son los más importantes:

Navegación y sesión:

• /help — Ver ayuda completa
• /clear — Limpiar la pantalla (o Ctrl+L)
• /quit o /exit — Salir de Gemini CLI
• /stats — Ver estadísticas de la sesión (tokens, modelo, herramientas)

Contexto y memoria:

• /memory show — Ver el contexto cargado desde archivos GEMINI.md
• /memory add <texto> — Agregar texto al archivo GEMINI.md global
• /memory refresh — Recargar archivos de contexto
• /compress — Comprimir el historial del chat en un resumen

Modelo y configuración:

• /model — Ver o cambiar el modelo activo
• /model set <modelo> — Cambiar a un modelo específico (ej. gemini-2.5-pro)
• /model manage — Gestión interactiva de modelos disponibles
• /permissions — Ver permisos actuales
• /permissions trust <ruta> — Confiar en un directorio para evitar confirmaciones
• /settings — Abrir el editor interactivo de configuración
• /theme — Cambiar el tema visual
• /tools — Ver herramientas disponibles

Historial y control:

• /chat save <tag> — Guardar un checkpoint de la conversación
• /chat resume <tag> — Reanudar desde un checkpoint
• /rewind — Retroceder en el historial (o Esc Esc)
• /restore — Restaurar archivos al estado previo a una herramienta
• /plan — Activar Plan Mode (solo lectura, planifica sin ejecutar)

Extensiones y skills:

• /extensions — Gestionar extensiones
• /skills — Gestionar Agent Skills
• /mcp — Ver estado de servidores MCP

Gemini CLI no solo lee, también puede ayudarte a organizar tu espacio de trabajo. Vamos a simular una carpeta desordenada y pedirle que la organice.

PREPARACIÓN

Abre una nueva terminal y crea un desorden simulado:

mkdir desorden
cd desorden
touch foto1.jpg foto2.png notas.txt script.py data.json todo.md config.yml
cd ..

LA TAREA

Entra en la carpeta desorden con Gemini CLI (o navega hasta ella). Prompt:

Estoy en la carpeta ‘desorden’. Mira los archivos que hay y organízalos en subcarpetas lógicas (ej. Imágenes, Documentos, Código). Muévelos automáticamente.

ACCIÓN

Gemini analizará los archivos (usando herramientas como list_directory) y propondrá un plan:

• Mover .jpg, .png a Imágenes/
• Mover .txt, .md a Documentos/
• Mover .py, .json, .yml a Código/ o Config/

Te pedirá confirmación para ejecutar los comandos run_shell_command (como mv ...). Acepta y observa cómo tu carpeta queda limpia en segundos.

PLAN MODE: PLANIFICAR ANTES DE EJECUTAR

Cuando la tarea es compleja o riesgosa, puedes usar Plan Mode: un entorno de solo lectura donde Gemini investiga tu proyecto y diseña un plan de implementación sin modificar ningún archivo.

¿PARA QUÉ SIRVE?

• Investigar el codebase antes de hacer cambios
• Evaluar alternativas y trade-offs
• Crear un plan de implementación detallado en Markdown
• Revisar y aprobar la estrategia antes de que se ejecute

CÓMO ACTIVARLO

Hay varias formas de entrar en Plan Mode:

• Desde el chat: escribe /plan o simplemente pide “planifica cómo…”
• Con Shift+Tab: cicla entre modos de aprobación (incluido Plan)
• Desde la terminal: gemini --approval-mode=plan
• En settings.json:

  { "experimental": { "plan": true } }

FLUJO DE TRABAJO

1. Investigación: Describes tu objetivo. Gemini explora el código en modo solo lectura.
2. Diseño: El agente hace preguntas clarificadoras y presenta opciones.
3. Plan: Genera un plan detallado en Markdown dentro del directorio de planes.
4. Revisión: Apruebas para proceder, iteras con feedback, o cancelas con Esc.

HERRAMIENTAS DISPONIBLES EN PLAN MODE

Gemini puede leer pero no escribir:

• Lectura de archivos, directorios y búsqueda (read_file, glob, grep_search)
• Búsqueda web (google_web_search)
• Sub-agentes de investigación
• Herramientas MCP de solo lectura
• Escritura únicamente de archivos .md en el directorio de planes

ROUTING AUTOMÁTICO DE MODELOS

Cuando usas selección automática de modelo, Plan Mode es inteligente:

• Fase de planificación: usa el modelo Pro (mayor razonamiento)
• Fase de implementación: cambia a Flash (más rápido) tras aprobar el plan

EJERCICIO PRÁCTICO

Prueba Plan Mode con un escenario real:

/plan

Planifica cómo agregarías tests unitarios al archivo game.js del Capstone Project. Analiza las funciones existentes y propón qué framework usar y qué casos de prueba cubrir.

Revisa el plan generado. Si te convence, aprueba y Gemini lo ejecutará. Si no, presiona Esc para cancelar sin que se haya tocado un solo archivo.

TIPS DE USO ESTRATÉGICO

• Empieza siempre en Plan Mode para tareas complejas. Invierte tu energía en el plan para que la implementación salga en un solo intento.
• Si algo sale mal, vuelve a Plan Mode. No sigas empujando con errores acumulados — re-planifica.
• Usa Plan Mode también para verificar, no solo para construir. Pide que planifique cómo validar o testear lo que ya se implementó.
• Puedes usar un enfoque de doble agente: genera el plan en una sesión y luego abre otra sesión para que lo revise como un ingeniero senior antes de ejecutar.

SUBAGENTS: DELEGAR TAREAS A AGENTES ESPECIALIZADOS

Los subagents son agentes especializados que operan dentro de tu sesión principal de Gemini CLI. Cada uno tiene su propio contexto, herramientas y sistema de instrucciones, sin contaminar la ventana de contexto principal.

¿POR QUÉ USARLOS?

• Contexto limpio: Cada subagent tiene su propia ventana de contexto, manteniendo tu sesión principal enfocada.
• Especialización: Puedes crear agentes expertos en seguridad, testing, documentación, etc.
• Más poder de cómputo: Agrega “usa subagents” a cualquier petición para que Gemini delegue en paralelo.

SUBAGENTS INTEGRADOS

Gemini CLI incluye subagents listos para usar:

CREAR SUBAGENTS PERSONALIZADOS

1. Habilita la funcionalidad en settings.json:

{
  "experimental": {
    "enableAgents": true
  }
}

2. Crea un archivo Markdown en .gemini/agents/ (proyecto) o ~/.gemini/agents/ (usuario):

---
name: security-auditor
description: "Encuentra vulnerabilidades de seguridad en el código"
tools:
  - read_file
  - grep_search
model: gemini-2.5-pro
temperature: 0.2
max_turns: 10
---
Eres un auditor de seguridad experto. Analiza el código buscando:

1. Inyecciones SQL y XSS
2. Secrets hardcodeados
3. Dependencias vulnerables
4. Permisos excesivos

Campos del frontmatter:

EJERCICIO: CREAR UN SUBAGENT DE DOCUMENTACIÓN

mkdir -p .gemini/agents
cat > .gemini/agents/doc-writer.md << 'EOF'
---
name: doc-writer
description: "Genera documentación técnica para funciones y módulos"
tools:
  - read_file
  - grep_search
  - list_directory
model: gemini-2.5-flash
max_turns: 8
---
Eres un escritor técnico. Cuando te pidan documentar código:

1. Lee el archivo completo para entender el contexto.
2. Identifica funciones, clases y exports públicos.
3. Genera JSDoc/TSDoc con descripción, parámetros y ejemplos.
4. Incluye un README.md si se trata de un módulo completo.
EOF

Luego pide:

Documenta todas las funciones del archivo game.js, usa subagents

Gemini CLI viene equipado con “herramientas” (Tools) que le dan superpoderes más allá de generar texto. Dos de las más útiles son google_web_search y web_fetch.

BÚSQUEDA WEB

¿Necesitas información actualizada que el modelo no tiene en su entrenamiento? Intenta esto:

Busca en internet el precio actual de la accion de Nvidia.

Gemini usará la herramienta google_web_search, obtendrá resultados reales y te dará una respuesta fundamentada.

LEER URLS ESPECÍFICAS

Si tienes un enlace a una documentación o artículo: Intenta esto:

Ingresa a https://en.wikipedia.org/wiki/Artificial_intelligence y dime de que trata

La herramienta web_fetch descargará el contenido de la página para que Gemini pueda analizarlo, incluso si es muy largo.

VER TODAS LAS TOOLS

Para ver qué herramientas tienes disponibles en tu sesión actual: /tools

MCP (Model Context Protocol) es un estándar abierto que permite a Gemini conectarse con tus datos y herramientas externas de forma segura. Piensa en ello como “plugins” universales para la IA.

¿QUÉ ES UN SERVIDOR MCP?

Un servidor MCP es una aplicación que expone herramientas y recursos al CLI a través del protocolo MCP. Soporta tres tipos de transporte:

• Stdio: Comunicación por subproceso (lo más común)
• SSE: Server-Sent Events
• HTTP: Streaming HTTP

AGREGAR UN SERVIDOR MCP

Desde la terminal:

gemini mcp add <nombre> <comando> [args...]

Ejemplo con GitHub:

gemini mcp add github npx -y @modelcontextprotocol/server-github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=tu_token

Opciones útiles:

• -s, --scope — user o project
• -t, --transport — stdio, sse o http
• -e, --env — Variables de entorno
• --trust — Omitir confirmaciones (solo servidores controlados por ti)

GESTIONAR SERVIDORES

gemini mcp list              # Ver servidores configurados
gemini mcp remove <nombre>   # Eliminar un servidor
gemini mcp enable <nombre>   # Habilitar
gemini mcp disable <nombre>  # Deshabilitar

CONFIGURACIÓN EN SETTINGS.JSON

También puedes configurar servidores directamente en settings.json:

{
  "mcpServers": {
    "miServidor": {
      "command": "python",
      "args": ["-m", "mi_servidor_mcp"],
      "env": { "API_KEY": "$MI_API_KEY" },
      "timeout": 15000
    }
  }
}

USO EN EL CHAT

• Las herramientas MCP aparecen junto a las built-in en /tools.
• Usa /mcp dentro de una sesión para ver el estado de los servidores.
• Para ejecutar una herramienta, describe la acción en lenguaje natural.
• Los servidores MCP pueden exponer prompts como slash commands personalizados.

Las Agent Skills permiten extender Gemini CLI con experiencia especializada y flujos de trabajo procedimentales. Son parte del estándar abierto Agent Skills.

¿CÓMO FUNCIONAN?

1. Gemini CLI inyecta los nombres y descripciones de las Skills en el system prompt.
2. Cuando el modelo identifica una tarea que coincide, invoca la herramienta activate_skill.
3. Tú confirmas la activación en un prompt de consentimiento.
4. El contenido del SKILL.md y acceso al directorio se pasan al agente.

UBICACIONES DE DESCUBRIMIENTO

Las Skills se buscan en tres niveles (en orden de prioridad):

1. Proyecto: .gemini/skills/ o .agents/skills/
2. Usuario: ~/.gemini/skills/ o ~/.agents/skills/
3. Extensiones: Skills incluidas en extensiones instaladas

CREAR UNA SKILL

Hay dos formas de crear una Skill:

Opción 1: Usando el skill-creator integrado

Simplemente pídelo en el chat:

Crea una nueva skill llamada “code-reviewer”

Gemini CLI generará automáticamente el directorio, el archivo SKILL.md con metadata, y las carpetas de soporte.

Opción 2: Creación manual

Crea el directorio y el archivo SKILL.md tú mismo.

ESTRUCTURA DE UNA SKILL

mi-skill/
├── SKILL.md        (obligatorio)
├── scripts/        (opcional — scripts ejecutables)
├── references/     (opcional — documentación estática)
└── assets/         (opcional — plantillas y recursos)

FORMATO DE SKILL.MD

El archivo combina frontmatter YAML con instrucciones en Markdown:

---
name: code-reviewer
description: >
  Usa esta skill para revisar código. Soporta
  cambios locales y Pull Requests remotos.
---
# Code Reviewer Instructions

Eres un experto revisor de código. Sigue este proceso:

1. Analiza buscando bugs lógicos.
2. Asegúrate de cumplir con las convenciones del proyecto.
3. Busca vulnerabilidades de seguridad (OWASP Top 10).
4. Sugiere mejoras de rendimiento si aplican.

Campos del frontmatter:

• name — Identificador único (debe coincidir con el nombre del directorio)
• description — Explica el propósito de la skill y cuándo Gemini debería activarla. Es clave para que el modelo la elija correctamente.

Cuerpo Markdown: Instrucciones claras y accionables que guían el comportamiento del agente cuando la skill está activa. Mientras más específico y estructurado, mejor será el resultado.

EJERCICIO: CREAR UNA SKILL DE “CODE REVIEWER”

1. Crea la estructura:

mkdir -p .gemini/skills/code-reviewer

2. Crea el archivo SKILL.md:

cat > .gemini/skills/code-reviewer/SKILL.md << 'EOF'
---
name: code-reviewer
description: >
  Experto en revisión de código. Actívala cuando
  el usuario pida un code review o revisión de código.
---
# Code Reviewer Instructions

Eres un experto revisor de código. Sigue este proceso:

1. Analiza buscando bugs lógicos y edge cases.
2. Verifica que se cumplan las convenciones del proyecto.
3. Busca vulnerabilidades de seguridad.
4. Evalúa la legibilidad y mantenibilidad.
5. Presenta los hallazgos en una tabla con severidad (alta/media/baja).
EOF

GESTIONAR SKILLS

Desde una sesión interactiva:

• /skills list — Listar skills disponibles
• /skills reload — Recargar definiciones
• /skills enable — Habilitar
• /skills disable — Deshabilitar

Desde la terminal:

gemini skills list
gemini skills install <repo_o_directorio>
gemini skills link <directorio_local>
gemini skills uninstall <nombre>

PROBANDO LA SKILL

/skills reload

Haz un code review de mi archivo game.js

TIPS: SACARLE EL MÁXIMO A LAS SKILLS

COMMITEA TUS SKILLS A GIT

Las Skills en .gemini/skills/ son parte de tu proyecto. Haz commit y reutilízalas en todos tus repositorios:

# Copiar skills a un nuevo proyecto
cp -r proyecto-a/.gemini/skills/ proyecto-b/.gemini/skills/

O mejor aún, mantén un repositorio de skills personales e instálalas con gemini skills install.

CONVIERTE TAREAS REPETITIVAS EN SKILLS

Si haces algo más de una vez al día, conviértelo en una Skill. Ejemplos prácticos:

• techdebt-hunter — Ejecutar al final de cada sesión para encontrar código duplicado y deuda técnica
• test-writer — Genera tests unitarios siguiendo las convenciones de tu proyecto
• pr-reviewer — Revisa PRs con checklist personalizado de tu equipo
• migrator — Automatiza migraciones de base de datos con pasos específicos

IDEAS DE SKILLS AVANZADAS

• Un skill que sincronice contexto de Slack, GitHub Issues y docs en un solo resumen
• Un skill de analytics que escriba queries, revise código y testee cambios
• Un skill de seguridad que audite dependencias y escanee secrets

settings.json controla el comportamiento del CLI: modelos, UI, contexto, seguridad y más.

UBICACIÓN

• Usuario: ~/.gemini/settings.json — configuración global
• Proyecto: .gemini/settings.json — configuración del proyecto (tiene prioridad)

EDITAR RÁPIDO

Desde el CLI: ejecuta /settings para abrir el editor interactivo con todas las opciones organizadas por categorías.

CATEGORÍAS DE CONFIGURACIÓN

EJEMPLO DE CONFIGURACIÓN

{
  "model": {
    "modelId": "gemini-2.5-flash"
  },
  "ui": {
    "theme": "github-dark"
  },
  "context": {
    "fileName": ["GEMINI.md", "CONTEXT.md"]
  },
  "tools": {
    "autoAccept": false
  }
}

CONFIGURACIÓN DE MODELOS

Puedes cambiar el modelo activo de varias formas:

• En la sesión: /model set <nombre>
• En settings.json: "model": { "modelId": "gemini-2.5-pro" }
• Gestión interactiva: /model manage

CARPETAS DE CONFIANZA

Para evitar que Gemini CLI pida confirmación cada vez que accede a un directorio:

/permissions trust /ruta/a/mi/proyecto