DEV Community

Preecha
Preecha

Posted on

How to Connect Google Workspace CLI to OpenClaw

TL;DR

Google Workspace CLI (gws) is a command-line tool that gives AI agents access to Gmail, Drive, Calendar, Sheets, Docs, and Google Workspace APIs through structured JSON output. With native OpenClaw support and more than 100 pre-built agent skills, you can automate Workspace workflows through messaging apps such as WhatsApp or Discord. A basic setup takes a few minutes:

npm install -g @googleworkspace/cli
gws auth setup
Enter fullscreen mode Exit fullscreen mode

Try Apidog today

Introduction

What if an AI agent could read Gmail, update Calendar events, and organize Drive files without requiring a custom integration for every operation?

Google Workspace automation commonly involves OAuth configuration, API-specific code, rate limits, and documentation that can become outdated. Google Workspace CLI (gws) provides a command-line interface for these APIs and returns structured JSON that scripts and AI agents can consume directly.

The CLI is built in Rust and reads Google’s Discovery Service at runtime. The repository also includes more than 100 pre-built agent skills and setup guidance for OpenClaw.

For developers building and testing APIs, this creates a useful division of responsibilities: use your API tooling to design and test APIs, while gws handles Workspace actions such as sending deployment notifications or scheduling review meetings based on test results.

What Is Google Workspace CLI?

Google Workspace CLI is a single command-line tool for Google Workspace APIs, including:

  • Gmail
  • Google Drive
  • Calendar
  • Sheets
  • Docs
  • Slides
  • Chat
  • Tasks
  • Meet
  • Forms
  • Keep
  • Classroom
  • Admin APIs

The key design choice is dynamic command generation.

Traditional CLI wrappers hardcode their supported commands. When Google adds an endpoint, the wrapper must be updated and released. gws instead reads Google’s Discovery Service, which describes available APIs, resources, methods, and parameters.

When you run a command, gws uses that discovery data to construct its command tree. This lets it follow the API specification without requiring a manually maintained command for every endpoint.

Basic Commands 

# 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 Google Chat message
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}'
Enter fullscreen mode Exit fullscreen mode

Responses are returned as structured JSON rather than HTML or human-oriented terminal formatting. That makes them suitable for shell pipelines, scripts, and AI agents.

Why gws Works Well for AI Agents

Structured JSON Output

Every response is machine-readable. An agent can inspect fields, IDs, pagination information, and errors without parsing formatted text.

No Custom Tool for Every API

An agent only needs permission to execute the CLI or call its MCP tools. You do not need to build a separate custom tool for every Gmail, Drive, or Calendar operation.

Pre-Built Agent Skills

The repository includes more than 100 SKILL.md files covering individual services, helper commands, persona bundles, and workflow recipes.

OpenClaw Support

The project repository includes OpenClaw setup instructions. You can expose selected skills to an OpenClaw installation instead of building the integration from scratch.

Built-In MCP Server

gws includes a Model Context Protocol server that exposes Google Workspace APIs as structured tools. MCP-compatible clients such as Claude Desktop, Gemini CLI, and VS Code can use these tools directly.

How gws Works

The CLI uses a dynamic, multi-phase execution flow.

1. Identify the Service

For this command:

gws drive files list
Enter fullscreen mode Exit fullscreen mode

drive identifies the Google service.

2. Build the Command Tree

The CLI fetches the service’s Discovery Document, cached for 24 hours, and builds a clap::Command tree from the resources and methods defined in that document.

3. Execute the Request

The CLI parses the remaining arguments, authenticates with the configured credentials, builds the HTTP request, and executes it.

The overall flow is:

argv[1] = "drive"
      ↓
Fetch Discovery Document (cached for 24 hours)
      ↓
Build clap::Command tree from resources and methods
      ↓
Parse the remaining arguments
      ↓
Authenticate → Build HTTP request → Execute
      ↓
Return structured JSON
Enter fullscreen mode Exit fullscreen mode

This architecture allows gws to support Workspace APIs without hardcoding the entire command surface.

OpenClaw Integration

OpenClaw is a self-hosted AI agent framework that connects to messaging platforms such as WhatsApp, Telegram, and Discord. With gws skills installed, an OpenClaw agent can translate messages into Google Workspace operations.

Prerequisites

Before integrating the tools, make sure:

  • Node.js 18 or later is installed.
  • You have a Google account.
  • You have a Google Cloud project for OAuth credentials.
  • OpenClaw is installed and configured if you want messaging-based access.
  • The gws CLI is available on your PATH.

Install the CLI 

npm install -g @googleworkspace/cli
Enter fullscreen mode Exit fullscreen mode

The npm package installs a pre-built native binary for the supported operating system and architecture, so a Rust toolchain is not required.

Install All Skills with a Symlink

Clone the repository and symlink the skills directory:

git clone https://github.com/googleworkspace/cli.git
cd cli

ln -s "$(pwd)"/skills/gws-* ~/.openclaw/skills/
Enter fullscreen mode Exit fullscreen mode

Symlinking is useful during development because changes pulled into the repository are immediately available to OpenClaw.

