Wanda

Posted on Mar 6 • Originally published at apidog.com

How to Connect Google Workspace CLI to OpenClaw

TL;DR

Google Workspace CLI (gws) is a command-line tool that gives AI agents and developers direct access to Gmail, Drive, Calendar, Sheets, Docs, and all Google Workspace APIs, returning structured JSON output. With native OpenClaw support and 100+ pre-built agent skills, you can automate Workspace workflows through messaging platforms like WhatsApp or Discord. Setup takes 5 minutes:

npm install -g @googleworkspace/cli
gws auth setup

Try Apidog today

Introduction

Imagine your AI agent reading your Gmail, updating your Calendar, and organizing your Google Drive—all hands-free.

Traditional Google Workspace automation involves complex API configs, custom code, or pricy third-party services. Developers often spend hours dealing with OAuth, rate limits, and evolving APIs. AI agents are usually left out due to lack of direct access.

Google recently released the Google Workspace CLI (gws), already at 12,400+ GitHub stars, with 100+ built-in agent skills. It’s written in Rust, reads Google’s Discovery Service live, and outputs machine-readable JSON—ideal for direct agent consumption.

💡 For API design/testing, use Apidog for API workflows and let gws automate notifications, reviews, or meeting scheduling based on test results.

button

What is Google Workspace CLI?

Google Workspace CLI (gws) is a CLI that wraps every Google Workspace API as composable commands: Gmail, Drive, Calendar, Sheets, Docs, Slides, Chat, Tasks, Meet, Forms, Keep, Classroom, Admin, and more.

Unlike most CLIs with hardcoded commands, gws queries Google’s Discovery Service in real time. When new APIs launch, gws supports them instantly—no updates or releases required.

Quick Example

# List the 10 most recent files
gws drive files list --params '{"pageSize": 10}'

# Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# Send a Chat message
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}'

All responses are structured JSON—ready for immediate use in scripts or by AI agents.

Why gws Matters for AI Agents

gws is built with agent automation in mind:

Structured JSON Output: Clean, machine-readable responses.
No Custom Tooling: Agents can call shell commands—no wrappers needed.
100+ Pre-Built Agent Skills: Over 100 SKILL.md files for every API and common workflows.
Native OpenClaw Support: Built-in agent framework compatibility.
MCP Server Built-In: Exposes Workspace APIs as structured tools for MCP-compatible clients.

This standardized CLI approach lowers the entry barrier for AI automation—just install and go.

How gws Works: The Architecture

gws dynamically builds its CLI surface from Google API specs at runtime:

Service Identification: e.g., drive in gws drive files list.
Dynamic Command Building: Fetches the service’s Discovery Document (cached 24h), builds commands from resources/methods.
Request Execution: Parses arguments, authenticates, builds, executes HTTP requests.

All output is structured JSON.

┌─────────────────────────────────────────────────────────┐
│  argv[1] = "drive"                                      │
│       ↓                                                 │
│  Fetch Discovery Document (cached 24h)                  │
│       ↓                                                 │
│  Build clap::Command tree from resources & methods      │
│       ↓                                                 │
│  Re-parse remaining arguments                           │
│       ↓                                                 │
│  Authenticate → Build HTTP Request → Execute            │
│       ↓                                                 │
│  Output: Structured JSON                                │
└─────────────────────────────────────────────────────────┘

OpenClaw Integration: Step-by-Step

OpenClaw connects AI agents to messaging apps like WhatsApp, Telegram, or Discord. With gws, your agent can control Google Workspace via chat.

Option 1: Symlink All Skills (Dev Mode)

git clone https://github.com/googleworkspace/cli.git
cd cli
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

Option 2: Copy Specific Skills

cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

Option 3: Use the Skills CLI

npx skills add https://github.com/googleworkspace/cli
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

The `gws-shared` Skill

This special skill can auto-install the CLI via npm if missing, allowing your agent to bootstrap itself.

Using gws Through WhatsApp

After setup, send messages like:

"Check my calendar for today's meetings"
"Find unread emails from my boss"
"Create a new spreadsheet called Q2 Budget"
"Upload this PDF to the Projects folder"

OpenClaw translates your text to the right gws command and replies with the result.

100+ Agent Skills Breakdown

The repo ships over 100 SKILL.md files, grouped as:

Service Skills (25+)

Skill	Purpose
gws-drive	Managing files and folders
gws-gmail	Email operations
gws-calendar	Calendar and events
gws-sheets	Spreadsheets
gws-docs	Google Docs
gws-slides	Presentations
gws-tasks	Task lists
gws-chat	Google Chat
gws-people	Contacts
gws-admin	Users, groups, devices
gws-classroom	Classroom management
gws-forms	Google Forms
gws-keep	Google Keep notes
gws-meet	Conference management
gws-vault	eDiscovery
gws-apps-script	Apps Script projects

Additional skills: Cloud Identity, Alert Center, Group Settings, Licensing, Reseller, Model Armor.

Persona Skills (10 Pre-Built Agent Roles)

