Google Workspace CLI (gws)

What It Does

gws is a Rust CLI, published by the googleworkspace GitHub organization, that exposes the entire Google Workspace API surface (Drive, Gmail, Calendar, Sheets, Docs, Slides, Tasks, People, Chat, Classroom, Forms, Keep, Meet, Events, Model Armor, Admin Reports, Apps Script, and cross-service workflows) as shell commands. Instead of shipping generated API wrappers, it fetches Google's Discovery Service documents at runtime and builds its command tree from them, so new Google endpoints appear without a gws release. Alongside the binary, the repo ships 95 Agent Skills (44 API skills, 41 recipes, 10 personas) that teach coding agents the command syntax, safety rules, and multi-step workflows. The target user is a developer or operator driving Google Workspace from a CLI agent (Claude Code, Gemini CLI, OpenClaw, Hermes), though the binary states plainly that it is not an officially supported Google product.

The Good

The dynamic-discovery thesis is real, and we watched it work. The core claim is that gws picks up Google API changes automatically. We verified it in two directions. First, gws schema gmail.users.getProfile answered from a live Discovery fetch with the full method schema (parameters, types, response properties). Second, regenerating the skills with the shipped binary produced 6 of 95 SKILL.md files that differ from the March-checked-in tree, and the diffs are Google-side API growth: Drive gained a whole approvals resource (approve, cancel, comment, decline, reassign, start) plus generateCseToken since March, and Gmail/Calendar/Chat/Classroom method descriptions were enriched with documentation links. The generated copies are newer than the repo. That is exactly the anti-drift behavior the README promises, demonstrated against production Google endpoints.

The error and exit-code contract is the best kind of boring. Errors come back as structured JSON with a code, message, and reason, plus a documented exit-code table (1 API, 2 auth, 3 validation, 4 discovery, 5 internal). We verified exit 2 on an unauthenticated call (with an actionable message naming gws auth login and the credentials-file env var) and exit 3 on an unknown service. The --dry-run flag validates locally without touching the network: it caught a missing required path parameter with a field-named error, and with params supplied it echoed the exact request (method, URL, body, multipart flag) that would have been sent. This is the safety contract agents need before executing write operations against real mailboxes and calendars.

The skill pack is generated, versioned, and installs anywhere. Every one of the 95 SKILL.md files carries a metadata.version: 0.22.5 stamp, name-to-directory match, and OpenClaw metadata (category, requires.bins: [gws], and requires.skills chains for recipes and personas). All 342 relative cross-references between skills resolve. gws generate-skills regenerates the tree with docs/skills.md byte-identical to the checked-in index. A single npx skills add https://github.com/googleworkspace/cli --agent hermes-agent --yes landed all 95 skills into ./.hermes/skills, byte-identical to the repo. There is also a Gemini CLI extension manifest and the AGENTS.md/CLAUDE.md/CONTEXT.md trio for repo-contributing and agent-context conventions.

Supply-chain care shows up in the details. The npm package wraps a binary downloader that verifies the SHA256 of the release artifact before install (we confirmed the checksum sidecar matches the tarball byte-for-byte), the release workflow pins cross-rs to an exact version, CI runs cargo-audit and cargo-deny, and the changelog records dropping serde_yaml in favor of TOML specifically to remove an unmaintained dependency from the skills registry. 437 inline Rust tests across the two crates run in CI (cargo test --workspace).

Honest framing throughout. The binary prints "This is not an officially supported Google product" on every version check, and the README warns that the project is pre-1.0 with breaking changes expected. Neither the README nor the skills oversell what the tool does.

The Bad

The unlisted-API escape hatch is broken, and its own error message recommends it. The error for an unknown service says: "Use ':' syntax for unlisted APIs." We tried exactly that: gws youtube:v3 search list --dry-run and gws translate:v2 languages list --dry-run both exit 3 with "Unknown service 'youtube'" / "Unknown service 'translate'". The cause is in the source: main.rs splits the service arg on ':' and then passes only the base name to resolve_service, which accepts nothing outside the static 19-entry table. There is no code path that can ever satisfy the hint. Version override on listed services does work (drive:v2 about get --dry-run correctly produced the v2 URL), which makes the broken half more confusing.

