GWS-CLI — Google Workspace CLI Playbook for Solanasis

What: The official Google Workspace CLI (gws) — a single command-line tool that exposes every Google Workspace API (Calendar, Gmail, Drive, Sheets, Docs, and more).

Why: Replaces the Google Calendar MCP connector that only works in interactive Claude.ai sessions. With gws, Claude Code can access Google Workspace via Bash in both interactive AND headless (claude -p) scheduled tasks.

Status: Pre-1.0 (v0.19.0, released March 2026). Apache 2.0 license. Published by googleworkspace on GitHub but labeled “not an officially supported Google product.” 22k+ stars, extremely active development.

1. Installation

Prerequisites:

Node.js 18+ (this machine: v24.14)
A GCP (Google Cloud Platform) project with OAuth credentials (see Section 3)

Install:

npm install -g @googleworkspace/cli

Verify:

gws --version
gws --help

Alternative install methods:

Cargo (Rust): cargo install --git https://github.com/googleworkspace/cli --locked
Pre-built binaries: https://github.com/googleworkspace/cli/releases

2. Authentication Setup

Step 1: GCP Project Setup

You need a Google Cloud Platform project with OAuth 2.0 credentials. If you already have one for Solanasis, skip to Step 2.

Go to https://console.cloud.google.com/
Create a new project (or select existing): solanasis-gws-cli
Enable the APIs you need:
- APIs & Services > Library > search and enable:
  - Google Calendar API
  - Gmail API
  - Google Drive API
  - Google Sheets API
  - Google People API (Contacts)
  - Google Tasks API
Configure OAuth consent screen:
- APIs & Services > OAuth consent screen
- User Type: External (or Internal if using Google Workspace org)
- App name: Solanasis GWS CLI
- Scopes: Add the scopes for the APIs you enabled
- Test users: Add mr.sunshine@solanasis.com (required while app is in “Testing” mode)
Create OAuth Client ID:
- APIs & Services > Credentials > Create Credentials > OAuth client ID
- Application type: Desktop app
- Name: gws-cli
- Download the JSON credentials file

Step 2: Run Auth Setup

# If you have gcloud CLI installed:
gws auth setup
# This walks through project selection, API enabling, and OAuth client creation
 
# If gws auth setup has issues on Windows (known bug), do the manual setup above
# and skip to Step 3

gws auth login
# Opens browser for OAuth consent
# Select your Google account (mr.sunshine@solanasis.com)
# Grant requested permissions
# Browser redirects to localhost — close the tab when done

Windows gotcha: The redirect URI uses a random port (e.g., http://localhost:51065). If you get a redirect error:

Copy the full redirect URI from the console output
Go to GCP Console > APIs & Services > Credentials > your OAuth client
Add the URI to “Authorized redirect URIs”
Re-run gws auth login

Step 4: Verify

gws auth status
# Should show your Google account email

Credential Storage

Location: ~/.config/gws/credentials.json
Encrypted with AES-256-GCM
Encryption key stored in Windows Credential Manager
Automatic token refresh — no manual re-auth needed (unless revoked)
Fallback: set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file to store key at ~/.config/gws/.encryption_key

Headless/Scheduled Task Auth

For scheduled tasks running without a browser (Windows Task Scheduler):

Option A: Export credentials (simplest)

Authenticate interactively on this machine (Steps 2-4 above)
The refresh token persists in ~/.config/gws/credentials.json
Scheduled tasks inherit the credentials automatically — gws handles token refresh

Option B: Service account (more robust)

Create a service account in GCP Console
Download the JSON key file
Set environment variable: GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=path/to/service-account.json
Service accounts need domain-wide delegation for Workspace APIs

Option C: Access token (for CI/CD)

Set GOOGLE_WORKSPACE_CLI_TOKEN=<bearer-token>
Highest priority — overrides all other auth methods
Tokens expire — not suitable for long-running scheduled tasks

Recommendation: Option A for Solanasis. Authenticate once interactively, and the refresh token handles everything. Only move to Option B if token refresh becomes unreliable.

3. Google Calendar Commands

Quick Commands (Helper Skills)

# Today's agenda
gws calendar +agenda --today --timezone America/Denver
 
# This week's agenda in table format
gws calendar +agenda --week --format table --timezone America/Denver
 
# Next 3 days
gws calendar +agenda --days 3 --timezone America/Denver
 
# Create an event via natural language
gws calendar events quickAdd --params '{"calendarId": "primary", "text": "Coffee with Caryn tomorrow at 10am"}'

Full API Commands

# List events (raw API)
gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-23T00:00:00-06:00", "timeMax": "2026-03-24T00:00:00-06:00", "singleEvents": true, "orderBy": "startTime"}'
 
# Get a specific event
gws calendar events get --params '{"calendarId": "primary", "eventId": "abc123"}'
 
# Create an event
gws calendar events insert --params '{"calendarId": "primary"}' --json '{
  "summary": "ORB Assessment Call",
  "start": {"dateTime": "2026-03-25T10:00:00-06:00"},
  "end": {"dateTime": "2026-03-25T11:00:00-06:00"},
  "attendees": [{"email": "client@example.com"}]
}'
 
