Comment changer le répertoire du CLI Gemini

Le Gemini CLI open source de Google — l’agent IA en ligne de commande qui apporte Gemini dans votre shell — a rapidement mûri depuis son lancement et prend désormais en charge une configuration riche, des fichiers de contexte de projet (GEMINI.md / .gemini), des commandes slash personnalisées et des contrôles des répertoires d’espace de travail. Le projet évolue activement sur GitHub (dépôt officiel), est entré en préversion publique avec des quotas généreux, et est en cours d’intégration dans d’autres outils développeur (intégrations pour éditeurs et CI/Actions). Mais à mesure que les équipes se développent, ou lorsque vous travaillez sur plusieurs disques ou dans des environnements restrictifs (conteneurs, ordinateurs portables gérés par l’entreprise, Cloud Shell, systèmes Windows), vous vous heurtez rapidement à une question pratique : où Gemini stocke-t-il ses fichiers, et comment changer les répertoires que Gemini lit et écrit ?

Qu’est-ce que Gemini CLI ?

Gemini CLI est l’agent IA open source en ligne de commande de Google qui apporte la puissance des modèles Gemini directement dans votre terminal. Il offre des capacités d’agent interactif pour l’assistance au code, l’inspection de fichiers et de projets, l’exécution de commandes shell (avec garde-fous), ainsi que l’intégration d’outils tels que Google Search, les extensions Model Context Protocol (MCP) et les outils de génération de médias fournis avec Gemini. Le CLI est conçu pour être léger, scriptable et extensible ; il est disponible depuis le dépôt officiel et empaqueté pour une installation facile.

Pourquoi le répertoire est important

Gemini CLI stocke la configuration (par exemple, settings.json), les invites système ou le contexte (GEMINI.md), les identifiants d’authentification mis en cache, les identifiants de télémétrie et d’autres états persistants dans un répertoire .gemini. L’emplacement de ce répertoire détermine :

• quels paramètres le CLI charge (globaux vs spécifiques au projet),
• quels fichiers de « mémoire » l’agent lira,
• où les identifiants sont mis en cache (impacte le comportement de connexion),
• la reproductibilité entre machines ou en CI lorsque vous souhaitez fournir un dépôt de configuration personnalisé.

Comprendre et (si nécessaire) modifier le répertoire aide pour les flux de travail multi‑projets, la CI, les déploiements conteneurisés et les équipes avec des magasins de configuration centralisés.

Où Gemini CLI stocke-t-il la configuration par défaut ?

Par défaut, le CLI utilise un répertoire .gemini. Pour la plupart des installations utilisateur, cela correspond à ~/.gemini (le dossier .gemini dans votre répertoire personnel). Le CLI prend également en charge des fichiers .gemini au niveau du projet (par ex., .gemini/settings.json à la racine du projet) qui remplacent les paramètres utilisateur lorsque vous travaillez depuis ce dossier de projet. Les paramètres au niveau du système sont lus à partir d’emplacements spécifiques à l’OS (par exemple /etc/ sous Linux ou %PROGRAMDATA% sous Windows) lorsque c’est applicable. Chemins typiques :

• Linux / macOS : ~/.gemini/ (par exemple /home/alice/.gemini ou /Users/alice/.gemini).
• Windows : %USERPROFILE%\.gemini (par ex., C:\Users\Alice\.gemini).
  À l’intérieur de .gemini, vous trouverez généralement settings.json, GEMINI.md, commands/ et des caches locaux. Le CLI lit également les dossiers .gemini/ par projet (racine du projet) pour les paramètres au niveau du projet.

Ce comportement par défaut est important : historiquement, le répertoire de configuration a été codé en dur sur .gemini dans le répertoire personnel

---

Comment changer ou rediriger le répertoire de configuration de Gemini CLI ?

Il existe plusieurs méthodes pratiques — de la plus simple (travailler dans le dossier souhaité) à la plus robuste (variables d’environnement ou redirections du système de fichiers). Choisissez une approche selon que vous contrôlez l’environnement d’exécution (machine de développement locale vs CI), selon votre OS, et selon que vous préférez un changement temporaire ou permanent.

1) Utiliser un .gemini au niveau du projet (recommandé pour des paramètres par projet)

Si vous souhaitez des paramètres propres à chaque projet, créez un sous-répertoire .gemini à la racine de votre projet et placez-y settings.json, GEMINI.md et autres fichiers du projet. Gemini CLI privilégie les paramètres du projet lorsque vous l’exécutez depuis ce répertoire de projet :

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

