gws: Google Workspace CLI for Humans and AI Agents

What gws is

gws is the Google Workspace CLI: one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin and every other Workspace API, built, in the README's words, "for humans and AI agents". Instead of hand-writing curl calls against REST reference pages, you get a command for every resource and method, --help on each, --dry-run to preview requests, automatic pagination and structured JSON output.

The repository lives under the googleworkspace GitHub organisation, but the README states clearly, twice, that this is not an officially supported Google product. It is written in Rust, licensed under Apache-2.0, and also ships more than 100 Agent Skills so coding agents and LLM tools can drive Workspace without custom integration code. It suits developers and admins who script Workspace, teams automating reports or notifications in CI, and people wiring Workspace into agent tooling.

How it works

The distinctive design choice is that gws does not ship a static list of commands. It reads Google's own Discovery Service at runtime and builds its command surface dynamically, so when Workspace adds an API method, the CLI picks it up without a new release. The README describes a two-phase parse:

1. Read the first argument to identify the service, for example drive.
2. Fetch that service's Discovery Document, cached for 24 hours.
3. Build a clap command tree from the document's resources and methods.
4. Re-parse the remaining arguments against that tree.
5. Authenticate, build the HTTP request and execute it.

All output, including errors and download metadata, is JSON. Alongside the generated surface, some services have hand-written helper commands prefixed with + (such as gmail +send or calendar +agenda) so they never collide with Discovery-generated method names.

Key features

• Full API coverage from Discovery: every Workspace API and method, with gws schema to introspect any method's request and response schema.
• Structured output and exit codes: JSON everywhere, and exit codes that distinguish API errors (1), auth errors (2), validation errors (3), Discovery errors (4) and internal errors (5).
• Pagination controls: --page-all streams one JSON line per page as NDJSON, with --page-limit (default 10) and --page-delay (default 100 ms).
• Helper commands: Gmail send, reply, forward, triage and watch; Sheets append and read; Calendar insert and agenda; Drive upload; plus workflow helpers such as +standup-report, +meeting-prep, +email-to-task and +weekly-digest.
• Multiple auth modes: interactive OAuth, exported credentials for headless machines, service accounts and pre-obtained access tokens, with a documented precedence order.
• Encrypted credentials at rest: AES-256-GCM, with the key in the OS keyring or a file backend.
• Agent Skills: one SKILL.md per supported API, higher-level helpers, and 50 curated recipes for Gmail, Drive, Docs, Calendar and Sheets, plus a Gemini CLI extension.
• Model Armor integration: a --sanitize flag that runs API responses through a Google Cloud Model Armor template to screen for prompt injection, in warn or block mode.

Getting started

You need a Google Cloud project for OAuth credentials and a Google account with Workspace access; Node.js 18+ is only needed for the npm route. The recommended install is the pre-built binary from GitHub Releases. Alternatives from the README:

npm install -g @googleworkspace/cli

cargo install --git https://github.com/googleworkspace/cli --locked

brew install googleworkspace-cli

Then authenticate and make a first call:

gws auth setup     # walks you through Google Cloud project config
gws auth login     # subsequent OAuth login
gws drive files list --params '{"pageSize": 5}'

gws auth setup needs the gcloud CLI; without it, the README walks through creating a Desktop-app OAuth client in the Cloud Console and saving the JSON to ~/.config/gws/client_secret.json. If your OAuth app is unverified, limit scopes to the services you need:

gws auth login -s drive,gmail,sheets

For CI, export credentials from a machine with a browser and point the headless machine at the file:

gws auth export --unmasked > credentials.json

When several credential sources are present, gws picks them in a fixed order: an access token in GOOGLE_WORKSPACE_CLI_TOKEN first, then a credentials file named by GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE (user or service account), then the encrypted credentials created by gws auth login, and finally a plaintext credentials file in the config directory. Environment variables can also be loaded from a .env file.

To give a coding agent the bundled skills:

npx skills add https://github.com/googleworkspace/cli

Use cases

• Ops scripting: list or upload Drive files, append rows to a Sheet, or post a Chat message such as "Deploy complete." from a pipeline.
• Personal automation: a morning +standup-report or +agenda in the terminal, or +triage for an unread inbox summary.
• Event-driven tooling: gmail +watch and events +subscribe stream new mail or Workspace events as NDJSON for downstream processing.
• AI agents: giving an agent structured JSON access to Workspace through skills or the Gemini CLI extension, optionally sanitising responses with Model Armor.
• API exploration: using gws schema and --dry-run to understand a Workspace method before writing application code.

How it compares

The README positions gws against the status quo of writing curl requests from REST documentation, and against building custom tooling for agents. It also works alongside gcloud rather than replacing it: gcloud can automate project setup through gws auth setup, or mint tokens that gws consumes through GOOGLE_WORKSPACE_CLI_TOKEN. Compared with the official client libraries, the trade-off is the usual one between a CLI and an SDK: gws is quicker for scripts, shell pipelines and agents, while an SDK is the natural choice inside a long-running application.

Things to know before adopting

• Not an official Google product: the README says so explicitly, so support expectations should match a community-maintained tool.
• Pre-1.0 and changing: the README warns of breaking changes on the way to v1.0. The latest tagged release at the time of writing is v0.22.5 from March 2026, while the main branch was pushed to in October 2026.
• OAuth testing-mode limits: unverified apps are limited to about 25 scopes, and the recommended preset includes 85+ scopes, so it will fail for unverified apps, especially with @gmail.com accounts. You must also add yourself as a test user or login fails with "Access blocked".
• Credential handling: gws auth export --unmasked writes usable credentials to a file; treat it like any secret. A plaintext ~/.config/gws/credentials.json is the lowest-priority source in the precedence table.
• Discovery dependency: commands depend on fetching Discovery Documents (cached 24 hours); a failed fetch exits with code 4.
• Shell quoting: Sheets ranges contain !, which bash treats as history expansion, so the README says to wrap values in single quotes.
• Logging to stderr or JSON files is off by default and controlled by environment variables.
• Licence: Apache-2.0.

Project activity

As of October 2026 the repository has about 31,800 stars and roughly 1,950 forks. It was created in March 2026, is written in Rust, is licensed under Apache-2.0, and was last pushed to in October 2026. Development uses standard Cargo commands for build, lint and test. The source and releases are at github.com/googleworkspace/cli, and the Workspace API documentation it builds on is at developers.google.com/workspace.