settings.json : configurer Gemini CLI

Le fichier settings.json est le centre de configuration de Gemini CLI. Il règle le modèle utilisé, le mode d'approbation des actions, l'interface, les serveurs MCP et la sécurité, en dehors du code de vos projets. Ce guide montre où placer ce fichier selon la portée voulue (machine, utilisateur, projet), comment les niveaux se combinent, les réglages qui comptent vraiment, et pourquoi la commande /settings évite les erreurs de syntaxe. Il s'adresse à qui veut une configuration reproductible et partageable en équipe, débutant comme intermédiaire.

Ce que vous allez apprendre

Les trois niveaux de settings.json et leur précédence
Éditer la config sans se tromper avec /settings
Les réglages clés : modèle, approbation, interface, MCP, sécurité
Versionner une config de projet pour toute l'équipe
Diagnostiquer une configuration qui ne s'applique pas

Prérequis

Gemini CLI installé et une première session réussie. Voir Installer Gemini CLI et Prise en main du REPL.
Un éditeur de texte pour ouvrir des fichiers JSON.

settings.json, c'est quoi et où le trouver

C'est un simple fichier JSON que Gemini CLI lit au démarrage pour connaître vos préférences. Il n'y en a pas qu'un : la CLI combine trois niveaux, du plus général au plus spécifique, ce qui permet de fixer des défauts pour la machine, des préférences pour votre compte, et des réglages propres à chaque dépôt.

Niveau	Emplacement	Usage
Système	`/etc/gemini-cli/system-defaults.json` (Linux)	Défauts posés pour tous les comptes d'une machine
Utilisateur	`~/.gemini/settings.json`	Vos préférences pour tous vos projets
Projet	`<projet>/.gemini/settings.json`	La config du dépôt courant

La règle de précédence est simple : le projet l'emporte sur l'utilisateur, qui l'emporte sur le système. Autrement dit, un réglage défini dans le dépôt écrase le même réglage défini pour votre compte. C'est ce qui permet à une équipe d'imposer une configuration commune sur un projet, sans toucher aux préférences personnelles de chacun.

Dans un lab de test, le ~/.gemini/settings.json réel se limite souvent à l'essentiel après la première authentification :

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  },
  "ide": {
    "hasSeenNudge": true
  }
}

Éditer sans se tromper avec /settings

Un fichier JSON est intolérant : une virgule en trop ou une clé mal orthographiée et le réglage est ignoré, parfois sans erreur visible. Pour éviter ce piège, Gemini CLI fournit un éditeur intégré. Dans le REPL, lancez :

> /settings

Vous obtenez un dialogue qui liste les réglages par catégorie (General, UI, Model, Context, Tools, Security, Output, Billing), avec leurs valeurs actuelles et leur type attendu. Vous modifiez, la CLI écrit un JSON valide à votre place. C'est la méthode recommandée pour découvrir les options sans mémoriser leurs noms exacts.

Les réglages qui comptent

Les options sont nombreuses, mais quelques familles couvrent l'essentiel des besoins. Elles sont regroupées par catégorie, ce qui donne des clés imbriquées comme general.vimMode ou model.name.

Modèle et session

La catégorie model choisit le moteur et cadre la longueur des échanges. Sans réglage, la CLI utilise son mode Auto ; vous pouvez forcer un modèle précis et limiter le nombre de tours d'une session pour maîtriser la consommation :

{
  "model": {
    "name": "gemini-2.5-pro",
    "maxSessionTurns": 50
  }
}

maxSessionTurns à -1 signifie illimité. Fixer une valeur basse est un garde-fou utile quand on débute et qu'on surveille son quota.

Approbation des actions

C'est le réglage de sécurité le plus structurant. La clé general.defaultApprovalMode décide du niveau de contrôle sur ce que l'agent exécute :

Mode	Comportement
`default`	L'agent demande avant chaque action sensible
`auto_edit`	Les modifications de fichiers sont auto-approuvées, le reste demande
`plan`	Mode lecture seule : l'agent propose sans rien exécuter