Persona	Responsibilities
Executive Assistant	Schedules, inbox, comms
Project Manager	Projects, tasks, meetings
HR Coordinator	Onboarding, announcements, comms
Sales Ops	Sales workflows, deals, calls
IT Admin	Users, security, Workspace config
Content Creator	Content creation/distribution
Customer Support	Tickets, issues, escalation
Event Coordinator	Events, invitations, logistics
Team Lead	Standups, tasks, team comms
Researcher	Research, references, collaboration

Each persona bundles the appropriate skills and helpers for the role.

Helper Skills

gws-drive-upload: Quick file uploads
gws-gmail-send: Send emails
gws-modelarmor-sanitize-prompt: Prompt sanitization

Recipe Skills (50 Workflows)

Ready-to-use multi-step automations, e.g.:

Audit externally shared Drive files
Send personalized emails from Sheets data
Create meeting agendas from Calendar events
Generate weekly status reports

Real-World Automation Workflows

Gmail Automation

# List unread emails from a sender
gws gmail users.messages list --params '{"userId": "me", "q": "from:boss@company.com is:unread"}'

# Read an email
gws gmail users.messages get --params '{"userId": "me", "id": "MSG_ID"}'

# Send an email
gws gmail +send --to alice@company.com --subject 'Q2 Report Ready' --body 'Hey Alice, the Q2 report is ready for review.'

# Agent-friendly summary
gws gmail +triage --max 5 --query 'from:boss'

Calendar Management

# Today's agenda
gws calendar +agenda

# Create a meeting
gws calendar +insert --summary 'Weekly Standup' --start '2026-03-10T09:00:00-07:00' --end '2026-03-10T09:30:00-07:00'

# Recurring event
gws calendar events insert --params '{"calendarId": "primary"}' --json '{
  "summary": "Weekly Standup",
  "start": {"dateTime": "2026-03-10T09:00:00", "timeZone": "America/Vancouver"},
  "end": {"dateTime": "2026-03-10T09:30:00", "timeZone": "America/Vancouver"},
  "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO"],
  "attendees": [{"email": "team@company.com"}]
}'

# Reschedule and notify attendees
gws calendar events patch --params '{"calendarId": "primary", "eventId": "EVENT_ID", "sendUpdates": "all"}' --json '{
  "start": {"dateTime": "2026-03-10T14:00:00", "timeZone": "America/Vancouver"},
  "end": {"dateTime": "2026-03-10T15:00:00", "timeZone": "America/Vancouver"}
}'

Drive File Management

# List recent files
gws drive files list --params '{"pageSize": 10}'

# Upload to folder
gws drive +upload --file ./report.pdf --parent FOLDER_ID

# Create a project folder
gws drive files create --json '{"name": "Q2 Project", "mimeType": "application/vnd.google-apps.folder"}'

# Download a file
gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' -o report.pdf

# Export Doc as PDF
gws drive files export --params '{"fileId": "FILE_ID", "mimeType": "application/pdf"}' -o document.pdf

# Share a folder
gws drive permissions create --params '{"fileId": "FOLDER_ID"}' --json '{"role": "writer", "type": "user", "emailAddress": "colleague@company.com"}'

Sheets Operations

# Read data
gws sheets +read --spreadsheet-id SHEET_ID --range 'Contacts!A2:C'

# Append a row
gws sheets +append --spreadsheet-id SHEET_ID --range 'Sheet1' --values '["2026-03-05", "Marketing", "Ad spend", "1500"]'

# Create a spreadsheet
gws drive files create --json '{"name": "Expense Tracker 2026", "mimeType": "application/vnd.google-apps.spreadsheet"}'

Docs and Content Creation

# Create a document
gws docs documents create --json '{"title": "Meeting Notes - March 2026"}'

# Write to a doc
gws docs +write --document-id DOC_ID --text '## Project: Q2 Launch\n\n### Objective\nLaunch the new feature by end of Q2.'

Chat, Meet, Forms, and More

# Send a Chat message
gws chat +send --space spaces/TEAM_SPACE --text 'Important: Please check your email for the updated policy.'

# Create a Meet room
gws meet spaces create --json '{"config": {"accessType": "OPEN"}}'

# Create a Form
gws forms forms create --json '{"info": {"title": "Event Feedback", "documentTitle": "Event Feedback Form"}}'

# Create a presentation
gws slides presentations create --json '{"title": "Quarterly Review Q2"}'

Most operations are one-liners using + helper commands.

Security and Model Armor

To defend against prompt injection or malicious data, gws integrates Google Cloud Model Armor for response sanitization.

Example Usage

gws gmail users messages get --params '...' --sanitize "projects/P/locations/L/templates/T"

Sanitization Modes

Mode	Behavior
warn	Flags suspicious content, still returns it
block	Removes potentially malicious content entirely

Why This Matters

Agent security is a real-world concern. Model Armor ensures workspace data sent to agents is filtered for known attack patterns.

Environment Variables

# Default Model Armor template
export GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE="projects/P/locations/L/templates/T"

# Sanitization mode (warn or block)
export GOOGLE_WORKSPACE_CLI_SANITIZE_MODE="block"

