gws for Google Workspace
A dynamic CLI for calling Google Workspace APIs with structured JSON output for scripts, operators, and AI-assisted workflows.
Per-dimension scores and reasoning
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.
- 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.
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.
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 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.
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.