Google just dropped a Rust-powered bomb:
gws (the official Google Workspace CLI)
If you’ve ever tried to automate Workspace, you know the pain:
wrestling with the REST API, building boilerplate OAuth flows, or writing brittle Apps Script workarounds.
gws changes the game by using a dynamic discovery service to build its command surface at runtime.
If Google adds it, gws sees it.
Here is the developer’s guide to setting up gws, including the exact commands I used to integrate it into my agentic workflow.
Installation: The 30-Second Start
The CLI is built in Rust but distributed via npm, making it light and fast.
Open your terminal and run:
# Global installation
npm install -g @googleworkspace/cli# Verify the install
gws --version
The Authentication Dance
This is where my friend Sumeet usually tripped up, but you won’t.
You can’t just run the CLI, you need to give it a passport via a Google Cloud Project.
The GCP Prep:
- Go to
console.cloud.google.comand create a project (e.g.,gws-terminal-access). - Enable the APIs you need: Google Drive API, Gmail API, and Google Calendar API.
- Set up your OAuth Consent Screen (Internal/External) and add your email as a Test User.
- Create OAuth 2.0 Client ID credentials (Desktop App) and download the JSON.
The Local Setup:
Rename that downloaded file to client_secret.json and move it to the required config directory:
# For macOS/Linux
mkdir -p ~/.config/gws
mv ~/Downloads/your_downloaded_file.json ~/.config/gws/client_secret.json# Now, trigger the login flow
gws auth login --scopes drive,gmail,calendar
The CLI will open a browser window.
Once you hit “Allow,” your terminal is officially “Sovereign.”
Real-World Commands for High-Velocity Devs
Once authenticated, you can stop Vibe Coding your automation and start executing.
Here is the syntax that works:
Managing Drive Files:
# List all files in your Drive
gws drive files list# Search for a specific project file
gws drive files list --params '{\"q\":\"name contains \'PlayoPartner\'\"}'
Querying Gmail:
# List your 10 most recent messages
gws gmail users messages list --params '{\"userId\":\"me\",\"maxResults\":10}'Checking the Calendar:
# List upcoming events on your primary calendar
gws calendar events list --params '{\"calendarId\":\"primary\"}'Pro-Tip for PowerShell users: If you’re running this on Windows, the Linux-style JSON escaping will break. Use the PowerShell syntax: '{\"key\":\"value\"}'.The Agentic Leap: Integrating with Claude (MCP)
This is why I was the most excited.
Because gws outputs structured JSON, it’s a perfect fit for Model Context Protocol (MCP).
By adding it to my claude_desktop_config.json, I could let my Claude handle the document lookups while I stay focused on the Python logic.
Add this to your Claude Desktop config:
{
"mcpServers": {
"gws": {
"command": "gws",
"args": ["mcp", "-s", "drive,gmail,calendar"]
}
}
}Now, I don’t run commands; I just tell Claude: “Check my Gmail for the latest Stripe invoice and find the corresponding contract in Drive.”
Claude calls gws, parses the JSON, and gives me the summary.
So,
Does it beat Gemini?
For general “Knowledge Work” and deep research, I still rely on Gemini.
Its ability to synthesize information across the web is unmatched for my Outer Layer strategy.
But for local execution and repo-level integration, gws was the missing link.
It treats Google Workspace like a database rather than a website.
If you are building agents or just tired of the "API overhead," this tool is non-negotiable.