Google Workspace CLI (`gws`)

Services

drive, gmail, calendar, sheets, docs, slides, tasks, people, chat, classroom, forms, keep, meet, events, workflow

Helper Commands (preferred)

Helpers are prefixed with + and handle boilerplate (threading, encoding, metadata). Always prefer helpers over raw API calls when available.

Gmail

# Triage inbox
gws gmail +triage                              # unread summary (table)
gws gmail +triage --max 5 --query 'from:boss'  # filtered

# Read a message
gws gmail +read --id MSG_ID                    # plain text body
gws gmail +read --id MSG_ID --headers          # include From/To/Subject/Date

# Send
gws gmail +send --to [email protected] --subject 'Hello' --body 'Hi there'
gws gmail +send --to [email protected] --subject 'Report' --body 'Attached' -a report.pdf
gws gmail +send --to [email protected] --subject 'Hi' --body '<b>Bold</b>' --html

# Reply / Reply-all / Forward
gws gmail +reply --message-id MSG_ID --body 'Thanks!'
gws gmail +reply-all --message-id MSG_ID --body 'Noted'
gws gmail +forward --message-id MSG_ID --to [email protected] --body 'FYI'

Calendar

# View agenda
gws calendar +agenda                   # upcoming events (account timezone)
gws calendar +agenda --today           # today only
gws calendar +agenda --week            # this week
gws calendar +agenda --days 3          # next 3 days
gws calendar +agenda --timezone America/New_York

# Create event
gws calendar +insert --summary 'Standup' \
  --start '2026-06-17T09:00:00-07:00' --end '2026-06-17T09:30:00-07:00'
gws calendar +insert --summary 'Sync' \
  --start ... --end ... --attendee [email protected] --meet

Drive

# List files
gws drive files list --params '{"pageSize": 10}'
gws drive files list --params '{"q": "mimeType=\"application/vnd.google-apps.folder\"", "pageSize": 20}'

# Upload
gws drive +upload ./report.pdf
gws drive +upload ./report.pdf --parent FOLDER_ID --name 'Q1 Report'

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

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

# Delete
gws drive files delete --params '{"fileId": "FILE_ID"}'

Sheets

# Read
gws sheets +read --spreadsheet SHEET_ID --range 'Sheet1!A1:D10'

# Append row
gws sheets +append --spreadsheet SHEET_ID --values 'Alice,100,true'
gws sheets +append --spreadsheet SHEET_ID --json-values '[["a","b"],["c","d"]]'

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

⚠️ Shell quoting: Sheets ranges use ! — always wrap in single quotes to avoid bash history expansion.

Docs

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

# Append text
gws docs +write --document DOC_ID --text 'Hello, world!'

Workflow (cross-service)

gws workflow +standup-report           # today's meetings + open tasks
gws workflow +meeting-prep             # next meeting: agenda, attendees, docs
gws workflow +email-to-task --message-id MSG_ID   # email → task
gws workflow +weekly-digest            # week's meetings + unread count

Raw API Access

When no helper exists, use the raw Discovery API surface:

# Introspect any method schema
gws schema drive.files.list
gws schema gmail.users.messages.get

# Generic pattern
gws <service> <resource> <method> --params '{"key": "val"}' --json '{"body": "data"}'

Run gws <service> --help to see all resources and methods for a service.

Common Patterns

Pagination

gws drive files list --params '{"pageSize": 100}' --page-all --page-limit 50

Search Drive

# Files by name
gws drive files list --params '{"q": "name contains \"report\"", "pageSize": 10}'

# Files in folder
gws drive files list --params '{"q": "\"FOLDER_ID\" in parents", "pageSize": 50}'

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

Gmail Search

gws gmail +triage --query 'from:[email protected] after:2026/01/01'
gws gmail +triage --query 'subject:invoice has:attachment'
gws gmail users messages list --params '{"userId": "me", "q": "is:unread label:important", "maxResults": 5}'

Send Email with Raw API (when +send is insufficient)

# Base64url-encode the RFC 5322 message
RAW=$(echo -e "From: me\nTo: [email protected]\nSubject: Hi\n\nBody" | base64 -w 0 | tr '+/' '-_' | tr -d '=')
gws gmail users messages send --params '{"userId": "me"}' --json "{\"raw\": \"$RAW\"}"

Exit Codes

• 0 → success
• 1 → API error (Google 4xx/5xx)
• 2 → auth error (missing/expired credentials)
• 3 → validation error (bad args)
• 4 → discovery error
• 5 → internal error

Troubleshooting

• 403 insufficientPermissions → re-auth with needed scopes: gws auth login
• 403 accessNotConfigured → enable the API in GCP console (URL in error message)
• Exit code 2 → run gws auth login to refresh credentials
• "Using keyring backend: keyring" on stderr → normal, ignore

For detailed API schemas and advanced usage, see references/api-patterns.md.