Gemini CLI

Gemini CLI est l’agent de terminal open source de Google. Il peut comprendre un projet, analyser des fichiers et utiliser des commandes et des outils après autorisation. Configurez l’adresse API Gemini, l’API Key et l’ID du modèle pour utiliser l’endpoint Gemini Generate Content compatible d’AGTCloud.

Ce tutoriel couvre uniquement la connexion de base et sa validation sécurisée. Les modifications de fichiers, commandes Shell, appels de fonctions et autres capacités d’agent dépendent du modèle et de son support effectif de Gemini Parts, Function Call et des autres structures du protocole.

Prérequis

Avant de commencer, vérifiez que vous avez :

• Installé Node.js 20 ou une version ultérieure ;
• Préparé un terminal Bash, Zsh ou PowerShell ;
• Créé une API Key AGTCloud dans API Keys ;
• Copié dans le catalogue de modèles un ID accessible à la clé et compatible Gemini Generate Content ;
• Préparé un répertoire de test sans code sensible ni identifiants de production.

MODEL_ID est une valeur à remplacer, pas un nom réel. Utilisez un ID accessible à l’API Key et compatible Gemini Generate Content.

Installer Gemini CLI

Installez de préférence la version stable actuelle. Les méthodes suivantes fournissent toutes la même commande gemini.

npm install -g @google/gemini-cli

Vérifiez la version après l’installation :

gemini --version

Si la commande est introuvable, rouvrez le terminal et vérifiez que le répertoire des commandes npm globales figure dans PATH.

Configurer AGTCloud

Gemini CLI nécessite quatre variables : API Key, ID du modèle, adresse API Gemini personnalisée et méthode d’authentification Bearer.

export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="MODEL_ID"
export GOOGLE_GEMINI_BASE_URL="https://api.agtcloud.cn"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

Description des paramètres

Ce tutoriel ne définit pas GOOGLE_GENAI_API_VERSION et laisse Gemini CLI utiliser la version par défaut v1beta. Ne saisissez pas non plus le chemin complet generateContent dans la Base URL.

Enregistrer la configuration utilisateur

Après validation des paramètres temporaires, enregistrez les variables dans le .env utilisateur de Gemini CLI. Ce fichier peut contenir une véritable API Key : ne le soumettez pas au dépôt.

~/.gemini/.env

GEMINI_API_KEY=your-api-key
GEMINI_MODEL=MODEL_ID
GOOGLE_GEMINI_BASE_URL=https://api.agtcloud.cn
GEMINI_API_KEY_AUTH_MECHANISM=bearer

Gemini CLI recherche les fichiers d’environnement dans le répertoire courant et ses parents. Un .env ou .gemini/.env plus proche dans le projet peut primer sur la configuration utilisateur ; vérifiez ces fichiers si les paramètres ne sont pas appliqués.

Fixer la méthode d’authentification API Key

Gemini CLI propose plusieurs authentifications Google. Avec AGTCloud, choisissez Gemini API Key, pas la connexion Google ni Vertex AI.

Fusionnez les paramètres suivants dans le settings.json utilisateur sans écraser le thème, les autorisations ou les autres paramètres :

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

Emplacement du fichier :

Après enregistrement, quittez complètement puis redémarrez Gemini CLI. selectedType choisit le parcours API Key, tandis que GEMINI_API_KEY_AUTH_MECHANISM=bearer produit le Header Bearer requis par AGTCloud ; ils ne se remplacent pas.

Choisir un modèle

GEMINI_MODEL définit le modèle par défaut. Pour un choix temporaire dans une session, exécutez :

gemini --model MODEL_ID

/model dans une session interactive est une interface complémentaire, mais sa liste n’inclut pas forcément tous les modèles accessibles à l’API Key AGTCloud. Si un modèle est absent ou inaccessible, recopiez son ID complet dans le catalogue et privilégiez GEMINI_MODEL ou --model.

Valider la connexion

gemini -p "Répondez uniquement : connexion AGTCloud réussie." --output-format json

gemini -p "@README.md Résumez l’objectif du projet en trois points, sans modifier aucun fichier." --output-format json

gemini

Questions fréquentes

En cas de problème non identifié, consignez l’heure, l’API Base URL, l’ID du modèle, la version CLI, le code HTTP et l’erreur expurgée, puis consultez Erreurs et dépannage. Ne fournissez pas d’API Key complète ni de .env contenant des identifiants.

Conseils de sécurité

• N’inscrivez pas de véritable API Key dans un dépôt, un script partagé, une capture d’écran, un journal ou une conversation ;
• Validez d’abord avec des variables temporaires, puis enregistrez la configuration utilisateur ;
• Définissez des droits d’accès locaux adaptés au .env et évitez sa synchronisation vers un stockage public ;
• Conservez l’approbation humaine pour les premiers appels d’outils et validez hors production ;
• Retirez les clés complètes, noms d’utilisateur, chemins locaux et sources métier avant de partager des informations de dépannage.

Étapes suivantes

• API Key, Base URL et authentification
• Gemini Generate Content API Reference
• Gemini Stream Generate Content API Reference
• Choix du protocole
• Erreurs et dépannage