Lancez gemini lorsque votre shell se situe dans your-project/, et le CLI détectera les fichiers .gemini depuis cet arbre (il remonte l’arborescence pour trouver le contexte du projet). C’est la méthode la plus sûre et explicite pour une configuration par projet.

2) Utiliser des variables d’environnement documentées (lorsqu’elles sont prises en charge)

Le code et la documentation de Gemini CLI mentionnent plusieurs variables d’environnement utilisées pour modifier le comportement. Certaines sont prévues pour des paramètres système ou des remplacements de fichiers spécifiques :

• GEMINI_API_KEY, GEMINI_MODEL, etc. sont couramment utilisées pour l’authentification et le choix du modèle.
• Il existe des références dans le code et la documentation à des variables telles que GEMINI_CLI_SYSTEM_SETTINGS_PATH (utilisée pour remplacer le chemin des paramètres système) et à des constantes comme GEMINI_CONFIG_DIR (le nom .gemini par défaut utilisé dans le code). Certaines demandes de la communauté et PR proposent d’ajouter ou de respecter une variable d’environnement GEMINI_CONFIG_DIR pour permettre aux utilisateurs de relocaliser l’ensemble du répertoire de configuration.

Exemple (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

Mise en garde importante : selon les dernières discussions et issues de la communauté, GEMINI_CONFIG_DIR a été demandée et référencée à certains endroits dans le code — mais des bugs spécifiques aux plateformes et des comportements incohérents (en particulier sous Windows) ont été signalés. Cela signifie que la redirection basée sur des variables d’environnement peut ne pas être uniformément fiable sur toutes les plateformes ou versions. Consultez les notes de version de Gemini CLI et les issues du dépôt pour votre version installée si vous vous appuyez sur cette option.

3) Ajouter des répertoires à l’espace de travail de Gemini pendant une session

Si vous souhaitez que Gemini prenne en compte des répertoires supplémentaires (afin qu’il puisse lire des fichiers comme contexte), il existe un ensemble de commandes interactives /directory. Par exemple :

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

Cela ne déplace pas le répertoire de configuration, mais permet à l’agent d’inclure des fichiers provenant d’autres répertoires dans le contexte de son espace de travail. C’est utile lorsque vous souhaitez que l’agent référence d’autres dépôts sans modifier votre configuration globale.

4) Créer un lien symbolique ou un bind du système de fichiers (solution de contournement pratique)

Si le CLI refuse d’accepter des substitutions via l’environnement ou si vous avez besoin d’une solution fiable entre processus, utilisez une redirection du système de fichiers :

Sur Unix/macOS :

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

Sous Windows (invite PowerShell avec privilèges administrateur) :

# 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

Cette approche force le CLI à lire depuis l’emplacement souhaité sans nécessiter de prise en charge native dans le CLI. Note : les liens symboliques/jonctions requièrent des privilèges appropriés sur le système de fichiers et peuvent se comporter différemment dans des environnements conteneurisés ou sous Windows. À utiliser avec prudence. (Voir « Notes spécifiques à Windows » ci‑dessous.)

5) Changer le répertoire personnel effectif du processus (astuce pour conteneur/CI)

En exécution dans la CI, des conteneurs ou des environnements éphémères, vous pouvez modifier la variable d’environnement $HOME (Unix) ou %USERPROFILE% (Windows) pour le processus gemini afin que son ~/.gemini par défaut pointe vers un chemin que vous contrôlez :

# 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

C’est utile pour la reproductibilité en CI, mais attention : modifier HOME peut affecter d’autres outils et flux d’authentification (par ex., les caches Google OAuth), donc limitez cette technique à des conteneurs isolés ou des wrappers au niveau du processus.

Comment installer et utiliser Gemini CLI via CometAPI ?

Réponse courte : deux voies pratiques — (A) appeler les modèles Gemini directement via CometAPI (recommandé et le plus simple), ou (B) faire en sorte que le Gemini CLI officiel communique avec CometAPI soit en utilisant une version de Gemini CLI qui prend en charge une URL de base personnalisée (certaines versions/PR l’ajoutent), soit en exécutant un petit proxy local qui traduit les requêtes Gemini CLI en appels au format CometAPI/OpenAI.

Qu’est-ce que CometAPI ?

CometAPI est une passerelle/agrégateur d’API qui expose des centaines de modèles tiers (y compris la famille Gemini de Google) derrière une API HTTP au style OpenAI. Vous vous inscrivez, obtenez une clé API bearer, puis appelez des endpoints tels que https://api.cometapi.com/v1/chat/completions. CometAPI utilise des jetons bearer standard dans l’en‑tête Authorization.

