How to Set Up the Google Workspace CLI (gws)

Before you start

The Google Workspace CLI (we call it gws) is a small program that lets Claude Code do things in your Google account on your behalf. Things like reading your inbox, scheduling a calendar event, creating a Google Doc, or pulling rows from a Sheet.

You give Claude Code access once, and then your AI assistant can help you with your real work, in your real Google account, without you copying and pasting.

You'll need three things to start:

• A Google account (any free Gmail or Google Workspace account works)
• Node.js installed on your computer (the Download Claude Code guide covers this)
• About 20 minutes

Heads up. This guide walks through Google's free Cloud Console. Everything here is free. You won't be charged.

Step 1, Install the gws CLI

Open your terminal (Terminal on Mac, PowerShell on Windows) and paste this:

npm install -g @googleworkspace/cli

Press Enter. Wait for it to finish. It usually takes under a minute.

To confirm it installed, run:

gws --help

You should see a list of commands. If you do, you're good.

Tip. If the terminal says "command not found," Node.js isn't installed yet. Pop back to the Download Claude Code guide for that piece first.

Step 2, Create a Google Cloud project

A "project" is just a container that holds the permissions you're about to give Claude Code. Every Google API access starts with one.

1. Open this page: console.cloud.google.com/projectcreate
2. Sign in with the Google account you want Claude Code to use
3. Project name: type something simple like My Claude Code or Jane Smith Workspace
4. Leave Organization and Location as whatever Google suggests
5. Click Create

Wait about 10 seconds. A little notification at the top right will say the project is ready. Click Select Project in that notification (or use the project picker at the top of the page).

Tip. You only ever need one project for this, even if you use gws across many computers.

Step 3, Turn on the Google APIs you need

Each Google service (Gmail, Drive, Calendar, etc.) is a separate API that you have to switch on. Do them one at a time. It's faster than it sounds.

Open each of these links, click the blue Enable button, then come back here for the next one:

1. Enable Gmail API
2. Enable Google Drive API
3. Enable Google Calendar API
4. Enable Google Sheets API
5. Enable Google Docs API
6. Enable Google Slides API
7. Enable Google Tasks API
8. Enable People API

Each one just takes a click. You'll see a green checkmark and "API enabled" when it's on.

Tip. Make sure your project name is showing at the top of the page before you click Enable. If a different project is selected, you'll enable the API on the wrong one.

Step 4, Set up the consent screen

This is the screen Google shows when you log in for the first time, asking "do you really want this app to read your email?" You're the developer and the user, so you're answering for yourself.

1. Open this page: console.cloud.google.com/auth/overview
2. Click Get started
3. App name: type My Claude Code Workspace (or anything you'll recognize later)
4. User support email: pick your own email from the dropdown
5. Click Next
6. Audience: select External, then click Next
7. Contact information: paste your email address again
8. Click Next, then Finish

Now add yourself as a test user (this is important, or login will fail):

1. From the same area, open the Audience tab on the left
2. Scroll to Test users and click + Add users
3. Paste your own Google email address and click Save

Tip. Test mode is fine. It just means only the emails you list (yours) can use the app. You can leave it in test mode forever.

Step 5, Create your credentials file

This is the file that proves to Google your gws install is the one you set up.

1. Open this page: console.cloud.google.com/auth/clients
2. Click + Create client (top of the page)
3. Application type: choose Desktop app
4. Name: type gws CLI
5. Click Create
6. A dialog pops up showing your client ID. Click the Download JSON button on that dialog (or the download icon next to the client in the list)
7. The file will save to your Downloads folder with a long name like client_secret_79333...apps.googleusercontent.com.json

Keep this file safe. It's the key to your Google account. Don't share it or post it anywhere.

Step 6, Save the credentials file in the right place

gws looks for the credentials in a specific folder. We'll move the file there and rename it.

On Mac or Linux

Open your terminal and run:

mkdir -p ~/.config/gws
mv ~/Downloads/client_secret_*.json ~/.config/gws/client_secret.json

On Windows (PowerShell)

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\gws" | Out-Null
Move-Item "$env:USERPROFILE\Downloads\client_secret_*.json" "$env:USERPROFILE\.config\gws\client_secret.json"

If you have more than one client_secret_*.json in Downloads, delete the old ones first so only the new one moves.

Step 7, Log in with gws

This is the moment gws asks you which permissions to grant.

In your terminal, run:

gws auth login

What happens next:

1. A browser window opens
2. Pick the Google account you want to connect (the same one you added as a test user)
3. Google warns you the app isn't verified. That's normal for a personal project. Click Advanced, then Go to My Claude Code Workspace (unsafe)
4. Tick all the permission boxes (Gmail, Drive, Calendar, Sheets, Docs, Slides, Tasks, profile)
5. Click Continue
6. The browser will say "The authentication flow has completed." Close the tab
7. Back in the terminal, you'll see "Login successful"

Tip. The "unsafe" warning is because Google hasn't reviewed your personal project. It's safe because you built it. You're not handing access to a stranger, you're handing it to yourself.

Verify it worked

Run this in your terminal:

gws auth status

You should see your email address, a list of scopes (the permissions you just granted), and "token_valid": true. That means everything is wired up.

For a real test, try this. It lists your three most recent Gmail labels:

gws gmail users labels list --params "{\"userId\":\"me\"}"

If you see JSON come back with your label names in it, you are done. Claude Code can now act inside your Google account whenever you ask it to.

Reach out if any step trips you up. The first time through is the hardest. After this, you never have to think about it again.