ServicesÀ proposNotesContact Me contacter →
EN FR
Note

Google Workspace CLI (gws)

Le CLI gws donne un accès programmatique à toutes les API Google Workspace via un seul binaire — Gmail, Drive, Calendar, Sheets, Docs — comblant la lacune que gcloud n'a jamais couverte.

Planté
gcpmcpautomationaidata engineering

Le CLI gcloud couvre l’infrastructure GCP (Compute, BigQuery, Cloud Storage, IAM, et plus) mais ne couvre pas Google Workspace. Gmail, Google Sheets, Calendar et Drive ne sont pas accessibles via gcloud. Le Google Workspace CLI (gws) comble cette lacune.

Ce qu’est gws

gws est un outil en ligne de commande open source créé par Justin Poehnelt, Senior Developer Relations Engineer dans l’équipe Workspace de Google. Il donne un accès programmatique à toutes les API Google Workspace via un seul binaire : Gmail, Drive, Calendar, Sheets, Docs, Chat, Admin, et plus. Le projet vit sous l’organisation GitHub officielle googleworkspace et porte l’avertissement standard « not an officially supported Google product ».

Début 2026, le projet est à la version v0.3.5 avec environ 5 100 étoiles GitHub. Il est écrit en Rust, distribué via npm avec des binaires précompilés, et en développement actif vers v1.0 avec des changements incompatibles attendus. Le statut pre-v1.0 et la désignation de support non officiel sont de vrais risques de maturité — valent la peine d’être suivis de près, mais pas des raisons d’attendre.

Terminal window
# Installer globalement via npm (binaires natifs précompilés, Rust non requis)
npm install -g @googleworkspace/cli


# Vérifier avec une liste rapide des fichiers Drive récents
gws drive files list --params '{"pageSize": 5}'

Ce qui existait avant

Avant gws, la principale option d’automatisation pour Google Workspace était Google Apps Script. Cela fonctionne, mais c’est fondamentalement inadéquat dans les contextes d’ingénierie des données :

  • Timeout d’exécution de 6 minutes sur les comptes gratuits (30 minutes sur Workspace)
  • Exécution synchrone single-thread — pas de parallélisme
  • Pas de gestionnaire de packages — limité aux services intégrés
  • Quotas API journaliers facilement atteints dans les contextes de pipeline
  • Pas d’intégration CI/CD — tout vit dans le runtime de Google

Les API REST fonctionnent aussi, mais nécessitent un boilerplate substantiel pour l’authentification, la pagination et la gestion des erreurs — trois choses que les ingénieurs ne devraient pas écrire depuis zéro en 2026.

gws abstrait tout cela derrière une interface cohérente.

L’architecture de découverte dynamique

Ce qui est techniquement intéressant dans gws, c’est la façon dont il construit sa surface de commandes. Au lieu d’expédier une liste statique de commandes gravées au moment de la publication, gws lit le Discovery Service de Google au runtime et génère dynamiquement chaque commande depuis les spécifications API actuelles.

Quand Google ajoute un nouvel endpoint, le CLI le récupère automatiquement. Les documents de découverte sont mis en cache pendant 24 heures, donc le coût de performance est minimal. Cela signifie que l’outil ne prendra jamais de retard sur les API qu’il encapsule — un véritable avantage architectural par rapport aux wrappers écrits à la main.

Vous pouvez inspecter le schéma de n’importe quelle méthode directement :

Terminal window
# Obtenir le schéma complet des paramètres et des réponses pour le listing de fichiers Drive
gws schema drive.files.list

Cela retourne du JSON lisible par machine : paramètres, corps de requête, types de réponse, portées OAuth. Utile à la fois pour les humains qui cherchent quels paramètres passer et pour les agents générant des appels API sans avoir besoin de consulter la documentation externe.

Conception agent-first

Ce qui est le plus intéressant dans gws pour les analytics engineers n’est pas sa couverture API — c’est la philosophie de conception derrière lui. L’outil a été conçu dès le premier jour pour la consommation par des agents IA, pas pour une utilisation interactive humaine. Il est livré avec :

  • 100+ fichiers de skill agent — fichiers Markdown structurés avec frontmatter YAML encodant des conseils au-delà de ce que --help montre (« Utilisez toujours --dry-run pour les opérations mutantes », « Confirmez toujours avec l’utilisateur avant d’exécuter des commandes d’écriture/suppression »)
  • Un serveur MCP intégré — gws mcp -s drive,gmail,calendar expose les API Workspace comme outils structurés via stdio pour tout client compatible MCP
  • Sortie JSON structurée par défaut — pas de formatage lisible par des humains que les agents doivent analyser autour
  • Renforcement des entrées contre les hallucinations — validation contre le directory traversal, les caractères de contrôle, l’injection de paramètres de requête et le double encodage

Les sept principes derrière cette conception sont documentés séparément. La distinction centrale : les CLI humains optimisent pour la découvrabilité ; les CLI agent optimisent pour la prévisibilité et la validation des entrées.

MCP et exécution shell directe : deux chemins d’intégration

gws s’intègre avec les agents de codage IA via deux chemins complémentaires.

Le mode serveur MCP expose les API Workspace comme outils structurés pour tout client compatible MCP :

Terminal window
# Enregistrer gws comme serveur MCP dans Claude Code
claude mcp add gws -- gws mcp -s drive,gmail,calendar

Ou en modifiant ~/.claude.json directement :

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar"]
    }
  }
}

Chaque service ajoute environ 10 à 80 outils, donc limitez aux services dont vous avez réellement besoin pour rester sous les limites typiques de 50 à 100 outils des clients. Vérifiez la connexion avec /mcp dans une session Claude Code — vous devriez voir gws: connected.

L’exécution shell directe permet à Claude Code d’invoquer des commandes gws directement, d’analyser la sortie JSON et d’enchaîner des opérations. Ce chemin est souvent plus efficace en tokens que MCP car les outils ne consomment des tokens que lors de leur utilisation active, plutôt que de charger des définitions de schéma dans le contexte en permanence. Voir CLI vs MCP for AI Agents pour l’analyse complète des compromis.

Installation des skills agent

Le dépôt inclut 100+ fichiers de skill structurés qui peuvent être chargés dans tout agent utilisant des fichiers de skills :

Terminal window
# Installer tous les skills
npx skills add https://github.com/googleworkspace/cli


# Ou choisir des services spécifiques
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

Les skills encodent la sagesse opérationnelle qui n’est pas évidente depuis la documentation API : quelles opérations sont réversibles, quand confirmer avant de procéder, comment gérer la pagination pour les grands ensembles de résultats.

Alternatives tierces

Plusieurs serveurs MCP communautaires existent pour Google Workspace. Le plus complet en termes de fonctionnalités est le google_workspace_mcp de taylorwilsdon, couvrant 12 services avec 100+ outils. Des implémentations existent également en Go et Python. Ils nécessitent tous une configuration OAuth similaire et offrent des capacités comparables.

L’avantage de gws sur ceux-ci est la provenance de maintenance : il vit sous l’organisation GitHub officielle Google Workspace, est créé par un ingénieur DevRel de Google, et reste à jour avec les changements d’API dynamiquement plutôt qu’en nécessitant des mises à jour manuelles. L’inconvénient est sa maturité pre-v1.0 et son statut de support non officiel.

Pour les workflows spécifiques aux Sheets dans les contextes d’ingénierie des données, gws est actuellement l’option la plus capable avec la meilleure histoire d’intégration agent.