LE MONDE NE S’ARRÊTE PAS.RSS
BIG CHANGE.

Édition Markdown

AI-translated from English; not yet reviewed by a fluent editor.

# Connecter Claude Code à Google Workspace avec cinq vérifications de lecture

> Une procédure documentée pour vérifier le compte Google Workspace CLI de Claude Code, les autorisations OAuth et les demandes de permission au moyen de lectures limitées dans Drive, Sheets, Docs et Gmail.

By BIG CHANGE Editorial

Published: 2026-10-20T09:34:40.461Z
Updated: 2026-10-20T09:34:40.461Z
Canonical: https://bigchange.ai/blog/claude-code-google-workspace-cli-read-checks

![Conceptual charcoal illustration of one person studying abstract command lines on a desktop monitor, with a plain folder, grid sheet, document and sealed envelope on the table.](https://bigchange.ai/api/media/file/gws-claude-read-check-workstation-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE.

Claude Code peut exécuter les commandes Google Workspace CLI (`gws`) depuis un shell local, avec le compte Google authentifié dans `gws`. Le titulaire autorisé du compte peut vérifier cette connexion avec un élément sans risque dans chacun des services Drive, Sheets, Docs et Gmail. Confirmez d’abord le compte et ses autorisations. Ce guide suit l’interface documentée du dépôt CLI, examinée le 20 octobre 2026. BIG CHANGE n’a installé aucun des deux outils ni accédé à un compte.

## Le grand changement

- **Ce qui a changé :** Le CLI `gws` actuel expose les méthodes des API Google Workspace sous forme de commandes shell que Claude Code peut exécuter. Un compte authentifié peut donner accès à plusieurs services de travail, dans les limites de ses autorisations réelles et des permissions du shell de l’agent.
- **Pourquoi cela compte :** La connexion permettant à un agent de consulter un fichier ou un message sélectionné peut aussi atteindre d’autres données couvertes par ses scopes OAuth. Le titulaire du compte peut comparer des résultats restreints et connus dans le terminal et dans Claude Code avant de déléguer davantage de travail.
- **Points à surveiller :** Vérifiez les commandes générées par le CLI installé et les règles de permission effectives de la session à chaque modification de cette configuration. Le CLI est antérieur à la version 1.0 ; une requête d’exemple limitée ou un masque de champs ne réduit pas l’autorisation à l’échelle du compte.

## Avant la connexion

Utilisez un compte de test Google dédié et approuvé, sans contenu sensible, et un projet Cloud où vous pouvez configurer OAuth. Demandez à l’administrateur si les quatre API et les autorisations demandées sont permises. Préparez un fichier Drive existant au nom unique, une feuille de calcul avec des valeurs connues dans une petite plage, un court Google Doc en texte brut à un seul onglet et un message Gmail sans risque. Pour Gmail, récupérez son identifiant RFC `Message-ID` dans **Show original**. Vous comparerez ces originaux aux résultats du CLI. Ces vérifications ne créent ni n’envoient rien.

Installez Claude Code sur un ordinateur maîtrisé. Installez `gws` depuis la [version du dépôt destinée à votre système d’exploitation](https://github.com/googleworkspace/cli/releases) ou, avec Node.js 18 ou une version ultérieure, utilisez la commande documentée :

```bash
npm install -g @googleworkspace/cli
gws --version
gws --help
gws auth login --help
```

Conservez en privé les versions installées du CLI et de Claude Code. Le CLI est encore antérieur à la version 1.0 et ses commandes sont construites à partir des documents de découverte des API Google. Vérifiez l’aide installée et les schémas des méthodes ci-dessous avant d’exécuter les exemples.

## 1. Configurer une connexion OAuth limitée

Dans le projet Cloud approuvé, activez les API Drive, Sheets, Docs et Gmail. Configurez l’audience OAuth et créez un client **Desktop app**. Si l’application est de type External et en test, ajoutez le compte choisi comme utilisateur de test. Enregistrez le fichier JSON du client téléchargé à l’emplacement documenté `~/.config/gws/client_secret.json` ou utilisez un répertoire séparé sélectionné avec `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`. Gardez ce répertoire hors du projet Claude et accessible uniquement au titulaire du compte.

Avant la connexion, vérifiez en privé si `GOOGLE_WORKSPACE_CLI_TOKEN` ou `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` est défini, notamment dans un fichier `.env`. Ces sources sont prioritaires sur les identifiants OAuth enregistrés. N’affichez pas leurs valeurs et ne demandez pas à Claude Code de lire les fichiers d’identifiants. Utilisez un environnement propre et la configuration du client prévue.

Demandez explicitement ces quatre scopes :

```bash
gws auth login --scopes 'https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/gmail.readonly'
gws auth status
```

Effectuez vous-même la sélection du compte et le consentement. Le code source du CLI à la révision indiquée ajoute également les scopes d’identité `openid`, `userinfo.email` et `userinfo.profile`. Comparez en privé le consentement et les informations de `gws auth status` sur le compte, les autorisations et la validité du jeton avec vos intentions ; un champ de statut absent reste non vérifié. Arrêtez si le compte est incorrect ou si une autorisation plus large inattendue demeure. Choisir des services dans le sélecteur de connexion filtre les choix ; cela ne définit pas ces quatre scopes en lecture seule.

Les scopes sont plus larges que les requêtes d’exemple. L’accès aux métadonnées Drive couvre les métadonnées des fichiers accessibles ; l’accès Sheets et Docs en lecture seule couvre les feuilles de calcul et documents accessibles ; Gmail en lecture seule peut accéder au contenu de la boîte. Noms, identifiants, plages, requêtes et masques de champs limitent chaque réponse, pas l’autorité du jeton. Un outil shell peut aussi atteindre les identifiants locaux : masquer un chemin ou donner une instruction dans un prompt ne les isole pas.

## 2. Exécuter directement les lectures limitées

Examinez d’abord chaque méthode avec `gws schema drive.files.list` et les noms de schéma correspondants pour les autres méthodes. Consultez l’aide générée `--help` si un paramètre diffère dans la version installée. Les commandes ci-dessous utilisent les apostrophes de Bash ; adaptez volontairement la syntaxe de citation pour un autre shell. Remplacez uniquement les identifiants et le nom de test. Exécutez une commande à la fois et conservez sa réponse ou son erreur réelle en privé, sans jetons ni contenu sensible.

Recherchez le fichier Drive nommé. La séquence JSON `\u0027` échappe les apostrophes dans l’expression de recherche Drive tout en préservant la syntaxe de citation Bash :

```bash
gws drive files list --params '{"pageSize":5,"q":"trashed = false and name = \u0027GWS connection check\u0027","fields":"files(id,name,mimeType),nextPageToken,incompleteSearch"}'
```

Comparez son identifiant et son nom avec le fichier dans Drive. L’absence de correspondance ou `incompleteSearch` ne prouve pas l’accès au fichier prévu.

Lisez les cellules connues avec l’identifiant réel de la feuille de calcul et le nom de l’onglet :

```bash
gws sheets spreadsheets values get --params '{"spreadsheetId":"SPREADSHEET_ID","range":"Sheet1!A1:C3","fields":"range,majorDimension,values"}'
```

Comparez les valeurs retournées avec la feuille. Google peut omettre les cellules vides finales ; préparez donc des valeurs connues non vides.

Lisez le premier onglet du court document de test :

```bash
gws docs documents get --params '{"documentId":"DOCUMENT_ID","includeTabsContent":false,"fields":"documentId,title,body(content(paragraph(elements(textRun(content)))))"}'
```

Vérifiez l’identifiant, le titre et le texte connu. Cette réponse limitée ne contrôle ni les autres onglets, ni les commentaires, ni la structure complète du document.

Pour Gmail, recherchez le message existant par son identifiant RFC `Message-ID`, puis utilisez l’identifiant Gmail retourné pour demander deux en-têtes :

```bash
gws gmail users messages list --params '{"userId":"me","maxResults":1,"q":"rfc822msgid:MESSAGE_ID_FROM_SHOW_ORIGINAL","fields":"messages(id,threadId),nextPageToken,resultSizeEstimate"}'
gws gmail users messages get --params '{"userId":"me","id":"GMAIL_MESSAGE_ID","format":"metadata","metadataHeaders":["Message-ID","Subject"],"fields":"id,threadId,payload(headers)"}'
```

Comparez le `Message-ID` retourné et l’objet sans risque avec l’original. Le premier appel retourne les identifiants des messages, pas leurs en-têtes. Le second demande les métadonnées des en-têtes, pas le corps du message. Une première réponse vide ne permet pas la seconde vérification. Le scope OAuth Gmail de métadonnées, plus étroit, n’autorise pas la requête de recherche utilisée ici ; l’autorisation explicite Gmail en lecture seule l’autorise.

## 3. Répéter avec Claude Code et les demandes de permission

Démarrez Claude Code dans un projet que vous maîtrisez, avec la même configuration de compte approuvée. Dans `/permissions`, examinez le mode effectif et les règles du shell. Utilisez Manual (également appelé `default`) et une règle **Ask** pour l’outil shell réellement utilisé ; réglez toute règle d’autorisation plus large ou de contournement conformément à la politique de votre organisation. Évitez une autorisation générale pour `gws *` ou un programme enveloppant le shell. À chaque commande proposée, examinez la commande complète et n’approuvez que la lecture limitée voulue.

Demandez en langage courant à Claude Code de proposer les cinq commandes ci-dessus avec les mêmes cibles de test et de les exécuter une par une, uniquement après votre décision de permission. Demandez les sorties ou erreurs sans lecture des identifiants, élargissement des requêtes ni écriture. Comparez ensuite chaque résultat avec le résultat direct et l’objet original. Les instructions du projet peuvent décrire la tâche, mais les permissions effectives des outils et les autorisations OAuth régissent l’accès.

| Service | Preuve de réussite pour les deux voies |
| --- | --- |
| Drive | Même identifiant et même nom de fichier ; recherche complète. |
| Sheets | Onglet, plage et valeurs connues attendus. |
| Docs | Identifiant, titre et texte du premier onglet attendus. |
| Gmail | La liste trouve le message de test ; la récupération des métadonnées correspond à son `Message-ID` et à son objet. |

Consignez les versions, le compte authentifié, les autorisations réelles, les identifiants cibles, le résultat direct, celui de Claude et les erreurs dans une fiche privée. Une requête échouée, une réponse réussie mais vide et un objet vérifié sont des résultats différents. Terminez uniquement lorsque les quatre services sont vérifiés par les deux voies.

## Si une vérification échoue

Une erreur **Access blocked** à la connexion peut signifier que le compte de test ne figure pas parmi les utilisateurs de test de l’application OAuth. Pour une erreur d’API ou de scope, confirmez l’API activée, le compte sélectionné et les autorisations réelles avant de demander un nouveau consentement approuvé. Pour une liste vide, vérifiez la cible exacte, la requête et le compte. Si l’aide installée diffère des exemples, consultez le schéma actuel de la méthode avant de continuer. Si Claude Code propose une commande qui modifie des données ou élargit l’accès, refusez-la lors de la demande de permission et revenez à la lecture limitée.

Le dépôt CLI est disponible sans package payant. Le compte ou le forfait Workspace, les quotas Cloud et le forfait Claude Code ou l’usage de l’API peuvent entraîner des coûts. Le fournisseur configuré dans Claude Code peut traiter le contenu récupéré : utilisez uniquement des données de test non sensibles et approuvées. Le CLI précise qu’il n’est pas un produit Google officiellement pris en charge et avertit de changements avant la version 1.0. BIG CHANGE n’a testé ni performances ni compatibilité. Arrêtez avant toute écriture, tout envoi ou toute modification de compte. [Le module complémentaire Google Workspace distinct de Claude](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) traite la modification de fichiers ouverts avec approbation par une autre voie.

## Sources

- [README de Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — Dépôt officiel à une révision précise, examiné le 20 octobre 2026. Établit l’installation, la configuration OAuth manuelle, les commandes dynamiques, la priorité des identifiants, l’instabilité des versions et l’avis de produit non pris en charge. Il ne prouve aucune exécution par BIG CHANGE.
- [Contexte des commandes Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — Instructions officielles à une révision précise concernant les méthodes imbriquées, --params, l’inspection des schémas et la sélection limitée des champs ; vérifiez l’aide réellement installée.
- [Implémentation de l’authentification Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — Le code d’authentification à la révision indiquée confirme les --scopes personnalisés, le comportement distinct du sélecteur de services et l’ajout de scopes d’identité. Examiner le code ne montre pas l’autorisation réelle d’un lecteur.
- [Guide d’activation des API Google Workspace](https://developers.google.com/workspace/guides/enable-apis) — Instructions Google pour activer les API dans un projet Cloud ; les politiques du projet et de l’administrateur régissent toujours l’accès.
- [Référence Drive files.list](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — Confirme les paramètres Drive q, pageSize et les champs de réponse utilisés pour limiter la recherche de métadonnées. Une requête limitée ne limite pas l’autorité OAuth.
- [Référence Sheets spreadsheets.values.get](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — Confirme la lecture d’un identifiant de feuille de calcul et d’une plage A1 ainsi que la structure de réponse ; les cellules vides finales peuvent être omises.
- [Référence Docs documents.get](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — Confirme la récupération d’un document et la limitation au premier onglet lorsque includeTabsContent vaut false. L’exemple concerne un document de test en texte brut à un seul onglet.
- [Références Gmail messages.list et messages.get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — La référence list établit la recherche par identifiant de message et les résultats contenant uniquement des identifiants ; q n’est pas disponible avec gmail.metadata. La référence get associée est https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get et établit metadataHeaders avec le format METADATA.
- [Permissions de Claude Code](https://code.claude.com/docs/en/permissions) — Référence actuelle d’Anthropic sur le mode Manual/default, les règles Ask, les permissions effectives des outils et les demandes d’approbation du shell. Elle ne prouve pas qu’une session donnée possède une règle particulière.