Overview

Google has released an official CLI for Google Workspace — @googleworkspace/cli (binary name: gws). Written in Rust, it dynamically generates its entire command surface from Google's Discovery Service, giving it automatic access to every Google Workspace API. Released March 2, 2026 by Justin Poehnelt (Google Workspace DevRel).

Our current google-workspace skill uses ~750 lines of custom Python scripts wrapping google-api-python-client. It covers 6 services with limited operations. The gws CLI gives us comprehensive access to ALL 25+ Workspace APIs, 730 MCP tools, cross-service workflows, and helper commands — all with zero maintenance on our side.

Hands-on testing confirmed: gws is ready for integration. See testing comment for full results.

Research Findings

How gws Works

Dynamic command generation from Google's Discovery Service — never goes stale:

gws <service> <resource> [sub-resource] <method> [flags]

Helper commands (agent-optimized):

gws gmail +send --to user@example.com --subject "Hello" --body "Hi!"
gws gmail +triage                                    # Unread inbox summary
gws drive +upload ./report.pdf                       # Upload with auto metadata
gws calendar +insert --summary "Meeting" --start ... --end ...
gws calendar +agenda                                 # Upcoming events
gws sheets +read SHEET_ID "Sheet1!A1:D10"
gws docs +write DOC_ID --text "..."
gws workflow +standup-report                         # Cross-service workflow

Built-in MCP server (730 tools for all services):

gws mcp -s gmail,drive,calendar,sheets,docs -e -w

Key features:

• Schema introspection: gws schema drive.files.list
• Dry-run validation: --dry-run
• Output formats: JSON, table, YAML, CSV
• Auto-pagination: --page-all
• File upload/download support
• Model Armor integration for prompt injection protection

Maturity Assessment

Current State in Hermes Agent

Existing skill: skills/productivity/google-workspace/ — Python scripts (~750 lines), 6 services, limited operations.

Coverage gap is massive:

Implementation Plan

Classification

This remains a bundled skill (not a tool). Per CONTRIBUTING.md:

• Wraps an external CLI (gws) that the agent calls via terminal
• Google Workspace is broadly useful to most users
• No custom Python integration needed in the agent harness

Phase 1: gws-Backed Skill (Target: This Month)

Goal: Replace Python scripts with gws commands in the skill, keeping our auth flow.

1. Install gws — Add to skill setup: cargo install gws or download prebuilt binary (once Linux npm is fixed)

2. Auth bridge — Keep our existing setup.py OAuth flow (works on CLI, Telegram, Discord, headless):

   • User does OAuth via our redirect-to-localhost:1-copy-URL-back flow
   • After auth, export credentials in gws-compatible format:

     {"client_id": "...", "client_secret": "...", "refresh_token": "..."}

   • Set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE to point to this file
   • gws handles token refresh from there

3. Rewrite SKILL.md — Replace $GAPI Python commands with gws commands:

   # Old
   $GAPI gmail search "is:unread" --max 10
   # New
   gws gmail +triage --max 10 --query "is:unread"
   
   # Old
   $GAPI gmail send --to user@example.com --subject "Hello" --body "Hi"
   # New
   gws gmail +send --to user@example.com --subject "Hello" --body "Hi"
   
   # Old
   $GAPI calendar list
   # New
   gws calendar +agenda
   
   # Old (didn't exist!)
   # New
   gws drive +upload ./file.pdf
   gws workflow +standup-report
   gws tasks tasks list --params '{"tasklist": "@default"}'

4. Expand coverage — Add sections for Slides, Tasks, Keep, Forms, etc. (trivial since gws already supports them)

5. Remove Python scripts — Delete scripts/google_api.py (~486 lines). Keep scripts/setup.py for auth bridge.

Deliverables:

• Updated SKILL.md with gws commands
• Modified setup.py to also export gws-compatible credentials
• Removed google_api.py
• Added gws install instructions

Phase 2: MCP Integration (Future)

Goal: Use gws as an MCP server for native tool-level Google API access.

1. Add gws MCP server to ~/.hermes/config.yaml:

   mcp_servers:
     google-workspace:
       command: gws
       args: [mcp, -s, gmail,drive,calendar,sheets,docs, -e, -w]
       env:
         GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: ~/.hermes/google_credentials.json

2. This gives the agent direct tool access to 137+ Google API operations without going through terminal

3. The skill would shift from "how to use gws CLI" to "when to use which Google Workspace MCP tools"

Benefits:

• No terminal parsing — structured JSON in/out
• Parallel tool calls to multiple Google APIs
• Richer error handling via MCP protocol

Phase 3: Full Ecosystem (Future)

• Evaluate gws's recipe skills for complex workflows
• Consider supporting gws auth setup when gcloud is available (faster setup for users who have it)
• Monitor for gws v1.0 — may simplify auth story

Pros & Cons

Pros

• 10x API coverage — 730 tools vs ~15 commands
• Zero maintenance — Discovery-based, auto-updates with Google APIs
• Better security — AES-256-GCM encrypted credentials
• Agent-optimized — Helper commands, workflows, Model Armor
• MCP server — Direct path to native Hermes MCP integration
• Single binary — No Python dependency chain

Cons / Risks

• Pre-1.0 — Breaking changes possible (our skill layer absorbs these)
• Linux npm broken — Must use cargo install for now
• "Not officially supported" — Could lose maintenance (but it's Apache-2.0, we can fork)
• Auth UX on headless — gws auth login requires browser on same machine; mitigated by keeping our auth bridge
• Cargo dependency — Users need Rust toolchain or wait for npm fix

Open Questions

1. Binary distribution: Wait for npm Linux fix, or ship a prebuilt binary? Or require cargo?
2. MCP vs CLI: Start with CLI (Phase 1) and add MCP later, or go directly to MCP?
3. Scopes: gws requests broad scopes by default. Should we match our current scope set or go broader?
4. Auth migration: For users with existing google_token.json, auto-convert to gws format?

References

• googleworkspace/cli
• gws issue #86 — Linux x64 npm
• skills.sh — Agent Skills Directory
• Hands-on testing results