cli: Use Google Workspace APIs from Humans and AI Agents

Overview

gws is a command-line interface for Google Workspace, built on Google’s Discovery Service. Instead of maintaining a fixed command list, it reads API descriptions at runtime to construct commands for services such as Drive, Gmail, Calendar, Sheets, Docs, and Chat. It aims to make Workspace APIs easier to use from a terminal and from AI agents, without hand-written REST calls or custom integration code.

The Rust CLI is available as pre-built binaries for supported operating systems, through npm, Homebrew on macOS and Linux, or from source. It returns structured JSON and includes agent skills for Workspace APIs and common workflows. The project is not an officially supported Google product.

Key Features

• Builds its command surface dynamically from Google Discovery Service documents, which it caches for 24 hours.
• Provides --help for API resources and methods, plus a schema command for inspecting request and response formats.
• Emits structured JSON and supports pagination as newline-delimited JSON for scripting.
• Offers --dry-run to preview requests and helper commands for common actions such as sending email or uploading files.
• Supports interactive OAuth, credentials files, service accounts, and pre-obtained access tokens.
• Includes agent skills for supported APIs and curated Workspace workflows, with Gemini CLI extension support.
• Can sanitize API responses with Google Cloud Model Armor when configured.

Use Cases

• A developer can inspect and call Workspace API methods from a shell without writing a separate curl request for each endpoint.
• An operations team can use JSON output and pagination to automate Drive or Sheets tasks in scripts.
• An AI-agent developer can pair the CLI and its skills to let an agent work with Workspace through existing APIs.
• A user can run helper commands for routine tasks such as checking a calendar agenda, sending a Gmail message, or uploading a Drive file.

Getting Started

Install the CLI with npm, then follow the README’s authentication instructions:

npm install -g @googleworkspace/cli
gws auth setup
gws auth login
gws drive files list --params '{"pageSize": 5}'

See the README for binary installation, OAuth alternatives, and detailed usage.

Considerations

• The project is under active development toward v1.0 and explicitly warns that breaking changes may occur. Its health status is quiet, with no commits recorded in the last 90 days; the project has multiple contributors, and the data does not indicate contributor concentration.
• Authentication requires Google Cloud project and OAuth configuration, or another supported credentials source. Unverified OAuth apps have scope limits that can make broad scope presets fail.
• The repository describes itself as unofficial, so do not treat it as a Google-supported product.
• The README identifies Rust and Node.js 18 or later as relevant requirements, depending on whether you build from source or install through npm. The project uses the Apache-2.0 license.