# gws

> Command-line tool for Google Workspace APIs (Drive, Gmail, Calendar, Sheets, Chat) with commands built at runtime from Google's Discovery Service. JSON output.

Stars: 32.0k · Language: Rust · License: Apache-2.0 · Categories: Productivity

- Repository: https://github.com/googleworkspace/cli
- Website: https://developers.google.com/workspace
- Page: https://www.trmn.sh/tools/gws

## Install

- Homebrew: `brew install googleworkspace-cli`
- npm: `npm install -g @googleworkspace/cli`
- Cargo: `cargo install --git https://github.com/googleworkspace/cli --locked`

## Overview

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

```bash
# via Homebrew
brew install googleworkspace-cli
```

```bash
# via npm
npm install -g @googleworkspace/cli
```

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

## Alternatives

- [navi](https://www.trmn.sh/tools/navi.md): Interactive cheatsheet tool that helps you browse, search, and execute CLI commands with dynamic argument suggestions (Rust, 17.8k stars)
- [presenterm](https://www.trmn.sh/tools/presenterm.md): Terminal slideshow tool that runs markdown files as presentations, with images, themes, code highlighting and execution, and PDF/HTML export. (Rust, 8.9k stars)
- [Himalaya](https://www.trmn.sh/tools/himalaya.md): Rust CLI for managing email across IMAP, SMTP, JMAP, Gmail, Microsoft Graph and Maildir backends, with multi-account TOML config and JSON output. (Rust, 7.5k stars)
- [ncspot](https://www.trmn.sh/tools/ncspot.md): Cross-platform ncurses Spotify client written in Rust on librespot, with Vim keybindings and an IPC socket for remote control. Requires Spotify Premium. (Rust, 6.8k stars)
- [pueue](https://www.trmn.sh/tools/pueue.md): Command-line task management tool for sequential and parallel execution of long-running shell commands (Rust, 6.4k stars)

---

Canonical: https://www.trmn.sh/tools/gws