Google Workspace CLI

Product Introduction

1. Definition: The Google Workspace CLI (gws) is a unified, high-performance command-line interface and development framework built in Rust, designed to provide comprehensive access to the entire suite of Google Workspace APIs, including Google Drive, Gmail, Calendar, Sheets, Docs, Chat, and Admin SDK. It functions as a dynamic wrapper around the Google Discovery Service, allowing users to interact with RESTful Google Cloud services through a structured terminal interface.

2. Core Value Proposition: gws exists to eliminate the high friction and boilerplate code typically required to integrate with Google Workspace REST APIs. By offering a "zero boilerplate" environment, it enables developers and system administrators to execute complex API calls—such as managing file permissions, sending emails, or updating spreadsheets—without writing custom scripts or manually constructing cURL commands. Its primary value lies in its dual-purpose design: providing a human-friendly interactive CLI and serving as a highly optimized toolset for AI agents (LLMs) via structured JSON outputs and pre-defined agent skills.

Main Features

1. Dynamic Discovery Engine: Unlike traditional CLIs with static command sets, gws utilizes Google’s Discovery Service at runtime. It fetches the latest API schema documents to dynamically generate its command surface. This ensures that as soon as Google adds a new endpoint or method to a Workspace service, gws can interact with it immediately without requiring a software update. The internal architecture builds a clap-based command tree from these discovery documents, mapping resources and methods to CLI arguments.

2. AI Agent Skills and Tooling: The repository includes over 100 specialized "Agent Skills" (formatted as SKILL.md files). These provide high-level abstractions and "recipes" for common workflows like Gmail triage, meeting preparation, and document summarization. It features a dedicated Gemini CLI Extension and OpenClaw integration, allowing LLMs to execute Workspace operations directly. A "compact tool mode" is available to minimize context window usage when passing API schemas to AI models.

3. Structured JSON and NDJSON Output: Every response from the CLI is returned as structured JSON, making it natively compatible with data processing tools like jq or programming languages. For large datasets, such as listing thousands of Drive files, gws supports auto-pagination and streams results as Newline Delimited JSON (NDJSON) using the --page-all flag, preventing memory overflow and enabling real-time data processing.

4. Advanced Helper Commands (+Prefix): Beyond auto-generated methods, gws includes hand-crafted helper commands prefixed with a plus sign (e.g., +send, +agenda, +triage). These helpers handle complex multi-step logic, such as automatically managing email threading and RFC 2047 encoding for Gmail, or performing time-aware calculations for Calendar events using the user’s specific Google account timezone.

5. Secure Multi-Modal Authentication: gws supports various OAuth2 workflows tailored for different environments. This includes interactive browser-based login for local desktops, service account integration for server-to-server communication, and pre-obtained access tokens for CI/CD pipelines. Sensitive credentials are encrypted at rest using AES-256-GCM and stored in the operating system’s native keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

Problems Solved

1. REST API Complexity and Documentation Fatigue: Developers often spend hours navigating Google’s extensive REST documentation to find correct endpoints and JSON body structures. gws solves this by providing built-in --help for every resource and a gws schema command to introspect request/response requirements directly in the terminal.

2. Manual Pagination and Rate Limiting: Handling Google’s page tokens and exponential backoff is a common pain point in Workspace automation. gws automates the pagination process with flags like --page-limit and --page-delay, allowing users to fetch entire datasets with a single command.

3. Target Audience:

• DevOps and System Administrators: Automating user onboarding, auditing file permissions, and managing Workspace resources at scale.
• AI Engineers and Agent Developers: Integrating Google Workspace capabilities into LLM-based agents and autonomous workflows.
• Software Developers: Rapidly prototyping API calls or performing quick data exports without writing full-scale application code.

4. Use Cases:

• Automated Reporting: Using gws sheets +append to log CI/CD build results directly into a Google Sheet.
• Inbox Management: Utilizing gws gmail +triage to generate summaries of unread emails for a morning brief.
• File Migration: Scripting the upload of local assets to Google Drive using multipart upload support (gws drive files create --upload).

Unique Advantages

1. Zero-Maintenance CLI Surface: Because the tool is dynamically generated from Discovery Documents, it does not suffer from "bit rot." It remains compatible with Google’s evolving API landscape without manual code changes for every new feature.

2. Safety and Sanitization: Integration with Google Cloud Model Armor allows users to scan and sanitize API responses for prompt injection or sensitive data leaks before the information is passed to an AI agent, using the --sanitize flag.

3. Rust-Powered Performance: Built in Rust, the CLI offers near-instant startup times and minimal resource overhead compared to similar tools built in Python or Node.js. It is distributed as a single native binary, eliminating the need for complex runtime dependencies in production environments.

Frequently Asked Questions (FAQ)

1. How do I install the Google Workspace CLI? The most common way to install gws is via npm using npm install -g @googleworkspace/cli, which downloads the pre-built native binary for your architecture. Alternatively, users on macOS or Linux can use Homebrew via brew install googleworkspace-cli, or install it directly from source using cargo install.

2. Is the Google Workspace CLI an official Google product? No, according to the project documentation, this is not an officially supported Google product. It is an open-source project maintained under the googleworkspace GitHub organization, and users should expect breaking changes as it moves toward version 1.0.

3. How does gws handle Google API authentication and security? gws uses OAuth2 for authentication. For local security, it employs an encrypted keyring backend (AES-256-GCM) to store credentials. It supports multiple flows, including gws auth setup (which automates Google Cloud project configuration) and gws auth login for individual user consent.

4. Can I use gws for automated scripts in CI/CD pipelines? Yes, gws is designed for headless environments. You can provide credentials via the GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE environment variable or use a pre-obtained access token with GOOGLE_WORKSPACE_CLI_TOKEN to bypass interactive login prompts.

5. Does the CLI support all Google Workspace services? Yes, gws can interact with any service included in the Google Discovery Service. This includes core services like Drive, Gmail, and Sheets, as well as specialized APIs like the Admin SDK, Vault, and Chat. If Google provides a discovery document for the API, gws can command it.