Cómo cambiar el directorio de gemini cli

El Gemini CLI de código abierto de Google —el agente de IA basado en terminal que lleva Gemini a tu shell— ha madurado rápidamente desde su lanzamiento y ahora admite configuración avanzada, archivos de contexto de proyecto (GEMINI.md / .gemini), comandos personalizados con barra y controles del directorio del espacio de trabajo. El proyecto evoluciona activamente en GitHub (repositorio oficial), ha entrado en vista previa pública con cuotas generosas y se está integrando en otras herramientas de desarrollo (integraciones con editores y CI/Actions). Pero a medida que los equipos escalan, o cuando trabajas entre unidades o en entornos restrictivos (contenedores, portátiles gestionados por la empresa, Cloud Shell, sistemas Windows), rápidamente te encontrarás con una pregunta práctica: ¿dónde almacena Gemini sus archivos y cómo puedes cambiar qué directorios lee y escribe?

¿Qué es Gemini CLI?

Gemini CLI es el agente de IA de línea de comandos de código abierto de Google que lleva el poder de los modelos Gemini directamente a tu terminal. Proporciona capacidades de agente interactivo para asistencia de código, inspección de archivos y proyectos, ejecución de comandos de shell (con salvaguardas) e integración de herramientas como Google Search, extensiones del Model Context Protocol (MCP) y herramientas de generación de medios incluidas con Gemini. El CLI está pensado para ser ligero, scriptable y extensible; está disponible desde el repositorio oficial y empaquetado para una instalación sencilla.

Por qué importa el directorio

Gemini CLI almacena la configuración (por ejemplo, settings.json), prompts del sistema o contexto (GEMINI.md), credenciales en caché, identificadores de telemetría y otro estado persistente dentro de un directorio .gemini. Dónde vive ese directorio controla:

• qué configuración carga el CLI (global vs. específica del proyecto),
• qué archivos de “memoria” leerá el agente,
• dónde se almacenan las credenciales en caché (afecta al comportamiento de inicio de sesión),
• la reproducibilidad entre máquinas o en CI cuando quieres proporcionar un repositorio de configuración personalizado.

Entender y (si es necesario) cambiar el directorio ayuda en flujos de trabajo multi-proyecto, CI, despliegues en contenedores y equipos con repositorios de configuración centralizados.

¿Dónde almacena la configuración Gemini CLI por defecto?

Por defecto, el CLI usa un directorio .gemini. En la mayoría de instalaciones de usuario eso se resuelve como ~/.gemini (la carpeta .gemini en tu directorio personal). El CLI también admite archivos .gemini a nivel de proyecto (p. ej., .gemini/settings.json en la raíz del proyecto) que sobrescriben la configuración del usuario mientras trabajas desde esa carpeta del proyecto. La configuración a nivel de sistema se lee desde ubicaciones específicas del SO (por ejemplo /etc/ en Linux o %PROGRAMDATA% en Windows) cuando aplica. Rutas típicas:

• Linux / macOS: ~/.gemini/ (por ejemplo /home/alice/.gemini o /Users/alice/.gemini).
• Windows: %USERPROFILE%\.gemini (p. ej., C:\Users\Alice\.gemini).
  Dentro de .gemini normalmente encontrarás settings.json, GEMINI.md, commands/ y cachés locales. El CLI también lee carpetas .gemini/ por proyecto (raíz del proyecto) para configuraciones a nivel de proyecto.

Este valor predeterminado es importante: históricamente el directorio de configuración se ha codificado de forma fija como .gemini en el directorio personal

---

¿Cómo puedo cambiar o redirigir el directorio de configuración de Gemini CLI?

Hay varias formas prácticas — desde la más simple (trabajar en la carpeta deseada) hasta las más robustas (variables de entorno o redirecciones del sistema de archivos). Elige un enfoque según si controlas el entorno de ejecución (máquina de desarrollo local vs. CI), en qué SO estás y si prefieres un cambio temporal o permanente.

1) Usa un .gemini a nivel de proyecto (recomendado para configuración por proyecto)

Si quieres configuraciones por proyecto, crea un subdirectorio .gemini en la raíz de tu proyecto y coloca ahí settings.json, GEMINI.md y otros archivos del proyecto. Gemini CLI prefiere la configuración del proyecto cuando lo ejecutas desde ese directorio del proyecto:

your-project/├─ .gemini/│  ├─ settings.json│  └─ GEMINI.md└─ src/

Inicia gemini mientras tu shell está en your-project/ y el CLI recogerá los archivos .gemini de ese árbol (busca hacia arriba para encontrar el contexto del proyecto). Este es el método más seguro y explícito para configuración por proyecto.

2) Usa variables de entorno documentadas (cuando estén soportadas)

La base de código y la documentación de Gemini CLI hacen referencia a varias variables de entorno usadas para alterar comportamientos. Algunas están pensadas para configuración del sistema o para reemplazos especiales de archivos:

