DEV Community

Cover image for Comment utiliser Google Workspace CLI : Le guide complet
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser Google Workspace CLI : Le guide complet

#automation #cli #google #tutorial

Google Workspace CLI (gws) est un outil en ligne de commande open-source qui offre un accès unifié à Drive, Gmail, Agenda, Sheets, Docs, Chat, Admin et à toutes les API Google Workspace. Il repose sur le service Discovery dynamique de Google pour garantir des commandes toujours à jour sans mise à jour manuelle. Installez-le globalement via npm, authentifiez-vous une seule fois avec OAuth, et connectez-le à des agents IA comme Claude Code ou Cursor grâce aux compétences incluses. Plus besoin de gérer l’OAuth manuellement ni de composer plusieurs SDK.

Essayez Apidog dès aujourd'hui

Pourquoi utiliser Google Workspace CLI ?

Automatiser ou interroger Google Workspace (ex : Drive, Gmail, Agenda, Sheets, Docs, Chat) implique souvent d’écrire des scripts curl personnalisés, de gérer les portées OAuth, la pagination, ou de composer différents SDK rapidement obsolètes. Les API Google Workspace sont puissantes mais segmentées, chaque service ayant ses propres endpoints et spécificités. Google Workspace CLI élimine ce casse-tête : un seul CLI en Rust qui découvre dynamiquement chaque méthode d’API Workspace à l’exécution. Les nouveaux endpoints sont accessibles instantanément.

Résumé des avantages

  • Génère du JSON propre
  • Prend en charge le dry-run et la pagination NDJSON
  • Propose 40+ raccourcis conviviaux (préfixés par +)
  • Compétences d’agent prêtes pour Claude Code, Cursor, OpenClaw, Gemini CLI, etc.

Pour le test et la validation d’API, combinez-le à Apidog, client API gratuit pour envoyer des requêtes, vérifier les réponses, gérer des environnements et exécuter des tests.

Installation de Google Workspace CLI

Prérequis : Node.js 18 ou supérieur.

Vérifiez votre version :

node --version
Enter fullscreen mode Exit fullscreen mode

Exécuter sans installer

Pour un essai rapide ou des scripts ponctuels :

npx @googleworkspace/cli --help
npx @googleworkspace/cli drive files list --params '{"pageSize":1}'
Enter fullscreen mode Exit fullscreen mode

Installer globalement

Pour un usage régulier :

npm install -g @googleworkspace/cli
gws --version
Enter fullscreen mode Exit fullscreen mode

Des binaires précompilés sont intégrés, aucun besoin de compiler Rust localement. Alternativement, récupérez les binaires via GitHub Releases, utilisez Homebrew (brew install googleworkspace/cli) ou Nix.

Configuration initiale

Authentification

Pour configurer et authentifier votre compte :

gws auth setup
Enter fullscreen mode Exit fullscreen mode

Cette commande ouvre le navigateur, crée un projet Google Cloud si besoin, active les API requises et stocke les identifiants dans le trousseau sécurisé de l’OS (AES-256-GCM).

Installer les compétences d’agent

Après configuration :

npx skills add https://github.com/googleworkspace/cli
Enter fullscreen mode Exit fullscreen mode

Ou suivez les instructions spécifiques à votre agent (Claude Code, Cursor…). Redémarrez l’agent pour qu’il détecte les commandes.

Configuration projet vs globale

Par défaut, la config est globale. Pour une config projet :

gws auth setup --project
Enter fullscreen mode Exit fullscreen mode

Gestion des comptes et tokens

  • Se réauthentifier/changer de compte :

    gws auth login

  • Vérifier l’utilisateur courant :

    gws auth whoami

  • Se déconnecter :

    gws auth logout

  • Pour usage CI/CD (export des credentials) :

    gws auth export --unmasked > creds.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json

  • Réutiliser les jetons gcloud :

    export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

Désactiver la télémétrie 

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1
Enter fullscreen mode Exit fullscreen mode

Utilisation des commandes principales

Google Workspace CLI découvre dynamiquement les commandes. Pour lister les services disponibles :

gws --help
Enter fullscreen mode Exit fullscreen mode

Exemples pratiques

Drive : Lister et uploader

gws drive files list --params '{"pageSize":10, "q":"name contains report"}'
gws drive +upload ./budget.xlsx --name "2026 Budget"
Enter fullscreen mode Exit fullscreen mode

