gws — Shared Reference
gws is a unified CLI for all Google Workspace APIs. It reads Google's Discovery Service at runtime, so every Workspace API endpoint is available without custom integration code.
Installation
npm install -g @googleworkspace/cli
gws --version
Authentication
Interactive (desktop / laptop)
gws auth setup # One-time: creates Cloud project, enables APIs, logs you in (requires gcloud)
gws auth login # Subsequent scope selection and login
Log in with specific services to stay within testing-mode scope limits:
gws auth login -s drive,gmail,calendar,sheets
Service Account (server / CI)
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list # Works without interactive login
Pre-obtained access token
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
Headless / CI export flow
# On machine with browser
gws auth export --unmasked > credentials.json
# On headless machine
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
CLI Syntax
gws <service> <resource> [sub-resource] <method> [flags]
Global Flags
| Flag | Description |
|---|
--format <FORMAT> | Output format: json (default), table, yaml, csv |
--dry-run | Validate request locally without calling the API |
--sanitize <TEMPLATE> | Screen responses through Model Armor |
Method Flags
| Flag | Description |
|---|
--params '{"key": "val"}' | URL / query parameters |
--json '{"key": "val"}' | Request body |
-o, --output <PATH> | Save binary responses to file |
--upload <PATH> | Upload file content (multipart) |
--page-all | Auto-paginate (NDJSON output) |
--page-limit <N> | Max pages when using --page-all (default: 10) |
--page-delay <MS> | Delay between pages in ms (default: 100) |
Discovering Commands
# Browse all services
gws --help
# Browse a service's resources
gws drive --help
# Inspect a specific method's schema
gws schema drive.files.list
gws schema gmail.users.messages.send
Shell Tips
zsh ! expansion in ranges
Sheet ranges like Sheet1!A1 contain ! which zsh interprets as history expansion. Use double quotes:
# WRONG (zsh mangles the !)
gws sheets +read --spreadsheet ID --range 'Sheet1!A1:D10'
# CORRECT
gws sheets +read --spreadsheet ID --range "Sheet1!A1:D10"
JSON with inner double quotes
gws drive files list --params '{"pageSize": 5}'
Security Rules
- Never output secrets, tokens, or API keys in responses
- Always confirm with the user before executing write or delete commands
- Prefer
--dry-run for any destructive or sending operation
- Use
--sanitize for PII screening when processing user-generated content
MCP Server (for AI agents)
# Start a built-in MCP server exposing selected APIs
gws mcp -s drive,gmail,calendar,sheets
This exposes all methods of the selected services as MCP tools, giving any MCP-compatible AI agent direct Workspace access without additional integration code.