Skip to main content

​
Introduction to gws

gws is a dynamic command-line interface for Google Workspace APIs. Unlike traditional CLIs that ship with a fixed set of commands, gws builds its entire command surface at runtime by reading Google’s Discovery Service.
This project is under active development. Expect breaking changes as we march toward v1.0.

​
What makes gws different?

​
Dynamic Discovery

gws doesn’t ship a static list of commands. Instead, it:
  1. Reads Google’s Discovery Service at runtime
  2. Builds a complete command tree dynamically from API schemas
  3. Automatically supports new endpoints when Google Workspace adds them
When Google Workspace adds an API endpoint or method, gws picks it up automatically — no updates required.

​
Two-Phase Architecture

The CLI uses a unique two-phase parsing strategy:
1

Service Identification

Reads argv[1] to identify the service (e.g., drive, gmail, calendar)
2

Discovery Document Fetch

Fetches the service’s Discovery Document (cached for 24 hours)
3

Command Tree Generation

Builds a complete clap::Command tree from the document’s resources and methods
4

Argument Parsing

Re-parses the remaining command-line arguments against the generated tree
5

Execution

Authenticates, builds the HTTP request, and executes the API call

​
Built for humans and AI agents

​
For Humans

Stop writing curl calls against REST documentation. gws gives you:
  • Tab completion for all commands and resources
  • --help on every resource with full API documentation
  • --dry-run to preview requests before sending
  • Auto-pagination with --page-all flag
  • Multiple output formats: JSON, YAML, table, CSV

​
For AI Agents

Every response is structured JSON, making it perfect for programmatic consumption:
  • 100+ Agent Skills included (SKILL.md files)
  • Structured JSON output for all operations
  • Model Context Protocol (MCP) server support
  • 50+ curated recipes for Gmail, Drive, Docs, Calendar, and Sheets
  • No boilerplate — agents can call APIs directly
The CLI includes 100+ Agent Skills and works with popular AI platforms including OpenCode, Claude Desktop, and Gemini CLI.

​
Key Use Cases

Drive Management

List, upload, download, and manage files. Full support for permissions, sharing, and search.

Gmail Automation

Send messages, manage labels, search emails, and process attachments programmatically.

Calendar Operations

Create events, manage calendars, handle attendees, and query availability.

Sheets Automation

Read, write, and update spreadsheet data. Perfect for reporting and data pipelines.

Docs & Slides

Create and update documents and presentations through the API.

Chat & Spaces

Send messages to Google Chat spaces and manage conversations.

​
Example Commands

Terminal
# 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."}'  \
  --dry-run

​
Schema Introspection

Inspect any method’s request and response schema without leaving your terminal:
Terminal
# View method schema
gws schema drive.files.list

# View type definition with resolved references
gws schema drive.File --resolve-refs
All output is structured JSON, making it easy to understand request parameters, response fields, and data types.

​
What’s Next?

Installation

Install gws via npm or build from source

Quickstart

Get up and running in 5 minutes

Authentication

Set up Google Cloud OAuth credentials

Command Reference

Browse available services and commands