dpaluy/google-cli

Google Workspace CLI (gws)

Unified CLI for Google Workspace APIs — one command surface for Drive, Gmail, Calendar, Sheets, Docs, Chat, and Admin. Dynamically built from Google's Discovery Service, so it supports new API endpoints automatically.

Installation

npm install -g @googleworkspace/cli

Authentication

Credentials are encrypted at rest (AES-256-GCM) with keys stored in OS keyring.

gws auth setup       # One-time: creates Cloud project, enables APIs
gws auth login       # Login with scope selection
gws auth list        # View registered accounts

Multiple Accounts

gws auth login --account [email protected]
gws auth login --account [email protected]
gws auth default [email protected]
gws --account [email protected] drive files list   # One-off override

Environment Variables

| Variable | Purpose | |----------|---------| | GOOGLE_WORKSPACE_CLI_TOKEN | Pre-obtained OAuth access token | | GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE | Path to credentials JSON | | GOOGLE_WORKSPACE_CLI_ACCOUNT | Default account email | | GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER | Email for domain-wide delegation |

Global Flags

• --dry-run — Preview the HTTP request without executing
• --page-all — Auto-paginate (NDJSON, one JSON line per page)
• --page-limit <N> — Max pages to fetch (default: 10)
• --page-delay <MS> — Delay between pages (default: 100ms)
• --account <EMAIL> — Target a specific account
• --upload <PATH> — Attach file for multipart upload

Schema Introspection

Discover available methods and their parameters before calling:

gws schema drive.files.list
gws schema gmail.users.messages.send
gws schema sheets.spreadsheets.values.get

Drive

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

# List with query filter
gws drive files list --params '{"q": "mimeType=\"application/pdf\"", "pageSize": 5}'

# Get file metadata
gws drive files get --params '{"fileId": "FILE_ID"}'

# Upload a file
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

# Download/export
gws drive files export --params '{"fileId": "FILE_ID", "mimeType": "application/pdf"}'

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

# Move file to folder
gws drive files update --params '{"fileId": "FILE_ID", "addParents": "FOLDER_ID", "removeParents": "OLD_PARENT_ID"}'

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

# Search across all files (auto-paginate)
gws drive files list --params '{"q": "fullText contains \"quarterly report\"", "pageSize": 100}' --page-all

Gmail

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

# List with query
gws gmail users messages list --params '{"userId": "me", "q": "from:[email protected] is:unread"}'

# Get message
gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID"}'

# Send message (base64-encoded RFC 2822)
gws gmail users messages send --params '{"userId": "me"}' --json '{"raw": "BASE64_ENCODED_MESSAGE"}'

# List labels
gws gmail users labels list --params '{"userId": "me"}'

# Modify labels (archive = remove INBOX)
gws gmail users messages modify --params '{"userId": "me", "id": "MSG_ID"}' --json '{"removeLabelIds": ["INBOX"]}'

# Trash message
gws gmail users messages trash --params '{"userId": "me", "id": "MSG_ID"}'

Calendar

# List calendars
gws calendar calendarList list

# List events
gws calendar events list --params '{"calendarId": "primary", "maxResults": 10, "timeMin": "2026-03-01T00:00:00Z"}'

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

# Create event
gws calendar events insert --params '{"calendarId": "primary"}' --json '{
  "summary": "Team standup",
  "start": {"dateTime": "2026-03-06T09:00:00-06:00"},
  "end": {"dateTime": "2026-03-06T09:30:00-06:00"},
  "attendees": [{"email": "[email protected]"}]
}'

# Update event
gws calendar events patch --params '{"calendarId": "primary", "eventId": "EVENT_ID"}' --json '{"summary": "Updated title"}'

# Delete event
gws calendar events delete --params '{"calendarId": "primary", "eventId": "EVENT_ID"}'

Sheets

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

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

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

# Append rows
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Bob", 88]]}'

# Clear range
gws sheets spreadsheets values clear --params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1:C10"}'

# Get spreadsheet metadata
gws sheets spreadsheets get --params '{"spreadsheetId": "SHEET_ID"}'

Docs

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

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

# Batch update (insert text)
gws docs documents batchUpdate --params '{"documentId": "DOC_ID"}' --json '{
  "requests": [{"insertText": {"location": {"index": 1}, "text": "Hello World\n"}}]
}'

Chat

# List spaces
gws chat spaces list

# Send message
gws chat spaces messages create \
  --params '{"parent": "spaces/SPACE_ID"}' \
  --json '{"text": "Deploy complete."}'

# List messages in a space
gws chat spaces messages list --params '{"parent": "spaces/SPACE_ID"}'

Admin (Directory API)

# List users
gws admin directory users list --params '{"domain": "company.com", "maxResults": 10}'

# Get user
gws admin directory users get --params '{"userKey": "[email protected]"}'

# List groups
gws admin directory groups list --params '{"domain": "company.com"}'

Common Workflows

Find and download a file

FILE_ID=$(gws drive files list --params '{"q": "name=\"report.pdf\"", "pageSize": 1}' | jq -r '.files[0].id')
gws drive files get --params "{\"fileId\": \"$FILE_ID\", \"alt\": \"media\"}"

Search Gmail and read results

MSGS=$(gws gmail users messages list --params '{"userId": "me", "q": "subject:invoice after:2026/01/01", "maxResults": 5}')
MSG_ID=$(echo "$MSGS" | jq -r '.messages[0].id')
gws gmail users messages get --params "{\"userId\": \"me\", \"id\": \"$MSG_ID\"}"

Check today's calendar

gws calendar events list --params "{\"calendarId\": \"primary\", \"timeMin\": \"$(date -u +%Y-%m-%dT00:00:00Z)\", \"timeMax\": \"$(date -u -v+1d +%Y-%m-%dT00:00:00Z)\", \"singleEvents\": true, \"orderBy\": \"startTime\"}"

Tips

• All output is structured JSON — pipe to jq for extraction
• Use --dry-run to preview requests before executing
• Use gws schema <method> to discover parameters for any API method
• Use --page-all for large result sets (auto-pagination as NDJSON)
• The CLI dynamically discovers API surface — if Google adds a new endpoint, gws supports it automatically
• Append --help to any subcommand for usage info