gws: a Rust CLI that builds its Google Workspace command surface at runtime

The problem gws solves: one binary instead of a REST client per API

Anyone automating Google Workspace usually ends up with a folder of scripts, each one hand-written against a different REST surface. Drive pagination works one way, Chat message creation another, and every new endpoint means reading the same Discovery documents again. gws collapses that into a single binary whose commands are generated from Google's Discovery Service at runtime, so the command surface follows the APIs rather than a checked-in list. The README puts it as reading Google's own Discovery Service and building the command surface dynamically, and adds that when Workspace gains an endpoint, gws picks it up automatically. The audience is narrow and clear: engineers who script Workspace operations, and people wiring those operations into an LLM agent. The README frames the second group directly by promising structured JSON on every response and 40+ agent skills. If you only ever touch one API, the abstraction buys you little.

How the dynamic command surface works

The repository is a Cargo workspace with two members, crates/google-workspace-cli and crates/google-workspace, so the API layer is separated from the CLI layer rather than living in one crate. The npm package @googleworkspace/cli is marked private and its version tracks the Rust releases, which tells you the npm artifact is a distribution wrapper for the prebuilt binary, not a JavaScript implementation. That matches the installation section, where npm is described as a convenience for downloading the appropriate binary from GitHub Releases. The practical consequence of runtime discovery is that gws schema is the real documentation. Instead of trusting a README table that may lag an API change, you ask the binary for the request and response shape of a specific method. The trade-off is that offline use and reproducibility depend on discovery data being reachable when the command runs, and the README does not describe a caching or pinning mechanism for that data.

Installing gws and running a first Drive query

The README recommends downloading the prebuilt binary for your OS and architecture from GitHub Releases, extracting it, and placing gws on your PATH. If you prefer a package manager, npm automates the download, and Homebrew is available on macOS and Linux. Building from source uses Cargo against the repository.

npm install -g @googleworkspace/cli

brew install googleworkspace-cli

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

A Nix flake is also published, runnable with nix run github:googleworkspace/cli. Node.js 18 or newer is a prerequisite only for the npm route. Before any API call works you need OAuth credentials from a Google Cloud project, and the quick start sequences three commands: gws auth setup, which walks through Cloud project configuration, then gws auth login, then a first call.

gws auth setup
gws auth login
gws drive files list --params '{"pageSize": 5}'

The README notes that gws auth setup requires the gcloud CLI. Without gcloud you configure the OAuth consent screen and a Desktop app client in the Cloud Console by hand, download the client JSON to ~/.config/gws/client_secret.json, and run gws auth login. The one step people skip is adding themselves as a test user on the consent screen, which the README flags as the cause of a generic Access blocked error. Once authenticated, a file listing returns JSON, and you can inspect any method's schema with gws schema drive.files.list.

Auth paths: desktop, headless CI, and pre-obtained tokens

The README's decision table is the clearest part of the documentation. If you have gcloud installed and authenticated, gws auth setup is the fastest route. If you have a Cloud project but no gcloud, use manual OAuth setup. If you already hold an OAuth access token, set GOOGLE_WORKSPACE_CLI_TOKEN, which the .env.example describes as highest priority and bypassing all credential loading. If you have existing credentials, point GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE at them. Service-account credentials are covered under a server-to-server heading. For CI, the documented flow is to authenticate interactively on a machine with a browser, then export with gws auth export --unmasked into a credentials file. That export step is the one to think hardest about: the flag name says the output is unmasked, so the resulting file is a live secret and belongs in whatever secret store your CI already uses. Locally, credentials are encrypted at rest with AES-256-GCM and the key lives in the OS keyring, or in ~/.config/gws/.encryption_key when GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND is set to file. That fallback is a deliberate downgrade for environments without a usable keyring, and it means the key sits next to the encrypted data.

The scope ceiling is the sharpest limitation

