3. Autenticación en Gemini CLI

Objetivo del tema

Configurar de forma segura la autenticación requerida por Gemini CLI, comprendiendo las alternativas disponibles, su alcance y las buenas prácticas necesarias para proteger tus credenciales.

El CLI admite autenticación con cuenta de Google, API keys de Google AI o credenciales de Vertex AI. Seleccionaremos el método según el entorno y las políticas de tu organización.

3.1 Opciones de autenticación disponibles

Al ejecutar gemini por primera vez, el CLI propone un menú interactivo con las tres alternativas principales:

Método Uso recomendado Consideraciones clave
Login con cuenta de Google Personas usuarias individuales, Google AI Pro o Ultra, estaciones de trabajo con navegador disponible. Requiere abrir una URL localhost para vincular la sesión. Puede solicitar GOOGLE_CLOUD_PROJECT en suscripciones empresariales.
API key de Google AI Studio Integraciones rápidas, scripts simples o entornos sin navegador. La API key se exporta vía variable de entorno; debe resguardarse y rotarse según políticas internas.
Credenciales Vertex AI Equipos en Google Cloud, despliegues en CI/CD y escenarios headless. Permite usar Application Default Credentials, service accounts o API key de Vertex AI. Requiere definir proyecto y región.

Si trabajas en Cloud Shell, la autenticación suele estar resuelta automáticamente con las credenciales del entorno. Aún así, conviene conocer las opciones para replicar el setup en local.

3.2 Configuración paso a paso según el método

Los pasos siguientes siguen la guía oficial. Elige el método que mejor encaje en tu flujo y documenta la configuración para el resto del equipo.

3.2.1 Inicio de sesión con cuenta de Google

  1. Ejecuta gemini y selecciona Login with Google.
  2. El CLI abrirá una URL en tu navegador local. Inicia sesión con la cuenta asociada a tu suscripción o a tu organización.
  3. Si se solicita un proyecto de Google Cloud, define una variable persistente con el ID correspondiente: 
    export GOOGLE_CLOUD_PROJECT="tu-proyecto"

    Puedes utilizar GOOGLE_CLOUD_PROJECT_ID como alternativa. Prioriza la variante sin sufijo para mantener compatibilidad.

  4. Confirma el acceso regresando a la terminal; el CLI cachea las credenciales en tu perfil local.

Si permutas entre varios proyectos, crea perfiles de shell con variables distintas o usa un archivo .gemini/.env para cada repositorio.

3.2.2 Uso de Gemini API Key

  1. Obtén la clave desde Google AI Studio.
  2. Exporta la variable de entorno antes de lanzar el CLI: 
    export GEMINI_API_KEY="tu_api_key"
  3. Si deseas mantenerla disponible en cada sesión, agrégala a tu archivo de inicio (~/.bashrc, ~/.zshrc) o a ~/.gemini/.env. Este último es preferible para limitar el alcance a Gemini CLI.
  4. Almacena la API key en un gestor seguro y revócala inmediatamente si sospechas de uso indebido.

3.2.3 Integración con Vertex AI

Vertex AI ofrece tres alternativas, todas ellas exigen definir proyecto y ubicación:

export GOOGLE_CLOUD_PROJECT="tu-proyecto"
export GOOGLE_CLOUD_LOCATION="us-central1"

Luego, elige una de las opciones:

  • Application Default Credentials (ADC): 
    unset GOOGLE_API_KEY GEMINI_API_KEY
gcloud auth application-default login

    Ideal para desarrolladoras y desarrolladores con gcloud instalado. Asegúrate de que la cuenta tenga la API de Vertex AI habilitada.

  • Service Account JSON: 
    unset GOOGLE_API_KEY GEMINI_API_KEY
export GOOGLE_APPLICATION_CREDENTIALS="/ruta/credenciales.json"

    Asigna el rol Vertex AI User y resguarda el archivo fuera del repositorio. Es la opción preferida para CI/CD.

  • API key de Vertex AI: 
    export GOOGLE_API_KEY="api_key_vertex_ai"

    Consulta la guía oficial para generarla. Algunas organizaciones restringen este tipo de credencial; si aparece el error API keys are not supported, migra a ADC o service account.

3.3 Manejo seguro de tokens y persistencia

Protege tus credenciales tanto en repositorios como en estaciones de trabajo compartidas:

  • Evita guardar API keys o rutas sensibles en archivos que se versionan. Prefiere .gemini/.env (no versionado) o gestores de secretos corporativos.
  • Cuando uses variables en la shell, limita su alcance al proyecto actual. Puedes crear un script que exporte y luego limpie las variables al finalizar.
  • Revisa periódicamente el cache del CLI en ~/.config/gemini (Linux/macOS) o %APPDATA%\Gemini CLI (Windows) y elimina sesiones que ya no necesites.
  • Configura recordatorios de rotación según la política de seguridad de tu organización.

Una buena práctica es almacenar versiones enmascaradas de las variables en la documentación interna, de modo que cualquier persona pueda verificar rápidamente si la configuración está completa sin revelar el secreto.

3.4 Resolución de errores frecuentes

La documentación oficial destaca incidentes que suelen aparecer durante la configuración:

  • Falta de variables en modo headless: si ejecutas el CLI en CI/CD sin haber cacheado una sesión previa, debes definir todas las variables necesarias o el proceso fallará.
  • Conflicto entre métodos: antes de cambiar de API key a ADC (o viceversa) ejecuta unset GOOGLE_API_KEY GEMINI_API_KEY para evitar credenciales residuales.
  • Proyecto o ubicación no establecidos: los errores 403 o 404 en Vertex AI suelen indicar que falta GOOGLE_CLOUD_PROJECT o que la ubicación no coincide con la instancia configurada.
  • Restricciones corporativas: si tu organización bloquea el uso de API keys, recurre a service accounts con el rol adecuado o consulta al equipo de seguridad.

Conclusión: establecer una autenticación consistente es el paso final para habilitar todas las capacidades de Gemini CLI. Con credenciales protegidas y las variables bien documentadas, estarás listo para avanzar al ajuste fino de configuración en el siguiente tema.

Retornar