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.