Domina Gemini CLI, el asistente de IA para tu terminal. Guía completa que te enseñará a instalar, configurar, crear atajos y solucionar cualquier error en el camino.

Imagina poder conversar con tu computadora, pidiéndole en lenguaje normal que organice archivos, escriba un correo electrónico, analice datos o incluso desarrolle un programa complejo desde cero. Esa es la realidad que ofrece Gemini CLI, una herramienta gratuita y de código abierto (open-source) de Google que instala un potente asistente de inteligencia artificial directamente en tu terminal.

Esta guía es tu mapa completo y definitivo. Está diseñada para llevarte de la mano, sin importar si nunca has usado una terminal o si eres un desarrollador experto. Empezaremos con la preparación, te guiaremos por la instalación, resolveremos todos los errores comunes y terminaremos con flujos de trabajo avanzados y ejemplos prácticos para cada necesidad.

Sección 1: Instalación y configuración inicial

Para empezar, necesitamos preparar nuestro sistema. Este proceso se divide en dos pasos clave: instalar el “motor” que necesita la herramienta (Node.js) y luego instalar Gemini CLI de forma global.

Paso 1: Instalar Node.js, el motor de Gemini CLI

Node.js es el entorno de ejecución que permite que Gemini CLI funcione. La instalación es sencilla y segura.

Visita el sitio web oficial: nodejs.org. Verás dos versiones para descargar. Elige siempre la versión LTS (Long Term Support), que es la más estable y recomendada.

• En Windows: Descarga el instalador .msi y sigue el asistente de instalación con las opciones por defecto.
• En macOS: Usa el instalador .pkg de la web oficial o, si usas Homebrew, ejecuta brew install node en tu terminal.
• En Linux (Ubuntu/Debian): Ejecuta los siguientes comandos en tu terminal:
  curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Para verificar que la instalación fue exitosa en cualquier sistema, abre una nueva terminal y ejecuta el comando node -v. Debería devolverte un número de versión.

Paso 2: Instalar Gemini CLI de forma global

Para un uso regular y para poder crear accesos directos, la instalación debe ser “global”. Esto hace que el comando gemini esté disponible desde cualquier lugar en tu terminal.

En tu terminal, ejecuta:

npm install -g @google/gemini-cli

Sección 2: Resolución de problemas comunes de instalación (Windows)

Es muy probable que, en un sistema Windows, te encuentres con uno de los siguientes errores. Aquí están las soluciones en el orden en que suelen aparecer.

Problema 1: Error “la ejecución de scripts está deshabilitada”

Si al ejecutar `npm` ves un error rojo sobre “ejecución de scripts deshabilitada”, es una protección de Windows.

1. Busca “PowerShell” en el menú Inicio, haz clic derecho y selecciona “Ejecutar como administrador”.
2. Pega el siguiente comando y presiona Enter:
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
3. Confirma el cambio escribiendo S y presionando Enter.
4. Cierra la ventana de administrador y abre una terminal normal. El error habrá desaparecido.

Problema 2: Error “‘pm’ no se reconoce como nombre de un cmdlet”

Si al intentar un comando recibes este error, es simplemente un error de tipeo. El comando correcto no es `pm`, sino `npm` (Node Package Manager).

Solución: Vuelve a escribir el comando correctamente, asegurándote de usar `npm`.

Problema 3: Error “El sistema no puede encontrar el archivo especificado” (error 0x80070002)

Este es el error más común. Ocurre si intentas ejecutar `gemini` y Windows no lo encuentra. La solución es decirle a Windows dónde buscar, añadiendo su ubicación al PATH del sistema.

Paso 1: Encuentra dónde instaló `npm` la herramienta

1. Abre una nueva terminal.
2. Ejecuta el comando:
   npm config get prefix
3. El comando te devolverá una ruta, usualmente C:\Users\TuUsuario\AppData\Roaming\npm. Copia esta ruta.

Paso 2: Añade la ruta al PATH de Windows

1. Presiona la tecla de Windows, escribe “Editar las variables de entorno del sistema” y selecciónalo.
2. En la ventana de “Propiedades del sistema”, haz clic en “Variables de entorno…”.
3. En la sección de arriba (“Variables de usuario”), busca una variable llamada “Path” y haz doble clic.
4. Haz clic en “Nuevo” y pega la ruta que copiaste.
5. Haz clic en “Aceptar” en todas las ventanas para guardar los cambios.

Paso 3: Reinicia la terminal

Este paso es crucial: Cierra TODAS las ventanas de la terminal que tengas abiertas y abre una nueva para que Windows cargue la nueva configuración del PATH. Tu comando `gemini` y cualquier acceso directo ahora funcionarán.

Sección 3: Configuración de credenciales y uso diario

Paso 1: Configurar tu API Key para uso persistente

Para no tener que iniciar sesión cada vez, la mejor opción es usar una API Key.

1. Ve a Google AI Studio, inicia sesión y crea una nueva clave de API. Cópiala.
2. En Windows: Abre una terminal y ejecuta:
   setx GEMINI_API_KEY "TU_API_KEY_AQUI"
3. En macOS y Linux: Añade la siguiente línea a tu archivo ~/.zshrc o ~/.bashrc:
   export GEMINI_API_KEY="TU_API_KEY_AQUI"

Recuerda cerrar y abrir una nueva terminal para que los cambios surtan efecto.

Paso 2: Crear un acceso directo para iniciar Gemini al instante

Ahora que todo está configurado, puedes crear un atajo.

• En Windows: Crea un nuevo acceso directo en el escritorio y en “Ubicación del elemento”, pega:
  wt -p "Default" --title "Gemini CLI" gemini
• En macOS y Linux: Añade un alias a tu archivo ~/.zshrc o ~/.bashrc:
  alias gcli='gemini'
  Ahora podrás iniciar la herramienta simplemente escribiendo `gcli`.

Sección 4: Ejemplos prácticos para todos los niveles

Aquí es donde la magia ocurre. Veamos cómo Gemini CLI puede ayudarte en diferentes escenarios.

Para principiantes: tu asistente personal para el día a día

• Planificar un viaje:
  "Planifícame un viaje de 3 días a la Ciudad de México. Quiero un itinerario que combine historia, comida y arte. Sugiere museos, restaurantes de comida típica y alguna actividad al aire libre. @search"
• Aprender un nuevo concepto:
  "Explícame qué es la inflación como si tuviera 10 años, usando una analogía con caramelos. @search"
• Escribir un correo electrónico profesional:
  "Redacta un correo electrónico formal para mi jefe. El objetivo es solicitar un día de vacaciones para el próximo viernes. Sé amable y profesional."
• Generar ideas creativas:
  "Dame 10 ideas de nombres para un blog sobre cocina vegana fácil y económica."

Para estudiantes y académicos: tu aliado en la investigación

• Resumir un artículo científico (PDF):
  "Lee este artículo de investigación y resume sus puntos clave: la hipótesis, la metodología, los resultados principales y la conclusión. @ruta/al/paper.pdf"
• Generar preguntas de estudio:
  "Basado en el contenido de este documento sobre la Revolución Francesa, genera 15 preguntas de opción múltiple para un examen. @apuntes_historia.txt"
• Analizar datos de un archivo CSV:
  "Tengo este archivo CSV con datos de ventas. Explícame qué columnas contiene, calcula las ventas totales y dime cuál fue el producto más vendido. @ventas_trimestre.csv"
• Traducir y explicar citas:
  "Traduce esta cita de latín al español y explícame su significado en el contexto filosófico de Séneca: 'Non scholae, sed vitae discimus'. @search"

Para desarrolladores: tu copiloto de codificación