# Free/busy query
gws calendar freebusy query --json '{
  "timeMin": "2026-03-24T08:00:00-06:00",
  "timeMax": "2026-03-24T18:00:00-06:00",
  "items": [{"id": "primary"}]
}'
 
# List all calendars
gws calendar calendarList list
 
# Delete an event
gws calendar events delete --params '{"calendarId": "primary", "eventId": "abc123"}'

Timezone Handling

gws auto-detects your timezone from Google Calendar Settings (24-hour cache)
Override with --timezone America/Denver or --tz America/Denver
All Solanasis scheduled tasks should explicitly pass --timezone America/Denver

4. Beyond Calendar — Full Workspace Access

gws auto-discovers every Google Workspace API. Here are the most useful for Solanasis:

Gmail

# Triage inbox — see unread messages with AI summary
gws gmail +triage
 
# Send an email
gws gmail +send --to "client@example.com" --subject "ORB Follow-Up" --body "Thanks for the call..."
 
# Read a specific message
gws gmail +read --message-id "abc123"
 
# Search messages
gws gmail messages list --params '{"q": "from:client@example.com after:2026/03/20"}'

Google Drive

# List recent files
gws drive files list --params '{"orderBy": "modifiedTime desc", "pageSize": 10}'
 
# Search for files
gws drive files list --params '{"q": "name contains '\''ORB'\'' and mimeType='\''application/pdf'\''"}'
 
# Upload a file
gws drive files create --upload path/to/file.pdf --params '{"name": "ORB-Assessment-Report.pdf"}'

Google Sheets

# Read a range
gws sheets +read --spreadsheet-id "SHEET_ID" --range "Sheet1!A1:D10"
 
# Append data
gws sheets +append --spreadsheet-id "SHEET_ID" --range "Sheet1" --values '[["Name", "Email", "Status"]]'

Google Docs

# Append content to a document
gws docs +write --document-id "DOC_ID" --text "New section content here..."

Google Tasks

# List task lists
gws tasks tasklists list
 
# List tasks in a list
gws tasks tasks list --params '{"tasklist": "TASKLIST_ID"}'

People / Contacts

# Search contacts
gws people people searchContacts --params '{"query": "Caryn", "readMask": "names,emailAddresses,phoneNumbers"}'
 
# List connections
gws people people connections list --params '{"resourceName": "people/me", "personFields": "names,emailAddresses"}'

Full Service List

Service	Skill Prefix	Key Commands
Calendar	`gws calendar`	`+agenda`, `+insert`, events CRUD, freebusy
Gmail	`gws gmail`	`+triage`, `+send`, `+read`, `+reply`, `+forward`
Drive	`gws drive`	files CRUD, upload, sharing
Sheets	`gws sheets`	`+read`, `+append`
Docs	`gws docs`	`+write`
Slides	`gws slides`	presentation tools
Tasks	`gws tasks`	task list management
People	`gws people`	contact search, profiles
Chat	`gws chat`	`+send` to spaces
Meet	`gws meet`	conferencing
Forms	`gws forms`	form creation, responses
Admin	`gws admin`	audit logs, usage analytics