• GEMINI_API_KEY, GEMINI_MODEL, etc. se usan comúnmente para autenticación y elección de modelo.
• Hay referencias en el código y la documentación a variables como GEMINI_CLI_SYSTEM_SETTINGS_PATH (usada para sobrescribir la ruta de ajustes del sistema) y constantes como GEMINI_CONFIG_DIR (el nombre .gemini predeterminado usado en el código). Algunas solicitudes de la comunidad y PRs proponen añadir u honrar una variable de entorno GEMINI_CONFIG_DIR para permitir a los usuarios reubicar todo el directorio de configuración.

Ejemplo (bash / macOS / Linux):

# Temporary for this shell sessionexport GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir"​# Or override system settings path if your install supports it:export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/my-gemini/system.settings.json"​# Then rungemini

PowerShell (Windows):

$env:GEMINI_CONFIG_DIR = 'C:\Users\you\CustomGemini'gemini

Advertencia importante: según los últimos debates e incidencias de la comunidad, GEMINI_CONFIG_DIR se ha solicitado y está referenciada en el código en algunos lugares — pero se han reportado errores específicos de plataforma y comportamientos inconsistentes (especialmente en Windows). Eso significa que la redirección basada en variables de entorno puede no ser uniformemente fiable en todas las plataformas o versiones. Revisa las notas de versión de Gemini CLI y las incidencias del repositorio para tu versión instalada si dependes de esto.

3) Agrega directorios al espacio de trabajo de Gemini dentro de una sesión

Si quieres que Gemini sea consciente de directorios adicionales (para que pueda leer archivos como contexto), existe el conjunto de comandos interactivos /directory. Por ejemplo:

/directory add path/to/another/project/directory list

Esto no mueve el directorio de configuración, pero permite que el agente incluya archivos de otros directorios en su contexto de espacio de trabajo. Es útil cuando quieres que el agente haga referencia a otros repositorios sin cambiar tu configuración global.

4) Crea un enlace simbólico o vinculación del sistema de archivos (solución práctica)

Si el CLI no acepta reemplazos mediante variables de entorno o necesitas una solución fiable entre procesos, usa una redirección del sistema de archivos:

En Unix/macOS:

# move the original config foldermv ~/.gemini ~/gemini_backup​# create a symlink to your desired locationln -s /path/to/central/gemini-config ~/.gemini

En Windows (PowerShell con privilegios administrativos):

# Move the original directoryMove-Item -Path $env:USERPROFILE\.gemini -Destination C:\GeminiConfigBackup​# Create a junction (administrator)New-Item -ItemType Junction -Path $env:USERPROFILE\.gemini -Target C:\CentralGeminiConfig

Este enfoque fuerza al CLI a leer desde la ubicación deseada sin requerir soporte nativo en el CLI. Nota: los enlaces simbólicos/junctions requieren privilegios adecuados del sistema de archivos y pueden comportarse de forma diferente en contenedores o entornos Windows. Úsalo con cuidado. (Consulta las “Notas específicas de Windows” más abajo).

5) Cambia el directorio personal efectivo del proceso (truco para contenedor/CI)

Al ejecutar en CI, contenedores o entornos efímeros, puedes cambiar la variable $HOME (Unix) o %USERPROFILE% (Windows) para el proceso gemini de modo que su ~/.gemini predeterminado se resuelva a una ruta que controles:

# Run gemini with a custom HOME (bash)HOME=/ci/workspace/you gemini --some-command​# Or in a container DockerfileENV HOME=/app/userRUN mkdir -p /app/user/.geminiCOPY config /app/user/.gemini

Esto es útil para la reproducibilidad en CI, pero ten en cuenta: cambiar HOME puede afectar a otras herramientas y flujos de autenticación (p. ej., cachés de Google OAuth), así que limita esta técnica a contenedores aislados o envoltorios a nivel de proceso.

¿Cómo puedo instalar y usar Gemini CLI vía CometAPI?

Respuesta corta: tienes dos caminos prácticos — (A) llamar a los modelos Gemini directamente a través de CometAPI (recomendado y más simple), o (B) hacer que el Gemini CLI oficial hable con CometAPI usando una versión de Gemini-CLI que admita una URL base personalizada (algunas versiones/PRs lo añaden), o ejecutando un pequeño proxy local que traduzca las solicitudes de Gemini-CLI a llamadas estilo CometAPI/OpenAI.

¿Qué es CometAPI?

CometAPI es una pasarela/agregador de API que expone cientos de modelos de terceros (incluida la familia Gemini de Google) detrás de una API HTTP estilo OpenAI. Te registras, obtienes una clave de API de portador y llamas a endpoints como https://api.cometapi.com/v1/chat/completions. CometAPI usa tokens de portador estándar en el encabezado Authorization.