• Generar una API desde cero:
  "Escribe una API REST básica usando Flask en Python. Debe tener un endpoint '/saludo' que devuelva un JSON con el mensaje 'Hola, mundo'."
• Depurar un error complejo:
  "Mi aplicación de Node.js está fallando. Este es el log de errores. Analízalo, explícame la causa raíz probable y sugiéreme el código para solucionarlo. @error.log"
• Refactorizar y mejorar código:
  "Lee esta función en mi archivo y refactorízala para que sea más eficiente y siga las mejores prácticas de código limpio. Añade comentarios explicando los cambios. @utils.py"
• Escribir pruebas unitarias:
  "Tengo una función llamada 'calcular_iva' en mi archivo 'calculos.js'. Escribe un conjunto de pruebas unitarias para esta función usando el framework Jest, cubriendo los casos de éxito y los casos de borde. @calculos.js"

Para usuarios avanzados y DevOps: el motor de la automatización

• Crear scripts de automatización:
  "Escribe un script de shell (bash) que haga lo siguiente: 1. Comprima todos los archivos .log de la carpeta /var/log en un archivo tar.gz con la fecha de hoy. 2. Mueva el archivo comprimido a /mnt/backups. 3. Elimine los archivos .log originales que tengan más de 7 días."
• Generar configuración de infraestructura (IaC):
  "Crea un archivo de configuración de Docker Compose (docker-compose.yml) para un servicio web que consta de un frontend en React y un backend en Node.js, conectados a una base de datos PostgreSQL."
• Uso dentro de un script para generar informes:
  #!/bin/bashScript para generar un informe diario del sistema
  echo “Generando informe del sistema para $(date)…” > informe.txt

  Pedir a Gemini que resuma los logs de errores del sistema
  gemini -p “Resume los errores críticos encontrados en los siguientes logs del sistema” @/var/log/syslog >> informe.txt
  echo “Informe generado en informe.txt”

Sección 5: Técnicas avanzadas y buenas prácticas

Personaliza el comportamiento de Gemini con `GEMINI.md`

Para proyectos específicos, puedes crear un archivo llamado GEMINI.md en la raíz de tu proyecto. El contenido de este archivo actúa como un conjunto de instrucciones de sistema permanentes.

Ejemplo de un archivo GEMINI.md para un proyecto web:

Eres un asistente experto en desarrollo full-stack con React y Django.
- Todo el código de frontend que generes debe estar en TypeScript y usar hooks de React.
- El código de backend debe seguir las mejores prácticas de Django.
- La base de datos es PostgreSQL.
- Prioriza la seguridad en todas tus sugerencias.

Mejores prácticas de seguridad

• Revisa siempre antes de ejecutar: Gemini CLI siempre te pedirá permiso antes de ejecutar un comando. Lee cuidadosamente lo que propone.
• Trata el código generado como una revisión: El código de IA es un excelente punto de partida, pero revísalo como si fuera de un nuevo miembro del equipo antes de ponerlo en producción.
• Evita los privilegios de administrador: No ejecutes Gemini CLI con sudo o como Administrador a menos que sea absolutamente necesario.

Sección 6: Referencia rápida y preguntas frecuentes

Tabla de referencia (cheatsheet)

Preguntas frecuentes (FAQ)

¿En qué se diferencia de GitHub Copilot CLI?

Gemini CLI se enfoca más en un modelo conversacional y de razonamiento (actúa como un agente que puede planificar y ejecutar pasos), mientras que Copilot CLI se centra más en la sugerencia y traducción de comandos. Además, Gemini CLI es de código abierto.

¿Puedo usarlo sin conexión a internet?

No. Gemini CLI se conecta a los modelos de IA de Google en la nube y requiere una conexión a internet activa para funcionar.

¿Es realmente gratuito?

Sí, para uso personal. Con una cuenta de Google y una API Key personal, obtienes acceso al modelo Gemini 2.5 Pro con límites muy altos (miles de solicitudes por día) sin costo alguno.