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

June 18, 2026·AI Newsroom·11 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 March 2, 2026, the googleworkspace organization on GitHub — the public home for Google Workspace developer tooling — published a new open-source repository, 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. 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; README, 2026-06-18; npm weekly downloads, week ending 2026-06-16).

Why it matters now. Three reasons, in order of how under-reported they are. First, gws is the first first-party unified CLI for Google Workspace: one Rust binary covering all 18+ Workspace surfaces, with structured JSON output, four install paths (binary, npm, cargo, Nix, brew), and four auth flows (interactive, headless CI, service-account, pre-obtained-token). Second, the project is agent-native out of the box: it ships 95 skill directories (17 services, 29 helpers, 10 personas, 41 multi-step recipes), a npx skills add install path, and a first-party Gemini CLI extension. Third, and most under-reported, gws integrates with Google Cloud Model Armor to scan API responses for prompt injection before they reach the agent — opt-in via --sanitize or env vars, defaulting to warn rather than block (README — Model Armor section, 2026-06-18; Model Armor product page, 2026-06-18).

What it is

The gws binary. The README is explicit: the binary name is gws, the primary install path is “the recommended way to install gws is to download the pre-built binary for your OS and architecture from the GitHub Releases page”, and the package on npm is @googleworkspace/cli (README, 2026-06-18; npm registry, 2026-06-18). The repository language share 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).

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

The four auth flows. The README describes four distinct OAuth2 / credential flows: (1) interactive login via gws auth login for a local user account, (2) headless CI via GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE pointing at an exported credentials file, (3) service-account credentials for non-interactive workloads, and (4) a pre-obtained token flow for callers that already have a refresh token (README — Authentication section, 2026-06-18). Credentials are encrypted at rest with AES-256-GCM under a key derived from a passphrase (README, 2026-06-18). Nine GOOGLE_WORKSPACE_CLI_* environment variables override the default paths, the Model Armor template, the sanitize mode, the OAuth client ID, and the credential passphrase.

The Discovery Service hook — the genuine technical claim. The architectural differentiator is that gws does not ship a static method list. The two-phase parsing flow documented in the README works as follows: 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 — Architecture section, 2026-06-18; Google API Discovery Service, 2026-06-18). The practical consequence: when Google adds a new Workspace API method, gws picks it up on the next invocation without a code change and without a release. This is the genuine architectural claim that justifies the “first first-party unified CLI” framing — the alternatives (gcloud, the per-language google-api-* client libraries) all ship static method lists pinned to a release.

+helper shortcuts vs. auto-generated methods. Alongside the auto-generated method surface, the project ships 24 hand-curated +helper commands prefixed with + so they never collide with auto-generated method names (README, 2026-06-18). The helpers cover the most common operations: +agenda (calendar agenda), +today, +inbox, +unread, +upload (Drive), +append (Sheets), and so on. The CLI also supports --page-all for full-payload NDJSON streaming and --format json for structured output (README, 2026-06-18). A first-time user can run gws --help and see both the auto-generated method list and the +helper shortcuts side by side.

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, four install paths, four auth flows, and an Apache-2.0 license (repository metadata, 2026-06-18; README, 2026-06-18). The 31,992 weekly npm downloads (week ending 2026-06-16) and the 27,134 stars are dated metrics that confirm real adoption, not a paper launch (npm weekly downloads, 2026-06-16; repository metadata, 2026-06-18).

