google-workspace-cli

Google Workspace CLI

Expert guidance and automation for Google Workspace administration using the open-source gws CLI. Covers installation, authentication, 18+ service APIs, 43 built-in recipes, and 10 persona bundles for role-based workflows.

---

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

Variable	Purpose
GWS_CLIENT_ID	OAuth client ID
GWS_CLIENT_SECRET	OAuth client secret
GWS_TOKEN_PATH	Custom token storage path
GWS_SERVICE_ACCOUNT_KEY	Service account JSON key path
GWS_DELEGATED_USER	User to impersonate (service accounts)
GWS_DEFAULT_FORMAT	Default output format (json/ndjson/table)

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

Area	Check	Risk
Drive	External sharing enabled	Data exfiltration
Gmail	Auto-forwarding rules	Data exfiltration
Gmail	DMARC/SPF/DKIM records	Email spoofing
Calendar	Default sharing visibility	Information leak
OAuth	Third-party app grants	Unauthorized access
Admin	Super admin count	Privilege escalation
Admin	2-Step verification enforcement	Account takeover

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
gws_doctor.py	Pre-flight diagnostics	python3 scripts/gws_doctor.py [--json] [--services gmail,drive]
auth_setup_guide.py	Guided auth setup	python3 scripts/auth_setup_guide.py --guide oauth
gws_recipe_runner.py	Recipe catalog & runner	python3 scripts/gws_recipe_runner.py --list [--persona pm]
workspace_audit.py	Security/config audit	python3 scripts/workspace_audit.py [--json] [--demo]
output_analyzer.py	JSON/NDJSON analysis	gws ... --json | python3 scripts/output_analyzer.py --count

All scripts are stdlib-only, support --json output, and include demo mode with embedded sample data.

---

Best Practices

Security

1. Use OAuth with minimal scopes — request only what each workflow needs
2. Store tokens in the system keyring, never in plain text files
3. Rotate service account keys every 90 days
4. Audit third-party OAuth app grants quarterly
5. Use --dry-run before bulk destructive operations

Automation

1. Pipe --json output through output_analyzer.py for filtering and aggregation
2. Use recipes for multi-step operations instead of chaining raw commands
3. Select a persona bundle to scope recipes to your role
4. Use NDJSON format (--format ndjson) for streaming large result sets
5. Set GWS_DEFAULT_FORMAT=json in your shell profile for scripting

Performance

1. Use --fields to request only needed fields (reduces payload size)
2. Use --limit to cap results when browsing
3. Use --page-all only when you need complete datasets
4. Batch operations with recipes rather than individual API calls
5. Cache frequently accessed data (e.g., label IDs, folder IDs) in variables

---

Limitations

Constraint	Impact
OAuth tokens expire after 1 hour	Re-auth needed for long-running scripts
API rate limits (per-user, per-service)	Bulk operations may hit 429 errors
Scope requirements vary by service	Must request correct scopes during auth
Pre-v1.0 CLI status	Breaking changes possible between releases
Google Cloud project required	Free, but requires setup in Cloud Console
Admin API needs admin privileges	Some audit checks require Workspace Admin role

Required Scopes by Service

# List scopes for specific services
python3 scripts/auth_setup_guide.py --scopes gmail,drive,calendar,sheets

Service	Key Scopes
Gmail	gmail.modify, gmail.send, gmail.labels
Drive	drive.file, drive.metadata.readonly
Sheets	spreadsheets
Calendar	calendar, calendar.events
Admin	admin.directory.user.readonly, admin.directory.group
Tasks	tasks