Install Specific Skills

If you only need selected services, copy individual skill directories:

cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/
Enter fullscreen mode Exit fullscreen mode

You can also use the skills CLI:

# Install all skills
npx skills add https://github.com/googleworkspace/cli

# Install individual skills
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
Enter fullscreen mode Exit fullscreen mode

Use the Shared Skill

The gws-shared skill includes an installation block that can install the CLI with npm if gws is not already available on the PATH. This allows an OpenClaw agent to check for the dependency and bootstrap it when necessary.

Example OpenClaw Requests

After installing the skills, you can send requests such as:

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

OpenClaw determines which skill and command to use, executes gws, and returns the result through the configured messaging platform.

Agent Skills Included in the Repository

The skills are organized into several categories.

Service Skills

Service skills provide direct access to Workspace APIs:

Skill Purpose
gws-drive Manage files, folders, and shared drives
gws-gmail Read, send, and manage email
gws-calendar Manage calendars and events
gws-sheets Read and write spreadsheets
gws-docs Read and write Google Docs
gws-slides Manage presentations
gws-tasks Manage task lists
gws-chat Manage Chat spaces and messages
gws-people Access contacts and profiles
gws-admin Manage users, groups, and devices
gws-classroom Manage classes, rosters, and coursework
gws-forms Work with Google Forms
gws-keep Manage Google Keep notes
gws-meet Manage conference resources
gws-vault Work with eDiscovery
gws-apps-script Manage Apps Script projects

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

Persona Skills

The repository also includes persona bundles for common roles:

  • Executive Assistant
  • Project Manager
  • HR Coordinator
  • Sales Operations
  • IT Administrator
  • Content Creator
  • Customer Support
  • Event Coordinator
  • Team Lead
  • Researcher

Each persona combines service skills, helper commands, and workflow patterns for a particular role.

Helper Skills

Helper skills simplify common operations:

  • gws-drive-upload for file uploads
  • gws-gmail-send for sending email
  • gws-modelarmor-sanitize-prompt for sanitizing prompts before they reach an agent

Recipe Skills

Recipe skills provide multi-step workflows with commands included. Examples include:

  • Auditing externally shared Drive files
  • Sending personalized email from spreadsheet data
  • Creating meeting agendas from Calendar events
  • Generating weekly status reports from multiple Workspace sources

These recipes can serve as starting points for your own agent workflows.

Practical Automation Examples

Gmail 

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

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

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

# Summarize unread messages matching a query
gws gmail +triage \
  --max 5 \
  --query 'from:boss'
Enter fullscreen mode Exit fullscreen mode

Calendar 

# Show 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'

# Create a 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 an event 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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Drive 

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

# Upload a file
gws drive +upload \
  --file ./report.pdf \
  --parent FOLDER_ID

# Create a 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 a Google 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"
  }'
Enter fullscreen mode Exit fullscreen mode

Sheets 

# Read a range
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 through Drive
gws drive files create \
  --json '{
    "name": "Expense Tracker 2026",
    "mimeType": "application/vnd.google-apps.spreadsheet"
  }'
Enter fullscreen mode Exit fullscreen mode

Docs and Content Creation 

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

# Write content to an existing document
gws docs +write \
  --document-id DOC_ID \
  --text '## Project: Q2 Launch\n\n### Objective\nLaunch the new feature by end of Q2.'
Enter fullscreen mode Exit fullscreen mode

Chat, Meet, Forms, and Slides 

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

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

# Create a feedback 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"}'
Enter fullscreen mode Exit fullscreen mode

The + helper commands handle common encoding and formatting tasks. For example, +send avoids manually constructing RFC 2822 email content, while helpers such as +upload, +agenda, +triage, +read, +append, and +write reduce boilerplate.

Security and Model Armor

Workspace data can contain untrusted content. An email, document, or Drive file could include text designed to manipulate an AI agent’s behavior through prompt injection.

The repository includes integration with Google Cloud Model Armor to sanitize API responses before they reach an agent.

gws gmail users.messages get \
  --params '...' \
  --sanitize "projects/P/locations/L/templates/T"
Enter fullscreen mode Exit fullscreen mode

Sanitization Modes

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

Configure a default template and mode with environment variables:

export GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE="projects/P/locations/L/templates/T"
export GOOGLE_WORKSPACE_CLI_SANITIZE_MODE="block"
Enter fullscreen mode Exit fullscreen mode

Agent security should be part of the data pipeline, especially when an agent can read external messages or files and then take actions on your behalf.

gws Compared with Alternatives

gws vs. gcloud CLI

Feature gws gcloud CLI
Scope Google Workspace APIs Google Cloud services
Agent skills More than 100 pre-built skills None described here
OpenClaw support Native setup guidance Manual setup
Output Structured JSON Varies
Workspace focus Yes Partial

Use gcloud for Google Cloud infrastructure and gws for Workspace automation.

gws vs. Google Apps Script

Feature gws Apps Script
Execution Local CLI or AI agent Cloud-based
Language Shell commands JavaScript
AI integration CLI and MCP integration Manual
Authentication OAuth or service account OAuth
Primary use case External automation and agents In-Workspace automation