Agent-native out of the box. The project ships 95 skill directories indexed in docs/skills.md: 17 service skills (Drive, Sheets, Gmail, Calendar, Admin, Docs, Slides, Tasks, People, Chat, Classroom, Forms, Keep, Meet, Events, Model Armor, Workflow, plus the shared cross-service skill), 29 helper skills, 10 persona bundles (exec-assistant, project-manager, hr-coordinator, sales-ops, it-admin, content-creator, customer-support, event-coordinator, team-lead, researcher), and 41 multi-step recipes such as recipe-draft-email-from-doc, recipe-organize-drive-folder, recipe-block-focus-time, and recipe-save-email-to-doc (docs/skills.md, 2026-06-18; skills/ directory listing, 2026-06-18). The directory listing reports 95; the README breakdown adds up to 97 — the article reports the load-bearing 95, the directory-listing number, per the brief’s “do not” guidance.

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. A second install path reaches the same surface scoped to one service (npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive) (README — Skills section, 2026-06-18). 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). OpenClaw is supported via a symlink to ~/.openclaw/skills/ plus an install block in gws-shared that auto-installs the CLI via npm if gws is not on $PATH (README — OpenClaw section, 2026-06-18). The combined effect is that a Claude, Gemini, Codex, or OpenCode agent can pick up the entire Workspace surface in a single install line and start using gws immediately.

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 through a Model Armor template), +sanitize-response (sanitize a model response through a Model Armor template), and +create-template (create a new Model Armor template) (README, 2026-06-18).

The README section on response sanitization is direct: “Integrate Google Cloud Model Armor to scan API responses for prompt injection before they reach your agent” (README — Model Armor section, 2026-06-18; Model Armor product page, 2026-06-18). 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). The default mode is warn, not block — the article does not describe gws as “automatically sanitizing agent responses”; it is opt-in, and warn is the default. This is one of the five load-bearing caveats.

For an AI Newsroom primary reader — an ML engineer using Workspace as an agent data source — this is the most important feature in the project, and it is the under-reported story. 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. The same model-armor +sanitize-prompt helper handles the symmetric case — a user prompt being routed through a Model Armor template before it leaves the agent. The article does not turn this into a Model Armor deep-dive; Model Armor is one of the three pillars, and the deep-dive is a separate story.

What to watch

Six follow-up signals are worth tracking, in order of how informative each one is about the project’s direction.

  1. The next release tag. The project is on v0.22.5, dated 2026-03-31, with no new release in 11 weeks as of 2026-06-18. Commits are still landing (pushed_at: 2026-06-10), so a v0.23.x or v1.0.0-rc is plausible in the next cycle (releases API, 2026-06-18; repository metadata, 2026-06-18). The first new tag after 2026-03-31 is the signal that resolves the “are the v1.0 march and the release pause the same thing?” question.
  2. Whether GOOGLE_WORKSPACE_CLI_SANITIZE_MODE defaults flip from warn to block. The current default is the log-a-warning-and-pass-through mode. A flip to block would be the single most important change for agent safety, and the most user-visible behavior change (README — env vars, 2026-06-18).
  3. More helper commands beyond the current 24 +helper shortcuts. Each new helper signals that a Workspace operation has earned its place in the curated surface.
  4. More persona bundles beyond the current 10. Each new persona signals that a role (not just a task) has stabilized in the agent ecosystem.
  5. Gemini CLI extension enhancements. The extension is a thin shim today; deeper integration (session state, multi-step plans, model-armor as a default-on extension behavior) would matter.
  6. Workspace API surface additions auto-tracked via the Discovery Service hook. This is the architectural claim that makes the CLI self-updating. A new Workspace API method that appears in gws --help without a release is the cleanest demonstration of the Discovery Service hook in production.

Risks and caveats

