/google-workspace-cli

name: google-workspace-cli
description: Interact with all Google Workspace APIs via the gws CLI. Use when managing Drive files, sending/reading Gmail, creating Calendar events, reading/writing Sheets/Docs/Slides, managing Chat spaces, contacts, Admin users/groups, Vault eDiscovery, Classroom, Apps Script, Workspace Events, or configuring the gws MCP server. Triggers on Google Workspace, gws, Drive, Gmail, Calendar, Sheets, Docs, Slides, Chat, Tasks, Meet, Forms, Keep, Admin, People, Vault, Classroom, Apps Script, Cloud Identity, Alert Center, Groups Settings, Licensing, Reseller, Model Armor, gws CLI, gws mcp, Google API, Workspace automation, npx skills add.

Google Workspace CLI (`gws`)

One CLI for **all** of Google Workspace — Drive, Gmail, Calendar, Sheets, Docs, Slides, Chat, Tasks, Admin, Meet, Forms, Keep, and every other Workspace API. Built for humans and AI agents. Structured JSON output. 100+ agent skills included.

> **Note:** This is not an officially supported Google product.

> **Important:** This project is under active development. Expect breaking changes as we march toward v1.0.

**Repository:** https://github.com/googleworkspace/cli

How It Works

`gws` does NOT ship a static list of commands. It reads Google's own [Discovery Service](https://developers.google.com/discovery) at runtime and builds its entire command surface dynamically. When Google adds a new API endpoint or method, `gws` picks it up automatically — zero updates needed.

Prerequisites

• **Node.js 18+** — for `npm install` (or download a pre-built binary from [GitHub Releases](https://github.com/googleworkspace/cli/releases))
• **A Google Cloud project** — required for OAuth credentials. You can create one via the [Google Cloud Console](https://console.cloud.google.com/), with the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install), or with the `gws auth setup` command.
• **A Google account** with access to Google Workspace

Installation

# Install globally via npm (recommended — bundles native binaries, no Rust needed)
npm install -g @googleworkspace/cli

# Verify installation
gws --version

Alternative installation methods:

# From GitHub Releases (pre-built binaries)
# Download from: https://github.com/googleworkspace/cli/releases

# Build from source (requires Rust toolchain)
cargo install --git https://github.com/googleworkspace/cli --locked

# Nix flake
nix run github:googleworkspace/cli

Quick Start

gws auth setup     # walks you through Google Cloud project config
gws auth login     # subsequent OAuth login
gws drive files list --params '{"pageSize": 5}'

Authentication

Which setup should I use?

| I have… | Use | |:--------|:----| | `gcloud` installed and authenticated | `gws auth setup` (fastest — one command) | | A GCP project but no `gcloud` | Manual OAuth setup in Cloud Console | | An existing OAuth access token | `GOOGLE_WORKSPACE_CLI_TOKEN` env var | | Existing credentials JSON (service account or exported) | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` env var |

Quick Setup (recommended — requires gcloud CLI)

gws auth setup       # one-time: creates a Cloud project, enables APIs, logs you in
gws auth login       # subsequent logins with scope selection

> Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring.

Scoped Login (for unverified/testing OAuth apps, limited to ~25 scopes)

> **Warning:** Unverified (testing-mode) apps are limited to ~25 OAuth scopes. The `recommended` scope preset includes 85+ scopes and **will fail** for unverified apps (especially for `@gmail.com` accounts). Choose individual services instead:

# Select only the services you need to stay under the scope limit
gws auth login -s drive,gmail,sheets
gws auth login --scopes drive,gmail,calendar,docs,chat

Multiple Accounts

gws auth login --account work@corp.com
gws auth login --account personal@gmail.com

gws auth list                                    # list registered accounts
gws auth default work@corp.com                   # set the default

gws --account personal@gmail.com drive files list  # one-off override
export GOOGLE_WORKSPACE_CLI_ACCOUNT=personal@gmail.com  # env var override

Credentials are stored per-account as `credentials.<b64-email>.enc` in `~/.config/gws/`, with an `accounts.json` registry tracking defaults.

Manual OAuth Setup (no gcloud)

Use this when `gws auth setup` cannot automate project/client creation, or when you want explicit control.

1. Open Google Cloud Console in the target project:

• OAuth consent screen: `https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>`
• Credentials: `https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>`

2. Configure OAuth branding/audience if prompted — App type: **External** (testing mode is fine) 3. Add your account under **Test users** 4. Create an OAuth client — Type: **Desktop app** 5. Download the client JSON → save to `~/.config/gws/client_secret.json`

> **Important:** You must add yourself as a test user. In the OAuth consent screen, click **Test users → Add users** and enter your Google account email. Without this, login will fail with a generic "Access blocked" error.

Then run:

gws auth login

Headless / CI

# On a machine with a browser:
gws auth export --unmasked > credentials.json

# On the headless machine:
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list   # just works

Service Account (server-to-server)

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

# For Domain-Wide Delegation:
export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com

Pre-obtained Access Token

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

Browser-Assisted Auth (for AI agents)

Agent