Grok CLI et Grok Build : installation et configuration API

« Grok CLI » peut désigner deux outils différents :

• Grok Build, le coding agent officiel de xAI ;
• Community Grok CLI, un projet open source sans affiliation avec xAI.

Lors d’un test sur macOS avec un modèle GPT, Community Grok CLI 1.1.7 a renvoyé OK pour les requêtes texte, mais son test de lecture de fichier n’a pas abouti. Grok Build 1.0.67 a traité des requêtes texte et des appels d’outils de lecture de fichiers avec api_backend = "chat_completions" ; son flux Responses a échoué à l’analyse côté client (voir Grok Build). Les deux configurations utilisent une BetterToken API Key, une Base URL et un Model ID.

Les deux outils utilisent la commande grok. S’ils sont installés ensemble, le terminal lance la première version trouvée dans PATH, ce qui peut donner l’impression que la configuration ne fonctionne pas. Gardez une seule version ou installez-les dans des environnements distincts.

Différences entre Grok CLI et Grok Build

Élément	Grok Build officiel	Community Grok CLI
Mainteneur	xAI	superagent-ai/grok-cli, sans affiliation avec xAI
Idéal pour	Utilisateurs souhaitant l’agent de codage officiel de xAI	Utilisateurs souhaitant appeler un modèle via une Base URL personnalisée
Authentification	Connexion par navigateur ou XAI_API_KEY	GROK_API_KEY
Base URL personnalisée	Dans ~/.grok/config.toml	Avec GROK_BASE_URL
Modèle	Alias défini dans le fichier de configuration	GROK_MODEL
Appel de modèles via BetterToken	Requêtes texte et appels d’outils de lecture de fichiers réussis (1.0.67, chat_completions)	La requête texte a renvoyé OK ; le test de lecture de fichier a échoué (1.1.7)
Commande	grok	grok

Ce guide couvre uniquement les requêtes texte et code via BetterToken. Il ne couvre pas les API propres à xAI, comme X Search, la transcription vocale, la génération d’images ou de vidéos.

Utiliser Community Grok CLI avec BetterToken

Ces commandes s’appliquent à macOS, Linux et WSL. L’installation native de Community Grok CLI sur Windows n’a pas été testée.

Installation

curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash
grok --version

Si Bun est déjà installé :

bun add -g grok-dev

L’ancien paquet @vibe-kit/grok-cli n’est plus le mode d’installation recommandé dans le README actuel du projet.

Configurer BetterToken

export GROK_BASE_URL="https://bettertoken.ai/v1"
export GROK_API_KEY="YOUR_API_KEY"
export GROK_MODEL="YOUR_MODEL_ID"

Remplacez YOUR_MODEL_ID par le Model ID complet du model plaza et utilisez votre API Key BetterToken.

Vérifier la connexion

grok -p "Reply with only: OK"

Seule une réponse du modèle confirme le fonctionnement de l’API Key, de la Base URL et du Model ID. Redémarrez le client après avoir modifié les variables d’environnement.

Community Grok CLI 1.1.7 a renvoyé OK lors des trois essais de requête texte, mais le client a signalé des erreurs de validation du flux : il a rejeté delta.role: null à la fin du flux et signalé des erreurs de schéma dans les fragments de continuation d’appel d’outil. Le test de lecture de fichier n’a pas abouti. Utilisez ce client pour les requêtes texte uniquement dans le périmètre testé ; les appels d’outils de lecture de fichiers n’ont pas réussi.

Une session Grok CLI ouverte ne recharge pas automatiquement les variables d’environnement. Quittez le client et relancez-le après une modification de configuration.

Changer de modèle

Définissez GROK_MODEL sur un autre Model ID complet, redémarrez Grok CLI, puis répétez la requête courte.

Grok Build officiel

Grok Build est l’agent de codage officiel de xAI pour le terminal. Il prend en charge une interface TUI interactive, l’exécution sans interface et ACP.

Installation et authentification

macOS / Linux / WSL

curl -fsSL https://x.ai/cli/install.sh | bash
grok --version

Windows PowerShell

irm https://x.ai/cli/install.ps1 | iex
grok --version

Utiliser un compte xAI ou une API Key

