hoodini/ai-agents-skills/google-workspace-cli

Name: google-workspace-cli
Author: hoodini

Claude Code and agent skill by hoodini/ai-agents-skills

Trust tier 3

community

Source check pending

Checking that the SKILL.md file is still in the repository.

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.

Install

npx vskill@latest install hoodini/ai-agents-skills/google-workspace-cli

SKILL.md

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 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)
A Google Cloud project — required for OAuth credentials. You can create one via the Google Cloud Console, with the `gcloud` CLI, or with the gws auth setup command.
A Google account with access to Google Workspace

Installation

bash

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

Alternative installation methods:

bash

# 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

bash

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)

bash

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:

bash

# 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

bash

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.

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>

Configure OAuth branding/audience if prompted — App type: External (testing mode is fine)
Add your account under Test users
Create an OAuth client — Type: Desktop app
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:

bash

gws auth login

Headless / CI

bash

# 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)

bash

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

bash

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

Browser-Assisted Auth (for AI agents)

Agents can complete OAuth with browser automation:

Human flow: Run gws auth login, open the printed URL, approve scopes.
Agent-assisted flow: The agent opens the URL, selects the account, handles consent prompts, and returns control once the localhost callback succeeds.

If consent shows "Google hasn't verified this app" (testing mode), click Continue. If scope checkboxes appear, select required scopes (or Select all) before continuing.

Auth Precedence

Priority	Method	Source
1	Access token	`GOOGLE_WORKSPACE_CLI_TOKEN`
2	Credentials file	`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`
3	Per-account encrypted credentials	`gws auth login --account EMAIL`
4	Plaintext credentials	`~/.config/gws/credentials.json`

Account resolution: --account flag > GOOGLE_WORKSPACE_CLI_ACCOUNT env var > default in accounts.json.

All environment variables can also live in a .env file in your project root.

Command Structure

The universal pattern for ALL gws commands:

gws <service> <resource> <method> [--params '{ JSON }'] [--json '{ JSON }'] [flags]

Global Flags

Flag	Description
`--help`	Show help for any service, resource, or method
`--params '{ JSON }'`	URL/query parameters as JSON
`--json '{ JSON }'`	Request body as JSON
`--dry-run`	Preview the HTTP request without executing
`--page-all`	Auto-paginate, one JSON line per page (NDJSON)
`--page-limit <N>`	Max pages to fetch (default: 10)
`--page-delay <MS>`	Delay between pages (default: 100ms)
`--upload <path>`	Multipart file upload
`--account <email>`	Use a specific authenticated account
`--sanitize <template>`	Model Armor response sanitization

Introspecting Schemas

bash

# See the full request/response schema for any method
gws schema drive.files.list
gws schema gmail.users.messages.send
gws schema calendar.events.insert

Core Services — Commands & Examples

Google Drive

bash

# List files (paginated)
gws drive files list --params '{"pageSize": 10}'
 
# List ALL files (auto-paginate as NDJSON)
gws drive files list --params '{"pageSize": 100}' --page-all
 
# Search for files
gws drive files list --params '{"q": "name contains '\''report'\'' and mimeType = '\''application/pdf'\''", "pageSize": 20}'
 
# Get file metadata
gws drive files get --params '{"fileId": "FILE_ID"}'
 
# Upload a file
gws drive files create --json '{"name": "report.pdf", "parents": ["FOLDER_ID"]}' --upload ./report.pdf
 
# Create a folder
gws drive files create --json '{"name": "Project Docs", "mimeType": "application/vnd.google-apps.folder"}'
 
# Move a file to a folder
gws drive files update --params '{"fileId": "FILE_ID", "addParents": "FOLDER_ID", "removeParents": "OLD_PARENT_ID"}'
 
# Share a file
gws drive permissions create --params '{"fileId": "FILE_ID"}' --json '{"role": "writer", "type": "user", "emailAddress": "user@example.com"}'
 
# Download a file (export Google Docs as PDF)
gws drive files export --params '{"fileId": "FILE_ID", "mimeType": "application/pdf"}'
 
# Delete a file
gws drive files delete --params '{"fileId": "FILE_ID"}'
 
# List shared drives
gws drive drives list --params '{"pageSize": 10}'
 
# Create a shared drive
gws drive drives create --params '{"requestId": "unique-id"}' --json '{"name": "Team Drive"}'

Gmail

bash

# List messages in inbox
gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'
 
# Search messages
gws gmail users messages list --params '{"userId": "me", "q": "from:boss@company.com is:unread", "maxResults": 20}'
 
