| name | gws-cli |
| description | Use when interacting with Google Workspace (Drive, Sheets, Gmail, Calendar, Docs, Slides, Tasks, Contacts, Chat, Forms, Keep, Meet, Classroom, Apps Script) via the `gws` command-line tool |
gws — Google Workspace CLI
Overview
gws is a CLI that wraps the Google Workspace REST APIs. It's already installed at /opt/homebrew/bin/gws and authenticated.
Call shape:
gws <service> <resource> [sub-resource] <method> [flags]
Parameters that go in the URL/query string are passed as JSON via --params. Request bodies for POST/PATCH/PUT are passed as JSON via --json.
gws drive files list --params '{"pageSize": 10}'
gws drive files get --params '{"fileId": "abc123"}'
gws sheets spreadsheets values get --params '{"spreadsheetId": "...", "range": "Sheet1!A1:C10"}'
gws gmail users messages list --params '{"userId": "me", "q": "is:unread"}'
Prefer helper scripts for Docs and Slides
For Google Docs and Slides, use these helpers instead of gws docs / gws slides — they handle the multi-step fetch + flatten that you'd otherwise hand-roll:
~/.claude/scripts/fetch-google-doc.ts <DOC_ID>
~/.claude/scripts/fetch-google-slides.ts <PRESENTATION_ID>
If they fail with an auth error, tell the user — don't fall back to gws and retry.
Services
| Service | Purpose |
|---|
drive | Files, folders, shared drives, permissions |
sheets | Read/write spreadsheets |
gmail | Send, read, manage email |
calendar | Calendars and events |
docs | Read/write Google Docs (prefer helper script above) |
slides | Read/write presentations (prefer helper script above) |
tasks | Task lists and tasks |
people | Contacts and profiles |
chat | Chat spaces and messages |
forms | Read/write Google Forms |
keep | Google Keep notes |
meet | Google Meet conferences |
classroom | Classes, rosters, coursework |
script | Apps Script projects |
events | Subscribe to Workspace events |
admin-reports (alias reports) | Audit logs, usage reports |
workflow (alias wf) | Cross-service productivity workflows |
modelarmor | Filter user-generated content for safety |
Discovering resources, methods, and parameters
Don't guess — gws is self-documenting. Three cheap probes:
gws <service>
gws <service> <resource>
gws schema <service.resource.method>
gws schema drive.files.list --resolve-refs
Use gws schema … before composing a non-trivial request — it shows every parameter, which are required, accepted enums, and the response shape. Much faster than trial-and-error.
Useful flags
| Flag | Use |
|---|
--params <JSON> | URL/query parameters |
--json <JSON> | Request body (POST/PATCH/PUT) |
--upload <PATH> | Upload a local file as media (multipart) |
--upload-content-type <MIME> | Override the auto-detected MIME type |
--output <PATH> | Write binary responses to a file |
--format <json|table|yaml|csv> | Output format (default json) |
--page-all | Auto-paginate, NDJSON output, one line per page |
--page-limit <N> | Cap pages fetched by --page-all (default 10) |
--api-version <VER> | Override API version (e.g. v2, v3) |
--dry-run | Validate request locally without sending it |
Common patterns
Find a file by name:
gws drive files list --params '{"q": "name = '\''Budget 2026'\''", "fields": "files(id,name,mimeType)"}'
Read a sheet range:
gws sheets spreadsheets values get --params '{"spreadsheetId": "...", "range": "Sheet1!A:D"}'
Send mail:
gws gmail users messages send --params '{"userId": "me"}' --json '{"raw": "<base64url RFC2822>"}'
Page through results without truncation:
gws drive files list --params '{"pageSize": 100}' --page-all --page-limit 50
Exit codes
0 success · 1 API error · 2 auth · 3 validation (bad args) · 4 discovery (couldn't fetch schema) · 5 internal
Auth failures (2) usually mean the user needs to refresh credentials — surface this to them rather than retrying.
