@googleworkspace/cli

Qu'est-ce que googleworkspace-cli ?

googleworkspace/cli (publié sous @googleworkspace/cli) est un outil en ligne de commande pour Google Workspace. Il vous permet de travailler avec plusieurs API Workspace — telles que Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, et plus — via une seule CLI.

L'interface de commandes est générée dynamiquement à l'exécution à partir du Discovery Service de Google, plutôt que d'inclure une liste fixe de commandes. Le projet est également décrit comme incluant des « AI agent skills », et la CLI met l'accent sur une sortie JSON structurée pour l'automatisation.

Fonctionnalités principales

• Une seule CLI pour plusieurs services Workspace : Fournit une interface unique pour interagir avec Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin et d'autres API Workspace.
• Génération dynamique des commandes depuis le Discovery Service : Les commandes et méthodes sont construites en lisant le Discovery Service de Google à l'exécution, afin que les nouveaux points de terminaison/méthodes soient pris en charge sans liste statique.
• Sortie JSON structurée : Conçue pour l'automatisation et les agents IA ; les réponses sont retournées en JSON structuré.
• Introspection des schémas pour les méthodes API : Utilisez gws schema <...> pour inspecter le schéma de requête/réponse d'une méthode.
• Simulation de requêtes et aides à la pagination : Utilisez --dry-run pour prévisualiser les requêtes et --page-all pour diffuser les résultats paginés (optionnellement vers des outils comme jq).
• Flux d'authentification multiples : Prend en charge des workflows de configuration/connexion adaptés à un usage local, CI et serveurs, y compris l'intégration avec gcloud si disponible.
• Compétences d'agents intégrées : La documentation du dépôt note qu'il inclut « 40+ agent skills ».

Comment utiliser googleworkspace-cli

1. Installez la CLI :
   • Via npm : npm install -g @googleworkspace/cli
   • Ou avec un binaire précompilé depuis GitHub Releases
   • Ou compilation depuis la source : cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux mentionnent aussi Homebrew ; un Nix flake est disponible.)
2. Authentifiez-vous (configuration unique du projet, puis connexion) :
   • gws auth setup (nécessite gcloud installé et authentifié)
   • gws auth login (connexion OAuth ultérieure)
   • Pour des flux manuels basés sur des jetons ou console, les docs listent des variables d'environnement et un chemin de configuration OAuth manuel.
3. Exécutez des commandes sur une ressource. Exemples de workflows des docs :
   • Lister les fichiers : gws drive files list --params '{"pageSize": 5}'
   • Créer une feuille de calcul : gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • Envoyer un message Chat : gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • Introspection du schéma : gws schema drive.files.list

Cas d'usage

• Automatiser les workflows Drive avec pagination et JSON : Diffuser de grands ensembles de résultats depuis les points de terminaison de liste Drive et les traiter avec des outils en aval (ex. : combiner la sortie --page-all avec jq).
• Envoyer des requêtes Gmail/Chat/Calendar sans écrire de REST bruts : Utilisez les commandes centrées sur les ressources de la CLI pour créer ou mettre à jour des objets en vous appuyant sur l'interface générée.
• Valider la structure des requêtes avant exécution : Utilisez --dry-run pour prévisualiser ce que la CLI enverrait, utile pour générer des charges pour Sheets, Chat et autres ressources.
• Construire des outils pour agents IA autour des API Workspace : Utilisez les réponses JSON structurées et les compétences d'agents incluses pour qu'un agent piloté par LLM décide des actions Workspace à appeler avec moins de code personnalisé.
• Découvrir comment appeler une méthode API depuis la CLI : Quand vous connaissez une méthode mais pas sa forme exacte de requête, utilisez gws schema <method> pour inspecter le schéma de requête/réponse.

FAQ

• googleworkspace-cli est-il un produit Google officiel ? Non. Le dépôt précise : « This is not an officially supported Google product. »

• A-t-il une liste fixe de commandes ? Non. Les docs indiquent qu'il n'inclut pas de liste statique de commandes ; il lit le Discovery Service de Google à l'exécution et génère dynamiquement son interface de commandes.

• Que faut-il installer pour l'utiliser ? Les prérequis listent Node.js 18+ pour le flux d'installation npm. L'authentification nécessite un projet Google Cloud pour les identifiants OAuth et un compte Google avec accès Workspace.

• Quelle configuration d'authentification utiliser ? Les docs décrivent plusieurs chemins :

  • Configuration assistée par gcloud (gws auth setup) si gcloud est installé et authentifié
  • Configuration OAuth manuelle via Google Cloud Console quand l'automatisation n'est pas possible
  • Identifiants manuels/jetons via variables d'environnement (comme documenté)

• Y a-t-il des limitations liées aux scopes en développement/test ? Oui. Les docs avertissent que si l'app OAuth n'est pas vérifiée (mode test), Google limite le consentement à ~25 scopes et que le préréglage de scopes recommandé (85+ scopes) échouera pour les apps non vérifiées — surtout pour les comptes @gmail.com.

Alternatives

• Appels directs aux API REST avec curl ou un client HTTP : Vous permet d'appeler directement les endpoints Workspace, mais vous devez gérer vous-même le formatage des requêtes, la pagination et les détails d'authentification.
• SDK officiels pour des services Workspace spécifiques (par ex., bibliothèques Google APIs spécifiques à un langage) : Fournissent des méthodes client typées pour des services particuliers, mais impliquent généralement des chemins de code séparés par API plutôt qu'une interface CLI unique générée dynamiquement.
• Autres outils CLI pour les API Google : Les CLIs alternatives se concentrent souvent sur des services spécifiques ou utilisent des ensembles de commandes statiques ; selon l'outil, ils n'offrent pas nécessairement la même génération dynamique de commandes basée sur le Discovery Service ou le flux de travail d'introspection JSON structuré + schéma décrit ici.