The README carries a warning that deserves more attention than the feature list. If your OAuth app is unverified and sits in testing mode, Google limits consent to roughly 25 scopes. The recommended scope preset includes 85+ scopes and will fail for unverified apps, particularly on @gmail.com accounts. The documented workaround is to filter the picker by service, for example gws auth login -s drive,gmail,sheets. This is not a bug in gws; it is how Google gates unverified clients, and the CLI surfaces it rather than hiding it. The consequence is that a broad, do-everything setup is effectively blocked until the OAuth app is verified, and a narrow per-service login is the realistic path for individual developers. Two other boundaries are stated in the README. The project is under active development and the README tells you to expect breaking changes on the way to v1.0, so pinning a version matters for anything scripted. And the README states directly that this is not an officially supported Google product, which changes who can be held to support expectations. The repository also has no push since 2026-03-31, so the release cadence you see in the changelog is the cadence you get.

gws compared with MCP servers and gam

Two comparisons come up often enough to be worth stating precisely. An MCP server exposes Workspace operations as tools over a protocol, and the client application decides when to call them; the model sees a tool schema and the server holds the connection. gws inverts that. It is a process you invoke, its output is JSON on stdout, and the agent skills shipped in the repository describe how to drive that process. The difference matters for debugging, because a gws invocation is a command you can rerun by hand and pipe into jq, while an MCP tool call is mediated by the host application. The trade-off runs the other way for long-lived sessions: a CLI process starts per call, whereas an MCP server can hold state. Against gam, a long-established Workspace administration tool, the split is scope and origin. gam is a fixed command set that someone maintains by hand; gws derives its commands from Discovery at runtime, so new endpoints appear without a release. gam's command names are stable and documented as a product surface, while gws command paths follow the API resource hierarchy, which you can confirm with gws schema. If you need a stable, memorized command vocabulary for admin tasks, that stability is a feature gws does not offer.

Model Armor, exit codes, and the operational surface

Beyond auth, the .env.example reveals a response-sanitization layer tied to Model Armor. GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE sets a default template, overridable per call with a --sanitize flag, and GOOGLE_WORKSPACE_CLI_SANITIZE_MODE selects warn (the default) or block. This is aimed squarely at the agent use case: an LLM reading message bodies or document text is a prompt-injection surface, and running responses through a sanitization template before they reach the model is a reasonable mitigation. The default of warn rather than block is a deliberate choice, and it means a pipeline that ignores warnings gets no protection at all. Two smaller environment variables round out the config surface: GOOGLE_WORKSPACE_CLI_CONFIG_DIR overrides the default ~/.config/gws location, and GOOGLE_WORKSPACE_PROJECT_ID supplies a project fallback for gmail watch and events subscribe, overridden by a --project flag. The README also documents exit codes as a section, and --dry-run lets you preview a request before sending it, which is worth using the first time you construct a Chat message or a spreadsheet creation payload.

Licence and the cost of tracking a moving command surface

The repository is Apache-2.0, and every Cargo.toml source file carries the standard Apache header. For most users that is unremarkable: you can use the binary and the source commercially, and the licence includes a patent grant. The npm package declares publishConfig.provenance, which means published artifacts carry a provenance attestation. Nothing in the licence restricts the agent skills or the CLI itself. The upgrade cost is the part to budget for. Because commands are generated from Discovery at runtime, a Workspace API change can alter your command surface without a gws release, and the README's warning about breaking changes before v1.0 covers the CLI's own flags. Pin a version for anything scheduled, and check gws schema output rather than assuming a flag still exists. The README does not document a rollback procedure for a bad upgrade, so keep the previous binary until the new one has run against your real workflows. This is not legal advice; if you redistribute gws inside a product, read the LICENSE file in the repository.

Editorial conclusion

Adopt gws if you already run scripts or agent workflows against several Workspace APIs and want one binary with consistent JSON output and a schema introspection command. Do not adopt it if you need an officially supported Google product (the README states plainly that it is not one), or if you cannot own a Google Cloud project with OAuth credentials, because every flow depends on one. Verify first that your OAuth app's verification status allows the scopes you need: the README warns the recommended preset has 85+ scopes and will fail on unverified apps, so run gws auth login -s drive,gmail,sheets and confirm the filtered picker completes before you wire the binary into anything automated.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes