Le CLI gcloud couvre à peu près tout l’écosystème GCP : Compute, BigQuery (via bq), Cloud Storage (via gsutil), IAM, et des dizaines d’autres services. Mais il n’offre strictement aucune capacité d’interaction avec les applications Google Workspace. Impossible de lister les messages Gmail, de lire un Google Sheet, de créer un événement Calendar ou de gérer les permissions Drive depuis gcloud. Ce vide existe depuis le premier jour.
Le CLI Google Workspace (gws) vient le combler. Créé par Justin Poehnelt, Senior Developer Relations Engineer chez Google dans l’équipe Workspace, gws est un outil en ligne de commande open source qui donne un accès programmatique à toutes les API Google Workspace via un seul binaire : Gmail, Drive, Calendar, Sheets, Docs, Chat, Admin, et plus encore. Le projet en est à la v0.3.5 avec environ 5 100 étoiles GitHub, hébergé sous l’organisation GitHub officielle googleworkspace. Il porte la mention habituelle (“This is not an officially supported Google product”), est écrit en Rust, distribué via npm avec des binaires pré-compilés, et en développement actif vers la v1.0, avec des breaking changes à prévoir.
Ce qui le rend intéressant pour les équipes data, c’est moins la couverture API que la philosophie de conception : l’outil a été pensé dès le départ pour être consommé par des agents IA, pas par des humains. Il embarque plus de 100 fichiers de skills pour agents, un serveur MCP intégré, une sortie JSON structurée par défaut et un nettoyage des réponses contre l’injection de prompts.
Le vide que gws comble
Avant gws, la principale alternative pour automatiser Workspace était Google Apps Script. Ça fonctionne, mais avec un timeout d’exécution de 6 minutes sur les comptes gratuits (30 minutes sur Workspace), une exécution synchrone mono-thread, pas de gestionnaire de paquets, des quotas journaliers sur les appels API et aucune intégration CI/CD. Pour les data engineers qui ont besoin de gérer des ressources Workspace de manière programmatique dans leurs pipelines, Apps Script est fondamentalement inadapté. Les API REST fonctionnent aussi, mais nécessitent un boilerplate considérable pour l’authentification, la pagination et la gestion d’erreurs.
gws abstrait tout ça derrière une interface cohérente. Ce qui est techniquement malin, c’est la façon dont le CLI construit sa surface de commandes. Plutôt que de livrer une liste statique de commandes, gws interroge le Discovery Service de Google au runtime et génère dynamiquement chaque commande à partir des spécifications API. Quand Google ajoute un nouveau endpoint, le CLI le récupère automatiquement. Les documents de découverte sont mis en cache pendant 24 heures. Le résultat : l’outil ne sera jamais en retard sur les API qu’il encapsule.
Sept principes pour des CLI pensés agents-first
Poehnelt a publié un billet de blog le 4 mars 2026, intitulé “You Need to Rewrite Your CLI for AI Agents”, qui expose la philosophie derrière l’outil. Le billet a atteint la une de Hacker News. Sa thèse centrale : l’expérience développeur pour les humains optimise la découvrabilité et la tolérance aux erreurs, tandis que l’expérience développeur pour les agents optimise la prévisibilité et la défense en profondeur. Adapter un CLI conçu pour les humains afin qu’il serve des agents est, selon lui, une impasse.
Les sept principes :
Des payloads JSON bruts plutôt que des flags sur mesure. Les CLI traditionnels utilisent des espaces de noms de flags plats (--title "Q1 Budget" --locale "en_US") qui ne peuvent pas exprimer des structures imbriquées. Le CLI gws accepte des payloads API complets via les flags --json et --params, en correspondance directe avec le schéma API. Les LLM peuvent les générer sans aucune perte de traduction.
L’introspection de schéma remplace la documentation. Plutôt que d’intégrer de la documentation statique dans les system prompts (coûteux en tokens et sujet à l’obsolescence), gws schema drive.files.list produit les signatures complètes des méthodes en JSON lisible par les machines : paramètres, corps de requête, types de réponse, scopes OAuth. Le Discovery Document est la source unique de vérité.
Discipline de la fenêtre de contexte. Un seul message Gmail peut consommer une fraction significative du contexte d’un LLM. Les field masks (--params '{"fields": "files(id,name,mimeType)"}') limitent ce que l’API renvoie. La pagination NDJSON (--page-all) émet un objet JSON par page, traitable en flux sans avoir à mettre en mémoire tampon la réponse entière.
Durcissement des entrées contre les hallucinations. La position de Poehnelt est sans détour : “Agents hallucinate. Build like it.” Le CLI valide les chemins de fichiers pour empêcher les traversées de répertoires (les agents hallucinent ../../.ssh), rejette les caractères de contrôle en dessous de l’ASCII 0x20, rejette ? et # dans les noms de ressources (les agents intègrent des paramètres de requête dans les identifiants de ressources) et rejette % pour éviter le double encodage.
Livrer des skills pour agents, pas seulement des commandes. Le repo contient des fichiers Markdown structurés avec du YAML frontmatter, un par surface API plus des workflows de plus haut niveau. Les skills encodent des conseils qui ne sont pas évidents à partir du --help : “Toujours utiliser --dry-run pour les opérations de modification”, “Toujours confirmer avec l’utilisateur avant d’exécuter des commandes d’écriture/suppression.”
Diffusion multi-surface. Le même binaire sert de CLI, de serveur MCP (gws mcp), d’extension Gemini CLI et d’outil headless via des variables d’environnement.
Garde-fous de sécurité. --dry-run valide les requêtes sans appeler l’API. --sanitize fait passer les réponses par Google Cloud Model Armor pour se protéger contre l’injection de prompts dans les données (imaginez un corps d’email malveillant qui donne l’instruction à un agent de transférer tous les messages à un attaquant).
Installer le CLI et s’authentifier
Prérequis
Vous avez besoin de deux choses avant de commencer :
- Node.js (n’importe quelle version LTS récente) pour l’installation via npm. Si vous préférez Rust, vous pouvez compiler depuis les sources avec
cargo install --path ., ou utiliser le Nix flake (nix run github:googleworkspace/cli). - Le CLI
gcloud, installé et authentifié avecgcloud auth login. Le flux de configuration automatisé encapsule des appelsgcloudpour créer et configurer votre projet GCP. Si vous n’avez pasgcloud, sautez la méthode automatisée et suivez la configuration OAuth manuelle ci-dessous.
Configuration automatisée (recommandée)
C’est la façon la plus rapide de démarrer si vous avez déjà gcloud configuré, et ça évite la plupart des pièges OAuth qui font trébucher les gens dans le flux manuel.
# Installer le CLI globalement via npm (inclut des binaires natifs pré-compilés, pas besoin de Rust)npm install -g @googleworkspace/cli
# Lancer l'assistant de configuration interactifgws auth setupgws auth setup fait automatiquement ce qui suit : créer un projet GCP (ou utiliser un projet existant), activer les API Workspace nécessaires, configurer un écran de consentement OAuth, créer un client OAuth Desktop, et vous guider à travers la connexion OAuth dans le navigateur. Les identifiants sont chiffrés au repos avec AES-256-GCM, la clé de chiffrement étant stockée dans le keyring de votre OS.
Une fois la configuration terminée, vérifiez que tout fonctionne :
# Lister vos 5 fichiers Drive les plus récentsgws drive files list --params '{"pageSize": 5}'Si vous voyez un tableau JSON de fichiers, c’est bon.
Configuration OAuth manuelle (Google Cloud Console)
Utilisez cette méthode quand gws auth setup ne peut pas automatiser la création du projet (restrictions organisationnelles, par exemple), ou quand vous voulez un contrôle explicite sur la configuration OAuth. Avertissement : le fil Hacker News de ce projet est rempli de gens qui ont passé 30 à 45 minutes à se battre avec le flux OAuth manuel. L’essentiel de la friction vient de deux erreurs spécifiques, faciles à éviter une fois qu’on les connaît.
Étape 1 : Créer ou sélectionner un projet GCP. Ouvrez la Google Cloud Console et créez un nouveau projet ou sélectionnez-en un existant. Notez l’identifiant du projet.
Étape 2 : Configurer l’écran de consentement OAuth. Naviguez vers APIs & Services > OAuth consent screen. Définissez le type d’application sur External. Le mode Testing suffit pour un usage personnel. Sous Test users, ajoutez votre propre adresse email Google. Cette étape est cruciale : sans elle, vous obtiendrez une erreur générique “Access blocked” en essayant de vous connecter, sans aucune indication que l’utilisateur test manquant en est la cause.
Étape 3 : Créer un OAuth client ID. Naviguez vers APIs & Services > Credentials. Cliquez sur Create Credentials > OAuth client ID. C’est ici que survient la première erreur courante : vous devez choisir Desktop app comme type d’application, et non “Web application”. La GCP Console propose Web application par défaut, et rien dans la configuration de gws ne vous avertit si vous faites le mauvais choix. Si vous avez accidentellement créé un client Web app, supprimez-le et créez-en un nouveau avec Desktop app sélectionné. Téléchargez le fichier JSON résultant.
Étape 4 : Enregistrer le fichier JSON client. Déplacez le fichier téléchargé vers ~/.config/gws/client_secret.json. Vous pouvez aussi définir les variables d’environnement GWS_CLIENT_ID et GWS_CLIENT_SECRET avec les valeurs du fichier JSON.
Étape 5 : Se connecter.
gws auth loginSi vous n’avez pas enregistré le fichier JSON client ni défini les variables d’environnement, le CLI vous demandera vos identifiants de manière interactive. C’est la deuxième source de confusion courante : le prompt demande votre “OAuth ID”, mais ce qu’il attend en réalité, c’est le client ID (la longue chaîne se terminant par .apps.googleusercontent.com), suivi du client secret dans un second prompt. Ce sont les deux valeurs du fichier JSON téléchargé à l’étape 3. Les libellés du prompt pourraient être plus clairs, et ce n’est pas évident de savoir quelle valeur va où quand on fait ça pour la première fois.
Une fois les identifiants fournis, le CLI ouvre une fenêtre de navigateur pour le consentement OAuth. Deux choses vont se passer qui peuvent paraître alarmantes :
- Un avertissement “Google hasn’t verified this app” : cliquez sur Advanced, puis “Go to [app name] (unsafe)”. C’est attendu et sans risque pour un usage personnel. La vérification n’est requise que pour les applications publiées auprès d’autres utilisateurs.
- Des cases à cocher pour les scopes : sélectionnez les scopes dont vous avez besoin (ou Select all) et cliquez sur Continue.
Le piège de la limite de scopes
Même après avoir choisi le bon type de client OAuth et saisi les identifiants correctement, il reste un piège. Les applications OAuth non vérifiées en mode test sont limitées à environ 25 scopes OAuth. Le preset “all services” recommandé par gws inclut plus de 85 scopes et échouera silencieusement ou générera une erreur si vous dépassez cette limite. Un utilisateur sur Hacker News a décrit avoir dû ajouter les scopes un par un pour contourner le problème, exactement le genre de friction qui fait abandonner les gens.
La solution : n’autorisez que les services dont vous avez réellement besoin. Si vous prévoyez d’utiliser uniquement Drive, Gmail et Sheets, ça fait beaucoup moins de scopes et vous resterez bien en dessous de la limite. Vous pourrez toujours ajouter d’autres services plus tard avec un nouvel appel gws auth login.
Comptes multiples
Si vous travaillez avec plusieurs comptes Google (comptes personnels et clients, par exemple), gws gère ça nativement :
# Se connecter avec un compte spécifiquegws auth login --account work@corp.comgws auth login --account personal@gmail.com
# Lister les comptes enregistrésgws auth list
# Définir un compte par défautgws auth default work@corp.com
# Override ponctuel pour une seule commandegws --account personal@gmail.com drive files list
# Ou via variable d'environnementexport GOOGLE_WORKSPACE_CLI_ACCOUNT=personal@gmail.comChaque compte dispose de son propre fichier d’identifiants chiffré, stocké sous credentials.<base64-email>.enc dans ~/.config/gws/.
Environnements headless et CI
Pour les pipelines et serveurs sans navigateur :
# Sur une machine AVEC navigateur : exporter les identifiants après connexion interactivegws auth export --unmasked > credentials.json
# Sur la machine headless : pointer vers le fichier exportéexport GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.jsongws drive files list # fonctionne sans aucune interaction navigateurPour les flux serveur-à-serveur entièrement automatisés, vous pouvez utiliser un fichier de clé de service account GCP :
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.jsongws drive files listSi le service account dispose de la Domain-Wide Delegation configurée, usurpez l’identité d’un utilisateur avec :
export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.comVous pouvez aussi injecter un access token préobtenu, ce qui est utile quand gcloud génère déjà des tokens :
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)Ordre de priorité de l’authentification
Le CLI résout les identifiants dans cet ordre (premier trouvé gagne) :
- Access token (
GOOGLE_WORKSPACE_CLI_TOKEN) - Fichier d’identifiants (
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE) - Identifiants chiffrés par compte (depuis
gws auth login --account) - Identifiants en clair (
~/.config/gws/credentials.json)
La résolution du compte suit : flag --account > variable d’environnement GOOGLE_WORKSPACE_CLI_ACCOUNT > défaut dans accounts.json.
Dépannage : “API not enabled”
Quand vous essayez d’utiliser un service pour la première fois, vous pouvez obtenir une erreur 403 avec la raison accessNotConfigured. Le CLI affiche un indice avec un lien direct pour activer l’API dans la GCP Console. Cliquez sur le lien, cliquez sur Enable, attendez une dizaine de secondes, puis réessayez. Vous pouvez aussi relancer gws auth setup, qui active automatiquement toutes les API requises.
Connecter gws à Claude Code
Le CLI s’intègre aux agents IA de codage par deux chemins complémentaires : MCP et commandes shell directes.
Configuration du serveur MCP
Le serveur MCP intégré (gws mcp -s drive,gmail,calendar) expose les API Google Workspace sous forme d’outils structurés via stdio pour tout client compatible MCP : Claude Desktop, Gemini CLI, VS Code Copilot, Cursor. Chaque service ajoute environ 10 à 80 outils, donc limitez-vous à ce dont vous avez réellement besoin pour rester sous les limites typiques de 50 à 100 outils par client.
Enregistrez gws comme serveur MCP avec la commande CLI :
claude mcp add gws -- gws mcp -s drive,gmail,calendarUtilisez --scope user pour le rendre disponible dans tous vos projets, ou --scope project pour le partager avec votre équipe via le fichier .mcp.json.
Vous pouvez aussi modifier directement le fichier JSON de configuration. Ajoutez ceci dans votre ~/.claude.json sous la clé mcpServers :
{ "mcpServers": { "gws": { "command": "gws", "args": ["mcp", "-s", "drive,gmail,calendar"] } }}Après l’ajout, redémarrez Claude Code et vérifiez avec /mcp en session. Vous devriez voir gws: connected. Si vous débutez avec la création et connexion de serveurs MCP, la configuration de gws fait partie des plus simples.
Commandes shell directes
Claude Code dispose d’une exécution bash intégrée et peut invoquer des commandes gws directement, parser la sortie JSON structurée et enchaîner les opérations. C’est souvent plus économique en tokens que MCP, car les outils ne consomment des tokens que lorsqu’ils sont activement utilisés, au lieu de charger les définitions de schémas dans le contexte. Vous pouvez demander à Claude Code de “lister mes Google Sheets récents et vérifier si certains correspondent au schéma de notre table seed BigQuery” et il composera les commandes gws et bq appropriées.
Installer les skills pour agents
Le repo embarque plus de 100 skills pour agents sous forme de fichiers Markdown structurés. Pour les installer dans Claude Code (ou tout agent qui utilise des fichiers de skills) :
# Installer tous les skills d'un coupnpx skills add https://github.com/googleworkspace/cli
# Ou ne prendre que ce dont vous avez besoinnpx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drivenpx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmailComparaison avec les serveurs MCP tiers
Plusieurs serveurs MCP communautaires existent pour Google Workspace. Le plus complet est celui de taylorwilsdon, google_workspace_mcp, qui couvre 12 services avec plus de 100 outils, auxquels s’ajoutent des implémentations en Go et Python par d’autres développeurs. Ils nécessitent tous une configuration OAuth similaire et offrent des capacités comparables. L’avantage du CLI gws est qu’il est maintenu sous l’organisation GitHub officielle de Google Workspace par un ingénieur DevRel de Google, qu’il reste automatiquement à jour avec les changements d’API via le Discovery Service, et qu’il offre à la fois une surface CLI et MCP depuis un seul outil. L’inconvénient est son statut “non officiellement supporté” et sa maturité pré-v1.0.
CLI vs MCP : les compromis en pratique
Le débat sur la question de savoir si les agents IA devraient utiliser des CLI ou MCP a produit de vrais benchmarks. Mario Zechner a réalisé 120 séries d’évaluation sur des tâches standardisées et a constaté que les deux approches atteignaient un taux de réussite de 100 %, MCP étant 23 % plus rapide et 2,5 % moins cher. Mais l’avantage de vitesse provenait principalement du contournement de la détection de commandes malveillantes de Claude Code sur les invocations bash, et non d’une supériorité inhérente du protocole. Un benchmark distinct d’automatisation de navigateur a révélé que le CLI obtenait un score 33 % meilleur en efficacité de tokens, complétant des tâches que MCP ne pouvait structurellement pas réaliser, avec des requêtes CLI sélectives consommant 43 fois moins de tokens que les snapshots MCP équivalents.
Les CLI l’emportent sur l’efficacité en tokens (pas de coût de schéma ambient, puisque les outils ne consomment des tokens que lorsqu’ils sont activement utilisés), la familiarité des données d’entraînement (les LLM connaissent bien la syntaxe CLI), la composabilité Unix (les pipes permettent des workflows multi-étapes en une seule expression) et l’absence de surcoût d’implémentation (pas de serveur à construire ou déployer). MCP l’emporte sur les schémas typés (la validation JSON Schema empêche les commandes mal formées), l’universalité des clients (fonctionne dans Claude Desktop et les extensions IDE qui n’ont pas d’accès shell), les opérations stateful (sessions et tokens d’authentification gérés nativement) et l’audit de sécurité (permissions granulaires et pistes d’audit).
Le consensus émergent, bien résumé par Zechner : “The protocol is just plumbing. What matters is whether your tool helps or hinders the agent’s ability to complete tasks.” Le CLI gws incarne ce pragmatisme en offrant les deux surfaces depuis un seul binaire.
Ce que ça signifie pour les équipes data sur GCP
Google Sheets est l’une des “sources de données fantômes” les plus courantes en analytics engineering. Les parties prenantes métier maintiennent des tables de correspondance, des seed data, des chiffres de budget et des saisies ad hoc dans des feuilles de calcul. BigQuery supporte les tables externes adossées à Sheets, et le dbt Semantic Layer s’intègre désormais directement avec Sheets et Excel. Mais gérer ces Sheets de manière programmatique nécessitait soit la bibliothèque Python gspread, soit l’API REST brute.
Avec gws et un agent IA de codage, le workflow devient conversationnel. Un agent peut découvrir des Sheets dans Drive, inspecter leur structure, valider les schémas par rapport aux définitions de tables BigQuery, créer ou mettre à jour des tables externes, et déclencher des runs dbt via des commandes CLI ou des appels d’outils MCP. Une fois un job terminé, le même agent peut composer un email de synthèse via gws gmail, mettre à jour un runbook Google Doc avec des descriptions de colonnes, pousser des résultats de requêtes vers un dashboard Sheets, ou créer un événement Calendar pour la prochaine revue de qualité des données. Le repo embarque 50 recettes curées pour exactement ces patterns, dont recipe-create-events-from-sheet, recipe-draft-email-from-doc et recipe-label-and-archive-emails.
La tendance de fond ici est la convergence. Les outils d’infrastructure data (BigQuery, dbt, Airflow) et les outils de productivité (Gmail, Sheets, Docs, Calendar) fusionnent à travers les couches d’agents IA. Le propre BigQuery Data Engineering Agent de Google (expérimental) automatise la création de pipelines à partir de langage naturel. Les utilisateurs de Claude Code combinent déjà les skills d’agent dbt avec le MCP BigQuery, et ajouter le MCP gws à cette stack boucle la boucle entre les sorties de pipelines data et la communication métier.
Le CLI gws est une implémentation concrète d’une philosophie de conception qui gagne du terrain : construire les outils pour les agents d’abord, pour les humains ensuite. Pour les analytics engineers sur GCP, la valeur immédiate est pratique : un accès programmatique à la couche Google Workspace que gcloud a toujours ignorée, livré dans un format que les agents IA de codage peuvent consommer nativement. Le risque de maturité (pré-v1.0, non officiellement supporté) est réel mais atténué par l’architecture dynamique du Discovery Service et la position de l’auteur dans l’équipe DevRel de Google Workspace. À surveiller de près, et à installer dès aujourd’hui.