AB
AB
AiBoss

All Categories

project

gws - an open-source command-line tool from the Google Workspace team.

gws (Google Workspace CLI) is an open-source command-line tool developed by the Google Workspace team. Written in Rust and distributed via npm, its biggest feature is its ability to dynamically build commands at runtime, independent of a static command list...

What is GWS?

gws (Google Workspace CLI) is an open-source command-line tool from the Google Workspace team, written in Rust and distributed via npm. Its biggest highlight is its runtime dynamic command building, independent of a static command list. It reads Google Discovery Services in real-time and automatically supports all Workspace APIs (Drive, Gmail, Calendar, Sheets, etc.), allowing new Google endpoints to be used without updates. Designed specifically for the AI Agent era, gws features a built-in MCP server, supports JSON structured output, automatic pagination, Model Armor security scanning, and Git-like pull/push workflows, enabling AI to directly edit local files and sync them back to Workspace.

The main functions of GWS

  • Dynamic API DiscoveryIt builds the command tree from Google Discovery Service in real time at runtime, automatically supporting all Workspace APIs and new endpoints without waiting for tool updates.
  • Unified command interfaceA single CLI covers all Google Workspace services, including Drive, Gmail, Calendar, Sheets, Docs, and Chat, eliminating the need to switch between multiple tools.
  • Structured JSON outputAll responses (including errors) are in JSON format, which facilitates script parsing and downstream automated processing.
  • MCP server supportsIt has a built-in Model Context Protocol server, and AI agents such as Claude and Gemini can directly call the Workspace API as a tool.
  • Intelligent Authentication ManagementSupports multiple authentication methods such as interactive OAuth, service accounts, and headless CI/CD environments, and automatically handles token refresh.
  • Automatic pagination:--page-all Automatic API pagination with flags, streaming NDJSON output, and easy extraction of large amounts of data.
  • Model Armor IntegrationScan API responses for security risks such as tooltip injection to protect the AI Agent from malicious content attacks.
  • Agent Skills LibraryIt has 100+ built-in skills covering common workflows and can be directly integrated with Agent frameworks such as OpenClaw.
  • Pull/Push WorkflowSimilar to Git, it pulls Google Docs as local structured files (TSV/JSON), edits them with AI, and then pushes them back to Workspace.
  • Gemini CLI ExtensionA dedicated extension allows the Gemini CLI Agent to natively access all gws commands and Skills capabilities.

GWS technical principles

  • Rust Core ArchitectureIt is written in Rust to ensure high performance and memory safety, and distributes pre-built binaries through npm to support cross-platform operation.
  • Discovery Service Dynamic ResolutionIt fetches Google Discovery Documents (API specifications in JSON format) in real time at startup, dynamically building the command tree and parameter structure instead of hard-coding static commands.
  • Command tree generated at runtimeBased on the resource and method definitions in Discovery Documents, it automatically generates corresponding CLI subcommands, parameter mappings, and request body structures.
  • REST API wrapper layerAll operations are ultimately converted into standard HTTP calls to the Google REST API, with unified handling of URL construction, request serialization, and response parsing.
  • OAuth 2.0 authentication pipelineIt features built-in full OAuth workflow support, including local callback server, token caching, automatic refresh, and JWT signature authentication for service accounts.
  • JSON Schema ValidationUse the parameter definitions in Discovery Documents to perform type checking and format validation of request parameters locally.
  • Streaming pagination engine:--page-all In this mode, the page token (pageToken/nextPageToken) in the response is automatically identified, and the results are recursively retrieved and streamed in NDJSON format.
  • MCP Protocol AdapterImplement the Model Context Protocol standard interface to expose gws commands as MCP Tools for AI clients to discover and invoke.
  • Model Armor Security GatewayIt calls the Google Cloud Model Armor API to perform real-time security scanning of the API response content and intercepts attack vectors such as injection warnings.
  • Pull/Push data transformation layerIt has a built-in format conversion engine that can convert Google Docs (Sheets/Docs) to local structured files (TSV/JSON/Markdown) in both directions, and supports difference detection and incremental synchronization.

gws project address

  • Github repositoryhttps://github.com/googleworkspace/cli

Application scenarios of GWS

  • AI Agent DevelopmentThe MCP protocol allows LLM to directly control Google Workspace, enabling Agent capabilities such as intelligent document processing, automatic email replies, and intelligent scheduling.
  • Batch data migration:use --page-all Automatic pagination; batch export of Drive file lists, Gmail emails, Sheets data, etc.; supports enterprise data backup and migration.
  • CI/CD AutomationIt runs in a headless server environment, automating DevOps workflows such as document generation, report push, and permission management, and supports service account authentication.
  • Content Management AutomationPull/Push workflows enable document version control, converting Google Docs to local Markdown for AI editing and then syncing back to the cloud.
  • Enterprise-level data pipeline: Build a real-time synchronization pipeline for Sheets ↔ data warehouses, automate report generation and distribution, and replace some of the capabilities of traditional ETL tools.
  • Security and compliance auditIntegrate with Model Armor to scan API responses, preventing the risks of injection and data leakage in enterprise-grade agent applications.

Back