¿Por qué usar CometAPI? Ofrece precios de API más bajos que la API oficial para facilitar la integración. Guía de Instalación y Uso de Gemini CLI:

¿Cómo puedo llamar a los modelos Gemini directamente vía CometAPI? (Recomendado)

Si tu objetivo es simplemente usar modelos Gemini y no necesitas estrictamente las funciones de Gemini CLI, llamar directamente a CometAPI es sencillo y fiable.

export COMET_KEY="sk-xxxx"​curl -s -X POST "https://api.cometapi.com/v1/chat/completions" \  -H "Authorization: Bearer $COMET_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gemini-2.5-pro",    "messages": [      {"role": "system", "content": "You are a helpful assistant."},      {"role": "user", "content": "Summarize the 3 key benefits of unit tests."}    ],    "max_tokens": 300  }' | jq .

Estas llamadas directas te permiten integrar CometAPI en scripts, aplicaciones o CI sin depender de Gemini CLI.

¿Puedo hacer que Gemini CLI use CometAPI?

Algunas versiones/PRs de Gemini CLI añaden variables de entorno para sobrescribir la URL base de la API de Gemini. Si tu gemini instalado admite configurar una URL base personalizada de la API de Gemini y usar la clave de CometAPI, puedes apuntarlo a CometAPI y establecer la clave de CometAPI como GEMINI_API_KEY (el CLI espera una variable de clave llamada GEMINI_API_KEY para la autenticación de la API de Gemini).

Ejemplo:

# example env — *check your gemini-cli docs for exact var names*export GEMINI_API_KEY="sk-xxxxx"                    # CometAPI keyexport GOOGLE_GEMINI_BASE_URL="https://api.cometapi.com/v1"  # if supportedgemini   # run the CLI; it will use the configured base URL

Solución de problemas: problemas comunes y soluciones

Problema: Gemini no puede ver archivos en otro repositorio

1. Prueba gemini --include-directories /path/to/repo al iniciar. O en sesión: /directory add /path/to/repo.
2. Si el repositorio está en un montaje de red, verifica permisos y que el usuario del proceso del CLI pueda leer los archivos.
3. Si usaste un enlace simbólico para mover .gemini, verifica que el CLI siga el enlace simbólico para GEMINI.md y settings.json (algunas versiones no siguen ciertos enlaces simbólicos por seguridad).

Problema: gemini no logra crear ~/.gemini en Windows (EPERM)

Normalmente significa que tu proceso no tiene permiso para escribir en %USERPROFILE%. Soluciones:

• Ejecuta la terminal como Administrador o ajusta los permisos de la carpeta.
• Establece una ubicación de configuración personalizada mediante enlace simbólico o, cuando esté soportado, mediante variable de entorno (estate atento al futuro soporte de GEMINI_CONFIG_DIR).

Problema: cd no cambia el directorio de trabajo dentro del modo shell

Es un problema reconocido en algunas plataformas. Recomendación: cambia a ejecutar comandos de shell fuera del proceso de Gemini CLI o agrega directorios vía /directory add.

Problema: los nombres de modelos de CometAPI no coinciden con lo que espero

Llama al endpoint /v1/models e inspecciona el JSON. Los IDs de modelos a menudo contienen cadenas exactas de variante (p. ej., gemini-2.5-flash-preview-04-17). Usa la cadena exacta en tu solicitud.

Conclusión

El diseño predeterminado de Gemini CLI favorece un comportamiento sensato y fácil de descubrir: un ~/.gemini global para valores predeterminados a nivel de usuario y un .gemini del proyecto para sobrescrituras por repositorio. La comunidad ha impulsado una mayor configurabilidad nativa (variables de entorno explícitas o flags) para hacer la herramienta más amigable en entornos multiusuario, con contenedores y empresariales.

Cómo cambiar el directorio de Gemini CLI:

Descripción general: Gemini CLI almacena la configuración y archivos de contexto a nivel de usuario en un directorio .gemini (normalmente ~/.gemini). Puedes influir en qué directorio usa el CLI mediante (1) confiar en el .gemini a nivel de proyecto en el directorio de trabajo actual, (2) usar variables de entorno u opciones del CLI cuando estén soportadas, (3) añadir directorios de espacio de trabajo dentro de una sesión interactiva o (4) usar técnicas del sistema de archivos (enlaces simbólicos, bind mounts o cambiar las variables home/profile) cuando falten opciones nativas.

Para empezar, explora las capacidades de los modelos Gemini (como Gemini 3 Pro) en el Playground y consulta la guía de la API para instrucciones detalladas. Antes de acceder, asegúrate de haber iniciado sesión en CometAPI y de haber obtenido la clave de API. CometAPI ofrece un precio mucho más bajo que el oficial para ayudarte a integrar.

¿Listo para empezar? → Prueba gratuita de modelos Gemini !