Install Google Workspace CLI using Winget - wingetCollections

Google Workspace CLI Google LLC

agent-skills ai-agent artificial-intelligence-agent artificialintelligenceagent automation cli discovery-api google-admin google-api google-calendar google-chat google-docs google-drive google-gemini-cli-extension google-sheets google-workspace google-workspace-cli

Use this command to install Google Workspace CLI:

winget install --id=Google.WorkspaceCLI -e

Google Workspace CLI (gws) is a versatile command-line tool designed to interact with Google Workspace services such as Drive, Gmail, Calendar, Sheets, Docs, Chat, and Admin. Built dynamically from Google's Discovery Service, it adapts to new API endpoints automatically, offering a comprehensive suite of commands for developers and IT administrators.

Key Features:

AI Agent Skills: Pre-built skills enable AI agents to perform tasks like managing files or sending messages without custom coding.
Dynamic Command Surface: Automatically generates commands from Google's Discovery Service, ensuring up-to-date support for all Workspace APIs.
Structured JSON Output: Facilitates integration with tools and workflows by providing consistent, machine-readable responses.
Multiple Authentication Methods: Supports OAuth, service accounts, access tokens, and credentials file for flexible deployment in various environments.
Integration with Automation Tools: Works seamlessly with OpenClaw and Gemini CLI for enhanced workflow automation.

Audience & Benefit:

Ideal for developers and IT administrators seeking to streamline Google Workspace interactions. Benefits include reduced boilerplate code, simplified API integration, and the ability to automate tasks across multiple services efficiently. AI agents benefit from ready-to-use skills, enabling them to manage Workspace resources without custom tooling.

Installable via winget, gws offers a powerful solution for automating and managing Google Workspace services effectively.

README

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.

Versions

0.22.5

0.22.4

0.22.3

0.22.1

Website

github.com

License

Last updated

4/28/2026

Download latest version

npm install -g @googleworkspace/cli

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

nix run github:googleworkspace/cli

brew install googleworkspace-cli

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

# List the 10 most recent files
gws drive files list --params '{"pageSize": 10}'

# Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# Send a Chat message
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# Introspect any method's request/response schema
gws schema drive.files.list