# Get a specific message
gws gmail users messages get --params '{"userId": "me", "id": "MESSAGE_ID"}'
 
# Send an email
gws gmail users messages send --params '{"userId": "me"}' --json '{
  "raw": "<BASE64_ENCODED_RFC2822_MESSAGE>"
}'
 
# List labels
gws gmail users labels list --params '{"userId": "me"}'
 
# Create a label
gws gmail users labels create --params '{"userId": "me"}' --json '{"name": "Important/Projects"}'
 
# Modify message labels
gws gmail users messages modify --params '{"userId": "me", "id": "MESSAGE_ID"}' --json '{"addLabelIds": ["LABEL_ID"], "removeLabelIds": ["INBOX"]}'
 
# Trash a message
gws gmail users messages trash --params '{"userId": "me", "id": "MESSAGE_ID"}'
 
# List drafts
gws gmail users drafts list --params '{"userId": "me"}'
 
# Create a draft
gws gmail users drafts create --params '{"userId": "me"}' --json '{
  "message": {"raw": "<BASE64_ENCODED_RFC2822_MESSAGE>"}
}'
 
# Set vacation auto-reply
gws gmail users settings updateVacation --params '{"userId": "me"}' --json '{
  "enableAutoReply": true,
  "responseSubject": "Out of Office",
  "responseBodyPlainText": "I am out of office until March 10.",
  "restrictToContacts": false,
  "restrictToDomain": false
}'

Google Calendar

bash

# List upcoming events
gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-05T00:00:00Z", "maxResults": 10, "singleEvents": true, "orderBy": "startTime"}'
 
# Get a specific event
gws calendar events get --params '{"calendarId": "primary", "eventId": "EVENT_ID"}'
 
# Create an event
gws calendar events insert --params '{"calendarId": "primary"}' --json '{
  "summary": "Team Standup",
  "description": "Daily standup meeting",
  "start": {"dateTime": "2026-03-06T09:00:00-05:00", "timeZone": "America/New_York"},
  "end": {"dateTime": "2026-03-06T09:30:00-05:00", "timeZone": "America/New_York"},
  "attendees": [{"email": "alice@example.com"}, {"email": "bob@example.com"}]
}'
 
# Update an event
gws calendar events update --params '{"calendarId": "primary", "eventId": "EVENT_ID"}' --json '{
  "summary": "Updated Standup",
  "start": {"dateTime": "2026-03-06T10:00:00-05:00"},
  "end": {"dateTime": "2026-03-06T10:30:00-05:00"}
}'
 
# Delete an event
gws calendar events delete --params '{"calendarId": "primary", "eventId": "EVENT_ID"}'
 
# List calendars
gws calendar calendarList list
 
# Check free/busy
gws calendar freebusy query --json '{
  "timeMin": "2026-03-06T08:00:00Z",
  "timeMax": "2026-03-06T18:00:00Z",
  "items": [{"id": "alice@example.com"}, {"id": "bob@example.com"}]
}'
 
# Create a recurring event
gws calendar events insert --params '{"calendarId": "primary"}' --json '{
  "summary": "Weekly Review",
  "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=FR"],
  "start": {"dateTime": "2026-03-06T16:00:00-05:00", "timeZone": "America/New_York"},
  "end": {"dateTime": "2026-03-06T17:00:00-05:00", "timeZone": "America/New_York"}
}'

Google Sheets

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 95 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/google-workspace-cli/SKILL.md

Popularity

Repository stars: 206
Repository forks: 44
7-day trend score: 27

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 10 May 2026, 5 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/hoodini/ai-agents-skills/google-workspace-cli/badge)](https://verified-skill.com/skills/hoodini/ai-agents-skills/google-workspace-cli)

Something wrong with this skill or its page? Tell us.

Install

SKILL.md

Google Workspace CLI (gws)

How It Works

Prerequisites

Installation

Quick Start

Authentication

Which setup should I use?

Quick Setup (recommended — requires gcloud CLI)

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

Multiple Accounts

Manual OAuth Setup (no gcloud)

Headless / CI

Service Account (server-to-server)

Pre-obtained Access Token

Browser-Assisted Auth (for AI agents)

Auth Precedence

Command Structure

Global Flags

Introspecting Schemas

Core Services — Commands & Examples

Google Drive

Gmail

Google Calendar

Google Sheets

Security

Quality evaluation

Source

Popularity

Works with

Google Workspace CLI (`gws`)