5. Integration with Claude Code

Approach A: Direct CLI via Bash (Recommended)

Claude Code can call gws directly via the Bash tool. No MCP config needed.

# In Claude Code, just ask:
"What's on my calendar today?"

# Claude runs:
gws calendar +agenda --today --timezone America/Denver

Why this is better than MCP:

Zero context overhead — MCP loads 200-400 tool definitions upfront, gws loads nothing
Works in claude -p headless mode — no cloud MCP connector needed
Full API coverage — auto-discovers new endpoints as Google adds them
On-demand discovery — Claude can run gws schema calendar.events.list to learn the API

Setup: Just install gws and authenticate. Claude Code inherits your shell environment.

Approach B: MCP Server Mode (Alternative)

If you prefer structured tool interfaces:

# Add to Claude Code MCP config
claude mcp add --transport stdio gws-workspace -- gws mcp -s calendar,gmail --tool-mode compact

--tool-mode compact reduces from 200+ tools to ~26 (one per service + discovery meta-tool).

When to use Approach B:

You want explicit tool schemas for type safety
You’re building a more structured automation pipeline
You want Claude to discover available operations without running gws schema

Recommendation: Start with Approach A. Switch to B only if you find the direct CLI approach insufficient.

6. Integration with Solanasis Scheduled Tasks

Daily GTM Briefing

The daily briefing (run-daily-briefing.py) previously relied on Google Calendar MCP tools that aren’t available in claude -p. With gws:

Before (broken in headless mode):

mcp__claude_ai_Google_Calendar__gcal_list_events

After (works everywhere):

gws calendar +agenda --today --timezone America/Denver

The Bash tool is already in the ALLOWED_TOOLS list, so no additional tool permissions needed.

How the Briefing Agent Uses Calendar

The briefing prompt instructs Claude to cross-reference calendar events with meeting notes. With gws, Claude:

Runs gws calendar +agenda --today --timezone America/Denver via Bash
Parses the output to identify today’s meetings
Cross-references with Fireflies-synced meeting notes
Highlights follow-ups and prep needed for upcoming meetings

7. Windows-Specific Notes

JSON Quoting

# Git Bash (what this machine uses) — single quotes work:
gws calendar events list --params '{"calendarId": "primary"}'
 
# PowerShell — must escape double quotes:
gws calendar events list --params "{`"calendarId`": `"primary`"}"
 
# CMD — must escape double quotes differently:
gws calendar events list --params "{\"calendarId\": \"primary\"}"

Credential Storage

Uses Windows Credential Manager for encryption key
Credentials at %USERPROFILE%\.config\gws\credentials.json
If Windows Credential Manager has issues (like we saw with git), set:
```
export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file
```

Python Scripting

import subprocess
import json
 
result = subprocess.run(
    ["gws", "calendar", "+agenda", "--today", "--timezone", "America/Denver"],
    capture_output=True, encoding="utf-8", errors="replace"
)
events = result.stdout  # Parse as needed

8. Security Considerations

OAuth scope minimization: Only enable the APIs you actually use in GCP Console. Calendar + Gmail is sufficient for current scheduled tasks.
Service account vs OAuth: OAuth is fine for a single-user setup like Solanasis. Service accounts are for multi-user or domain-wide scenarios.
Credential encryption: gws encrypts credentials at rest with AES-256-GCM. The key lives in the OS keyring (Windows Credential Manager).
Sensitive data in context: When Claude reads emails or documents via gws, that content passes through the context window. Be mindful with client-sensitive data.
GCP project in “Testing” mode: Limits to 100 users and tokens expire after 7 days. For production use, submit for Google verification.
Never commit credentials: The ~/.config/gws/ directory is outside the repo. Never copy credential files into the workspace.

9. Limitations & Gotchas

