Gemini CLI no funciona: arregla errores de instalación, autenticación e inicio
¿Gemini CLI no arranca, rechaza tu inicio de sesión con Google o lanza "'gemini' is not recognized"? Aquí tienes la reparación del PATH de Windows, los dos fallos reales de inicio de sesión con cuenta de Google y la decisión entre OAuth y clave API, en el orden en que se solucionan.
En resumen
- El error "'gemini' is not recognized" tras una instalación npm limpia es un problema de PATH, no una instalación rota. Ejecuta npm config get prefix, añade la carpeta que muestra (C:\Users\<tu-usuario>\AppData\Roaming\npm) al PATH de usuario y vuelve a abrir la terminal.
- ¿El inicio de sesión falla con "This account requires setting the GOOGLE_CLOUD_PROJECT env var"? Las cuentas individuales gratuitas, AI Pro o AI Ultra NO lo necesitan — solo las cuentas Workspace, las licencias de Code Assist, los menores de 18 años y las regiones sin soporte gratuito.
- "Not eligible for Gemini Code Assist for individuals … 18 years old or older" significa que tu cuenta de Google no tiene una edad confirmada. Verifica tu edad en la página de estado de edad de Google y vuelve a ejecutar gemini para iniciar sesión.
- ¿Sigues bloqueado tras dos inicios de sesión fallidos? Deja OAuth a un lado: crea una clave API de Gemini en AI Studio y expórtala como GEMINI_API_KEY — tiene su propio nivel gratuito. Los fallos de autenticación salen con el código 41.
How to Fix Gemini CLI is Not Recognized Error in Windows (Step by Step)
Canal: Web Tech Knowledge4:38
Several error issues encountered when logging into Gemini CLI with a Google account
Canal: AttackOnLife2:56
Troubleshooting — official documentation
Documentación oficial: google-gemini.github.io
Authentication setup — official documentation
Documentación oficial: google-gemini.github.io
Cada comando, mensaje de error y cuadro de diálogo de esta página se contrastó con la documentación oficial de autenticación y solución de problemas de Gemini CLI. La grabación de Windows es la fuente visual de la instalación y la reparación del PATH; la de macOS aporta los dos fallos reales de inicio de sesión con Google y el flujo de verificación de edad que los resuelve.
Las capturas pertenecen a sus creadores y enlazan al momento exacto; no se usa ninguna imagen con rostro.
Arreglar Gemini CLI, paso a paso
Parte 1 — "'gemini' is not recognized": reparar el PATH de Windows
- 1
Primero reproduce el fallo exacto
En la grabación, npm install -g @google/gemini-cli termina limpiamente — "changed 577 packages in 4m" — y al escribir gemini aún devuelve "'gemini' is not recognized as an internal or external command, operable program or batch file.". Igual en la terminal de VS Code. Ese texto es la firma de un problema de PATH: el paquete está instalado, pero Windows no tiene idea de dónde dejó npm el lanzador.
577 paquetes instalados y aun así gemini responde "is not recognized" — síntoma de PATH, no una instalación rota.Ver desde 0:08 - 2
Pregúntale a npm dónde instala los lanzadores globales
Ejecuta npm config get prefix. Imprime la carpeta que npm usa para los paquetes globales — aquí C:\Users\User\AppData\Roaming\npm. Ahí vive precisamente el comando gemini, y esa es la carpeta que falta en el PATH. Anótala o déjala en el portapapeles.
npm config get prefix imprime C:\Users\User\AppData\Roaming\npm — la carpeta que el PATH necesita.Ver desde 0:54 - 3
Mostrar AppData en el Explorador de archivos
La carpeta npm está bajo el directorio AppData de tu perfil de usuario, que Windows oculta por defecto. En el Explorador, en C:\Users\User, abre Vista > Mostrar y marca Elementos ocultos — la grabación hace exactamente eso y AppData aparece enseguida en la lista.
Vista > Mostrar > Elementos ocultos hace visible AppData bajo C:\Users\User.Ver desde 1:30 - 4
Confirmar que el lanzador existe en la carpeta npm
Navega a AppData > Roaming > npm. Ahí está gemini.cmd — el script de comandos de Windows que ejecuta el comando gemini — junto a gemini (el script de shell para Unix) y node_modules. Que exista demuestra que la instalación salió bien y solo el PATH está roto.
gemini.cmd, un script de comandos de Windows de 347 bytes, dentro de AppData\Roaming\npm.Ver desde 2:02 - 5
Abrir el cuadro de diálogo Variables de entorno
Busca "variables de entorno" en el menú Inicio, abre "Editar las variables de entorno del sistema" y pulsa el botón Variables de entorno. La mitad inferior son variables del sistema; la superior — donde el cursor de la grabación apunta a PATH — son las variables de usuario de tu cuenta. El PATH de usuario es el sitio correcto para una carpeta npm propia de tu cuenta.
Cuadro Variables de entorno con el cursor sobre PATH en las variables de usuario.Ver desde 2:38 - 6
Añadir la carpeta npm como nueva entrada del PATH
Selecciona PATH, pulsa Editar y luego Nuevo, y pega el prefijo npm del paso 2 — C:\Users\User\AppData\Roaming\npm. Confirma con Aceptar en todos los cuadros abiertos. En la grabación, la lista ya contiene entradas de Python, Ollama y VS Code; la fila vacía nueva queda debajo. El orden no influye en este arreglo.
Cuadro Editar variable de entorno: la nueva entrada PATH vacía seleccionada, lista para pegar la carpeta npm.Ver desde 3:01
Parte 2 — El inicio de sesión falla: resolver los dos errores de la cuenta de Google
- 7
Reconocer los dos errores de inicio de sesión con Google
Arreglado el PATH, gemini arranca y pregunta cómo iniciar sesión — elige "Login with Google". La segunda grabación muestra los dos fallos que bloquean inicios de sesión reales. Error uno: "Failed to login. Message: This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID env var." Error dos: "Failed to login. Message: Your current account is not eligible for Gemini Code Assist for individuals. To use Gemini Code Assist for individuals you must be 18 years old or older."
Ambos mensajes "Failed to login" al pie de la letra: el requisito de GOOGLE_CLOUD_PROJECT y el rechazo por ser menor de 18.Ver desde 0:35 - 8
No fijes GOOGLE_CLOUD_PROJECT si no es necesario
La discusión de los mantenedores #13516, "Clarifying Authentication and Google Cloud Project Settings", visible en la grabación, aclara cuándo hace falta la variable: NO debes fijarla si inicias sesión como particular con una cuenta gratuita, AI Pro o AI Ultra. Es obligatoria para cuentas Workspace, licencias de Code Assist, menores de 18 años y cuentas fuera de las regiones con nivel gratuito. Si la fijaste con un plan personal, quítala y vuelve a iniciar sesión.
Discusión gemini-cli #13516: cuándo NO fijar GOOGLE_CLOUD_PROJECT con cuentas gratuitas, AI Pro y AI Ultra.Ver desde 1:05 - 9
Verifica tu edad si Google rechazó el inicio de sesión
El rechazo "not eligible … 18 years old or older" no va de tu cumpleaños real, sino del confirmado. La cuenta de la grabación no tenía edad verificada, así que Google muestra la página de estado de edad con "Your age isn't confirmed" y un botón azul Verify your age. Completa ese flujo (el creador usó el pasaporte), vuelve a ejecutar gemini y elige Login with Google — el mismo inicio de sesión ahora funciona.
"Your age isn't confirmed" con el botón Verify your age — una vez resuelto, el inicio de sesión pasa.Ver desde 1:35
Parte 3 — Demostrar el arreglo en una terminal nueva
- 10
Relanzar en un símbolo del sistema totalmente nuevo
Las terminales abiertas antes del cambio de PATH conservan el PATH antiguo. Cierra todas las ventanas y abre un símbolo del sistema nuevo. Escribe gemini: aparece el banner ASCII de GEMINI con "Tips for getting started" y, como la sesión corre en el directorio personal, la recomendación de usar un directorio de proyecto — es un aviso, no un error.
Primer arranque con éxito: el banner GEMINI y los consejos de inicio en el símbolo del sistema.Ver desde 4:08 - 11
Confirmar que también funciona en VS Code
La grabación termina en VS Code: con la terminal ya abierta en una carpeta de proyecto real (G:\TestProject), gemini imprime el banner, muestra "no sandbox" al pie y deja el cursor en "Type your message or @path/to/file". Si VS Code estaba abierto durante el cambio de PATH, ciérralo y vuelve a abrirlo — la misma regla que el símbolo del sistema.
Terminal de VS Code en G:\TestProject con el banner GEMINI y el cuadro de entrada listo.Ver desde 4:32
Gemini CLI sigue sin funcionar — las causas menos comunes
El PATH y los dos errores de inicio de sesión cubren la mayoría de los casos. Si Gemini CLI sigue colgada, lenta o con errores después, recorre esta lista de arriba abajo:
- 1Reinstala en vez de adivinar. La documentación oficial de solución de problemas manda los fallos de PATH/npm directo a npm install -g @google/gemini-cli@latest; la grabación además comprueba que Node.js siga en el PATH del sistema — un Node borrado o un npm a medio actualizar deja a gemini.cmd apuntando a la nada.
- 2¿Atascado en "Initializing" o esperando la autenticación? Esa pantalla espera a que termine el flujo OAuth del navegador. Si no se abrió ninguna pestaña, vuelve a ejecutar gemini y completa Login with Google en la pestaña que describe; un proxy o una red sin conexión cuelgan justo en ese paso.
- 3¿La autenticación falla una y otra vez? Un inicio de sesión fallido termina con el código 41, y las credenciales de Google en caché viven en ~/.gemini (oauth_creds.json junto a settings.json). Borra las credenciales en caché y vuelve a ejecutar gemini — inicia sesión limpiamente en lugar de reintentar una sesión rota.
- 4¿OAuth no termina nunca? Cambie de método. La tercera opción del cuadro de autenticación es una clave API de Gemini de Google AI Studio: expórtela como GEMINI_API_KEY y la CLI se salta por completo el flujo del navegador. La documentación recomienda primero el inicio con Google, pero la clave API tiene su propio nivel gratuito y no exige proyecto ni edad.
- 5¿Errores de acceso a modelos o de cuota? Las cuentas de Gmail vinculadas a Workspace pueden no activar el nivel gratuito de Code Assist ("Request contains an invalid argument") — las salidas oficiales son fijar GOOGLE_CLOUD_PROJECT con un ID de proyecto real o pasarse a la clave API. Los límites gratuitos se reinician; los planes de pago AI Pro/Ultra los suben.
- 6¿Fallan solo en VS Code? Es otra vez la regla de la terminal obsoleta: VS Code hereda el PATH al arrancar, y una ventana abierta antes del cambio jamás ve la carpeta npm. Cierra y reabre VS Code (al menos tu terminal) y prueba gemini de nuevo.
¿Nada de lo anterior encaja? Lee lo que la propia CLI registró: los registros y ajustes viven bajo ~/.gemini, y relanzar con --verbose imprime más detalle; la página oficial de solución de problemas acaba como los mantenedores — busca en el seguimiento de issues de gemini-cli en GitHub y abre uno nuevo con tu versión y el texto completo del error.