THE WORLD IS NOT STANDING STILL.RSS
BIG CHANGE.

Markdown edition

# Connect Claude Code to Google Workspace with five read checks

> A documented setup for checking Claude Code's Google Workspace CLI account, OAuth grants and permission prompts with bounded Drive, Sheets, Docs and Gmail reads.

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 can run Google Workspace CLI (`gws`) commands from a local shell, using the Google account authenticated in `gws`. An authorized account owner can check that connection with one harmless record each in Drive, Sheets, Docs and Gmail. First, confirm the account and grants. This guide follows the CLI repository's documented interface as inspected on October 20, 2026. BIG CHANGE did not install either tool or access an account.

## The big change

- **What changed:** The current `gws` CLI exposes Google Workspace API methods as shell commands that Claude Code can run. One authenticated account can provide a route across several work services, subject to its actual grants and the agent's shell permissions.
- **Why it matters:** The same connection that lets an agent inspect a selected file or message can reach other data covered by its OAuth scopes. An account owner can compare small, known results from the terminal and Claude Code before deciding whether to delegate more work.
- **What to watch:** Check the installed CLI's generated commands and the session's effective permission rules whenever this setup changes. The CLI is before 1.0; a narrow example query or field mask does not reduce the account-wide grant.

## Before you connect

Use a dedicated, approved Google test account without sensitive content and a Cloud project where you may configure OAuth. Ask your administrator whether the four APIs and requested grants are permitted. Prepare an existing uniquely named Drive file, a spreadsheet with known values in a small range, a short plain-text Google Doc with one tab, and a harmless Gmail message. For Gmail, get its RFC `Message-ID` from **Show original**. You will compare these originals with the CLI results. These checks create and send nothing.

