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 or, with Node.js 18 or later, use the documented command:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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 covers editing open files with approval through a different route.