Quick Verdict
gws, short for Google Workspace CLI, is an open-source command-line interface from the googleworkspace/cli repository. It reads Google’s Discovery Service at runtime to construct commands for Gmail, Drive, Calendar, Docs, Sheets, Chat, Admin, and other Workspace APIs, then produces structured JSON for shell users, scripts, and AI agents. It is useful for developers and IT automation teams that already understand Google Cloud OAuth, command-line quoting, and Workspace permissions. It is not a safe shortcut from an unconstrained natural-language request to email, deletion, sharing, or administrator changes.
The repository location must not be confused with product support. Its README explicitly says: this is not an officially supported Google product. Current version v0.22.5 is also pre-1.0, and the project warns users to expect breaking changes on the way to version 1.0. Production scripts should pin a release, capture representative Discovery schemas and JSON outputs, and test read and write workflows before upgrading. gws removes API boilerplate; it does not replace Workspace administration, OAuth approval, records policy, or human authority.
Best For
- Developers automating Workspace with shell commands, JSON,
jq, and explicit API resources. - IT teams able to create a Cloud project, review OAuth consent, and choose service-specific scopes.
- Organizations giving an AI agent narrow Workspace tools behind read/write separation and confirmation gates.
- Teams that want local CLI execution rather than a third-party hosted integration.
- It is not ideal for ordinary office users without OAuth experience or for granting an unconstrained model a domain-wide service account, complete mailbox access, or admin APIs.
Key Features
- Dynamic command surface: Runtime Discovery documents generate resources, methods, parameters, and schemas instead of relying on one static command list.
- Structured automation output: JSON is the default, with pagination, NDJSON streaming, schema introspection, and meaningful exit codes for scripts.
- Broad Workspace coverage: Discovered APIs include Drive, Gmail, Calendar, Sheets, Docs, Chat, Tasks, Admin, and other services available to the credential.
- Hand-written helpers: Commands such as
+send,+reply,+agenda,+upload, and+appendsimplify frequent workflows alongside raw API methods. - Agent skills and Gemini extension: The repository distributes service skills, helpers, and recipes for compatible agents.
- Request preview:
--dry-runvalidates and displays a request without calling the API, useful before writes and destructive operations. - Authentication choices: Interactive OAuth, existing tokens, credential files, and service accounts cover desktop, CI, and server contexts.
Use Cases
Low-risk examples include reading today’s calendar, listing files within a known Drive folder, reading a specific Sheets range, or summarizing unread-message metadata. Write workflows can draft and send mail, create events, append rows, upload files, or post Chat messages, but the agent should first run --dry-run and present the account, recipients, resource identifiers, item count, and request body. Deletion, move, sharing changes, domain administration, Vault operations, bulk mail, and Apps Script replacement need stronger second confirmation, limits, and a durable change record.
Workspace content is untrusted input. An email, document, calendar description, or spreadsheet cell can tell an agent to export contacts, read credentials, ignore policy, or perform another service action. Content cannot authorize broader OAuth scopes, a different account, access to local credential files, or a write command. Optional Model Armor response sanitization can flag some prompt injection, but it is not an authorization boundary. Fixed tool policy, provenance labels, parameter validation, read/write separation, and human approval remain necessary.
Pricing
gws is Apache-2.0 software with no CLI license charge. Google Workspace subscriptions, Cloud projects, API quotas, model calls, audits, and operations remain separate. Current v0.22.5 is pre-1.0. Dynamic Discovery can also reveal new API methods without a new CLI release, so teams need to pin the CLI while monitoring schema changes and allowlisting approved services and methods.
| Method | CLI price | Best use | Primary boundary |
|---|---|---|---|
Prebuilt v0.22.5 | Free | Local and controlled scripts | Pre-1.0; regression-test upgrades |
| npm installation | Free | Automatic platform binary download | Pin exact version and package source |
| Interactive user OAuth | Free | One user’s local actions | Select only task-required scopes |
| Service account or CI | Free | Server automation | Avoid domain-wide delegation and long-lived keys |
| Agent skills | Free | Controlled AI workflows | Confirm every write and delete action |
An unverified OAuth app in testing mode is limited to roughly 25 scopes, while the repository says its recommended preset includes more than 85 and can fail. More importantly, that preset is rarely least privilege. Filter login by the smallest service set, such as gws auth login -s drive,gmail,sheets, then choose the narrowest scopes. A mailbox-reading job should not get modification rights, and a personal workflow should not enable Admin or domain-wide delegation.
Pros
- One CLI unifies many Workspace APIs and removes repetitive REST, authentication, and pagination code.
- Dynamic Discovery can surface current API resources and methods quickly.
- JSON, NDJSON, schema introspection, and exit codes work well for scripts and agents.
--dry-run, service-filtered login, and skill security rules support a review workflow.- Prebuilt binaries, npm, Homebrew, Cargo, and Nix provide several installation paths.
- Local execution gives teams more control than routing every operation through another hosted integrator.
Cons
- The project explicitly lacks official Google product support and associated Workspace product SLA commitments.
- Pre-1.0 releases may break arguments, credential storage, or output compatibility, so automation must pin versions.
- A dynamically expanding command surface increases permission-review and change-detection work.
- OAuth exports,
.envfiles, refresh tokens, and service-account keys can expose broad data if mishandled. - Agents consume adversarial email and document content, creating cross-service prompt-injection risk.
--dry-runpreviews an HTTP request but cannot understand business authority or stop every destructive misuse.
Alternatives
| Tool | Best fit | Advantage | Main tradeoff |
|---|---|---|---|
| Gemini CLI | Google users needing a general terminal coding agent | Complete model, shell, file, and MCP workflow | Not equivalent to a Workspace API CLI |
| Gemini for Google Workspace | Employees using AI inside Gmail, Docs, and Meet | Native UI and administrator licensing | Different API automation and scripting model |
| Google Drive MCP Server | Agents needing only Drive file tools | Official single-service surface supports least privilege | Still in Developer Preview and does not cover the complete Workspace suite |
| Google Calendar MCP Server | Calendar-only automation | Official single-service boundary is easier to audit | Still in Developer Preview with no unified Workspace access |
| Google Sheets MCP Server | Agents focused on spreadsheet operations | Official, focused spreadsheet tool surface | Still in Developer Preview, with write-scope documentation requiring verification |
| Workspace MCP | Teams self-hosting several Workspace services | Broad coverage with read-only and granular configuration | Community implementation; users govern OAuth, tokens, and broad write operations |
FAQ
Is gws an officially supported Google product?
No. The repository explicitly disclaims official product support. Hosting under a Google Workspace GitHub organization does not provide a commercial SLA or support entitlement.
Can version 0.22.5 be used in production scripts?
It can be evaluated in a controlled scope, but it remains pre-1.0. Pin the exact release, retain regression fixtures, and test authentication, arguments, JSON output, and writes before each upgrade.
Should an operator choose the recommended OAuth scope preset?
Usually not by default. It has more than 85 scopes and may exceed the testing-mode cap. Select the smallest services and read-only scopes needed for the exact job.
Must an agent confirm email sends and file deletion?
Yes. The repository’s shared skill rules require confirmation before write and delete commands and recommend --dry-run for destructive operations. Confirmation should identify account, target, quantity, and final request.
How should credentials be stored?
Desktop OAuth can use encrypted storage and the operating-system keyring. CI should use short-lived tokens or controlled credential injection. Never place client secrets, refresh tokens, exported JSON, service-account keys, or .env content in a repository or prompt.
How should prompt injection in mail or documents be handled?
Treat Workspace content as data that cannot change tool policy, scopes, accounts, or approval state. Separate read analysis from write execution, allowlist methods, validate parameters, and use sanitization only as an additional signal.
Bottom Line
gws offers a low-boilerplate, structured, agent-friendly interface to Workspace APIs and is attractive for teams that understand OAuth and automation. It is not an officially supported product, remains pre-1.0, and combines a changing API surface with sensitive credentials and adversarial office content. Start with one test account, one read-only service, and pinned v0.22.5. Add scopes one at a time after output validation. Preview and confirm every write or destructive command, keep credentials out of prompts, and never let an email or document become an authority source.