# Stream paginated results as NDJSON
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

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`

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

gws auth login

Complete interactive auth on a machine with a browser.

Export credentials:

gws auth export --unmasked &gt; credentials.json

On the headless machine:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list   # just works

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

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

Priority	Source	Set via
1	Access token	`GOOGLE_WORKSPACE_CLI_TOKEN`
2	Credentials file	`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`
3	Encrypted credentials	`gws auth login`
4	Plaintext credentials	`~/.config/gws/credentials.json`

# Install all skills at once
npx skills add https://github.com/googleworkspace/cli

# Or pick only what you need
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

# Symlink all skills (stays in sync with repo)
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

# Or copy specific skills
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

# Read cells A1:C10 from "Sheet1"
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

# Append rows
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'

gws gmail --help      # shows +send, +reply, +reply-all, +forward, +triage, +watch …
gws calendar --help   # shows +insert, +agenda …
gws drive --help      # shows +upload …

Service	Command	Description
`gmail`	`+send`	Send an email
`gmail`	`+reply`	Reply to a message (handles threading automatically)
`gmail`	`+reply-all`	Reply-all to a message
`gmail`	`+forward`	Forward a message to new recipients
`gmail`	`+triage`	Show unread inbox summary (sender, subject, date)
`gmail`	`+watch`	Watch for new emails and stream them as NDJSON
`sheets`	`+append`	Append a row to a spreadsheet
`sheets`	`+read`	Read values from a spreadsheet
`docs`	`+write`	Append text to a document
`chat`	`+send`	Send a message to a space
`drive`	`+upload`	Upload a file with automatic metadata
`calendar`	`+insert`	Create a new event
`calendar`	`+agenda`	Show upcoming events (uses Google account timezone; override with `--timezone`)
`script`	`+push`	Replace all files in an Apps Script project with local files
`workflow`	`+standup-report`	Today's meetings + open tasks as a standup summary
`workflow`	`+meeting-prep`	Prepare for your next meeting: agenda, attendees, and linked docs
`workflow`	`+email-to-task`	Convert a Gmail message into a Google Tasks entry
`workflow`	`+weekly-digest`	Weekly summary: this week's meetings + unread email count
`workflow`	`+file-announce`	Announce a Drive file in a Chat space
`events`	`+subscribe`	Subscribe to Workspace events and stream them as NDJSON
`events`	`+renew`	Renew/reactivate Workspace Events subscriptions
`modelarmor`	`+sanitize-prompt`	Sanitize a user prompt through a Model Armor template
`modelarmor`	`+sanitize-response`	Sanitize a model response through a Model Armor template
`modelarmor`	`+create-template`	Create a new Model Armor template

# Send an email
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"

# Reply to a message
gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"

# Append a row to a spreadsheet
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"

# Show today's calendar agenda
gws calendar +agenda

# Upload a file to Drive
gws drive +upload ./report.pdf --name "Q1 Report"

# Morning standup summary
gws workflow +standup-report

# Show today's agenda in a specific timezone
gws calendar +agenda --today --timezone America/New_York

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

Variable	Description
`GOOGLE_WORKSPACE_CLI_TOKEN`	Pre-obtained OAuth2 access token (highest priority)
`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`	Path to OAuth credentials JSON (user or service account)
`GOOGLE_WORKSPACE_CLI_CLIENT_ID`	OAuth client ID (alternative to `client_secret.json`)
`GOOGLE_WORKSPACE_CLI_CLIENT_SECRET`	OAuth client secret (paired with `CLIENT_ID`)
`GOOGLE_WORKSPACE_CLI_CONFIG_DIR`	Override config directory (default: `~/.config/gws`)
`GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE`	Default Model Armor template
`GOOGLE_WORKSPACE_CLI_SANITIZE_MODE`	`warn` (default) or `block`
`GOOGLE_WORKSPACE_CLI_LOG`	Log level for stderr (e.g., `gws=debug`). Off by default.
`GOOGLE_WORKSPACE_CLI_LOG_FILE`	Directory for JSON log files with daily rotation. Off by default.
`GOOGLE_WORKSPACE_PROJECT_ID`	GCP project ID override for quota/billing and fallback for helper commands

Code	Meaning	Example cause
`0`	Success	Command completed normally
`1`	API error	Google returned a 4xx/5xx response
`2`	Auth error	Credentials missing, expired, or invalid
`3`	Validation error	Bad arguments, unknown service, invalid flag
`4`	Discovery error	Could not fetch the API schema document
`5`	Internal error	Unexpected failure

gws drive files list --params '{"fileId": "bad"}'
echo $?   # 1 — API error

gws unknown-service files list
echo $?   # 3 — validation error (unknown service)

gws auth login --scopes drive,gmail,calendar

{
  "error": {
    "code": 403,
    "message": "Gmail API has not been used in project 549352339482 ...",
    "reason": "accessNotConfigured",
    "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482"
  }
}

💡 API not enabled for your GCP project.
   Enable it at: https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482
   After enabling, wait a few seconds and retry your command.

cargo build                       # dev build
cargo clippy -- -D warnings       # lint
cargo test                        # unit tests
./scripts/coverage.sh             # HTML coverage report → target/llvm-cov/html/

Flag	Description	Default
`--page-all`	Auto-paginate, one JSON line per page (NDJSON)	off
`--page-limit`	Max pages to fetch	10
`--page-delay`	Delay between pages	100 ms

Google Workspace CLI Google LLC

README

gws

Contents

Prerequisites

Installation

Quick Start

Why gws?

Authentication

Which setup should I use?

Interactive (local desktop)

Manual OAuth setup (Google Cloud Console)

Browser-assisted auth (human or agent)

Headless / CI (export flow)

Service Account (server-to-server)

Pre-obtained Access Token

Precedence

AI Agent Skills

Gemini CLI Extension

Advanced Usage

Multipart Uploads

Pagination

Google Sheets — Shell Escaping

Helper Commands

Model Armor (Response Sanitization)

Environment Variables

Exit Codes

Architecture

Troubleshooting

"Access blocked" or 403 during login

"Google hasn't verified this app"

Too many scopes / consent screen error

`gcloud` CLI not found

`redirect_uri_mismatch`

API not enabled — `accessNotConfigured`

Development

License

Disclaimer

Google Workspace CLI Google LLC

README

gws

Contents

Prerequisites

Installation

Quick Start

Why gws?

Authentication

Which setup should I use?

Interactive (local desktop)

Manual OAuth setup (Google Cloud Console)

Browser-assisted auth (human or agent)

Headless / CI (export flow)

Service Account (server-to-server)

Pre-obtained Access Token

Precedence

AI Agent Skills

Gemini CLI Extension

Advanced Usage

Multipart Uploads

Pagination

Google Sheets — Shell Escaping

Helper Commands

Model Armor (Response Sanitization)

Environment Variables

Exit Codes

Architecture

Troubleshooting

"Access blocked" or 403 during login

"Google hasn't verified this app"

Too many scopes / consent screen error

gcloud CLI not found

redirect_uri_mismatch

API not enabled — accessNotConfigured

Development

License

Disclaimer

`gcloud` CLI not found

`redirect_uri_mismatch`

API not enabled — `accessNotConfigured`