googleworkspace / cli

gws 
**One CLI for all of Google Workspace — built for humans and AI agents.** 
Drive, Gmail, Calendar, and every Workspace API. Zero boilerplate. Structured JSON output. 40+ agent skills included.
> [!NOTE]
> This is **not** an officially supported Google product.
⬇️ **Download the latest release for your OS**
`gws` doesn't ship a static list of commands. It reads Google's own Discovery Service at runtime and builds its entire command surface dynamically. When Google Workspace adds an API endpoint or method, `gws` picks it up automatically.
> [!IMPORTANT]
> This project is under active development. Expect breaking changes as we march toward v1.0.
## Contents
- Prerequisites
- Installation
- Quick Start
- Why gws?
- Authentication
- AI Agent Skills
- Advanced Usage
- Environment Variables
- Exit Codes
- Architecture
- Troubleshooting
- Development
## Prerequisites
- **Node.js 18+** — for `npm install` (or download a pre-built binary from GitHub Releases)
- **A Google Cloud project** — required for OAuth credentials. You can create one via the Google Cloud Console or with the `gcloud` CLI or with the `gws auth setup` command.
- **A Google account** with access to Google Workspace
## Installation
The recommended way to install `gws` is to download the pre-built binary for your OS and architecture from the **GitHub Releases** page. Extract the archive and place the `gws` binary in your `$PATH`.
For convenience, you can also use `npm` to automate downloading the appropriate binary from GitHub Releases:
 [code] 
Or build from source:
 [code] 
A Nix flake is also available at `github:googleworkspace/cli`
 [code] 
On macOS and Linux, you can also install via Homebrew:
 [code] 
## Quick Start
 [code] 
## Why gws?
**For humans** — stop writing `curl` calls against REST docs. `gws` gives you `--help` on every resource, `--dry-run` to preview requests, and auto‑pagination.
**For AI agents** — every response is structured JSON. Pair it with the included agent skills and your LLM can manage Workspace without custom tooling.
 [code] 
## Authentication
The CLI supports multiple auth workflows so it works on your laptop, in CI, and on a server.
### Which setup should I use?
| I have… | Use |
|---|---|
| `gcloud` installed and authenticated | `gws auth setup` (fastest) |
| A GCP project but no `gcloud` | Manual OAuth setup |
| An existing OAuth access token | `GOOGLE_WORKSPACE_CLI_TOKEN` |
| Existing Credentials | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` |
### Interactive (local desktop)
Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring (or `~/.config/gws/.encryption_key` when `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file`).
 [code] 
> `gws auth setup` requires the `gcloud` CLI. If you don't have `gcloud`, use the manual setup below instead.
> [!WARNING]
> **Scope limits in testing mode:** If your OAuth app is unverified (testing mode),
> Google limits consent to ~25 scopes. The `recommended` scope preset includes 85+
> scopes and