Pourquoi utiliser CometAPI ? Il propose des tarifs API inférieurs à ceux de l’API officielle pour faciliter l’intégration. Guide d’installation et d’utilisation de Gemini CLI :

Comment appeler directement les modèles Gemini via CometAPI ? (Recommandé)

Si votre objectif est simplement d’utiliser les modèles Gemini et que vous n’avez pas strictement besoin des fonctionnalités de Gemini CLI, appeler directement CometAPI est simple et 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 .

Ces appels directs vous permettent d’intégrer CometAPI dans des scripts, des applications ou la CI sans dépendre de Gemini CLI.

Puis-je faire en sorte que Gemini CLI utilise CometAPI ?

Certaines versions/PR de Gemini CLI ajoutent des variables d’environnement pour remplacer l’URL de base de l’API Gemini. Si votre gemini installé permet de configurer une URL de base Gemini personnalisée et d’utiliser une clé CometAPI, vous pouvez le pointer vers CometAPI et définir la clé CometAPI comme GEMINI_API_KEY (le CLI s’attend à une variable nommée GEMINI_API_KEY pour l’authentification par clé API Gemini).

Exemple :

# 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

Dépannage : problèmes courants et correctifs

Problème : Gemini ne voit pas les fichiers dans un autre dépôt

1. Essayez gemini --include-directories /path/to/repo au démarrage. Ou en session : /directory add /path/to/repo.
2. Si le dépôt se trouve sur un montage réseau, vérifiez les permissions et que l’utilisateur du processus CLI peut lire les fichiers.
3. Si vous avez utilisé un lien symbolique pour déplacer .gemini, vérifiez que le CLI suit le lien pour GEMINI.md et settings.json (certaines versions ne suivent pas certains liens symboliques pour des raisons de sécurité).

Problème : gemini ne parvient pas à créer ~/.gemini sous Windows (EPERM)

Cela signifie généralement que votre processus n’a pas la permission d’écrire dans %USERPROFILE%. Corrections :

• Exécutez le terminal en tant qu’administrateur ou ajustez les permissions du dossier.
• Définissez un emplacement de configuration personnalisé via un lien symbolique ou, lorsqu’il est pris en charge, via une variable d’environnement (surveillez la prise en charge future de GEMINI_CONFIG_DIR).

Problème : cd ne change pas le répertoire de travail en mode shell

C’est un problème reconnu sur certaines plateformes. Recommandation : exécutez les commandes shell en dehors du processus Gemini CLI ou ajoutez des répertoires via /directory add.

Problème : les noms de modèles CometAPI ne correspondent pas à ce que vous attendez

Appelez l’endpoint /v1/models et inspectez le JSON. Les IDs de modèle contiennent souvent des chaînes de variante exactes (par ex., gemini-2.5-flash-preview-04-17). Utilisez la chaîne exacte dans votre requête.

Conclusion

La conception par défaut de Gemini CLI privilégie un comportement raisonnable et facile à découvrir : un ~/.gemini global pour les valeurs par défaut au niveau utilisateur et un .gemini de projet pour les remplacements par dépôt. La communauté milite pour davantage de configurabilité native (variables d’environnement ou drapeaux explicites) afin de rendre l’outil plus adapté aux environnements multi‑utilisateurs, conteneurisés et d’entreprise.

Comment changer le répertoire de Gemini CLI :

Aperçu : Gemini CLI stocke la configuration et les fichiers de contexte au niveau utilisateur dans un répertoire .gemini (typiquement ~/.gemini). Vous pouvez influencer le répertoire utilisé par le CLI en (1) vous appuyant sur un .gemini au niveau du projet dans le répertoire de travail actuel, (2) utilisant des variables d’environnement ou des options du CLI lorsqu’elles sont prises en charge, (3) ajoutant des répertoires d’espace de travail lors d’une session interactive, ou (4) recourant à des techniques du système de fichiers (liens symboliques, bind mounts ou modification des variables home/profile) lorsque les options natives manquent.

Pour commencer, explorez les capacités des modèles Gemini (tels que Gemini 3 Pro) dans le Playground et consultez le guide de l’API pour des instructions détaillées. Avant d’y accéder, assurez‑vous de vous être connecté à CometAPI et d’avoir obtenu la clé API. CometAPI propose un prix bien inférieur au prix officiel pour vous aider à intégrer.

Prêt à vous lancer ? → Essai gratuit des modèles Gemini !