Pre-1.0 software: “Expect breaking changes as we march toward v1.0.” Pin to a version if stability matters.
gws auth setup on Windows: Has been reported as broken. Use the manual GCP Console setup (Section 2, Step 1) instead.
Redirect URI port: Changes per gws auth login session. You may need to update the authorized redirect URIs in GCP Console each time.
Rate limits: Standard Google Workspace API quotas apply. Use --page-delay for bulk operations.
No built-in retry: API errors return structured exit codes but don’t auto-retry. Your scripts should handle retries if needed.
Not officially supported: No Google SLA or support channels. File issues on GitHub.
Extremely rapid development: 7 releases in 10 days (March 2026). Check for breaking changes after updates.

10. Quick Reference Card

# Auth
gws auth login                    # Interactive OAuth
gws auth status                   # Check current user
gws auth logout                   # Clear credentials
 
# Calendar
gws calendar +agenda --today      # Today's events
gws calendar +agenda --week       # Week view
gws calendar events quickAdd ...  # Natural language event creation
 
# Gmail
gws gmail +triage                 # Inbox overview
gws gmail +send --to X --subject Y --body Z
 
# Drive
gws drive files list              # List files
gws drive files create --upload F # Upload file
 
# Sheets
gws sheets +read --spreadsheet-id ID --range R
gws sheets +append --spreadsheet-id ID --range R --values V
 
# Discovery
gws schema calendar.events.list   # Show API schema for any method
gws --help                        # Full help

Resources

GitHub: https://github.com/googleworkspace/cli
Releases: https://github.com/googleworkspace/cli/releases
Skills docs: https://github.com/googleworkspace/cli/blob/main/docs/skills.md
Calendar skill: https://github.com/googleworkspace/cli/blob/main/skills/gws-calendar/SKILL.md

Last updated: 2026-03-23 Playbook version: 1.0

Solanasis Docs

Explorer

gws-cli-google-workspace-playbook

GWS-CLI — Google Workspace CLI Playbook for Solanasis

1. Installation

2. Authentication Setup

Step 1: GCP Project Setup

Step 2: Run Auth Setup

Step 4: Verify

Credential Storage

Headless/Scheduled Task Auth

3. Google Calendar Commands

Quick Commands (Helper Skills)

Full API Commands

Timezone Handling

4. Beyond Calendar — Full Workspace Access

Gmail

Google Drive

Google Sheets

Google Docs

Google Tasks

People / Contacts

Full Service List

5. Integration with Claude Code

Approach A: Direct CLI via Bash (Recommended)

Approach B: MCP Server Mode (Alternative)

6. Integration with Solanasis Scheduled Tasks

Daily GTM Briefing

How the Briefing Agent Uses Calendar

7. Windows-Specific Notes

JSON Quoting

Credential Storage

Python Scripting

8. Security Considerations

9. Limitations & Gotchas

10. Quick Reference Card

Resources

Graph View

Table of Contents

Solanasis Docs

Explorer

gws-cli-google-workspace-playbook

GWS-CLI — Google Workspace CLI Playbook for Solanasis

1. Installation

2. Authentication Setup

Step 1: GCP Project Setup

Step 2: Run Auth Setup

Step 3: Login

Step 4: Verify

Credential Storage

Headless/Scheduled Task Auth

3. Google Calendar Commands

Quick Commands (Helper Skills)

Full API Commands

Timezone Handling

4. Beyond Calendar — Full Workspace Access

Gmail

Google Drive

Google Sheets

Google Docs

Google Tasks

People / Contacts

Full Service List

5. Integration with Claude Code

Approach A: Direct CLI via Bash (Recommended)

Approach B: MCP Server Mode (Alternative)

6. Integration with Solanasis Scheduled Tasks

Daily GTM Briefing

How the Briefing Agent Uses Calendar

7. Windows-Specific Notes

JSON Quoting

Credential Storage

Python Scripting

8. Security Considerations

9. Limitations & Gotchas

10. Quick Reference Card

Resources

Graph View

Table of Contents