googleworkspace

googleworkspace — Google Workspace via the gws CLI

Overview

The gws CLI provides access to Google Workspace APIs (Drive, Gmail, Calendar, Sheets, Docs, Chat, and more). Commands are dynamically generated from Google's Discovery Service.

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

Helper commands (prefixed with +) provide shortcuts for common workflows.

Authentication

# Browser-based OAuth (interactive, one-time)
gws auth login

# Or use an existing access token
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

Global flags

Flag	Description
--params '{...}'	URL/query parameters (JSON)
--json '{...}'	Request body (JSON)
--dry-run	Preview request without calling the API
--page-all	Auto-paginate all results (NDJSON output)
--upload <PATH>	Upload file content (multipart)
--format <FMT>	Output format: json (default), table, yaml, csv

Discovering commands

Always inspect before calling an unfamiliar method:

gws <service> --help
gws schema <service>.<resource>.<method>

Gmail

# Send an email
gws gmail +send --to [email protected] --subject "Hello" --body "Hi there"

# Unread inbox summary
gws gmail +triage

# Read a message body
gws gmail +read --message-id MESSAGE_ID

# Reply to a message (threading handled automatically)
gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"

# Reply-all
gws gmail +reply-all --message-id MESSAGE_ID --body "Acknowledged"

# Forward a message
gws gmail +forward --message-id MESSAGE_ID --to [email protected]

# Watch for new emails (streams NDJSON)
gws gmail +watch

# List messages via API
gws gmail users messages list --params '{"maxResults": 10}'

Calendar

# Show upcoming events
gws calendar +agenda

# Show agenda in a specific timezone
gws calendar +agenda --timezone America/New_York

# Create an event
gws calendar +insert --title "Standup" --time "2026-05-02T09:00:00"

# List events via API
gws calendar events list --params '{"calendarId": "primary", "maxResults": 5}'

# Check free/busy
gws calendar freebusy query --json '{"timeMin": "...", "timeMax": "...", "items": [{"id": "primary"}]}'

Drive

# List files
gws drive files list --params '{"pageSize": 10}'

# Upload a file
gws drive +upload ./report.pdf --name "Q1 Report"

# Download a file
gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' -o output.pdf

# Search for files
gws drive files list --params '{"q": "name contains '\''budget'\''", "pageSize": 10}'

# Create a folder
gws drive files create --json '{"name": "Projects", "mimeType": "application/vnd.google-apps.folder"}'

Sheets

# Read a range
gws sheets +read --spreadsheet SPREADSHEET_ID --range "Sheet1!A1:D10"

# Append a row
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95,A"

# Read via API
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1:C10"}'

# Append via API
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'

# Create a new spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

Docs

# Append text to a document
gws docs +write --document-id DOC_ID --text "New paragraph of text"

# Get document content
gws docs documents get --params '{"documentId": "DOC_ID"}'

Chat

# Send a message to a space
gws chat +send --space-id spaces/SPACE_ID --text "Deploy complete."

# List spaces
gws chat spaces list

Shell tips

• zsh ! expansion: Sheet ranges like Sheet1!A1 contain ! which zsh interprets as history expansion. Always use double quotes for ranges:

  gws sheets +read --spreadsheet ID --range "Sheet1!A1:D10"
  

• JSON quoting: Wrap --params and --json values in single quotes so the shell doesn't interpret the inner double quotes.

Safety rules

• Confirm with the user before executing write or delete operations.
• Prefer --dry-run for destructive operations until the user confirms.
• Never output secrets, API keys, or tokens directly.

Exit codes

Code	Meaning
0	Success
1	API error (4xx/5xx)
2	Auth error
3	Validation error
4	Discovery error
5	Internal error