name: google-workspace description: Access Google Workspace APIs (Drive, Docs, Calendar, Gmail, Sheets, Slides, People) via local helper scripts. Handles OAuth login and direct API calls. USE WHEN user wants to search Google Drive, check calendar, search Gmail, read Google Docs, or interact with any Google Workspace service.

Google Workspace

Access Google Workspace APIs via the gws CLI — a single binary, no scripts or Node.js needed.

Supports: Drive, Docs, Calendar, Gmail, Sheets, Slides, People, Tasks, Chat, Classroom, Forms, Keep, Meet.

Auth

# Check auth status
gws auth status

# Login (opens browser)
gws auth login

# Clear credentials
gws auth logout

Operational Guidance for the Agent

Always check auth first: Run gws auth status — look for "token_valid": true.
If auth is missing/expired: Run gws auth login and wait for browser consent.
Do not explain setup unless a command actually failed.
Use gws schema to discover method parameters when unsure.
Never print token/credential contents back to the user.

CLI Usage

gws <service> <resource> [sub-resource] <method> [flags]

Flags

Flag	Description
`--params '<JSON>'`	URL/query parameters
`--json '<JSON>'`	Request body (POST/PATCH/PUT)
`--upload <PATH>`	File to upload (multipart)
`--output <PATH>`	Save binary response to file
`--format <FMT>`	Output: `json` (default), `table`, `yaml`, `csv`
`--page-all`	Auto-paginate (NDJSON, one JSON per page)
`--page-limit <N>`	Max pages (default: 10)

Schema Introspection

# Discover parameters for any method
gws schema calendar.events.list
gws schema drive.files.list
gws schema gmail.users.messages.list

Common Patterns

Calendar

# Today's events (use ISO dates with timezone)
gws calendar events list --params '{
  "calendarId": "primary",
  "timeMin": "2025-01-20T00:00:00Z",
  "timeMax": "2025-01-21T00:00:00Z",
  "singleEvents": true,
  "orderBy": "startTime"
}'

# Upcoming N days — compute timeMin/timeMax with `date`
gws calendar events list --params "{
  \"calendarId\": \"primary\",
  \"timeMin\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
  \"timeMax\": \"$(date -u -d '+7 days' +%Y-%m-%dT%H:%M:%SZ)\",
  \"singleEvents\": true,
  \"orderBy\": \"startTime\"
}"

# Specific calendar
gws calendar events list --params '{
  "calendarId": "work@redhat.com",
  "timeMin": "...",
  "timeMax": "...",
  "singleEvents": true,
  "orderBy": "startTime"
}'

Drive

# Search files
gws drive files list --params '{
  "q": "name contains '\''Roadmap'\'' and trashed=false",
  "pageSize": 10,
  "fields": "files(id,name,mimeType,modifiedTime,webViewLink)"
}'

# Recent files
gws drive files list --params '{
  "pageSize": 10,
  "orderBy": "modifiedTime desc",
  "fields": "files(id,name,mimeType,modifiedTime,webViewLink)"
}'

# By type
gws drive files list --params '{"q": "mimeType='\''application/vnd.google-apps.document'\''", "pageSize": 10}'
gws drive files list --params '{"q": "mimeType='\''application/vnd.google-apps.spreadsheet'\''", "pageSize": 10}'

Gmail

# Search messages
gws gmail users messages list --params '{
  "userId": "me",
  "q": "is:unread newer_than:1d",
  "maxResults": 10
}'

# Read a message
gws gmail users messages get --params '{
  "userId": "me",
  "id": "<messageId>",
  "format": "full"
}'

# Common queries
# "from:alice@example.com newer_than:7d"
# "has:attachment newer_than:7d"
# "in:sent newer_than:1d"

Docs

gws docs documents get --params '{"documentId": "<DOC_ID>"}'

Sheets

gws sheets spreadsheets values get --params '{
  "spreadsheetId": "<SHEET_ID>",
  "range": "Sheet1!A1:D10"
}'

People

gws people people connections list --params '{
  "resourceName": "people/me",
  "personFields": "names,emailAddresses",
  "pageSize": 10
}'

Environment Variables

Variable	Description
`GOOGLE_WORKSPACE_CLI_TOKEN`	Pre-obtained OAuth2 access token (highest priority)
`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`	Path to OAuth credentials JSON
`GOOGLE_WORKSPACE_CLI_CLIENT_ID`	OAuth client ID
`GOOGLE_WORKSPACE_CLI_CLIENT_SECRET`	OAuth client secret