Google Workspace CLI (gws): Rust CLI for Workspace APIs

June 18, 2026·AI Newsroom·5 min read·12 sources
google-workspacegwsclirustgoogle-apigemini-cli+8
Google Workspace CLI open-source repository social preview card
Image: GitHub / googleworkspace/cli repository (Apache 2.0)

On 2026-03-02, the googleworkspace organization on GitHub published googleworkspace/cli. The binary, gws, is a Rust command-line client for every Workspace API surface (Drive, Gmail, Calendar, Sheets, Docs, Slides, Forms, Tasks, Chat, Meet, Keep, Classroom, People, Admin, Model Armor, Script, Events, Workflow). The CLI is built dynamically against Google’s Discovery Service: it does not ship a static method list, but instead fetches each service’s Discovery Document at runtime, builds the clap::Command tree from it, and re-parses argv (README, 2026-06-18). As of 2026-06-18, the repository carries 27,134 stars, 1,426 forks, 95 skill directories, and 31,992 weekly npm downloads — and the README opens with two caveats the article must lead with: “This is not an officially supported Google product” and “This project is under active development. Expect breaking changes as we march toward v1.0” (googleworkspace/cli repository, 2026-06-18; npm weekly downloads, week ending 2026-06-16).

What it is

The gws binary. The binary name is gws; the recommended install path is a pre-built binary from GitHub Releases. The npm package is @googleworkspace/cli. The repository is 98.5% Rust and the license is Apache-2.0 (repository metadata, 2026-06-18; LICENSE, 2026-06-18). The top contributor is jpoehnelt (Jeremy Poehnelt, Google Workspace Developer Relations) with 124 contributions, followed by googleworkspace-bot (62) and github-actions[bot] (12) (contributors API, 2026-06-18).

Install paths. Five install paths: a pre-built binary from GitHub Releases (recommended), npm install -g @googleworkspace/cli, cargo install gws, Nix, and brew install googleworkspace-cli. The npm package was created on 2026-03-03, one day after the repository itself (npm registry, 2026-06-18).

Auth flows. Four OAuth2 / credential flows: (1) interactive login via gws auth login, (2) headless CI via GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE, (3) service-account credentials, and (4) a pre-obtained token flow. Credentials are encrypted at rest with AES-256-GCM under a passphrase-derived key (README, 2026-06-18). Nine GOOGLE_WORKSPACE_CLI_* environment variables override defaults for paths, the Model Armor template, the sanitize mode, the OAuth client ID, and the credential passphrase.

The Discovery Service hook — the genuine technical claim. On first invocation of gws <service>, the CLI reads the service name, fetches that service’s Google Discovery Document over HTTPS, builds a clap::Command tree from the Discovery Document’s methods[*] array, and re-parses argv against that tree before performing OAuth and HTTP (README, 2026-06-18; Google API Discovery Service, 2026-06-18). When Google adds a new Workspace API method, gws picks it up on the next invocation without a code change and without a release — the architectural differentiator that justifies the “first first-party unified CLI” framing.

+helper shortcuts. The project ships 24 hand-curated +helper commands prefixed with + so they never collide with auto-generated method names: +agenda, +today, +inbox, +unread, +upload, +append, and so on. The CLI supports --page-all for full-payload NDJSON streaming and --format json for structured output (README, 2026-06-18).

Why it matters

First first-party unified CLI for Workspace. Until now, Workspace power users had to choose between curl plus a hand-rolled Discovery Document parser, the per-language google-api-python-client and googleapis Node libraries, or third-party CLIs like gcloud (which covers Admin but does not go deep on Gmail / Calendar / Sheets). gws is the first project published under the googleworkspace org that ships a single binary covering all 18+ Workspace surfaces, with structured JSON output, five install paths, four auth flows, and an Apache-2.0 license. The 31,992 weekly npm downloads and 27,134 stars confirm real adoption (npm weekly downloads, 2026-06-16).

Agent-native out of the box. The project ships 95 skill directories indexed in docs/skills.md: 17 service skills, 29 helper skills, 10 persona bundles, and 41 multi-step recipes. The install path is the cleanest “give your agent the entire Workspace surface” path in the open-source ecosystem: npx skills add https://github.com/googleworkspace/cli. The first-party Gemini CLI extension ships in the same repository and is installed with gemini extensions install https://github.com/googleworkspace/cli (README, 2026-06-18).

Model Armor integration — the under-reported story. Most third-party coverage focuses on the agent-skill / Gemini-extension angle. The load-bearing differentiator for AI agent safety is the Model Armor integration. The README documents a dedicated modelarmor service skill with three helper commands: +sanitize-prompt (sanitize a user prompt), +sanitize-response (sanitize a model response), and +create-template. The mechanism is --sanitize "projects/P/locations/L/templates/T" (or the GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE and GOOGLE_WORKSPACE_CLI_SANITIZE_MODE env vars) (README, 2026-06-18; Model Armor product page, 2026-06-18).

For an AI Newsroom primary reader — an ML engineer using Workspace as an agent data source — this is the most important feature. A Workspace API can return attacker-controlled content (an email body, a Doc comment, a Chat message) that the agent will then read. With Model Armor enabled in block mode, gws refuses to return content that Model Armor flags.

What to watch

  1. The next release tag (currently v0.22.5, dated 2026-03-31; no new release in 11 weeks).
  2. Whether GOOGLE_WORKSPACE_CLI_SANITIZE_MODE defaults flip from warn to block.
  3. More helper commands beyond the current 24 +helper shortcuts.
  4. Workspace API surface additions auto-tracked via the Discovery Service hook.

Risks and caveats

  1. Not officially supported by Google. “This is not an officially supported Google product” is the first line of the README, repeated in the closing line (README, 2026-06-18). There is no SLA.
  2. v0.22.x, not v1. “This project is under active development. Expect breaking changes as we march toward v1.0” is the second > NOTE block (README, 2026-06-18). The latest tag is v0.22.5 from 2026-03-31.
  3. No release since 2026-03-31. The repository shipped 30 release tags between 2026-03-05 and 2026-03-31 and no further release tag in the 11 weeks since (releases API, 2026-06-18). Commits are still landing, but the release pause is real.
  4. OAuth2 testing-mode scope limits. The recommended scope preset has 85+ scopes, which exceeds the ~25-scope cap for unverified apps in OAuth testing mode — especially for @gmail.com accounts. The fix is gws auth login -s drive,gmail,sheets to pick scopes per service (README, 2026-06-18).
  5. Model Armor is opt-in, default warn. The default GOOGLE_WORKSPACE_CLI_SANITIZE_MODE is warn, not block (README, 2026-06-18). In an agent context, set GOOGLE_WORKSPACE_CLI_SANITIZE_MODE=block explicitly.

Verdict

googleworkspace/cli is the first first-party unified CLI for Google Workspace: a single Rust binary built dynamically against the Google Discovery Service, with 95 skill directories, a Gemini CLI extension, and an opt-in Model Armor integration that scans API responses for prompt injection. The 27,134 stars, 1,426 forks, and 31,992 weekly npm downloads confirm real adoption (repository metadata, 2026-06-18; npm weekly downloads, 2026-06-16). The 30 release tags from v0.4.4 to v0.22.5 — all between 2026-03-05 and 2026-03-31, with no new release in 11 weeks — and the README’s > NOTE blocks set the honest frame (releases API, 2026-06-18; README, 2026-06-18).