
I have spent a significant portion of my career working with various command-line interfaces for Google Workspace, from gcloud to gam. The recent release of the Google Workspace CLI (gws), which is not an officially supported Google product but has a number of Googler contributions, represents a fundamental shift in how we interact with the entire Google API surface.
In this post, I will provide an overview of the gws tool and explain how it differs from the Gemini CLI Workspace Extensions. More importantly, we will examine the modular architecture of “Skills”, “Recipes” and “Personas” that makes this tool in my view a masterpiece in modern, role-based automation.
GWS vs. GAM: Understanding the Overlap
Many Workspace Admins are already deeply familiar with gam (Google Apps Manager), the open-source command-line tool that has long served as a staple for domain administration. While gam is exceptional for bulk administrative tasks, such as creating users, modifying groups, or auditing devices, gws serves a different primary audience.
There is certainly a slight overlap between the two. You will notice administrative skills like gws-admin-reports present in the new repository. However, gws is fundamentally a developer and agentic tool focused on individual productivity applications like Drive, Gmail, and Docs, rather than domain-wide directory administration.
GWS vs. Gemini CLI Workspace Extensions
It is easy to confuse the Google Workspace CLI with the Workspace Extensions available for the Gemini CLI, but they serve entirely different purposes. The Gemini CLI Extension is a high-level interface designed for natural language tasks, such as “Summarize my unread emails” or “Find a file in Drive.” It is a convenient, user-centric tool for common, daily interactions.
In contrast, gws is a developer’s infrastructure tool. While the Gemini Extension is about “doing,” gws is about “orchestrating.” It provides the granular, programmatic control needed to build complex, multi-step workflows that can be automated, tested, and shared across a team.
The Modular Approach: Atomic Skills
The repository breaks down Google Workspace API interactions into highly modular components called “skills”. Instead of a monolithic script handling an entire workflow, the architecture relies on specific, atomic actions. Some examples from the repository include gws-gmail-send and gws-docs-write.
This atomic design means each skill has a single responsibility. For Apps Script developers, this is highly reminiscent of creating focused, single-purpose functions within an Apps Script library. By keeping these functions isolated, the code becomes easier to test, maintain, and reuse across different parts of an application.
Combining Forces: Recipes and Personas
Where this architecture becomes particularly interesting is how it combines these basic building blocks. The repository introduces the concept of “recipes,” such as recipe-backup-sheet-as-csv or recipe-create-expense-tracker. These recipes orchestrate multiple underlying skills to achieve a larger, practical goal.
In addition, these recipes are mapped to specific user “personas” like persona-content-creator or persona-it-admin. By grouping actions based on the user’s operational role, the tool becomes highly intuitive. When building Google Workspace automation tools, adopting a persona-driven approach can significantly improve the user experience: you are no longer just presenting a list of features, but offering targeted workflows tailored to what the user actually needs to accomplish their daily work.
Why this Approach Fits Workspace APIs Perfectly
This architectural choice is particularly effective given the versatile nature of Google Workspace APIs. Consider the Google Drive API, which features a generic endpoint for creating files. A basic integration might simply expose this raw “create file” capability. However, given the massive range of situations where you might want to create a file, a generic tool often leaves users or AI agents guessing how to properly format the request.
This is where skills, recipes, and personas show their true value. They allow us to dictate exactly how a file should be created for a specific context. For instance, if you want to turn a Markdown document into a natively formatted Google Doc, you could try to use the complex Google Docs API to insert text paragraph by paragraph. Instead, a targeted recipe can use the Drive API’s built-in file conversion features. By packaging instructions to upload the Markdown content and explicitly set the target MIME type to application/vnd.google-apps.document, the recipe abstracts away a complex API quirk into a reliable, repeatable action.
The Future of Agentic AI: The CLI + Skills Paradigm
As a recent VentureBeat article highlighted, the real breakthrough of gws is not that it makes Google Workspace programmable, given those APIs have existed for years. Instead, the innovation is the interface itself. By eliminating the need for custom wrappers and endless glue code, the CLI transforms Workspace from a collection of siloed applications into a single, unified programmable runtime.
This touches on a growing industry debate around the Model Context Protocol (MCP). Interestingly, while gws initially launched with a native MCP server mode, the maintainers explicitly removed it in version 0.8.0. Justin Poehnelt, one of the main contributors behind gws, refers to this overhead as the “MCP Abstraction Tax”. Exposing hundreds of granular API tools via a standard MCP server requires passing massive JSON schemas that bloat the AI’s context window and often lead to complex mapping bugs.
Instead, gws is now focused on a pure “CLI + Skills” architecture. In a related post on why developers should “Rewrite your CLI for AI Agents”, Justin outlines a shift from imperative to declarative design. An AI agent should “think” in terms of the high-level business goal (the “what”) rather than worrying about the underlying API steps to edit a document (the “how”). By moving the complex reconciliation logic directly into the CLI library, agents can simply use bash commands, a language they are already highly fluent in, to execute tasks efficiently.
Agent skills supply the “recipes” for these declarative commands, acting as modular, portable sets of instructions that teach an AI agent exactly which CLI tools to execute. The repository already incorporates over 100 of these Markdown skills, following a standardised structure. This framework is a powerful example of how we are moving away from simple prompt engineering toward “Skill Engineering”. By encoding our organisational knowledge and engineering judgement into these portable files, we ensure that AI agents follow token-efficient, reliable workflows every time they interact with our data.
Summary
The Google Workspace CLI is a glimpse into a future where our development environments are natively aware of our roles and workflows. For those interested in mastering this new framework, Anthropic recently shared a Complete Guide to Building Skills for Claude which explores the technical patterns and best practices for creating your own high-order skills.
Whether you are looking to automate your local development loop or build complex agentic workflows, the googleworkspace/cli provides the infrastructure you should keep an eye on!







