Google Workspace CLI

Expert guidance and automation for Google Workspace administration using the open-source

gws

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

GWS_CLIENT_ID

GWS_CLIENT_SECRET

GWS_TOKEN_PATH

GWS_SERVICE_ACCOUNT_KEY

GWS_DELEGATED_USER

GWS_DEFAULT_FORMAT

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

gws_doctor.py

python3 scripts/gws_doctor.py [--json] [--services gmail,drive]

auth_setup_guide.py

python3 scripts/auth_setup_guide.py --guide oauth

gws_recipe_runner.py

python3 scripts/gws_recipe_runner.py --list [--persona pm]

workspace_audit.py

python3 scripts/workspace_audit.py [--json] [--demo]

output_analyzer.py

gws ... --json | python3 scripts/output_analyzer.py --count

All scripts are stdlib-only, support

--json

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

Required Scopes by Service

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

gmail.modify

gmail.send

gmail.labels

drive.file

drive.metadata.readonly

spreadsheets

calendar

calendar.events

admin.directory.user.readonly

admin.directory.group

tasks