Google Workspace CLI (gws): The Complete Guide
Stop writing curl calls against REST docs. gws is Google's official open-source command-line tool that unifies all Google Workspace APIs — Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more — into a single binary. With 15,800+ GitHub stars, dynamically built commands from Google's Discovery Service, 100+ AI agent skills, and a Gemini CLI extension, it's the definitive CLI for Google Workspace.
What Is gws?
gws (Google Workspace CLI) is an open-source, Rust-based command-line tool that provides a unified interface to all Google Workspace APIs. Commands are dynamically generated from Google's Discovery Service, so any API update is automatically reflected — no CLI update needed.
- Language: Rust
- License: Apache 2.0
- Stars: 15,800+ ⭐
- Forks: 588
- Contributors: 26
- Releases: 20
- Team: Google Workspace
Core Features
🔧 Unified Command Surface
One binary covers every Google Workspace API:
- Drive — List, upload, download, create, delete files
- Gmail — Send, read, search messages, manage labels
- Calendar — Create, list, update events
- Sheets — Read cells, append rows, create spreadsheets
- Docs — Create, update documents
- Chat — Send messages to spaces
- Admin — Manage users, groups, domains
- And more — Tasks, Vault, People, Classroom, etc.
🤖 100+ AI Agent Skills
Ships with 100+ SKILL.md files — one for every supported API, plus higher-level helpers for common workflows and 50 curated recipes for Gmail, Drive, Docs, Calendar, and Sheets. Works with Claude Code, OpenClaw, and other AI agents.
# Install all skills at once
npx skills add https://github.com/googleworkspace/cli
# Or pick only what you need
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
🔌 Gemini CLI Extension
Install gws as a Gemini CLI extension, giving your Gemini agent direct access to all Google Workspace APIs:
gws auth setup
gemini extensions install https://github.com/googleworkspace/cli
🛡️ Model Armor (Response Sanitization)
Integrate Google Cloud Model Armor to scan API responses for prompt injection before they reach your AI agent:
gws gmail users messages get --params '...' \
--sanitize "projects/P/locations/L/templates/T"
📊 Structured JSON Output
All output — success, errors, download metadata — is structured JSON. Perfect for piping into jq, scripting, and AI agent consumption.
📄 Auto-Pagination
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'
🔍 Schema Introspection
gws schema drive.files.list # View request/response schema for any method
Quick Start
Installation
npm install -g @googleworkspace/cli
Pre-built native binaries bundled for your OS. No Rust toolchain required. Also available via cargo install or Nix flake.
Authentication
gws auth setup # Walks you through Google Cloud project config
gws auth login # OAuth login
First Commands
# List 5 most recent Drive files
gws drive files list --params '{"pageSize": 5}'
# Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
# Send a Chat message (dry-run)
gws chat spaces messages create \
--params '{"parent": "spaces/xyz"}' \
--json '{"text": "Deploy complete."}' \
--dry-run
Authentication Modes
| Mode | Use Case |
|---|---|
| Interactive (OAuth) | Local desktop development |
| Manual OAuth | Google Cloud Console setup |
| Browser-assisted | Human or AI agent |
| Headless / CI | Export token flow for pipelines |
| Service Account | Server-to-server automation |
| Pre-obtained Token | Existing access token |
Architecture
gws uses a two-phase parsing strategy:
- Read
argv[1]to identify the service (e.g.,drive) - Fetch the service's Discovery Document (cached 24h)
- Build a
clap::Commandtree from the document's resources/methods - Re-parse the remaining arguments
- Authenticate, build HTTP request, execute
This means the CLI automatically covers new API methods as Google adds them — no update required.
gws vs Alternatives
Category: This tool is a Google Workspace command-line interface.
| Feature | gws | GAM | rclone |
|---|---|---|---|
| Focus | Unified Workspace API CLI | Workspace admin management | Cloud storage sync |
| Stars | 15.8K ⭐ | 4.1K ⭐ | 55.9K ⭐ |
| License | Apache 2.0 | Apache 2.0 | MIT |
| Language | Rust | Python | Go |
| Drive | ✅ Full API | ✅ Basic | ✅ Sync, backup, mount |
| Gmail | ✅ Full API | ✅ Send/manage | ❌ |
| Calendar | ✅ Full API | ✅ Basic | ❌ |
| Sheets | ✅ Full API | ❌ | ❌ |
| Docs | ✅ Full API | ❌ | ❌ |
| Chat | ✅ Full API | ❌ | ❌ |
| Admin (Users/Groups) | ✅ Full API | ✅ Deep admin features | ❌ |
| AI Agent Skills | ✅ 100+ skills | ❌ | ❌ |
| Gemini CLI Extension | ✅ | ❌ | ❌ |
| Model Armor | ✅ Prompt injection defense | ❌ | ❌ |
| Auto-Discovery | ✅ Dynamic from API | ❌ Static | ❌ |
| JSON Output | ✅ Structured | ✅ CSV/JSON | ✅ JSON |
| Pagination | ✅ --page-all | ✅ Built-in | N/A |
| Schema Introspection | ✅ gws schema | ❌ | ❌ |
| Multi-cloud | ❌ Google only | ❌ Google only | ✅ 70+ providers (S3, Azure, Dropbox...) |
| File Sync/Mount | ❌ | ❌ | ✅ rsync, mount, VFS |
| Encryption | ❌ | ❌ | ✅ Client-side encryption |
| Since | 2026 | 2014 | 2014 |
| Team | Community | Community |
When to choose gws: You need complete access to all Google Workspace APIs from the terminal, AI agent skills for LLM integration, Gemini CLI extension, Model Armor for security, and dynamic command generation from Discovery Service. Official Google tool.
When to choose GAM: You're a Google Workspace administrator who needs deep admin features — bulk user management, group provisioning, policy enforcement. GAM is battle-tested since 2014 with a strong admin community.
When to choose rclone: You need file sync/backup across 70+ cloud providers (not just Google). Mount cloud storage as FUSE, encrypt files, sync Drive to local disk. Rclone is the gold standard for cloud storage management but doesn't touch Gmail, Calendar, or Sheets.
Environment Variables
| Variable | Purpose |
|---|---|
GOOGLE_WORKSPACE_CLI_TOKEN | Pre-obtained access token |
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE | Path to credentials file |
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) |
GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE | Default Model Armor template |
GOOGLE_WORKSPACE_CLI_SANITIZE_MODE | warn (default) or block |
Conclusion
gws is Google's official answer to the fragmented Google Workspace CLI landscape. One Rust binary, dynamically generated from Discovery Service, covering every Workspace API with structured JSON output, 100+ AI agent skills, Gemini CLI extension, and Model Armor security. Whether you're a developer scripting automation, an admin managing your organization, or an AI agent operating Workspace — gws is the unified interface.