Le mode yolo (tout auto-approuver) existe aussi, mais il se réserve à des environnements jetables. Débuter en default est le choix prudent.

Interface et confort

La catégorie ui ajuste l'affichage du REPL. Deux réglages reviennent souvent : afficher les numéros de ligne dans les diffs, et activer le mode Vim pour l'édition des prompts :

{
  "general": { "vimMode": true },
  "ui": { "showLineNumbers": true }
}

Ces options ne changent rien au comportement de l'agent, seulement votre confort de lecture et de saisie.

Serveurs MCP

La clé mcpServers déclare les serveurs MCP (Model Context Protocol) qui étendent l'agent avec des outils externes. Chaque entrée nomme une commande et ses arguments. Placée dans le .gemini/settings.json du projet, cette déclaration est partagée avec quiconque clone le dépôt :

{
  "mcpServers": {
    "demo-fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

La lecture de ce fichier se vérifie sans consommer de quota, avec la sous-commande gemini mcp list, qui liste les serveurs configurés et leur état de connexion :

$ gemini mcp list
Configured MCP servers:

✓ demo-fs: npx -y @modelcontextprotocol/server-filesystem /tmp (stdio) - Connected

Voir le serveur remonter ici confirme que le settings.json de projet est bien pris en compte. Le protocole MCP fait l'objet d'un guide dédié plus loin dans cette formation.

Versionner la config de projet

Le .gemini/settings.json d'un dépôt a vocation à être committé : il porte les choix qui doivent valoir pour toute l'équipe (serveurs MCP du projet, modèle imposé, mode d'approbation). C'est l'intérêt du niveau projet sur le niveau utilisateur.

Autorisations d'outils : le Policy Engine

Pour contrôler finement quels outils s'exécutent sans confirmation, l'ancien drapeau --allowed-tools est déprécié au profit du Policy Engine, un système de règles dédié. C'est lui qu'il faut viser pour durcir un poste ou un pipeline, plutôt qu'une liste blanche figée. Son fonctionnement, avec le sandboxing et le plan mode, est traité dans le guide d'approbation et de sécurité de cette formation.

Dépannage : ma configuration ne s'applique pas

Quand un réglage semble ignoré, la cause est presque toujours l'une de ces trois-là :

Symptôme	Cause probable	Solution
Un réglage utilisateur n'a aucun effet sur un projet	Le `.gemini/settings.json` du projet le surcharge	Vérifier le fichier projet, il gagne toujours
Le fichier entier est ignoré	JSON invalide (virgule, guillemet)	Rouvrir via `/settings` ou valider avec le schéma
Une clé ne fait rien	Nom de clé erroné ou catégorie oubliée	Comparer au schéma officiel, respecter l'imbrication

Le réflexe le plus rapide reste /settings : puisque la CLI écrit le JSON elle-même, les erreurs de syntaxe et de nommage disparaissent.

À retenir

settings.json existe en trois niveaux : système, utilisateur (~/.gemini/), projet (<projet>/.gemini/).
La précédence va du plus spécifique au plus général : le projet l'emporte sur l'utilisateur, puis sur le système.
/settings édite la configuration sans risque d'erreur de syntaxe JSON ; un schéma officiel aide l'édition manuelle.
Les réglages structurants : model.name, general.defaultApprovalMode (default / auto_edit / plan) et mcpServers.
La config de projet se versionne pour l'équipe ; les secrets vont dans un .gemini/.env gitignoré, jamais dans settings.json.
Les autorisations fines d'outils passent désormais par le Policy Engine, pas par l'ancienne liste --allowed-tools.

Prochaines étapes

GEMINI.md : le contexte projet Donner à l'agent les conventions et commandes de votre dépôt.

Prise en main du REPL Les commandes /, les fichiers @ et le mode shell ! au quotidien.

Gemini CLI : le hub complet Le pilier de la formation et tous les guides par phase.

Claude Code : le hub L'autre grand agent CLI, pour comparer les approches de configuration.