gws: A Rust CLI That Builds Its Own Command Surface from Google's Discovery Service

What gws Solves and Who It Is For

Google Workspace exposes dozens of REST APIs, and each one has its own documentation, pagination rules, and auth requirements. The common workaround is writing curl commands with long URLs and hand-built JSON bodies. gws replaces that with a single CLI that generates commands for Drive, Gmail, Calendar, Sheets, Docs, Chat, and Admin. The README states it is built for humans and AI agents. For humans, it offers --help on every resource, --dry-run to preview requests, and auto-pagination. For AI agents, every response is structured JSON, and the project includes 40+ agent skills. This is not a thin wrapper around a static list of endpoints. The tool reads Google's Discovery Service at runtime, so when Google adds an API method, gws picks it up automatically. That design makes it suitable for teams that want to avoid maintaining generated bindings for each Workspace service.

Dynamic Command Generation from the Discovery Service

The core mechanism is runtime discovery. Instead of shipping a hardcoded command tree, gws fetches the Discovery Service and builds its command surface on the fly. The README says gws does not ship a static list of commands. This means the CLI can expose any method that Google publishes, including new ones added after a release. The trade-off is that the command surface is only as good as the Discovery Service metadata. If an API is not listed there, gws cannot know about it. The README gives an example of introspection: gws schema drive.files.list prints the request and response schema for that method. This is a direct way to inspect what the tool knows about an endpoint. The dynamic approach also means the CLI does not need a separate code generation step, but it does require network access to reach the Discovery Service at runtime. Offline usage is not described in the material.

Installation and First Commands

The recommended path is to download a pre-built binary from GitHub Releases and put it in your $PATH. There are several alternatives. You can install via npm with npm install -g @googleworkspace/cli, which the README says automates downloading the appropriate binary. You can build from source with cargo install --git https://github.com/googleworkspace/cli --locked. A Nix flake is available as nix run github:googleworkspace/cli, and Homebrew users can run brew install googleworkspace-cli. After installation, the quick start is gws auth setup, which walks through Google Cloud project configuration, then gws auth login for OAuth. The README warns that gws auth setup requires the gcloud CLI. If you do not have gcloud, you must use the manual OAuth setup in the Cloud Console. Once authenticated, commands follow a pattern: gws drive files list --params '{"pageSize": 5}' returns a JSON array. The --dry-run flag lets you preview a request without sending it, which is useful for checking the generated URL and body.

Authentication Modes and Their Constraints

The CLI supports several auth workflows. The interactive flow stores credentials encrypted at rest with AES-256-GCM, with the key in your OS keyring or in ~/.config/gws/.encryption_key when you set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file. For CI or headless use, you can export credentials after an interactive login with gws auth export --unmasked > credentials.json. There is also a service account flow via GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE, and a pre-obtained access token via GOOGLE_WORKSPACE_CLI_TOKEN. The most important constraint is the scope limit in testing mode. If your OAuth app is unverified, Google limits consent to about 25 scopes. The recommended scope preset includes 85+ scopes and will fail, especially for @gmail.com accounts. The README suggests choosing individual services with gws auth login -s drive,gmail,sheets to filter the scope picker. This is a practical limitation that affects anyone who has not completed Google's app verification process.

Structured Output and Pagination for Agents

A key feature for AI agents is that every response is structured JSON. The README shows a pagination pattern: gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name' streams paginated results as NDJSON. This is useful for agents that need to process large result sets without writing custom pagination logic. The --page-all flag is a concrete mechanism that the CLI provides, and it pairs well with jq for filtering. The README also mentions that the CLI includes 40+ agent skills, which are presumably pre-built prompts or functions that let an LLM call Workspace APIs without custom tooling. The material does not specify what those skills look like or how they are loaded, so that part remains vague. Still, the combination of structured JSON and pagination flags makes the tool a plausible building block for agent workflows that need to read or modify Workspace data.

Limitations and Failure Modes

The most obvious limitation is the project's pre-1.0 status. The README states it is under active development and breaking changes are expected. That means scripts written against one version may stop working after an update. Another failure mode is the scope limit for unverified OAuth apps, which can block the recommended auth path entirely. The README explicitly says the recommended scope preset will fail for unverified apps, especially for @gmail.com accounts. A third limitation is the dependency on the Discovery Service. If a method is not exposed there, gws cannot generate a command for it. Also, the tool requires network access to reach the Discovery Service and the Workspace APIs, so it is not suitable for fully offline environments. Finally, the README notes that gws is not an officially supported Google product, so there is no vendor SLA or support channel. The dynamic command surface also means that the help text and schemas can change between releases, which complicates documentation and training.

Comparing with a Static API Client Approach

A real alternative is using a language-specific client library, such as Google's official Python or Node.js client libraries, which are generated from the same Discovery Service but are compiled into a static API surface at release time. The difference is that those libraries ship a fixed set of methods and types, so you must update the library to get new endpoints. gws, by contrast, fetches the Discovery Service at runtime and can expose new methods without a CLI update. The trade-off is that a static library gives you compile-time type checking and a stable API, which matters for large codebases. gws gives you flexibility and a uniform command-line interface, but you lose type safety and you depend on the runtime metadata. If you are building a production application that calls Workspace APIs, a static client library is likely more reliable. If you are scripting ad-hoc tasks or building an agent that needs to discover capabilities on the fly, gws is a better fit.

Maintenance, Upgrades, and License

The project is licensed under Apache-2.0, which permits commercial use, modification, and distribution with attribution. The repository shows active development with releases in March 2026, including v0.22.5. The README warns of breaking changes before v1.0, so you should pin a specific version in your scripts or CI to avoid surprises. The npm package @googleworkspace/cli can be version-pinned, and the binary releases are tagged. There is no mention of a migration guide or a changelog in the provided material, so you should inspect release notes before upgrading. The maintenance cost is moderate: because the command surface is dynamic, you may need to re-test your automation after each release, especially if you rely on specific flags or output shapes. The project is not officially supported by Google, so you cannot expect a support contract. The Nix flake and Homebrew formula indicate a community-driven packaging effort, but the primary distribution channel is GitHub Releases.

Editorial conclusion

Adopt gws if you regularly script Google Workspace APIs and want a command surface that tracks the Discovery Service without manual updates, or if you build AI agents that need structured JSON output. Do not adopt it if you require a stable, versioned CLI before v1.0, since breaking changes are expected. Before relying on it, verify that the auth flow works with your OAuth app's verification status, because the recommended scope preset fails for unverified apps. Also confirm that the specific API methods you need are present in the Discovery Service, since gws cannot expose anything that Google does not list.

Official sources

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