gws is a command-line tool that exposes Google Workspace APIs — Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and the rest — through one binary. It does not ship a static command list: at runtime it reads Google's Discovery Service and builds its command surface from it, so new endpoints and methods become available without a release. It is a community project rather than an officially supported Google product.
Every command returns structured JSON, which makes the tool usable by AI agents as well as people. For agents, the project ships more than 100 Agent Skills (SKILL.md files), one per supported API plus higher-level workflow helpers and 50 recipes for Gmail, Drive, Docs, Calendar, and Sheets; these install with npx skills add, symlink into OpenClaw, or load as a Gemini CLI extension. For humans, every resource has --help, --dry-run previews a request, and --page-all streams paginated results as NDJSON.
Authentication covers laptops, CI, and servers: an interactive OAuth flow that can create the Cloud project for you via gcloud, manual OAuth client setup, an export flow for headless machines, service-account credentials, or a pre-obtained access token. Interactive credentials are encrypted at rest with AES-256-GCM and the key stored in the OS keyring.
Beyond the generated Discovery surface, some services carry hand-written helper commands prefixed with +, such as gmail +send, gmail +triage, calendar +agenda, workflow +standup-report, and events +subscribe. Time-aware helpers use the Google account's timezone from the Calendar settings API.
Features
- Discovery-driven commands: the full Workspace API surface is generated at runtime from Google's Discovery Service
- Structured output: JSON for every response, with NDJSON streaming for auto-paginated results
- Agent skills: 100+ SKILL.md files plus 50 recipes, installable with npx skills add, OpenClaw, or the Gemini CLI extension
- Multiple auth modes: interactive OAuth, manual client setup, headless credential export, service accounts, and access tokens with a defined precedence order
- Encrypted credentials: AES-256-GCM at rest with the key in the OS keyring or a file backend
- Schema introspection: gws schema prints any method's request and response schema
- Dry run: --dry-run shows the HTTP request without sending it
- Helper commands: +-prefixed shortcuts for sending mail, replying, appending sheet rows, uploading files, creating events, and streaming Workspace events
- Workflow helpers: standup reports, meeting prep, email-to-task, weekly digests, and file announcements to Chat
- Model Armor helpers: sanitize prompts and responses through a Model Armor template
- Multipart uploads: --upload attaches a file to a Drive create call
