Google Workspace CLI¶

Engineering - Core google-workspace-cli Source

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

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

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

Automation¶

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

Performance¶

Use --fields to request only needed fields (reduces payload size)
Use --limit to cap results when browsing
Use --page-all only when you need complete datasets
Batch operations with recipes rather than individual API calls
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`