gws for Google Workspace
A dynamic CLI for calling Google Workspace APIs with structured JSON output for scripts, operators, and AI-assisted workflows.
- Source repo
- googleworkspace/cli
- Stars
- ★ 32k
- Last updated
- 3d ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 54/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specific
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An operations engineer who needs to list recent Drive files, upload a report, or inspect Workspace API data from a terminal.
- Not a fit if
- Teams not on Google Workspace or without a Google Cloud project
- Users needing API stability before v1.0 breaking changes
- Those without gcloud who won't manually configure OAuth clients
- Source review
- 54/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
gws is a Google Workspace command-line tool for humans and AI agents, covering Drive, Gmail, Calendar, Sheets, Docs, Chat, and additional Workspace APIs. Instead of shipping a fixed command catalog, it reads Google Discovery Service documents at runtime and constructs the command surface for the selected service. Commands return structured JSON; paginated requests can emit NDJSON for downstream processing. The repository also includes more than 100 SKILL.md Agent Skills, workflow recipes, and a documented Gemini CLI extension path. It runs as a local CLI rather than a hosted service, and access to Workspace data requires configured Google Cloud credentials. The project is under active development and documents expected breaking changes before v1.0.
Authentication is configured through gws auth setup, gws auth login, GOOGLE_WORKSPACE_CLI_TOKEN, or GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE. For a command such as gws drive files list --params '{"pageSize": 5}', gws identifies the service from argv[1], fetches and caches its Discovery Document, builds a clap::Command tree from that document, and re-parses the remaining arguments. It then authenticates, builds and executes the HTTP request, and produces JSON for results, errors, and download metadata; --page-all emits one NDJSON line per page. In addition to Discovery-generated methods, it offers + helper commands including gmail +send, drive +upload, calendar +agenda, workflow +standup-report, and events +subscribe. API responses can be scanned through a Google Cloud Model Armor template with --sanitize.
- An operations engineer who needs to list recent Drive files, upload a report, or inspect Workspace API data from a terminal.
- A script author automating Gmail, Calendar, Sheets, Docs, or Chat through JSON inputs and outputs.
- A team using the documented Gemini CLI extension to give an authenticated terminal agent access to gws commands and repository skills.
- A Google Workspace user who wants calendar +agenda, workflow +meeting-prep, or +weekly-digest for daily planning.
- An engineering team that needs to export credentials and invoke Workspace APIs from CI or a headless server.
- A developer who wants Model Armor screening before an agent consumes Gmail or other API responses.
How do you install or deploy this agent?
You need a Google account with Google Workspace access and a Google Cloud project. The recommended installation is to download the matching pre-built binary from GitHub Releases and put gws on PATH. Alternatives are npm install -g @googleworkspace/cli, which requires Node.js 18+, cargo install --git https://github.com/googleworkspace/cli --locked, nix run github:googleworkspace/cli, or brew install googleworkspace-cli on macOS or Linux. For local interactive setup, run gws auth setup and then gws auth login. Without gcloud, create a Desktop app OAuth client in Google Cloud Console, save its JSON as ~/.config/gws/client_secret.json, and run gws auth login.
How do you use this agent?
After authentication, run: gws drive files list --params '{"pageSize": 5}'. To create a spreadsheet, run: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'. Inspect a method schema with gws schema drive.files.list, or stream paginated results as NDJSON with gws drive files list --params '{"pageSize": 100}' --page-all. For headless use, authenticate on a machine with a browser, run gws auth export --unmasked > credentials.json, then set export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json on the target machine.
What are this agent's strengths and limitations?
- Its command surface is built from Google Discovery Service documents at runtime, so newly added Workspace endpoints or methods can be picked up automatically.
- Successes, errors, and download metadata are structured JSON, with NDJSON pagination available through --page-all.
- It combines Discovery methods with clearly distinguished + helpers for email, file uploads, calendar summaries, and cross-service workflows.
- Documented authentication paths cover interactive OAuth, credential files, service accounts, and pre-obtained access tokens for desktop, CI, and server contexts.
- The repository includes more than 100 Agent Skills and a documented Gemini CLI extension installation path.
- Its core use is tied to Google Workspace, a Google Cloud project, and Google OAuth or service-account credentials; it is not a general-purpose SaaS CLI.
- Unverified OAuth apps in testing mode are limited to roughly 25 scopes, while the recommended preset includes 85+ scopes and can fail.
- gws auth setup requires gcloud; without it, adopters must manually configure a Desktop app OAuth client and test users in Google Cloud Console.
- The project is actively developed and explicitly warns that breaking changes are expected before v1.0.
- Runtime operation depends on fetching Discovery Documents; a failure to fetch one produces exit code 4.
How does this agent compare with similar options?
Compared with writing curl calls from REST documentation, gws provides Discovery-generated commands, built-in help, --dry-run, automatic pagination, and structured JSON output.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| gws for Google Workspace This agent | 54 · Major gaps | CLIFree | ★ 32k | 3d ago | Rust | — |
| ENZO Self-Hosted AI Workspace | 68 · Some gaps | Self-hosted serviceFree + model costs | ★ 117 | today | TypeScript | — |
| Zapier MCP Plugin | 41 · Major gaps | Agent plugin / skill | ★ 452 | 14d ago | — | Codex · Claude Code |
| Iva Personal Assistant | 85 · Good | Chat botFree + model costs | ★ 285 | 3d ago | TypeScript | ChatGPT · Codex |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README describes OAuth flow, credential encryption (AES-256-GCM), scope selection, --dry-run preview, environment variable precedence, security reporting channel (SECURITY.md), and dependency audit workflow (audit.yml). Deductions: no code-level verification, least privilege not explicit, user confirmation only via OAuth consent and --dry-run, data flow transparency limited, no rollback mechanism mentioned, publisher identity unverified.
Evidence shows: README provides exit codes, troubleshooting, structured JSON output, clear architecture description. Deductions: no test results or execution verification, dependency availability only implied by CI workflow, failure messages only partially exemplified.
Evidence shows: README targets humans and AI agents, provides multiple installation methods, environment variables, use cases (e.g., CI, headless). Deductions: capability boundaries not explicitly listed, trigger precision relies on dynamic discovery, environment fit not covering all platforms.
Evidence shows: README is well-structured, provides installation notes, examples, troubleshooting, license (Apache-2.0), version (0.22.5). Deductions: naming stability not guaranteed (pre-release), changelog not provided, maintenance responsibility unclear (publisher unverified).
Evidence shows: README emphasizes structured JSON output, auto-pagination, dynamic command surface, multiple installation methods. Deductions: no performance benchmarks or cost analysis, marginal value based on assertions.
Evidence shows: README claims dynamic construction, AI skills, etc., but no traceable tests or independent verification. Deductions: claims vs evidence separation unclear, cross-source corroboration limited.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Publisher identity unverified; exercise caution regarding supply chain risks.
- Project is pre-release; breaking changes expected.
- Dynamic command surface may introduce unexpected behavior; test in isolated environment.
- Credential handling is encrypted, but ensure key management security.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Installation Download the archive for your OS and architecture from the assets below. Linux / macOS Replace <target> with your platform (e.g., aarch64-apple-darwin or x86_64-unknown-linux-gnu). ```bash 1. Download the archive and its checksum curl -sLO https://github.com/googleworkspace/cli/releases/download/v0.22.5/google-workspace-cli-<target>.tar.gz curl -sLO https://github.com/googleworkspace/cli/releases/download/v0.22.5/google-workspace-cli-<target>.tar.gz.sha256 2. Verify the checksum shasum -a 256 -c google-workspace-cli-<target>.tar.gz.sha256 …View on GitHub ↗ -
Release notes excerpt
What's Changed * chore: remove cargo-dist, use native fetch for npm installer by @jpoehnelt in https://github.com/googleworkspace/cli/pull/646 * chore: release versions by @googleworkspace-bot in https://github.com/googleworkspace/cli/pull/647 Full Changelog: https://github.com/googleworkspace/cli/compare/v0.22.3...v0.22.4View on GitHub ↗ -
v0.22.3 0.22.3
Release notes excerpt
Release Notes Patch Changes - 674d53a: Fix Lint Skills CI job by installing uv via astral-sh/setup-uv before running uvx - c7c42f6: fix: register script service and resolve test path validation errors - 80bd150: feat(auth): use strict OS keychain integration on macOS and Windows Closes #623. The CLI no longer writes a fallback .encryption_key text file on macOS and Windows when securely storing credentials. Instead, it strictly uses the native OS keychain (Keychain Access on macOS, Credential Manager on Windows). If an old .encryption_key file is found during a successf …View on GitHub ↗