9 min read
GWS CLI Review: A Faster Way to Give AI Access to Google Workspace
gws is an open-source command-line tool that lets Claude, Codex or ChatGPT work directly in your Google Drive, Docs, Sheets, Gmail and Calendar. In our test it beat the official connector on speed. The setup is the hard part.

Scorecard
SCORE
8/10 ★★★★☆
VERDICT
A fast, direct way to let AI work in Google Workspace. It loses two points because it isn’t officially supported by Google and it carries some minor security risks.
BEST FOR
Power users and developers who use Claude, Codex or ChatGPT with Google Drive, Docs, Sheets, Gmail or Calendar every day.
SKIP IF
Your company only allows officially supported tools, or you don’t want to manage a Google Cloud project and an OAuth key.
COST
Free and open source (Apache-2.0). You need your own Google account and Google Cloud project.
WORKS WITH
Claude, Codex, ChatGPT and other AI tools that can run terminal commands
TESTED ON
Windows (PowerShell), with Claude
WHY NOT A 10
Two points off: gws isn’t officially supported by Google, and it carries some minor security risks, because it runs on an OAuth key you have to protect yourself.
The problem with the official connector
Anthropic now offers official Google Workspace connectors for Claude, covering Gmail, Calendar and Drive on paid plans, and a Claude for Google Workspace editing beta was reported in October 2026. In our testing, the official route has limits, uses a lot of tokens and is slow on bigger tasks.
If you live in Google Docs and Sheets and want AI to do real work there, that adds up. gws is the alternative we tried. We lean on Claude a lot here: our founder even built Mercury Converter with its help.
What gws is
gws is an open-source command-line tool, published as googleworkspace/cli on GitHub under the Apache-2.0 licence. It covers Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin and more, and is built from Google’s Discovery Service. It also ships Agent Skills (SKILL.md files) that teach AI agents how to use it.
One important detail: the repo sits under the googleworkspace GitHub organization, but its README says “This is not an officially supported Google product.”
How it works
Your AI assistant runs gws commands in your terminal. gws then calls Google’s APIs through your own Google Cloud project, using your own OAuth login. There’s no middleman service. You decide which apps and which permissions (scopes) it gets.
–
Your AI (Claude, Codex, ChatGPT) asks gws to do something.
–
gws runs in your terminal and uses your OAuth key.
–
Your Google Cloud project holds the APIs and permissions you enabled.
–
Google Workspace (Drive, Docs, Sheets, Gmail, Calendar) does the work.
The demo
The video walks through the review, a live demo and the full setup on a fresh account.
With gws already connected, we asked Claude to build a full-year dummy dataset with charts in Google Sheets. It took about 3 minutes. Our estimate is that the official connector would take two to three times longer and use more tokens. That’s our experience, not a measured benchmark.
As a second test, Claude wrote a short poem about the setup into a Google Doc and changed its sharing setting to public. It worked first time.
Setting it up
This is where gws asks for patience. On our first try it took about 15 to 16 authentications and sign-ups to get working. The second time, we gave Claude a notes file (.md) that recorded every error from the first attempt, and Claude guided the setup much more smoothly. We recommend doing the same, and you can download our notes file for free below.
$ sudo
free –download
Free download: my GWS setup notes for your AI
Every error I hit on my first gws setup, and the fix for each, in one .md file. Give it to Claude, Codex or ChatGPT before you start, and it will know which errors to expect and how to avoid them.
–
1. Create a Google Cloud project. Use a dedicated one for gws.
–
2. Enable the APIs you want gws to use, such as Drive, Docs and Sheets.
–
3. Set up the OAuth consent screen in Testing mode.
–
4. Add yourself as a test user.
–
5. Add scopes manually on Data Access.
–
6. Create an OAuth client (Desktop) and download its JSON file.
–
7. Run the login command in PowerShell or Terminal: gws auth login --scopes followed by the full scope URLs.
–
8. Review the permissions on Google’s consent screen. Most people can skip Drive and Gmail access unless they need it.
–
9. Look for the success message. You’re connected.
You can install gws with npm (npm install -g @googleworkspace/cli), Homebrew, Cargo or a release binary from GitHub.
Common errors and fixes
These are the errors we hit, from our own setup notes:
–
403 access_denied: add your account as a test user on the consent screen.
–
invalid_scope: use the full scope URLs, not short names.
–
Insufficient scopes: add the scopes on Data Access and tick every box on the consent screen.
–
API not enabled: enable that API in your Cloud project.
–
401 after logging in again: run gws auth logout, then log in again.
–
Logged out after about a week: in our experience, Testing-mode logins expire after roughly a week, so you have to log in again.
Security checklist
gws runs on an OAuth key, so whoever has your device and that key can reach your Workspace. Secure your device first, then:
–
Use a dedicated Google account and Cloud project.
–
Never share the client JSON file. Claude suggested deleting the downloaded copy once it was set up.
–
Grant only the scopes you need.
–
Keep confirmation prompts on for sends, shares and deletes.
–
Review access at myaccount.google.com/permissions.
–
Rotate the client secret if it ever leaks.
Giving an AI agent real access to your accounts is a trust decision. We covered the bigger picture in NVIDIA’s plan to box in AI agents.
What it does well
–
Speed. In our testing it finished complex tasks faster than the official connector.
–
Fewer tokens. Direct commands meant less back-and-forth for the AI.
–
Broad coverage. Drive, Docs, Sheets, Gmail, Calendar, Chat, Admin and more.
–
Works with more than Claude. Codex, ChatGPT and other tools that can run terminal commands.
–
You stay in control. Your own project, your own login, your own scopes.
–
Free and open source under Apache-2.0.
The catch
–
Not officially supported by Google. Many companies and enterprises won’t allow it for that reason.
–
Hard setup. A Cloud project, APIs, consent screen, test user, scopes and an OAuth client before your first command.
–
Minor security risks. The OAuth key lives on your device, so you’re responsible for protecting it and limiting scopes.
–
Re-logins. Testing-mode logins expired after about a week in our experience.
Who should use it
–
Power users and developers who already work with Claude, Codex or ChatGPT in a terminal.
–
Anyone who finds the official connector too slow or token-hungry for real Docs and Sheets work.
–
Not for locked-down company accounts. Check your IT policy first.
If you’re building a lean toolkit around AI, gws fits next to the tools in our lean dev stack for under $20 a month. If you’d rather have AI in a launcher than a terminal, see our Raycast review. Leaving Google instead of going deeper? Our Takeout JSON Metadata Fixer review shows how to take your photos with you, dates intact.
$ sudo
verdict
8/10. Faster than the official route, with strings attached.
gws gave our AI direct, quick access to Google Workspace and handled a real task in about 3 minutes. It isn’t officially supported by Google, the setup takes patience, and the OAuth key needs care. If you’re comfortable with that, it’s the better way to connect AI to Workspace today.
Next step: read the README on GitHub, set it up on a dedicated Google account, and start with the fewest scopes you can.
Which tool should we review next? Tell us in the comments.
FAQ
What is the gws CLI?
gws is an open-source command-line tool (googleworkspace/cli on GitHub, Apache-2.0) that gives AI assistants such as Claude, Codex and ChatGPT direct access to Google Workspace, including Drive, Docs, Sheets, Gmail and Calendar.
Is gws an official Google product?
No. The project’s README says it is not an officially supported Google product, even though it sits under the googleworkspace GitHub organization.
How do I connect Claude to Google Workspace with gws?
Create a Google Cloud project, enable the APIs, set up the OAuth consent screen, add yourself as a test user, add scopes on Data Access, create a Desktop OAuth client, then run gws auth login with the scopes you need.
Is gws faster than the official Claude Google Workspace connector?
In our testing, yes. A full-year dataset with charts in Google Sheets took about 3 minutes. We estimate the official connector would take two to three times longer, but we didn’t run a measured side-by-side test.
Is gws safe to use?
It uses your own OAuth login, so treat the key like a password. Use a dedicated account and project, grant only the scopes you need, never share the client JSON, and review access in your Google account permissions. Many companies won’t allow it because it isn’t officially supported.
Why did gws get 8 out of 10?
It’s fast and flexible, but it loses two points because it isn’t officially supported by Google and it carries some minor security risks around the OAuth key and scopes.
Some links on this page may be affiliate links, always labeled. Opinions are ours. Verdicts aren’t for sale. How we work.
On this page
01
02
03
04
05
10
12
13
14
$ sudo
request –tool
Want us to test an AI tool?
← Back to