The README opens with two > NOTE blocks that any honest article must lead with, and three further caveats are load-bearing. The article preserves all five.

  1. Not officially supported by Google. “This is not an officially supported Google product” is the first line of the README, and the closing line of the README repeats it (README, 2026-06-18). The repository is owned by the googleworkspace GitHub organization and the lead contributor is a Google Workspace Developer Relations engineer, but the project is a developer-experience effort, not a Google Cloud product. There is no SLA and no first-party support channel. The article does not describe gws as “Google’s official CLI” without quoting the README’s disclaimer in the same paragraph.
  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. The article does not call this a “stable release” and does not treat breaking changes as improbable.
  3. No release since 2026-03-31. The repository shipped 30 release tags between 2026-03-05 and 2026-03-31 — a release roughly every day for four weeks — and no further release tag in the 11 weeks between 2026-03-31 and 2026-06-18 (releases API, 2026-06-18). Commits are still landing (pushed_at: 2026-06-10), but the release pause is real and is not glossed as “active development” without the dates. The v1.0 march is real, but the article does not project a near-term v1.0 ETA.
  4. OAuth2 testing-mode scope limits. The README explicitly warns that 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 (README, 2026-06-18). The fix is gws auth login -s drive,gmail,sheets to pick scopes per service. The article does not describe the recommended preset as the recommended starting point for @gmail.com users — per-service scope pick is the real recommendation. First-run OAuth is the most common failure mode for any new user, and the article preserves the warning.
  5. Model Armor is opt-in, default warn. The Model Armor sanitization is off by default; the default GOOGLE_WORKSPACE_CLI_SANITIZE_MODE is warn, not block (README, 2026-06-18). The article does not describe gws as “automatically sanitizing agent responses.” In an agent context, set GOOGLE_WORKSPACE_CLI_SANITIZE_MODE=block explicitly; the warn default is fine for interactive use, but inadequate for an unattended agent loop.

Practical advice for builders

For Workspace power users replacing curl + REST docs. Install via npm install -g @googleworkspace/cli (the fastest path, roughly 60 seconds to first command) or brew install googleworkspace-cli on macOS (README, 2026-06-18). Start with gws --help and pick one of the 24 +helper commands to feel the speed — gws calendar +agenda --days 7 for the next seven days of meetings, gws gmail +unread --max 20 for the unread inbox, or gws drive +upload ./file.pdf to push a file to Drive without leaving the terminal. For a per-service scope pick during first-run auth, use gws auth login -s drive,gmail,sheets rather than the recommended preset.

For AI agent builders wiring Workspace into a Claude / Gemini / Codex / OpenCode agent. The npx skills add https://github.com/googleworkspace/cli path is the cleanest install for a per-agent tool list. For the Gemini CLI specifically, use gemini extensions install https://github.com/googleworkspace/cli (README, 2026-06-18). Always set GOOGLE_WORKSPACE_CLI_SANITIZE_MODE=block in agent contexts, not the default warn — the warn default is fine for interactive use but inadequate for an unattended agent loop, and the load-bearing differentiator of gws over a hand-rolled REST client is the prompt-injection sanitization that turns on with that env var. The first-run OAuth flow needs the per-service scope pick (gws auth login -s drive,gmail,sheets) — the recommended preset will fail for unverified apps and @gmail.com users (README, 2026-06-18).

For IT admins adding a Workspace CLI to a team toolbox. Pin to a specific release tag (v0.22.5 as of 2026-06-18) rather than main, because the README explicitly warns “Expect breaking changes as we march toward v1.0” (README, 2026-06-18; releases API, 2026-06-18). Use the headless CI auth flow with a service account, not a user account (GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/service-account.json), and run gws auth login --check as a CI step to fail fast on credential drift. Audit the Workspace scopes you grant — the recommended preset is an 85-scope kitchen sink, and granting it is rarely what IT actually wants. For an agent that reads from any Workspace service that may contain user-controlled content, require GOOGLE_WORKSPACE_CLI_SANITIZE_MODE=block in the deployment manifest.

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 first-party Gemini CLI extension, and an opt-in Model Armor integration that scans API responses for prompt injection before they reach the agent. The 27,134 stars, 1,426 forks, and 31,992 weekly npm downloads (week ending 2026-06-16) 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 “This is not an officially supported Google product” / “Expect breaking changes as we march toward v1.0” > NOTE blocks set the honest frame (releases API, 2026-06-18; README, 2026-06-18).

The Discovery Service hook is the genuine technical claim — when Google adds a Workspace API method, gws picks it up on the next invocation without a code change and without a release. The Model Armor integration is the under-reported angle — opt-in via --sanitize or env vars, defaulting to warn, but trivially flippable to block for unattended agent loops. The combination is the most credible “open-source Workspace CLI for AI agents” surface in the open-source ecosystem today. Not officially supported, not v1, and not released since March. But a real, daily-active, 32,000-downloads-per-week tool for the people who need it.