Google Workspace CLI ‘gws’ auto-builds commands from live APIs

Google Workspace CLI (“gws”) is an Apache-2.0-licensed command-line tool that aims to make Google Workspace APIs feel less like a collection of REST docs and more like a cohesive interface—equally comfortable for shell scripts and AI agents. The project is explicitly not an officially supported Google product, but it has traction (about 10k stars) and is currently at v0.4.4 (released Mar 5, 2026), with a note that breaking changes are expected ahead of v1.0.

A CLI that builds itself from Google’s Discovery Service

The most distinctive design choice is that gws doesn’t ship a static list of commands. Instead, it reads Google’s Discovery Service at runtime, then constructs its command surface dynamically. The practical upshot is that when Workspace APIs add methods or resources, the CLI can pick them up without waiting for a hand-maintained command map.

Under the hood, gws describes a two-phase parsing approach: it identifies the target service first (for example, drive), fetches the service’s Discovery Document (cached for 24 hours), builds a clap::Command tree, and then re-parses the remaining arguments before authenticating and making the HTTP request. Across success paths and errors, the CLI emphasizes structured JSON output—including metadata for downloads.

Developer ergonomics: help, previews, pagination, and schema introspection

On the “human usability” side, gws focuses on reducing boilerplate and guesswork:

• --help is available on resources and methods.
• --dry-run previews requests before execution.
• Auto-pagination can be enabled; --page-all streams pages as NDJSON.
• Schema introspection is built in via commands like gws schema drive.files.list.

There are also some pragmatic notes from the docs, like handling bash history expansion in Sheets ranges by using single quotes when passing values containing !.

Installation options: npm first, with Cargo and Nix available

Installation is centered around npm:

• npm install -g @googleworkspace/cli

The repository notes that the npm package bundles pre-built native binaries per OS/architecture, so a Rust toolchain isn’t required. Pre-built binaries are also published on GitHub Releases. For source builds, cargo install --git [https://github.com/googleworkspace/cli](https://github.com/googleworkspace/cli) --locked is supported, and a Nix flake is available via github:googleworkspace/cli.

Authentication: multiple workflows, encrypted local storage, and CI-friendly export

gws supports several auth paths intended to cover local development, CI, and server environments:

• Interactive desktop: gws auth setup (requires the gcloud CLI) and gws auth login. Credentials are encrypted at rest (AES-256-GCM) with the key stored in the OS keyring.
• Manual OAuth: configure OAuth in the Cloud Console and save the client JSON to ~/.config/gws/client_secret.json, then run gws auth login.
• Headless / CI export flow: authenticate where a browser exists, then gws auth export --unmasked > credentials.json and set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE on the headless machine.
• Service accounts: point GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE at a service account key; optional domain-wide delegation via GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER.
• Pre-obtained access token: set GOOGLE_WORKSPACE_CLI_TOKEN (for example, from gcloud auth print-access-token).

The docs also spell out precedence rules (token first, then credentials file, then encrypted per-account credentials, then plaintext), along with multi-account support and overrides like --account and GOOGLE_WORKSPACE_CLI_ACCOUNT.

AI-assistance features: Skills, Gemini CLI extension, MCP server, and Model Armor sanitization

Beyond being a general-purpose Workspace CLI, the repository leans into agent workflows:

• The repo ships 100+ Agent Skills (SKILL.md files), plus a Skills Index. Skills can be added via npx skills add ..., including service-specific sets (Drive, Gmail).
• A Gemini CLI extension can be installed (gemini extensions install [https://github.com/googleworkspace/cli](https://github.com/googleworkspace/cli`)) after authenticating gws, allowing the agent to use gws commands while inheriting the CLI’s local credentials.
• gws mcp starts an MCP server over stdio. Services are exposed with -s (for example, drive,gmail,calendar), with optional --workflows and --helpers. The docs caution that each service can add roughly 10–80 tools, and that tool limits in clients often sit around 50–100.
• There’s also optional Model Armor response sanitization via a --sanitize flag or environment variables like GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE and GOOGLE_WORKSPACE_CLI_SANITIZE_MODE (warn or block).

Troubleshooting highlights: OAuth testing mode limits and common setup errors

A few issues get specific guidance:

• “Access blocked” / 403 during login typically means the OAuth app is in testing mode and the account isn’t listed as a test user.
• Unverified apps in testing mode have a ~25 scope consent limit; the repository notes that a recommended preset includes 85+ scopes and may fail, so service-specific scopes are encouraged.
• redirect_uri_mismatch is tied to OAuth clients not created as a Desktop app.
• For accessNotConfigured errors, gws reports the enable URL and suggests enabling the API and retrying.

Original source