gws vs Alternatives

gws vs gcloud CLI

Feature	gws	gcloud CLI
Scope	Google Workspace APIs	Google Cloud APIs
Agent Skills	100+ pre-built	None
OpenClaw Support	Native	Manual
Output Format	Structured JSON	Variable
Workspace-Specific	Yes	Partial

Use gcloud for infra, gws for Workspace automation.

gws vs Google Apps Script

Feature	gws	Apps Script
Execution	Local CLI/Agents	Cloud-based
Language	Shell commands	JavaScript
AI Integration	Built-in	Manual
Authentication	OAuth/Service Acct	OAuth
Use Case	Automation/Agents	In-Workspace

Apps Script: for in-Workspace automation.

gws: for agent/external automation.

gws vs Third-Party Tools (Zapier, Make)

Feature	gws	Zapier/Make
Cost	Free	$20-500/month
Customization	Full	Limited
Rate Limits	Google	Platform-imposed
Data Privacy	Local	Third-party servers
Learning Curve	Technical	Low-code

Third-party: for non-devs.

gws: for developers and agents.

Getting Started Guide

Prerequisites

Node.js 18+
Google Cloud project (for OAuth)
Google account (Workspace or standard)
gcloud CLI (optional, for quickest setup)

Step 1: Install gws

npm install -g @googleworkspace/cli

Step 2: Set Up Authentication

gws auth setup

Guides you through Google Cloud project creation, API enablement, and login.

Step 3: Login

gws auth login

Opens browser for OAuth.

Step 4: Test Your Setup

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

You should see JSON output with your recent files.

Step 5: Integrate with OpenClaw

git clone https://github.com/googleworkspace/cli.git
cd cli
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

Step 6: Use Through Messaging

Send a message via your configured OpenClaw platform:

"List my 5 most recent Drive files"

OpenClaw runs the gws command and responds with results.

Troubleshooting

"Access blocked" or 403 during login:

Add your email as a test user in the OAuth consent screen.

"Google hasn’t verified this app":

Click Advanced → "Go to (unsafe)" to continue (safe for personal use).

Too many scopes error:

Limit scopes:

gws auth login --scopes drive,gmail,calendar

API not enabled:

Enable the API from the provided link, wait 10 seconds, and retry.

Conclusion

Google Workspace CLI (gws) is a practical, robust automation tool for AI agents and developers. Its dynamic API support, OpenClaw integration, and security features make it a key resource for automating Google Workspace workflows. Setup is quick, and the skill ecosystem is extensive.

If you’re building agent-powered, automated workflows, add gws to your stack.

button

FAQ

Q: Is gws free to use?

A: Yes, open source (Apache-2.0). You pay Google API costs only if exceeding free quotas.

Q: Do I need a Google Workspace account?

A: Not for most features—a regular Google account works. Some Admin APIs require Workspace.

Q: Can I use gws without OpenClaw?

A: Yes, gws is a standalone CLI. OpenClaw adds messaging integration.

Q: How do I update gws?

A:

npm update -g @googleworkspace/cli

Since it reads Discovery Service live, the CLI always supports the latest APIs.

Q: Is my data secure with gws?

A: Credentials are encrypted at rest (AES-256-GCM, OS keyring). Model Armor integration adds agent security.

Q: Can I use gws in CI/CD pipelines?

A: Yes.

gws auth export --unmasked > credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=credentials.json

Q: Difference vs Google APIs Explorer?

A: gws is for automation/agents via CLI and JSON. APIs Explorer is web-based for manual testing.

Q: Does gws work with service accounts?

A: Yes. Set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE to your service account JSON key.

Q: Can I contribute?

A: Yes, open source on GitHub. Note: Pull requests from non-collaborators may be temporarily disabled.

Q: Supported platforms?

A: macOS, Linux, Windows—native binaries delivered via npm.

TL;DR

Introduction

What is Google Workspace CLI?

Quick Example

Why gws Matters for AI Agents

How gws Works: The Architecture

OpenClaw Integration: Step-by-Step

Option 1: Symlink All Skills (Dev Mode)

Option 2: Copy Specific Skills

Option 3: Use the Skills CLI

The gws-shared Skill

Using gws Through WhatsApp

100+ Agent Skills Breakdown

Service Skills (25+)

Persona Skills (10 Pre-Built Agent Roles)

Helper Skills

Recipe Skills (50 Workflows)

Real-World Automation Workflows

Gmail Automation

Calendar Management

Drive File Management

Sheets Operations

Docs and Content Creation

Chat, Meet, Forms, and More

Security and Model Armor

Example Usage

Sanitization Modes

Why This Matters

Environment Variables

gws vs Alternatives

gws vs gcloud CLI

gws vs Google Apps Script

gws vs Third-Party Tools (Zapier, Make)

Getting Started Guide

Prerequisites

Step 1: Install gws

Step 2: Set Up Authentication

Step 3: Login

Step 4: Test Your Setup

Step 5: Integrate with OpenClaw

Step 6: Use Through Messaging

Troubleshooting

Conclusion

FAQ

The `gws-shared` Skill