Au premier lancement, Grok Build ouvre un navigateur pour l’authentification. Pour les environnements sans navigateur, xAI documente XAI_API_KEY:

export XAI_API_KEY="YOUR_XAI_API_KEY"
grok

Facultatif : configurer BetterToken dans Grok Build

Grok Build prend en charge les modèles personnalisés compatibles OpenAI avec une Base URL, un Model ID, une variable d’environnement d’authentification et un protocole de requête.

[model.bettertoken]
model = "YOUR_MODEL_ID"
base_url = "https://bettertoken.ai/v1"
name = "BetterToken"
env_key = "BETTERTOKEN_API_KEY"
api_backend = "chat_completions"

[models]
default = "bettertoken"

BETTERTOKEN_API_KEY est un nom de variable donné en exemple, pas une exigence fixe de Grok Build. Grok Build lit la variable indiquée par env_key.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"
grok inspect
grok -p "Reply with only: OK" -m bettertoken

Grok Build 1.0.67 a traité des requêtes texte et des appels d’outils de lecture de fichiers avec api_backend = "chat_completions". Avec responses, il a reçu un flux HTTP 200, mais l’analyse côté client a échoué, d’abord sur keepalive ; le flux enregistré contenait aussi response.metadata. Gardez chat_completions si vous rencontrez unknown variant keepalive ou unknown variant response.metadata. Les API propres à xAI n’ont pas été vérifiées.

Requêtes auxiliaires de modèle

Les deux clients peuvent envoyer des requêtes auxiliaires vers des modèles qu’ils sélectionnent eux-mêmes, comme grok-4.20-non-reasoning dans Community Grok CLI et grok-4.6 dans Grok Build. Lors du test, BetterToken a renvoyé 503 model_not_found avec No available channel pour ces modèles auxiliaires, tandis que la requête du modèle principal a réussi. Vous pouvez ignorer ces erreurs auxiliaires si la requête principale aboutit ; elles ne signifient pas que le Model ID choisi a échoué.

Éviter les conflits de commande grok

macOS / Linux / WSL

type -a grok
grok --version

Windows PowerShell

Get-Command grok -All
grok --version

type -a grok et Get-Command grok -All affichent toutes les commandes portant le même nom. Supprimez le client inutilisé ou modifiez PATH si les deux sont installés.

Erreurs fréquentes

Problème	Vérification
Le mauvais Grok démarre après l’installation	Listez chaque grok et vérifiez son chemin et sa version.
Grok Build échoue avec unknown variant response.metadata	Définissez api_backend = "chat_completions" pour le modèle BetterToken et relancez grok inspect.
Grok Build officiel ouvre un navigateur	C’est le flux de connexion par défaut de Grok Build. Continuez avec xAI ; pour BetterToken, configurez un modèle personnalisé.
401 ou Unauthorized	Un modèle personnalisé de Grok Build lit la variable indiquée par env_key ; le client communautaire lit GROK_API_KEY. Définissez uniquement la variable utilisée par le client en cours.
model not found	Copiez le Model ID complet du model plaza, puis redémarrez le client.
Les requêtes sont toujours envoyées à xAI	Vérifiez GROK_BASE_URL pour le client communautaire. Dans Grok Build, lancez grok inspect pour vérifier base_url et l’alias de modèle actif.
Une fonction propre à xAI ne fonctionne pas	BetterToken traite uniquement les requêtes de modèle décrites ici. Utilisez l’API officielle xAI pour X Search, la voix et les fonctions média.

• Comparer tous les outils pris en charge
• Erreurs API, codes de statut et limites de débit

Modèles et limites fonctionnelles

Copiez depuis le model plaza un Model ID complet compatible avec les appels OpenAI. Une Base URL configurable ne garantit pas la compatibilité des requêtes, des appels d’outils ou du format de contexte d’une famille de modèles.

Cette page couvre uniquement les requêtes texte et code. Cette configuration ne fournit pas X Search, la transcription vocale, la génération d’images ou de vidéos ni d’autres API propres à xAI.

Sources

• model plaza BetterToken

• Grok Build : présentation officielle

• Grok Build : Settings Reference

• Community Grok CLI : dépôt

• Protocoles BetterToken