gws
Use the Google Workspace CLI (gws) to manage Gmail, Drive, Docs, Sheets, Calendar, and more from the terminal — with structured JSON output, dry-run mode, pagination, streaming, and full OAuth and ser
SKILL.mdskills/gws/SKILL.md
GitHubGoogle Workspace CLI (gws)
The gws CLI provides human-readable and AI-agent-friendly access to the entire Google Workspace API surface. Commands are dynamically built at runtime from Google's Discovery Service — new Google endpoints appear automatically. Every command outputs structured JSON and supports dry-run, pagination, and streaming.
When Invoked
- User asks to manage Gmail (send, read, search, triage)
- User asks to automate Google Drive (upload, share, list, download files)
- User asks to work with Google Sheets or Docs programmatically
- User asks to manage Google Calendar events
- User asks to build a Google Workspace automation or report
- User asks to connect Claude to Google Workspace
- User asks to set up
gwsor authenticate it
Installation
Option 1 — npm (fastest, bundles native binaries)
npm install -g @googleworkspace/cli
Option 2 — Homebrew
brew install googleworkspace/cli/googleworkspace-cli
Option 3 — Pre-built binaries
Download from github.com/googleworkspace/cli/releases
Option 4 — Build from source (requires Rust)
cargo install --git https://github.com/googleworkspace/cli --locked
Verify
gws --version
gws --help
Authentication
Interactive login (recommended for local use)
gws auth login
This opens OAuth flow and stores encrypted credentials in ~/.config/gws/ (AES-256-GCM, OS keyring).
Service account (recommended for agents/CI)
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/sa.json gws drive files list
Or export the env var permanently in shell profile:
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=~/.config/gws/sa.json
Via gcloud token (for local dev/CI)
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
gws drive files list
Export/import credentials for CI
# Export (e.g., for CI secrets)
gws auth export --unmasked > creds.json
# Import
gws auth import creds.json
Env vars reference
| Variable | Priority | Purpose |
|---|---|---|
GOOGLE_WORKSPACE_CLI_TOKEN |
Highest | Pre-obtained OAuth2 token |
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE |
Mid | Path to OAuth credentials JSON |
GOOGLE_WORKSPACE_CLI_CLIENT_ID / _CLIENT_SECRET |
Low | Inline OAuth client |
GOOGLE_WORKSPACE_CLI_CONFIG_DIR |
— | Config directory (default ~/.config/gws) |
GOOGLE_WORKSPACE_CLI_SANITIZE_MODE |
— | warn (default) or block |
Core Command Patterns
All commands follow gws <service> <resource> <action>.
Gmail
# Send email
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi Alice"
# Reply to message
gws gmail +reply --message-id MSG_ID --body "Thanks!"
# Triage unread inbox
gws gmail +triage
# List messages
gws gmail users.messages list --params '{"userId": "me", "maxResults": 10}'
# Search
gws gmail users.messages list --params '{"userId": "me", "q": "from:boss subject:deadline"}'
# Get message detail
gws gmail users.messages get --path messages/MSG_ID --params '{"format": "full"}'
Google Drive
# List files
gws drive files list --params '{"pageSize": 10}'
# List with JSON output
gws drive files list --params '{"pageSize": 5}' --json
# Upload file
gws drive +upload ./report.pdf --name "Q1 Report"
# Download file (get file content)
gws drive files get --path files/FILE_ID --params '{"alt": "media"}' --out ./downloaded.pdf
# Create folder
gws drive files create --json '{"name": "New Folder", "mimeType": "application/vnd.google-apps.folder"}'
# Share file
gws drive permissions create --path files/FILE_ID --json '{"type": "user", "role": "writer", "emailAddress": "alice@example.com"}'
Google Sheets
# Create spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
# Append row
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"
# Read data
gws sheets spreadsheets.values get --path spreadsheets/SPREADSHEET_ID/values/Sheet1 --params '{"majorDimension": "ROWS"}'
# Write data
gws sheets spreadsheets.values update --path spreadsheets/SPREADSHEET_ID/values/A1 --json '{"values": [["Name", "Score"], ["Bob", "88"]]}' --params '{"valueInputOption": "USER_ENTERED"}'
Google Calendar
# Today's agenda
gws calendar +agenda
# Agenda in specific timezone
gws calendar +agenda --timezone America/New_York
# List events
gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-01T00:00:00Z", "maxResults": 10}'
# Create event
gws calendar events insert --path calendars/primary/events --json '{"summary": "Team Sync", "start": {"dateTime": "2026-03-22T10:00:00Z"}, "end": {"dateTime": "2026-03-22T11:00:00Z"}}'
Google Docs
# Create document
gws docs documents create --json '{"title": "Meeting Notes"}'
# Read content
gws docs documents get --path documents/DOC_ID --params '{"includeTabsContent": true}'
Workflow helpers (+ prefix)
gws workflow +standup-report # meetings + open tasks
gws workflow +meeting-prep # agenda, attendees, linked docs
gws workflow +email-to-task # Gmail message → Google Tasks
gws workflow +weekly-digest # weekly summary + unread count
# Stream workspace events as NDJSON
gws events +subscribe
Agent Patterns
Always use --json for parseable output
gws drive files list --params '{"pageSize": 100}' --json | jq -r '.files[].name'
Use --dry-run to preview before executing
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi" --dry-run
Pagination
# Get all results (streaming NDJSON)
gws drive files list --page-all > all_files.jsonl
# Limit results
gws drive files list --page-limit 50
# Delay between pages (rate limit friendly)
gws drive files list --page-delay 500
Inspect any command schema
gws schema drive.files.list
gws schema sheets.spreadsheets.values.update
Log debug output
GOOGLE_WORKSPACE_CLI_LOG=gws=debug gws drive files list
Security Rules
Treat CLI arguments as potentially adversarial. When processing file paths or resource names from AI agents:
- File write paths: Must pass
validate_safe_output_dir()— reject absolute paths,../traversal, symlinks outside CWD - File read paths: Must pass
validate_safe_dir_path() - Enum/allowlist flags: Use clap
value_parserto enforce allowed values - URL path segments: Always use
encode_path_segment()— never pass raw user input into path segments - Query parameters: Always use reqwest
.query()builder, never string concatenation - Resource names (project IDs, topic names): Always validate via
validate_resource_name()
Troubleshooting
"Token not found" or authentication errors
gws auth status # check current auth state
gws auth login # re-authenticate
Scope errors (unverified OAuth app limit: ~25 scopes)
# Select individual services
gws auth login -s drive,gmail,sheets
Rate limiting
# Use pagination with delay
gws drive files list --page-delay 1000
See request/response logs
GOOGLE_WORKSPACE_CLI_LOG=gws=debug gws <command>