gws Puts All of Google Workspace on Your Agent's Command Line

Wiring an AI agent into Google Workspace usually means writing custom API glue for every task. gws — 31k stars, built under the googleworkspace org — takes a different route: one CLI whose entire command surface is generated at runtime from Google's own Discovery Service, so when Workspace adds an endpoint, the CLI already speaks it — with one disclaimer attached: the README states this is not an officially supported Google product.

Why This Skill Matters

Every response is structured JSON, which is what makes the CLI agent-friendly: your LLM reads the output directly, no parsing layer. The README's AI Agent Skills section says the repo ships 100+ Agent Skills (SKILL.md files) — one for every supported API — plus higher-level helpers for common workflows and 50 curated recipes spanning Gmail, Drive, Docs, Calendar, and Sheets. Hand-crafted helper commands are prefixed with + so they never collide with Discovery-generated methods: gws gmail +triage summarizes your unread inbox, gws workflow +standup-report compiles today's meetings and open tasks, and gws workflow +email-to-task turns a Gmail message into a Tasks entry. Time-aware helpers pull your Google account timezone automatically.

Installation

npm install -g @googleworkspace/cli

Homebrew, prebuilt release binaries, cargo, and a Nix flake are documented as alternatives. Then authenticate:

gws auth setup     # one-time: creates a Cloud project, enables APIs, logs you in
gws auth login     # subsequent scope selection and login

gws auth setup requires the gcloud CLI. Watch the scope warning if your OAuth app is unverified: Google caps testing-mode consent at roughly 25 scopes, and the README says the recommended preset includes 85+ scopes and will fail — especially for @gmail.com accounts. Select individual services instead:

gws auth login -s drive,gmail,sheets

The skills install separately from the binary:

npx skills add https://github.com/googleworkspace/cli

Or pick only what you need, one skill URL at a time (.../skills/gws-drive, .../skills/gws-gmail). A Gemini CLI extension is documented too: gemini extensions install https://github.com/googleworkspace/cli.

Real Workflow: A Morning Briefing Your Agent Can Run

1. Install the CLI, authenticate, and add the skills for the services you use.
2. Let the helpers do the compilation:

gws calendar +agenda
gws gmail +triage
gws workflow +standup-report

+standup-report returns today's meetings plus open tasks as a standup summary; +agenda shows upcoming events in your account timezone unless you override it with --timezone. 3. Point your agent at the same commands — or hand it the briefing prompt directly:

Run gws workflow +standup-report and gws gmail +triage, then draft a short
morning summary of my day from the JSON output.

Real Workflow: Agent-Driven Drive and Sheets

The agent works with plain commands and JSON. Listing the ten most recent files is gws drive files list --params '{"pageSize": 10}'; appending a row is gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95". Two flags keep agent loops safe: --dry-run previews the request without sending it, and --page-all streams every page as NDJSON instead of stopping at the default. When output looks wrong, gws schema drive.files.list prints the exact request/response schema for any method.

Tips

• Sheets ranges contain !, which triggers bash history expansion — wrap them in single quotes: 'Sheet1!A1:C10'.
• Scripts can branch on structured exit codes — six documented values from 0 success to 5 internal error — instead of parsing error text.
• Model Armor integration scans API responses for prompt injection before your agent sees them: pass --sanitize "projects/P/locations/L/templates/T"; the mode defaults to warn and can be set to block.
• Discovery documents are cached for 24 hours, so repeated agent calls do not re-fetch schemas.

When Not to Use This

You need a Google Cloud project and OAuth before the first useful command — there is no API-key quickstart. The project is under active development and the README expects breaking changes on the way to v1.0, so pin versions in automation. And because it is not an officially supported Google product, org admins may reasonably decline the OAuth app in managed domains.

See the leaderboard for more skills.