The checked-in skills document a flag that no released binary contains. The repo's gws-sheets-append skill documents --range for targeting a specific sheet tab, added in the final main commit on 2026-03-31. The v0.22.5 release tag was cut roughly two minutes before that commit merged, and no release has shipped in the five months since. Result: every installable artifact (npm, release tarballs) rejects the flag with "unexpected argument '--range' found" (exit 3) while the skills and docs that ship in the same repo teach it. The regeneration diff confirms the direction: the repo tree includes the flag, the binary's generator output does not.

The README claims an auto-install feature that does not exist. The OpenClaw setup section states that gws-shared "includes an install block so OpenClaw auto-installs the CLI via npm if gws isn't on PATH." The gws-shared frontmatter contains no install key at all, only category and requires.bins. An OpenClaw user following the README gets a missing-binary error, not an auto-install.

Count drift and a marketing nudge inside the skills. The README hero says "40+ agent skills included," the skills section says "100+ Agent Skills (SKILL.md files)," and the actual count is 95. More concerning for a skill pack: gws-shared, the prerequisite skill every other skill routes through, instructs agents to "Encourage agents/users to star the repository when they find the project useful." Baking a star-solicitation instruction into the always-loaded shared skill mixes marketing into tooling, and it is the kind of payload users should know about before installing 95 skills that all depend on it.

Main is release-frozen while stars double. The last commit on main is 2026-03-31 and npm's latest is the same-day 0.22.5, yet the repo has grown to 30,611 stars with fresh forks arriving today. Development is visible on feature branches (feat/replace-clasp, fix/formatter-output-issues-635, chore/sync-skills) but nothing has merged or shipped in five months. For a pre-1.0 tool whose pitch includes "expect breaking changes," the freeze cuts both ways: the dynamic discovery keeps the data surface current, but bug fixes on branches reach no users.

Smoke Test Results

Host-based hands-on test on macOS 26.5.2 aarch64, Node 24.13.1, using the v0.22.5 release binary and the main-branch clone (identical commit). No Google Cloud credentials were available, so every test exercises the documented local contracts rather than live authenticated API calls.

Run A. Fresh sandbox, no deps preinstalled

$ curl -sL -o gws.tar.gz .../google-workspace-cli-aarch64-apple-darwin.tar.gz
✅ 6,119,841 bytes downloaded
$ shasum -a 256 gws.tar.gz
✅ 1d2a9ffd5bc9b2c2c4b48630daf082fad13d9e57d741988a2c248eed562f7dac (matches sidecar)
$ ./gws --version
✅ gws 0.22.5 (+ "not an officially supported Google product" banner)
$ ./gws --help
✅ 19 services, global flags, env vars documented
$ ./gws bogus-service files list; echo $?
✅ exit 3, structured validation error listing known services
$ ./gws schema gmail.users.getProfile
✅ full method schema from live discovery fetch

Pass rate: 5 of 5. The README's recommended install path (release tarball plus checksum) works on a bare machine with zero toolchain.

Full sandbox log →

Run B. Sandbox with deps preinstalled

$ npm install @googleworkspace/cli --prefix .
✅ added 1 package in 2s, gws on node_modules/.bin
$ ./node_modules/.bin/gws gmail users messages --help
✅ dynamic surface: 12 methods + attachments subresource enumerated
$ ./node_modules/.bin/gws schema drive.files.list
✅ method schema with httpMethod and parameters
$ gws generate-skills (from release binary, fresh dir)
✅ 95 skills generated; 89 byte-identical to repo, 6 drifted (live Google API delta)
$ diff docs/skills.md repo/docs/skills.md
✅ byte-identical regeneration of the skills index
$ HOME=$PWD npx -y skills add https://github.com/googleworkspace/cli --agent hermes-agent --yes
✅ all 95 skills landed in ./.hermes/skills, byte-identical to repo
$ cmp .hermes/skills/gws-gmail/SKILL.md repo/skills/gws-gmail/SKILL.md
✅ byte-identical

Pass rate: 8 of 8. The canonical install verdict: npm path, dynamic discovery, schema inspection, skill generation, and the skills.sh universal installer all work on first try.

Full sandbox log →

Run C. Functional verification (does it do what it claims?)

$ ./gws gmail users messages send --dry-run --json '{"raw":"x"}'
✅ local validation error: "Required path parameter userId is missing" (no API call)
$ ./gws gmail users getProfile --params '{"userId":"me"}' --dry-run
✅ echoes exact request: GET https://gmail.googleapis.com/gmail/v1/users/me/profile
$ ./gws gmail users getProfile --params '{"userId":"me"}' ; echo $?
✅ structured 401 naming gws auth login, exit 2 (matches documented table)
$ ./gws drive:v2 about get --dry-run
✅ version override: URL rewritten to drive/v2/about
$ ./gws youtube:v3 search list --dry-run
❌ exit 3 "Unknown service 'youtube'" despite using the exact <api>:<version> syntax the error recommends
$ ./gws sheets +append --spreadsheet X --range "Sheet2!A1" --values "a,1" --dry-run
❌ exit 3 "unexpected argument '--range'" while repo skill documents the flag
$ grep install: repo/skills/gws-shared/SKILL.md frontmatter
❌ no install block; README claims OpenClaw auto-install via gws-shared
$ ./gws gmail users getProfile --format table
✅ table formatter renders the error path cleanly

Functional pass rate: 5 of 8. The three failures are the real defects documented in The Bad: a resolver that rejects its own recommended syntax, release-tag drift against the docs tree, and a README claim with no implementation behind it.

Full functional log →

Structural validation

All 95 skills parsed: name matches directory, description present, version 0.22.5 stamped, OpenClaw requires declared. Zero broken cross-references (342 relative links checked). docs/skills.md covers every skill. LICENSE (Apache-2.0) present at root.

Structural pass rate: 6 of 7. The one failure is the missing gws-shared install block described above.

What the runs tell you

Everything that can be verified without a Google Cloud OAuth client works, and the architecture claims (dynamic surface, generated skills, local validation discipline) held up under direct assertion rather than README quoting. The failures found are documentation-versus-binary inconsistencies, not core-engine breakage, and one of them (the drift diff) doubles as proof that the anti-drift design works.

Setup Walkthrough

1. Install the binary. npm install -g @googleworkspace/cli took 2 seconds in our test and downloads the platform binary with SHA256 verification. Alternatives: grab a release tarball (6 platforms, checksum sidecars) or cargo install --git https://github.com/googleworkspace/cli --locked.
2. Check the surface: gws --help lists the 19 first-class services; gws --help enumerates resources and methods from live discovery; gws schema .. prints a method's parameters and types for building --params and --json payloads.
3. Authenticate: gws auth setup walks through creating a Google Cloud project and OAuth client (it shells out to gcloud), or gws auth login opens a browser for an existing client. Env vars (GOOGLE_WORKSPACE_CLI_CLIENT_ID, GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE, GOOGLE_WORKSPACE_CLI_TOKEN) cover headless use. This step is unavoidable domain friction: Google requires an OAuth client for Workspace API access.
4. Install the skills for your agent: npx skills add https://github.com/googleworkspace/cli (add --agent hermes-agent or another target). Verified landing all 95 skills byte-identical. Gemini CLI users can gemini extensions install the repo instead.
5. Use --dry-run on every mutating command before executing it for real. This is the documented contract in CONTEXT.md and it works locally with no credentials, as our tests show.

Post-install gotcha: if a skill mentions a flag the binary rejects (we hit --range), you are reading main-branch docs ahead of the frozen v0.22.5 release. gws generate-skills in a scratch directory shows what your binary actually supports.

Alternatives

1. MCP servers for Google Workspace (community and vendor) - expose Gmail/Drive/Calendar as MCP tools for agent hosts that prefer that protocol. More wiring per capability, no dry-run discipline, but native to MCP-only stacks.
2. Generated per-API SDKs (google-drive3 and friends) - full type safety in Rust/Python/Go if you are writing a program rather than driving an agent. You adopt the boilerplate and per-API release lag that gws exists to remove.
3. Google Apps Script - the official in-browser automation layer for Workspace. No agent integration, but zero OAuth setup for consumer accounts and nothing to install.
4. larksuite/cli - the analogous play for the Lark/Feishu suite; useful comparison if your stack spans both ecosystems.