If your life already runs on Gmail, Google Docs, and Sheets, you’ve probably wished more of it could run itself. For me it was an inbox where everything gets archived instead of deleted, on the off chance (almost never) that I’ll need to find that one email, and the spreadsheet where I was still running this blog’s content calendar by hand, which had gotten a little shameful when everything else I’ve built runs without me. Those wishes turned into a Marie Kondo pass on a decade of Gmail labels and the auto-filters that feed them, a Japanese tutor that drills and tests me over Gmail, and a stock analyst that writes its analyses into a spreadsheet that tells me how close I am to FIRE.

The workhorse behind most of that is gws, a tool from the Google Workspace team that Claude can call straight from the terminal (a CLI, if you speak dev). It covers Gmail, Docs, Sheets, Drive, Calendar, Slides, and basically every other corner of Workspace.

WHY A CLI AND NOT THE OFFICIAL GOOGLE WORKSPACE MCP SERVERS

Google publishes official MCP servers for these same products, and if you’ve connected Gmail or Drive in Claude.ai those already show up in Claude Code. (If MCP is new to you, I’ve written about how those plug-ins fit together.) The CLI is still the better pick, for two reasons.

  1. The menu vs. the kitchen. An MCP server hands Claude a fixed menu, whatever buttons its developer decided to expose, each behind its own sign-in. A CLI hands Claude the whole kitchen. gws doesn’t even have a fixed list of commands: it reads Google’s own API catalog at runtime, so anything the API can do, Claude can do, and when Google ships something new it just shows up, no update required.

  2. The menu needs you standing at the counter. MCP tools mostly need a live Claude session. A CLI also runs in plain scripts and cron jobs anywhere, which is exactly where the best personal automation lives. This blog’s content calendar updates itself after every publish because a CLI can run inside a script.

For everyday jobs the tool also has shortcuts, small hand-written commands that start with a + and do one common thing in one step: gws gmail +send sends an email, gws sheets +append adds a row to a spreadsheet. You never type any of this yourself. You say “email me the summary” or “add this to the spend sheet,” Claude picks the right command, and whatever comes back is in a form Claude can read and act on directly.

INSTALLING GWS AND GETTING THROUGH GOOGLE OAUTH

On a Mac it’s brew install googleworkspace-cli, or npm install -g @googleworkspace/cli if you’d rather, with pre-built binaries on the releases page for everything else. Signing in is two commands:

gws auth setup
gws auth login -s gmail,drive,docs,sheets,calendar

The list after -s is which Google products you’re letting Claude reach, and that lineup covers everything in this post.

gws auth setup wants gcloud, Google Cloud’s own terminal tool, installed and logged in first, and in return it does the annoying part, creating the Google Cloud project, enabling the APIs, and walking you through OAuth. The last time I did auth stuff in Google Cloud myself, it ended poorly, so I highly suggest you just have Claude Code set this up for you with the prompt below.

I want to set up the Google Workspace CLI (gws) from https://github.com/googleworkspace/cli. Install it, install gcloud first if I don't have it, run the auth setup, and stop and tell me whenever something needs me to click through in a browser.

You probably don’t have gcloud unless you’ve done Google developer stuff before, and that’s fine, the prompt has Claude install it for you. There’s also a manual console setup if you’d rather click through the Google Cloud Console yourself. When Claude says it’s done, running gws auth status in the terminal will confirm you’re signed in.

TROUBLESHOOTING GWS AUTH: WATCH-OUTS IN THE ORDER YOU’LL HIT THEM

