Google Workspace Cli

What This Skill Does

The Google Workspace CLI skill provides expert guidance and automation for managing Google Workspace using the open-source gws CLI. It covers installation, authentication, and various service APIs, offering built-in recipes and persona bundles for role-based workflows. This skill is designed for Google Workspace administrators seeking to streamline their tasks.

When to Use

• Automate user provisioning and deprovisioning.
• Manage Google Drive files and permissions.
• Send emails and manage Gmail settings.
• Audit Google Workspace security settings.
• Generate reports on Google Workspace usage.
• Integrate Google Workspace with other systems.

Key Features

• Provides step-by-step guidance for installation and authentication.
• Offers pre-built recipes for common Google Workspace tasks.
• Supports multiple authentication methods, including OAuth and service accounts.
• Includes persona bundles for role-based workflows.
• Automates tasks across 18+ Google Workspace service APIs.
• Integrates with other tools via scripts and environment variables.

Quick Start

Check Installation

Verify gws is installed and authenticated

python3 scripts/gws_doctor.py

Send an Email

gws gmail users.messages send me --to "team@company.com"
--subject "Weekly Update" --body "Here's this week's summary..."

List Drive Files

gws drive files list --json --limit 20 | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table

Installation

npm (recommended)

npm install -g @anthropic/gws gws --version

Cargo (from source)

cargo install gws-cli gws --version

Pre-built Binaries

Download from github.com/googleworkspace/cli/releases for macOS, Linux, or Windows.

Verify Installation

python3 scripts/gws_doctor.py Checks: PATH, version, auth status, service connectivity

Authentication

OAuth Setup (Interactive)

Step 1: Create Google Cloud project and OAuth credentials

python3 scripts/auth_setup_guide.py --guide oauth

Step 2: Run auth setup gws auth setup

Step 3: Validate gws auth status --json

Service Account (Headless/CI)

Generate setup instructions

python3 scripts/auth_setup_guide.py --guide service-account

Configure with key file export GWS_SERVICE_ACCOUNT_KEY=/path/to/key.json export GWS_DELEGATED_USER=admin@company.com gws auth status

Environment Variables

Generate .env template

python3 scripts/auth_setup_guide.py --generate-env

Validate Authentication

python3 scripts/auth_setup_guide.py --validate --json Tests each service endpoint

Workflow 1: Gmail Automation

Goal: Automate email operations — send, search, label, and filter management.

Send and Reply

Send a new email

gws gmail users.messages send me --to "client@example.com"
--subject "Proposal" --body "Please find attached..."
--attachment proposal.pdf

Reply to a thread gws gmail users.messages reply me --thread-id <THREAD_ID>
--body "Thanks for your feedback..."

Forward a message gws gmail users.messages forward me --message-id <MSG_ID>
--to "manager@company.com"

Search and Filter

Search emails

gws gmail users.messages list me --query "from:client@example.com after:2025/01/01" --json
| python3 scripts/output_analyzer.py --count

List labels gws gmail users.labels list me --json

Create a filter gws gmail users.settings.filters create me
--criteria '{"from":"notifications@service.com"}'
--action '{"addLabelIds":["Label_123"],"removeLabelIds":["INBOX"]}'

Bulk Operations

Archive all read emails older than 30 days

gws gmail users.messages list me --query "is:read older_than:30d" --json
| python3 scripts/output_analyzer.py --select "id" --format json
| xargs -I {} gws gmail users.messages modify me {} --removeLabelIds INBOX

Workflow 2: Drive & Sheets

Goal: Manage files, create spreadsheets, configure sharing, and export data.

File Operations

List files

gws drive files list --json --limit 50
| python3 scripts/output_analyzer.py --select "name,mimeType,size" --format table

Upload a file gws drive files create --name "Q1 Report" --upload report.pdf
--parents <FOLDER_ID>

Create a Google Sheet gws sheets spreadsheets create --title "Budget 2026" --json

Download/export gws drive files export <FILE_ID> --mime "application/pdf" --output report.pdf

Sharing

Share with user

gws drive permissions create <FILE_ID>
--type user --role writer --emailAddress "colleague@company.com"

Share with domain (view only) gws drive permissions create <FILE_ID>
--type domain --role reader --domain "company.com"

List who has access gws drive permissions list <FILE_ID> --json

Sheets Data

Read a range

gws sheets spreadsheets.values get <SHEET_ID> --range "Sheet1!A1:D10" --json

Write data gws sheets spreadsheets.values update <SHEET_ID> --range "Sheet1!A1"
--values '[["Name","Score"],["Alice",95],["Bob",87]]'

Append rows gws sheets spreadsheets.values append <SHEET_ID> --range "Sheet1!A1"
--values '[["Charlie",92]]'

Workflow 3: Calendar & Meetings

Goal: Schedule events, find available times, and generate standup reports.

Event Management

Create an event

gws calendar events insert primary
--summary "Sprint Planning"
--start "2026-03-15T10:00:00" --end "2026-03-15T11:00:00"
--attendees "team@company.com"
--location "Conference Room A"

List upcoming events gws calendar events list primary --timeMin "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
--maxResults 10 --json

Quick event (natural language) gws helpers quick-event "Lunch with Sarah tomorrow at noon"

Find Available Time

Check free/busy for multiple people

gws helpers find-time
--attendees "alice@co.com,bob@co.com,charlie@co.com"
--duration 60 --within "2026-03-15,2026-03-19" --json

Standup Report

Generate daily standup from calendar + tasks

gws recipes standup-report --json
| python3 scripts/output_analyzer.py --format table

Meeting prep (agenda + attendee info) gws recipes meeting-prep --event-id <EVENT_ID>

Workflow 4: Security Audit

Goal: Audit Google Workspace security configuration and generate remediation commands.

Run Full Audit

Full audit across all services

python3 scripts/workspace_audit.py --json

Audit specific services python3 scripts/workspace_audit.py --services gmail,drive,calendar

Demo mode (no gws required) python3 scripts/workspace_audit.py --demo

Audit Checks

Review and Remediate

Review findings

python3 scripts/workspace_audit.py --json | python3 scripts/output_analyzer.py
--filter "status=FAIL" --select "area,check,remediation"

Execute remediation (example: restrict external sharing) gws drive about get --json # Check current settings Follow remediation commands from audit output

Python Tools

| Script | Purpose | Usage | |--------|---------|