<h1 align="center"gws</h1
One CLI for all of Google Workspace — built for humans and AI agents.<br 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.
<p <a href="https://www.npmjs.com/package/@googleworkspace/cli"<img src="https://img.shields.io/npm/v/@googleworkspace/cli" alt="npm version"</a <a href="https://github.com/googleworkspace/cli/blob/main/LICENSE"<img src="https://img.shields.io/github/license/googleworkspace/cli" alt="license"</a <a href="https://github.com/googleworkspace/cli/actions/workflows/ci.yml"<img src="https://img.shields.io/github/actions/workflow/status/googleworkspace/cli/ci.yml?branch=main&label=CI" alt="CI status"</a <a href="https://www.npmjs.com/package/@googleworkspace/cli"<img src="https://img.shields.io/npm/unpacked-size/@googleworkspace/cli" alt="install size"</a </p <br
⬇️ 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:
npm install -g @googleworkspace/cliOr build from source:
cargo install --git https://github.com/googleworkspace/cli --locked