Gmail : Envoyer et traiter des mails

gws gmail +send --to collegue@example.com --subject "Mise à jour" --body "Voir pièce jointe." --attach ./file.pdf
gws gmail +reply --message-id <ID> --body "Merci !"
gws gmail +triage
Enter fullscreen mode Exit fullscreen mode

Agenda : Créer et afficher un événement

gws calendar +insert --summary "Planification de Sprint" --start "2026-03-20T10:00" --end "2026-03-20T11:00" --attendees "team@example.com"
gws calendar +agenda --today
Enter fullscreen mode Exit fullscreen mode

Sheets : Ajouter une ligne

gws sheets +append --spreadsheetId <ID> --range "Sheet1!A:C" --values "Tâche X,Terminé,2026-03-16"
Enter fullscreen mode Exit fullscreen mode

Docs : Insérer du texte

gws docs +write --documentId <ID> --text "Nouvelle section ajoutée via Google Workspace CLI"
Enter fullscreen mode Exit fullscreen mode

Chat : Publier un message

gws chat +send --space <SPACE_ID> --text "Déploiement terminé 🚀"
Enter fullscreen mode Exit fullscreen mode

Options utiles

  • Simulation : ajoutez --dry-run pour prévisualiser l’appel API sans exécution.
  • Pagination complète NDJSON : ajoutez --page-all.

Configuration avancée

Paramètres par défaut, délais, format de sortie, trousseau fichier

  • Persister des paramètres globaux :

    export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'

  • Afficher la config :

    gws config

  • Format de sortie : --json, --yaml

  • Changer le trousseau : variables d’environnement ou .env

Intégration avec des agents IA

Après installation des skills, les agents appellent nativement Google Workspace CLI.

Prompt type

  • "Lister mes fichiers Drive récents en utilisant Google Workspace CLI"
  • "Envoyer un e-mail de suivi via Google Workspace CLI"

Règle d’auto-invocation
Ajoutez dans les instructions de l’agent :

"Chaque fois que la tâche implique Gmail, Drive, Agenda, Sheets, Docs ou Chat, utilisez automatiquement les commandes Google Workspace CLI avant de répondre. Résolvez d'abord le service et la méthode."

Les agents renvoient des chemins de fichiers ou du JSON, gardant le contexte léger.

Utiliser Apidog avec Google Workspace CLI

Google Workspace CLI facilite l’accès aux API Workspace. Pour le debug de payloads, portées ou réponses, utilisez Apidog :

  • Envoyez des requêtes et inspectez les réponses brutes
  • Configurez des environnements avec jetons OAuth
  • Automatisez des assertions

Exemples concrets :

  • Votre agent propose d’ajouter à une feuille Sheets → Testez la charge utile exacte Sheets.values.append dans Apidog.
  • Problème de portées Gmail → Construisez et exécutez la requête visuellement.
  • Stockez des clés de service ou jetons utilisateur comme variables → Changez de compte et validez le comportement.

Combiner Google Workspace CLI + Apidog = accès live aux données + tests API reproductibles.

FAQ

Google Workspace CLI envoie-t-il mes données à l'extérieur ?

Non. Aucun appel direct n’est effectué vers les API Google en dehors de votre compte.

Quels services sont pris en charge ?

Toutes les API Workspace détectées dynamiquement : Drive, Gmail, Agenda, Sheets, Docs, Chat, Admin, Script, etc.

Comment les commandes restent-elles à jour ?

Interrogation dynamique du service Discovery : nouvelles méthodes disponibles immédiatement.

Faut-il une clé API ?

Utilise les comptes de service ou OAuth Google standards. Pas de clé API séparée.

Quels agents et éditeurs sont compatibles ?

Claude Code, Cursor, OpenClaw, Gemini CLI, extensions VS Code, tout outil compatible MCP ou Agent Skills.

Différence entre commandes brutes et helpers (+) ?

  • Brutes : méthodes Discovery exactes (drive.files.list)
  • Helpers (+) : raccourcis pour tâches courantes (+upload, +send)

Peut-on utiliser Google Workspace CLI sans agent IA ?

Oui, idéal pour scripts, automatisation ou terminal quotidien.

Ressources supplémentaires

Top comments (0)