Apps Script is a strong choice for workflows that run inside Google Workspace. gws is better suited to external tools, scripts, and AI agents.

gws vs. Zapier or Make

Feature gws Zapier or Make
Cost Free Platform subscription
Customization Full control through commands Platform-dependent
Rate limits Google API limits Google and platform limits
Data handling Local execution Third-party platform
Learning curve Technical Low-code

Third-party automation platforms can be more accessible to non-technical users. gws provides more direct control for developers and agent-based systems.

Getting Started

1. Install the Prerequisites

Install Node.js 18 or later. A Google Cloud project and a Google account are also required.

The gcloud CLI is optional, but it can simplify project and credential setup.

2. Install gws 

npm install -g @googleworkspace/cli
Enter fullscreen mode Exit fullscreen mode

3. Configure Authentication 

gws auth setup
Enter fullscreen mode Exit fullscreen mode

This guides you through Google Cloud project configuration, API enablement, and authentication.

If you do not use gcloud, configure OAuth manually in the Google Cloud Console.

4. Log In 

gws auth login
Enter fullscreen mode Exit fullscreen mode

A browser opens for OAuth login and scope selection.

5. Verify the Installation 

gws drive files list \
  --params '{"pageSize": 5}'
Enter fullscreen mode Exit fullscreen mode

A successful request returns your recent Drive files as JSON.

6. Install OpenClaw Skills 

git clone https://github.com/googleworkspace/cli.git
cd cli

ln -s "$(pwd)"/skills/gws-* ~/.openclaw/skills/
Enter fullscreen mode Exit fullscreen mode

Then send a request through your configured messaging platform:

List my five most recent Drive files
Enter fullscreen mode Exit fullscreen mode

OpenClaw should select and execute the relevant gws command.

Troubleshooting

Login Returns “Access Blocked” or a 403

Your OAuth application may be in testing mode, and your account may not be listed as a test user.

To fix it:

  1. Open the OAuth consent screen in your Google Cloud project.
  2. Add your Google account under Test users.
  3. Run gws auth login again.

Google Says the App Is Not Verified

This is expected for an OAuth application in testing mode. Select Advanced, then choose the option to proceed to the app.

Too Many OAuth Scopes

Testing-mode applications have a limit on OAuth scopes. A broad preset can exceed that limit.

Request only the scopes you need:

gws auth login \
  --scopes drive,gmail,calendar
Enter fullscreen mode Exit fullscreen mode

An API Is Not Enabled

If a required API is disabled, Google may return a 403 error with the reason accessNotConfigured.

gws prints a hint with a link to enable the API. Enable it in the Google Cloud Console, wait briefly for the change to propagate, and retry the command.

Conclusion

Google Workspace CLI provides a practical command-line layer for Workspace automation and AI agent workflows. Its runtime use of Google’s Discovery Service, structured JSON output, pre-built skills, OpenClaw integration, and built-in MCP server reduce the amount of custom integration code required.

You can use it as a standalone CLI, call it from scripts and CI/CD jobs, or expose its skills to an agent framework. Start with one service—such as Gmail, Drive, or Calendar—verify authentication, and then expand your workflows with helper and recipe skills.

FAQ

Is gws free to use?

Yes. gws is open source under the Apache-2.0 license. Google API quotas and usage limits still apply.

Do I need a Google Workspace account?

A standard Google account works for many features. Some Admin APIs require a Google Workspace subscription.

Can I use gws without OpenClaw?

Yes. OpenClaw is optional. gws works as a standalone CLI tool and can also be used from scripts or MCP-compatible clients.

How do I update gws? 

npm update -g @googleworkspace/cli
Enter fullscreen mode Exit fullscreen mode

The CLI reads Google’s Discovery Service at runtime, so updating the npm package is separate from its ability to discover current API methods.

Is my data secure with gws?

The CLI stores credentials encrypted at rest using AES-256-GCM with keys in the operating system keyring. Model Armor integration provides an additional sanitization layer for agent workflows.

You should still apply least-privilege OAuth scopes and protect exported credentials.

Can I use gws in CI/CD pipelines?

Yes. Export credentials and configure the credentials file in the CI environment:

gws auth export --unmasked > credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE="$PWD/credentials.json"
Enter fullscreen mode Exit fullscreen mode

Protect the credentials file using your CI platform’s secret-management features.

How is gws different from Google APIs Explorer?

gws is a command-line tool designed for automation, scripting, and AI agent integration. Google APIs Explorer is a browser-based testing interface. gws returns structured JSON and can be composed with other command-line tools.

Does gws support service accounts?

Yes. Set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE to a service account JSON key file:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE="/path/to/service-account.json"
Enter fullscreen mode Exit fullscreen mode

Can I contribute to gws?

Yes. The project is open source on GitHub. Pull requests from non-collaborators are temporarily disabled according to the repository maintainers.

Which platforms does gws support?

The npm package provides pre-built binaries for macOS, Linux, and Windows and handles native binary installation automatically.

Top comments (0)