Install Claude Code on a controlled computer. Install `gws` from the [repository's release for your OS](https://github.com/googleworkspace/cli/releases) or, with Node.js 18 or later, use the documented command:

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

Record the installed version and Claude Code version privately. The CLI is still before 1.0, and its commands are built from Google's API discovery documents. Check your installed help and the method schemas below before running the examples.

## 1. Configure a narrow OAuth login

In the approved Cloud project, enable the Drive, Sheets, Docs and Gmail APIs. Configure the OAuth audience and create a **Desktop app** client. If the app is External and in testing, add the chosen account as a test user. Save the downloaded client JSON in the documented `~/.config/gws/client_secret.json` location, or use a separate directory selected with `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`. Keep that directory outside the Claude project and private to the account owner.

Before login, privately check whether `GOOGLE_WORKSPACE_CLI_TOKEN` or `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` is set, including through a `.env` file. Those sources take precedence over stored OAuth credentials. Do not print their values or ask Claude Code to read credential files. Use a clean environment and the intended client configuration.

Request these four scopes explicitly:

```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
```

Complete account selection and consent yourself. The pinned CLI source also adds `openid`, `userinfo.email` and `userinfo.profile` identity scopes. Privately compare the consent and `gws auth status` account, grants and token validity with what you intended; a missing status field remains unverified. Stop if the account is wrong or an unexpected broader grant remains. Selecting services in the login picker filters choices; it does not itself set these four read-only scopes.

The scopes are broader than the example requests. Drive metadata access reaches metadata for accessible files; Sheets and Docs read-only access covers accessible spreadsheets and documents; Gmail read-only can access mailbox contents. Names, IDs, ranges, queries and field masks limit each response, not the token's authority. A shell tool may also reach local credentials, so a hidden file path or a prompt instruction does not isolate them.

## 2. Run the bounded reads directly

First inspect each method with `gws schema drive.files.list` and the corresponding schema names for the other methods. Check generated `--help` if a parameter differs in your installed version. The commands below use Bash single-quote syntax; adapt quoting deliberately for another shell. Replace only the test identifiers and name. Run one command at a time and retain its actual response or error privately, without tokens or sensitive content.

Find the named Drive file. The JSON `\u0027` escapes apostrophes inside the Drive search expression while preserving the Bash quoting:

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

Match its ID and name with the file in Drive. A missing match or `incompleteSearch` does not prove access to the intended file.

Read the known cells, using the actual spreadsheet ID and tab name:

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

Compare the returned values with the spreadsheet. Google may omit trailing empty cells, so prepare nonempty known values.

Read the first tab of the short test Doc:

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

Match the ID, title and known text. This limited response does not check other tabs, comments or the full document structure.

For Gmail, search by the existing message's RFC `Message-ID`, then use the returned Gmail ID to request two headers:

```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)"}'
```

Compare the returned `Message-ID` and harmless subject with the original. The first call returns message IDs, not headers. The second requests header metadata, not the message body. An empty first response cannot support the second check. Gmail's narrower metadata OAuth scope does not allow the search query used here; the explicit Gmail read-only grant does.

## 3. Repeat through Claude Code with permission prompts

Start Claude Code in a project you control, under the same approved account configuration. In `/permissions`, inspect the effective mode and shell rules. Use Manual (also called `default`) and an **Ask** rule for the actual shell tool; resolve any broader allow or bypass rule under your organization's policy. Avoid blanket approval for `gws *` or a shell wrapper. At each proposed command, inspect the complete command and approve only the exact bounded read you intend.

Tell Claude Code in plain language to propose the five commands above, using the same test targets, and run them one at a time only after your permission decision. Ask it to report command output or errors without reading credentials, enlarging queries or running a write. Then compare each result with both the direct result and the original object. Project instructions can describe this task, but the effective tool permissions and OAuth grants govern access.

| Service | Completion evidence from both routes |
| --- | --- |
| Drive | Same named file ID and name; search is complete. |
| Sheets | Expected tab, range and known cell values. |
| Docs | Expected ID, title and first-tab text. |
| Gmail | List finds the test message; metadata get matches its `Message-ID` and subject. |

Record the versions, authenticated account, actual grants, target IDs, direct result, Claude result and any errors in a private check sheet. A failed request, a successful empty response and a verified object are different outcomes. Finish only when all four services verify in both routes.

## If a check fails

An **Access blocked** login can mean the test account is missing from the OAuth app's test-user list. For an API or scope error, confirm the enabled API, selected account and actual grants before asking for approved re-consent. For an empty list, check the exact target, query and account. If installed help differs from these examples, use its current method schema before proceeding. If Claude Code proposes a mutating or wider command, decline it at the permission prompt and return to the bounded read.

The CLI repository is available without a paid package. The account or Workspace plan, Cloud quotas and Claude Code plan or API usage can carry costs. Retrieved content may be processed by Claude Code's configured provider, so keep these tests on approved nonsensitive data. The CLI says it is not an officially supported Google product and warns of pre-1.0 changes. BIG CHANGE has not tested performance or compatibility. Stop before any write, send or account change. [Claude's separate Google Workspace add-on](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) covers editing open files with approval through a different route.

## Sources

- [Google Workspace CLI README](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — Pinned official repository inspected October 20, 2026. Establishes installation, manual OAuth setup, dynamic commands, credential precedence, version instability and unsupported-product notice. It does not establish a BIG CHANGE execution result.
- [Google Workspace CLI command context](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — Pinned official command guidance for nested methods, --params, schema inspection and bounded field selection; actual installed help must be checked.
- [Google Workspace CLI authentication implementation](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — Pinned auth source confirms custom --scopes, separate service-picker behavior and appended identity scopes. Source inspection cannot show a reader's actual grant.
- [Google Workspace API enablement guide](https://developers.google.com/workspace/guides/enable-apis) — Google's instructions for enabling APIs in a Cloud project; project and administrator policies still govern access.
- [Drive files.list reference](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — Confirms Drive q, pageSize and response fields used to bound the metadata search. A narrow request does not narrow OAuth authority.
- [Sheets spreadsheets.values.get reference](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — Confirms a spreadsheet ID and A1 range read and response shape; empty trailing cells may be omitted.
- [Docs documents.get reference](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — Confirms document retrieval and the first-tab limitation when includeTabsContent is false. The example is for a single-tab plain-text test document.
- [Gmail messages.list and messages.get references](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — The list reference establishes message-ID search and ID-only list results; q is unavailable with gmail.metadata. The paired get reference is https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get and establishes metadataHeaders with METADATA format.
- [Claude Code permissions](https://code.claude.com/docs/en/permissions) — Anthropic's current reference for Manual/default mode, Ask rules, effective tool permissions and shell approval prompts. It does not establish that a reader's session has a particular rule.