2. Instalación de Gemini CLI

Objetivo del tema

Aprender a preparar el entorno, instalar la versión estable de Gemini CLI y validar que la herramienta responda correctamente, tanto en escenarios individuales como de equipo.

Basamos cada paso en la documentación oficial actualizada para garantizar compatibilidad con los flujos de trabajo recomendados por Google.

2.1 Requisitos previos

Antes de ejecutar tu primer comando es importante comprobar que el entorno cumple con las versiones y dependencias necesarias. El proyecto declara los siguientes requisitos mínimos:

• Node.js 20 o superior: el paquete @google/gemini-cli especifica node >= 20 en su campo engines. Verifícalo con node -v y actualiza desde Node.js si es necesario.
• npm 10+ (incluido con Node 20) para realizar instalaciones globales o ejecutar npx. Si prefieres Yarn, asegúrate de contar con la versión clásica (v1) o con el comando yarn dlx habilitado.
• Acceso de red seguro: Gemini CLI consume la API hospedada por Google, por lo que necesitarás salida HTTPS para descargar paquetes e iniciar sesión con tu cuenta.
• Credenciales de Google preparadas para el proceso de autenticación que abordaremos en el siguiente tema. Por ahora alcanza con poder iniciar sesión en un navegador.
• Opcional: Docker o Podman si planeas usar el modo sandbox documentado oficialmente o desplegar la herramienta en entornos aislados.
• Opcional: Git y herramientas de compilación para quienes quieran trabajar desde el código fuente. El repositorio usa scripts de npm y requiere permisos para ejecutar procesos locales.

Si administras equipos, conviene validar estas dependencias en una imagen base o en un contenedor de referencia. Evita discrepancias entre estaciones de trabajo antes de avanzar con la autenticación.

2.2 Instalación vía npm / Yarn / otros métodos

La guía oficial Gemini CLI Installation, Execution, and Deployment describe cuatro estrategias principales. Elige la que mejor se adapte a tu flujo y documenta el proceso para futuros miembros del equipo.

2.2.1 Instalación global con npm

Recomendada para la mayoría de las personas usuarias. Descarga el paquete desde el registro de npm y exponlo como comando global:

npm install -g @google/gemini-cli

Una vez instalado, el comando gemini queda disponible en tu PATH. Si utilizas Yarn v1, el equivalente es:

yarn global add @google/gemini-cli

Tras la instalación inicial ejecuta gemini para confirmar que la interfaz interactiva responda y pueda iniciar el flujo de autenticación cuando corresponda.

2.2.2 Ejecución con npx o Yarn dlx

Cuando prefieras evitar instalaciones globales, utiliza la versión publicada en el registro directamente desde el cache temporal:

npx @google/gemini-cli

Con Yarn 3 o superior puedes ejecutar yarn dlx @google/gemini-cli, que descarga un paquete efímero para la sesión actual. Este enfoque es ideal para probar nuevas versiones sin alterar tu entorno base.

2.2.3 Ejecución en sandbox (Docker/Podman)

Para aislar el agente y minimizar riesgos de escritura directa en tu sistema, emplea la imagen oficial gemini-cli-sandbox:

docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1

Reemplaza la etiqueta por la versión vigente en la página de releases. Si ya instalaste el CLI de forma global, puedes orquestar la misma imagen con el flag --sandbox:

gemini --sandbox -y -p "run a health check"

La bandera -y confirma la ejecución sin preguntas adicionales y -p define el prompt inicial.

2.2.4 Código fuente y versiones de desarrollo

Si contribuyes al proyecto o necesitas probar una función específica no publicada, clona el repositorio y utiliza los scripts internos:

Paso	Acción
1	Ejecuta npm run start desde la raíz para habilitar el modo desarrollo con recarga en caliente.
2	Usa npm link packages/cli para simular una instalación global con el paquete que acabas de compilar.
3	Si deseas la última confirmación del repositorio sin clonar, recurre a npx https://github.com/google-gemini/gemini-cli.

Documenta cualquier dependencia adicional (por ejemplo, variables de entorno corporativas) antes de distribuir una versión personalizada a tu equipo.

2.3 Verificación de la instalación

Gemini CLI incluye un comando de versión que comprueba la integridad del binario y su comunicación con el entorno:

gemini --version

La salida devuelve el número de versión actualmente activo, como gemini cli 0.9.0. Complementa la verificación con alguno de los siguientes chequeos rápidos:

• Ejecuta gemini para abrir el flujo interactivo e iniciar sesión cuando el tutorial lo indique.
• Si trabajas en sandbox, corre gemini --sandbox -p "run shell command: env | grep GEMINI" y comprueba que el contenedor monte los recursos esperados.
• Valida que el directorio ~/.config/gemini (o su equivalente en Windows) esté accesible para almacenar configuraciones futuras.

En equipos distribuidos, guarda una captura del comando gemini --version en la wiki interna para acelerar diagnósticos si aparecen discrepancias entre estaciones.

2.4 Desinstalación

Cuando necesites liberar espacio o resolver incidentes, sigue el método correspondiente al tipo de instalación:

2.4.1 Limpieza del cache de npx / Yarn dlx

Las ejecuciones efímeras quedan en el directorio _npx dentro del cache de npm. Bórralo para eliminar binarios antiguos:

rm -rf "$(npm config get cache)/_npx"

En Windows tienes dos alternativas equivalentes:

rmdir /s /q "%LocalAppData%\npm-cache\_npx"

Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force

2.4.2 Desinstalación global con npm o Yarn

Para revertir una instalación permanente ejecuta:

npm uninstall -g @google/gemini-cli

Si usaste Yarn v1 reemplaza el comando por yarn global remove @google/gemini-cli. Finalmente revisa que which gemini (o where gemini en Windows) ya no devuelva rutas residuales.

Conclusión: con el entorno preparado, la instalación validada y las rutas de desinstalación documentadas, estás listo para avanzar hacia la autenticación y configuración del CLI.