gws

gws is a command-line client for Google Workspace APIs, including Drive, Gmail, Calendar, Sheets, Docs, and Chat. It does not ship a static command list. At runtime it reads Google's Discovery Service and builds its command surface from that, so new API endpoints and methods appear without a CLI update. Commands follow the API structure, for example gws drive files list --params '{"pageSize": 5}' or gws sheets spreadsheets create --json '{...}'. Every response is structured JSON.

For direct use, it offers --help on every resource, --dry-run to preview requests, and gws schema drive.files.list to inspect a method's request and response schema. It also supports auto-pagination (--page-all streams NDJSON, with --page-limit and --page-delay) and multipart uploads via --upload. Some services have hand-written helper commands prefixed with +, such as gws gmail +send, +reply, +triage, +watch, gws calendar +agenda, and gws drive +upload. Time-aware helpers use the Google account timezone.

Authentication covers several cases. gws auth setup (requires gcloud) creates a Cloud project and enables APIs, and gws auth login handles OAuth with scope selection. Manual OAuth client setup is also supported. Credentials are encrypted at rest with AES-256-GCM, with the key stored in the OS keyring. For headless or CI use, you can export credentials with gws auth export, point GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE at a service account key, or pass an existing token through GOOGLE_WORKSPACE_CLI_TOKEN.

The repo includes 100+ agent skills (SKILL.md files), one per supported API plus workflow helpers and recipes. They install with npx skills add https://github.com/googleworkspace/cli. There are also OpenClaw setup instructions and a Gemini CLI extension. It targets developers, administrators, and AI-agent builders who want scriptable Workspace access without writing raw REST calls. It is not an officially supported Google product and is under active development, with breaking changes expected before v1.0.

Installation

# via Homebrew
brew install googleworkspace-cli

# via npm
npm install -g @googleworkspace/cli

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