google-workspace-cli

name	google-workspace-cli
description	Use when user wants to interact with Google Workspace APIs (Gmail, Drive, Calendar, Sheets, Docs, Chat, Admin) from the command line using `gws`. Also use when setting up Google Workspace CLI, OAuth for Google APIs, or automating Google Workspace tasks. Check `which gws` first — if missing, offer install.

Prerequisites

1. gcloud CLI (required for automated setup):

which gcloud || brew install google-cloud-sdk

2. gws CLI:

which gws || brew install googleworkspace-cli

# Or: npm install -g @googleworkspace/cli

Setup

Automated (requires gcloud CLI installed first)

gws auth setup

Creates a GCP project, enables APIs, configures OAuth, and logs you in.

Manual

1. Create a project at console.cloud.google.com
2. Configure OAuth consent screen → External → Testing mode
3. Add yourself as a test user (required)
4. Create OAuth credentials → type Desktop app (not Web app)
5. Download client JSON to ~/.config/gws/client_secret.json
6. Enable the APIs you need (Gmail, Drive, Calendar, etc.)
7. Login with only the scopes you need:

gws auth login -s gmail,drive,calendar,sheets

Check auth status

gws auth status

Common Gotchas

• Subcommands are space-separated, not dot-separated: gws gmail users messages list (NOT users.messages)
• OAuth client must be Desktop app type, not Web — otherwise redirect_uri_mismatch
• Must add yourself as test user in consent screen — otherwise "Access blocked"
• Testing mode apps limited to ~25 OAuth scopes — use -s to select only what you need
• If API not enabled, you get 403 with a direct link to enable it

Usage

# Core syntax (space-separated subcommands)
gws <service> <resource> [sub-resource] <method> [flags]

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

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

# Get a specific email
gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID", "format": "metadata", "metadataHeaders": ["Subject","From","Date"]}'

# Calendar agenda (helper command)
gws calendar +agenda

# Create calendar event
gws calendar +insert --summary "Meeting" --start 2026-04-05T10:00:00Z --end 2026-04-05T11:00:00Z --attendee [e-mail]

# Send email
gws gmail +send --to [e-mail] --subject "Hello" --body "Hi there"
gws gmail +send --to [e-mail] --subject "Report" --body "<h1>Hi</h1>" --html --attach ./report.pdf
gws gmail +send --to [e-mail] --subject "Draft" --body "Review this" --draft

# Upload to Drive
gws drive +upload ./file.pdf
gws drive +upload ./file.pdf --parent FOLDER_ID --name "Renamed.pdf"

# Read spreadsheet
gws sheets +read --spreadsheet SPREADSHEET_ID --range "Sheet1!A1:D10"

# Inspect any method's schema before calling it
gws schema drive.files.list

# Preview request without executing
gws drive files list --dry-run

Key Flags

Flag	Purpose
--params '<JSON>'	URL/query parameters
--json '<JSON>'	Request body (POST/PATCH/PUT)
--page-all	Auto-paginate (NDJSON output)
--page-limit <N>	Max pages (default 10)
--upload <PATH>	File upload
--output <PATH>	Download binary files
--dry-run	Preview without executing
--format <FMT>	Output format: json (default), table, yaml, csv

Helper Commands

Prefixed with +, these are convenience wrappers. Run gws <service> +cmd --help for full options.

• gmail: +send, +reply, +reply-all, +forward, +triage, +watch
• sheets: +append, +read
• docs: +write
• chat: +send
• drive: +upload
• calendar: +insert, +agenda
• workflow: +standup-report, +meeting-prep, +weekly-digest

Multi-Account Setup

gws = personal (default at ~/.config/gws/). For additional accounts, use separate config dirs via aliases:

# One-time: set up work account
GOOGLE_WORKSPACE_CLI_CONFIG_DIR=~/.config/gws-work gws auth setup

# Add to .zshrc
alias gws-work='GOOGLE_WORKSPACE_CLI_CONFIG_DIR=~/.config/gws-work gws'

Then: gws for personal, gws-work for work.

Auth Environment Variables

Variable	Purpose
GOOGLE_WORKSPACE_CLI_TOKEN	Pre-obtained access token
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE	Path to credentials JSON
GOOGLE_WORKSPACE_CLI_CLIENT_ID	OAuth client ID
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET	OAuth client secret
GOOGLE_WORKSPACE_CLI_CONFIG_DIR	Override config dir (default ~/.config/gws)

Reference

• Repo: https://github.com/googleworkspace/cli
• Credentials stored encrypted in ~/.config/gws/ (AES-256-GCM, key in OS keyring)
• Works with both personal Gmail and Google Workspace accounts (admin APIs are Workspace-only)
• Exit codes: 0 success, 1 API error, 2 auth error, 3 validation, 4 discovery, 5 internal