Mar 10, 2026
The Ultimate Google Workspace CLI Tool
If you've ever tried to manage Google Workspace from the command line, you know how messy it gets. People end up stitching together random scripts, fighting with OAuth setups, and building their own wrappers around different Google APIs. It's never been a smooth experience.
That's where gws comes in. It's a command-line tool written in Rust that talks to Drive, Gmail, Calendar, and every other Workspace API without making you write boilerplate code for each one. The clever part is how it works: gws fetches Google's Discovery Service documents when it starts up and builds its entire command surface from that metadata. So when Google adds new endpoints or capabilities, gws picks them up automatically on its next run. No updates required from the maintainers.
The tool has two audiences in mind. First, humans who want a cleaner way to work with Workspace APIs from their terminal. Second, AI agents that need structured, predictable output to do things on users' behalf. With over 40 built-in agent skills and support for frameworks like OpenClaw and Gemini CLI, gws bridges the gap between human workflow automation and AI-powered assistance.
How gws Works Under the Hood
The architecture here is pretty straightforward. Instead of hardcoding commands for every Google Workspace API, gws pulls down Discovery Service documents when it launches. These documents describe every available endpoint, what parameters they take, and what responses they return. From that metadata, gws builds its entire CLI interface on the fly.
This approach has some real benefits. The tool stays current with Google's API changes automatically. When Google adds something to the Drive API or tweaks Gmail's capabilities, gws reflects those changes the next time you run it. There's no waiting for a new release. Also, the command structure follows Google's API conventions consistently, so once you figure out how gws works with one service, that knowledge transfers to the others.
The system has four main pieces working together. The Dynamic Command Generator handles fetching those Discovery Service documents and constructing the CLI interface. The Authentication Manager deals with OAuth2 flows, service accounts, and credential management, including encrypting stored credentials with AES-256-GCM. The API Request Executor uses the reqwest HTTP client to make validated requests with automatic pagination for endpoints that return paginated results. Finally, the Response Processor converts everything into structured JSON output that works well for both humans reading it and programs parsing it.
Features That Set gws Apart
gws packs a lot of practical features into one tool. The structured JSON output means you can pipe results directly into other command-line tools, scripts, or AI agents without any parsing gymnastics. That design choice makes the tool especially powerful for automation pipelines and AI agent integration.
Authentication trips up a lot of developers working with Google APIs, but gws gives you multiple authentication flows to handle different situations. Interactive OAuth works well for local development and one-off commands. Service accounts fit automated systems and CI/CD pipelines. You can also provide access tokens directly or export encrypted credentials for headless environments. The encryption layer protects stored credentials using AES-256-GCM, with integration into the operating system's keyring for additional security.
For AI agent developers, gws includes over 100 pre-built skills designed for frameworks like OpenClaw and Gemini CLI. These skills let AI agents perform Workspace operations with structured responses they can reason about and act on. The Model Armor integration adds response sanitization to protect against prompt injection attacks, which is becoming a bigger concern as AI agents get more capable.
Beyond the main features, gws has quality-of-life improvements like dry-run mode for testing commands without making changes, multipart upload support for large files, and schema introspection to explore available API capabilities directly from the command line.
Practical Applications
The tool really shines in several common scenarios. System administrators can manage Google Workspace resources from the terminal without constantly switching between the admin console browser interface and various API tools. Drive file management, Gmail label organization, Calendar event handling, and user management all become scriptable operations.
Automation scripts get a reliable way to perform Workspace operations. You can build backup scripts that export Drive content, generate reports from Gmail logs, or synchronize Calendar events across organizational units. The structured JSON output makes it easy to process results in subsequent script steps or store them in monitoring systems.
For developers building applications that interact with Google Workspace, gws works as a rapid prototyping tool. Instead of writing HTTP calls and handling authentication boilerplate, you can experiment with API calls directly and see exactly what responses look like. That speeds up development and helps clarify API behavior before you write application code.
CI/CD pipelines benefit from the credential export functionality. You can configure automated tests that interact with Workspace APIs in headless environments, run compliance checks on Drive content, or automate user provisioning as part of your deployment process.
Enterprise security and compliance teams find value in being able to perform bulk operations programmatically. Content migration, Drive hygiene enforcement, and security audit automation all become achievable without custom development.
Security and Enterprise Readiness
gws takes security seriously and implements multiple layers of protection. Input validation prevents injection attacks and malformed requests. Path traversal protection guards against directory traversal attempts. URL encoding and resource name validation ensure requests are properly formatted before reaching Google's APIs.
The credential handling shows some thoughtful security design. Instead of storing credentials in plain text, gws encrypts them using AES-256-GCM and integrates with the operating system's keyring where available. That approach keeps credentials secure even on shared systems.
Since gws uses official Google Workspace APIs, it inherits the compliance capabilities those APIs provide. Audit trails, eDiscovery support, and vault-based retention policies remain available through the tool. One thing to keep in mind: gws is not an officially supported Google product. It's a community-driven open source project.
Getting Started with gws
The project is written in Rust, so installation is straightforward if you have Rust toolchain access. You can build from source using Cargo, and pre-built binaries may be available for common platforms. The repository includes comprehensive documentation covering installation, authentication setup, and usage examples.
Before you dive in, you'll want to figure out which authentication flow fits your needs. Interactive OAuth works well for personal use and exploration. Service accounts require domain-wide delegation setup but work best for automated systems. The documentation walks through each option with step-by-step guidance.
The tool is currently in active development at version 0.9.1, with the team noting that breaking changes may occur before the 1.0 release. That means you should pin to specific versions in production automation if you need stability guarantees.
The Bigger Picture
gws takes a practical approach to API tooling that serves both human and AI use cases in a single codebase. The dynamic command generation architecture proves its value by automatically keeping pace with Google's API evolution. The security features show awareness of enterprise requirements. The AI agent integration demonstrates forward-thinking design for an era where AI assistants increasingly handle complex tasks on users' behalf.
For teams already working with Google Workspace APIs, gws offers a way to simplify tooling and reduce maintenance burden. For teams exploring AI agent integration, it provides a practical bridge between AI capabilities and real-world services. The open source nature means you can inspect the code, contribute improvements, and adapt the tool to specific organizational needs.
If you manage Google Workspace resources, build automation around Google's services, or experiment with AI agents that need to interact with productivity tools, gws deserves a place in your toolkit. The combination of dynamic API discovery, structured output, and solid security makes it a versatile foundation for a wide range of workflows.
Head to the GitHub repository to explore the documentation, try out the tool, and see how it fits into your workflow.