Fair warning, this is not a fun or easy process. It wasn’t for me, and it isn’t for people way more technical than me either. You don’t have to memorize any of it, though. When something breaks, feed Claude this whole post and let it figure out which wall you hit, or trial-and-error your way through like I did.

  • Don’t accept the “recommended” scope preset. Unverified apps in testing mode are capped at roughly 25 OAuth scopes and the recommended set has 85+, so it fails, especially on a personal @gmail.com account. Pass -s with just the services you want and add more later.
  • “Insufficient authentication scopes” on a command. You signed in without that service. Re-run gws auth login with it added to the list.
  • “This app hasn’t been verified” screen during login. That’s your own OAuth app in testing mode. Click Advanced and continue.
  • “Access blocked” instead of the warning screen. Your email isn’t listed under Test users on the OAuth consent screen. This is the single most common failure and the fix is one click in the console.
  • redirect_uri_mismatch. The OAuth client was created as a Web app instead of Desktop app. Delete it, recreate as Desktop, download the new JSON to ~/.config/gws/client_secret.json.
  • 403 with accessNotConfigured. That API isn’t enabled on your Cloud project. gws prints the enable URL to stderr, click it, wait ten seconds, retry. Or re-run gws auth setup.
  • Auth works, then stops after a week. Testing-mode tokens expire after 7 days. Run gws auth login again. If it gets old, publish the OAuth app in the console (you’ll still see the unverified warning, but tokens stop expiring).
  • Command “not found” for something that exists. The command tree is generated from the API, so names follow the API resources: gws sheets spreadsheets values get, not gws sheets read. Run gws <service> --help to see the real tree, or gws schema <service.resource.method> for exact params.
  • Weird “event not found” error on Sheets commands. Ranges like Sheet1!A1:C10 contain a !, which bash treats as history expansion and mangles. Values have to be in single quotes. Claude usually gets this right once it knows the tool. Now you know it too.

TEST THAT THE GWS CLI WORKS WITH CLAUDE CODE

To find out whether the setup actually worked, give Claude a real use case to run:

Use gws to list my 10 most recent Drive files and tell me which ones are spreadsheets.

If you get an actual file list back, setup is done and everything from here is just asking for things.

The repo also ships skill files (Claude skills, one per API plus recipes for Gmail, Drive, Docs, Calendar, and Sheets) that teach Claude the command shapes ahead of time, installed with npx skills add https://github.com/googleworkspace/cli. Full honesty, I never installed them. Claude reads --help and works the commands out on its own, it just occasionally spends an extra turn getting there. Install them if you want fewer of those turns, skip them if you’d rather not think about it.

WHAT I ACTUALLY USE THE GOOGLE WORKSPACE CLI FOR

I use the gws CLI weekly, mostly for minor tasks and inside skills, but here are some bigger workflows you might find useful, each a little more involved.

  1. A mass Gmail audit, then automated ongoing organization. That Marie Kondo pass from the top of this post was Claude going through nearly two decades of Gmail, about 71,000 emails filed under 30 hand-made labels by 50 auto-filters, finding the filters that had stopped matching, and rebuilding the system so new mail gets filed automatically again. The rebuilt filters came back as a single XML file that Gmail imports in one click, instead of me recreating them one at a time in settings. The full story is its own post.

  2. The content calendar for this blog. It lives in a Google Sheet I was supposed to be updating by hand, and by the time I looked, it was 23 posts out of date and full of links that only worked on my machine. Claude read every row through gws, fixed the dead links, backfilled the missing posts, and then wrote a small script so the sheet now updates itself every time I publish.

  3. The FIRE spreadsheet. Every few months I drop raw exports from my bank and brokerage into a folder and tell Claude to run the pipeline it wrote. It cleans everything into one ledger, remembers every correction I’ve ever made, and pushes monthly summaries through gws into a sheet with one tab per question I care about, including how close we are to never needing a paycheck again. A retirement-scenarios layer sits on top of the same data, and seeing real numbers in one place has already proven a couple of my planning assumptions wrong. I’ll share a full how-to after a few more months of trial and error.

More are on my currently-in-experimentation list, like receipts forwarded to a Gmail label becoming rows in a spend sheet, and some calendar automation I haven’t settled on yet. Even the numbers in this post came from the same place, I asked Claude to query my inbox through gws mid-edit, and it counted the 71,000 emails and dated my account to 2008 in about a minute ;)