Google Workspace CLI (gws)

The gws CLI is installed globally and authenticated with the user's Google Workspace account. Use it via the Shell tool to interact with Google Drive, Docs, Sheets, Slides, Gmail, and Calendar.

Command Pattern

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

Common Flags

Drive

Search files

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

List recent files

gws drive files list --params '{"pageSize": 10, "orderBy": "modifiedTime desc"}'

List files in a folder

gws drive files list --params '{"q": "'\''FOLDER_ID'\'' in parents"}'

List shared drives

gws drive drives list

Get file metadata

gws drive files get --params '{"fileId": "FILE_ID"}'

Upload a file

gws drive +upload ./report.pdf --parent FOLDER_ID

Export Google Workspace files

# Doc as PDF
gws drive files export --params '{"fileId": "FILE_ID", "mimeType": "application/pdf"}' > doc.pdf

# Sheet as CSV
gws drive files export --params '{"fileId": "FILE_ID", "mimeType": "text/csv"}' > data.csv

Advanced search queries

The q parameter supports operators:

MIME types for Google Workspace files:

Docs

Read a document

gws docs documents get --params '{"documentId": "DOCUMENT_ID"}'

The response contains the full document structure with text content in body.content[].paragraph.elements[].textRun.content.

Create a document

gws docs documents create --json '{"title": "Meeting Notes"}'

Append text (helper)

gws docs +write --document DOCUMENT_ID --text 'Hello, world!'

Batch update (insert, format, replace)

gws docs documents batchUpdate --params '{"documentId": "DOCUMENT_ID"}' --json '{
  "requests": [
    {"insertText": {"location": {"index": 1}, "text": "New heading\n"}},
    {"updateTextStyle": {"range": {"startIndex": 1, "endIndex": 12}, "textStyle": {"bold": true}, "fields": "bold"}}
  ]
}'

Replace text

gws docs documents batchUpdate --params '{"documentId": "DOCUMENT_ID"}' --json '{
  "requests": [{"replaceAllText": {"containsText": {"text": "OLD", "matchCase": true}, "replaceText": "NEW"}}]
}'

Sheets

Read values

gws sheets +read --spreadsheet SPREADSHEET_ID --range 'Sheet1!A1:B10'

Read full sheet

gws sheets spreadsheets values get --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1"}'

Append rows (helper)

gws sheets +append --spreadsheet SPREADSHEET_ID --values 'Alice,100,true'
gws sheets +append --spreadsheet SPREADSHEET_ID --json-values '[["Alice",100],["Bob",200]]'

Write values

gws sheets spreadsheets values update \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:B2", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", "95"]]}'

Create a spreadsheet

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

Get spreadsheet metadata

gws sheets spreadsheets get --params '{"spreadsheetId": "SPREADSHEET_ID"}'

Gmail

List recent messages

gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'

Read a message

gws gmail users messages get --params '{"userId": "me", "id": "MESSAGE_ID"}'

Send an email (helper)

gws gmail +send --to user@example.com --subject "Hello" --body "Hi there!"

Search messages

gws gmail users messages list --params '{"userId": "me", "q": "from:alice@example.com subject:report"}'

Calendar

List today's events

gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-28T00:00:00Z", "timeMax": "2026-03-28T23:59:59Z", "singleEvents": true, "orderBy": "startTime"}'

Note: replace the date values with the actual current date. singleEvents: true is required for orderBy: startTime to work and expands recurring events into individual instances.

List upcoming events

gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-23T00:00:00Z", "maxResults": 10, "singleEvents": true, "orderBy": "startTime"}'

Create an event (helper)

gws calendar +insert --calendar primary --summary "Team Standup" --start "2026-03-24T10:00:00" --end "2026-03-24T10:30:00"

Get event details

gws calendar events get --params '{"calendarId": "primary", "eventId": "EVENT_ID"}'

Slides (Presentations)

Get presentation

gws slides presentations get --params '{"presentationId": "PRESENTATION_ID"}'

Create presentation

gws slides presentations create --json '{"title": "Q1 Review"}'

Tips

• Always use the Shell tool to execute gws commands.
• Responses are JSON by default. Use --format table for human-readable output when displaying to the user.
• For large result sets, use --page-all with --page-limit to control volume.
• Use --dry-run before write operations to preview what will be sent.
• Use gws <service> <resource> --help to discover available methods for any API.
• Use gws schema <service>.<resource>.<method> to inspect the full API schema for a method.
• The CLI is authenticated against your Google account (run gws auth login if not yet done).
• For full documentation: https://googleworkspace-cli.mintlify.app/commands/overview