The 31.8K-star gws: one command into Gmail, but the default scopes will block you first
The Google Workspace team put a command-line tool called gws on GitHub. It has 31.8K stars, and one command connects Gmail, Drive, Calendar, and Sheets. Installation takes three lines; the blocker is authorization: the recommended scope preset has 85+ scopes, while unverified apps get only about 25. And Model Armor, which can block prompt injection, only warns by default instead of blocking.
If you were given just one command to take over Gmail, Drive, and Calendar, gws is currently the shortest one. The catch comes later—not during installation, but on the authorization page.
What it is
gws lives under the googleworkspace GitHub organization, has 31.8K stars, and is Apache-2.0. One CLI covers Drive, Gmail, Calendar, Sheets, and Docs; the repo ships with 100+ agent skills, 50 of which are ready-made recipes. You can run it by saying things like this to an agent:
find every invoice PDF in my Drive from last month
make a Sheet that tracks these leads
what's on my calendar Thursday
Installation is three lines:
npm install -g @googleworkspace/cli
gws auth setup
npx skills add https://github.com/googleworkspace/cli
It supports agents that consume skills, such as Claude Code, Codex, and Gemini CLI. Gemini CLI has a separate extension install method; gemini extensions install points to the same repo. There are also Homebrew and cargo routes.
The command surface is built at runtime
There is no hard-coded command table in gws. On startup it reads argv[1] to determine which service you want, pulls Google's Discovery Service document, caches it for 24 hours, assembles a command tree on the fly from the resources and methods in the document, and then re-parses the remaining arguments. If Google Workspace adds an API one day, gws will recognize it a day later.
Output is uniformly structured JSON, including errors. Exit codes have five levels: 0 success, 1 API error, 2 authentication error, 3 invalid parameter or service name, 4 failed to fetch the Discovery document, 5 internal error. Scripts can branch directly on the code instead of grepping error text. Add --dry-run to preview requests and --page-all to auto-paginate and emit NDJSON; it pipes smoothly into jq:
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'
The blocker is on the authorization page, not in the terminal
There's an inconspicuously placed warning in the README: for unverified OAuth apps, Google allows only about 25 scopes. The recommended preset contains 85+, so selecting it directly will fail, and @gmail.com accounts are especially likely to hit this. The fix is to choose manually:
gws auth login -s drive,gmail,sheets
Another default deserves a closer look. gws can hook into Google Cloud's Model Armor to scan API responses for prompt injection. But it's optional, and the default mode is warn, not block. Unless you explicitly set GOOGLE_WORKSPACE_CLI_SANITIZE_MODE=block, a poisoned email will still be delivered to the agent, just with an extra line of warning next to it.
On this point, a commenter named Mano mentioned a Barracuda finding: phishing emails hide instructions in HTML comments, zero-font-size CSS text, and zero-width characters. To the human eye there's nothing there; the model reads it all cleanly. So he keeps Gmail send permission locked behind manual confirmation.
Rohan's approach is to start with a throwaway mailbox and read-only scopes for a week. Kevlar puts it more granularly: every connector starts read-only, write permissions are added one action at a time, and before adding one, look at what it actually did with that action. Soup_Oracle directly points out the detail many people gloss over: the recommended preset has 85 scopes; if an agent is driving, pick them manually and keep Gmail off for now.
My take
The scarcity of this tool isn't in its capabilities; it's in its form. Dawid is right: MCP could already do these things. The CLI wins elsewhere: it can be piped together, called by cron, run in shell scripts, audited, and --dry-run lets you do a dry run to see what the request looks like. Humans and agents face the same entry point and the same set of exit codes. In enterprises, what actually causes friction isn't installation; it's permissions. An agent that can read every invoice in Drive needs access that can be tiered and audited before anyone dares to sign off.
31.8K stars landing on a project that Google explicitly says is 'not an officially supported product'—that number itself shows how deep the backlog of demand is. It also shows that people haven't hit the wall on the authorization page often enough yet.
If you want to try it, the first thing after installation is to remove Gmail write permissions and enable only drive and sheets first. Once you've seen its --dry-run output a few times, then consider other things. There will be breaking changes before v1.0; that's not just a polite disclaimer.
发布时间: 2026-10-25 01:31