GOG Skill: Complete Google Workspace Guide

The GOG (Google on Go) skill is your all-in-one gateway to Google Workspace. Instead of juggling multiple skills for Gmail, Calendar, Drive, and Docs, GOG handles everything through a single OAuth connection. This guide covers setup, all available commands, and real-world examples.

Table of Contents

• What is GOG?
• Features at a Glance
• VPS Setup (Headless Mode)
• Environment Variables Configuration
• 📧 Gmail Commands
• 📅 Calendar Commands
• 📁 Drive Commands
• 📊 Sheets Commands
• 📝 Docs Commands
• 👥 Contacts Commands
• Troubleshooting
• Pro Tips

What is GOG?

GOG is a CLI tool that provides direct access to Google Workspace APIs. It's faster, more reliable, and more secure than browser automation or IMAP-based solutions. With one OAuth flow, you get access to:

Features at a Glance

VPS Setup (Headless Mode)

Running on a VPS requires a two-step OAuth flow since you can't open a browser directly. Here's the complete setup:

Step 1: Install GOG CLI

# Download and build from source
git clone https://github.com/steipete/gogcli.git
cd gogcli
make

# Install to local bin
mkdir -p ~/.local/bin
cp bin/gog ~/.local/bin/gog

# Add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Step 2: Create Google Cloud OAuth Client

1. Go to Google Cloud Console
2. Create a new project (or use existing)
3. Enable Google Workspace APIs:
   • Gmail API
   • Google Calendar API
   • Google Drive API
   • Google Sheets API
   • Google Docs API
   • People API (Contacts)
4. Go to "OAuth consent screen" → Choose "External" (for personal use)
5. Fill in required fields (app name, support email)
6. Add scopes: https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/calendar, https://www.googleapis.com/auth/drive, etc.
7. Go to "Credentials" → Create OAuth client ID → Desktop app
8. Download client_secret.json
9. Upload to VPS: scp client_secret.json account@your-vps:~/.openclaw/workspace/secrets/gog-credentials.json

Step 3: Load Credentials

# Store credentials in GOG
gog auth credentials ~/.openclaw/workspace/secrets/gog-credentials.json

Step 4: Authenticate (Two-Step Remote Flow)

# Set environment variables
export GOG_ACCOUNT=youremail@gmail.com
export GOG_KEYRING_BACKEND=file
export GOG_KEYRING_PASSWORD=your-secure-password

# Step 1: Generate auth URL (run on VPS)
gog auth add youremail@gmail.com --services gmail,calendar,drive,sheets,docs,contacts --remote --step 1

Step 1 output: A long URL starting with https://accounts.google.com/...

# Step 2: On your LOCAL machine:
# 1. Copy the URL from Step 1
# 2. Open in browser
# 3. Authorize the app
# 4. Copy the redirect URL (starts with http://localhost:...)

# Step 2: Exchange code for tokens (run on VPS)
gog auth add youremail@gmail.com --services gmail,calendar,drive,sheets,docs,contacts --remote --step 2 --auth-url "<paste-redirect-url-here>"

Step 5: Verify Authentication

# Check authorized accounts
gog auth list

# Test Gmail access
gog gmail search "newer_than:7d" --max 5

# Test Calendar access
gog calendar events primary --from "$(date -I)"

Environment Variables Configuration

For OpenClaw to use GOG, environment variables must be set in the OpenClaw configuration (~/.openclaw/openclaw.json) or via environment files.

# Default systemd service file may have:
Environment=GOG_KEYRING_PASSWORD=claw123  # OLD PASSWORD!

# This is why updates to .env files won't work!

Option 1: Add to ~.openclaw/openclaw.json (Configuration Files)

{
  "env": {
    "vars": {
      "GOG_ACCOUNT": "youremail@gmail.com",
      "GOG_KEYRING_BACKEND": "file",
      "GOG_KEYRING_PASSWORD": "your-secure-password"
    }
  }
}

Option 2: Set in .bashrc (for shell access)

# Add to ~/.bashrc
export GOG_ACCOUNT=youremail@gmail.com
export GOG_KEYRING_BACKEND=file
export GOG_KEYRING_PASSWORD=your-secure-password

# Edit service file
cat ~/.config/systemd/user/openclaw-gateway.service
# Find: Environment=GOG_KEYRING_PASSWORD=your-password
# Change to: Environment=GOG_KEYRING_PASSWORD=eZ1y_VaXDLKvnjj4x_zg_-Hdf-kEJ29vM0ZFYlcG-ls

# Reload and restart
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway

📧 Gmail Commands

Read Emails

# List recent emails
gog gmail list --max 10

# Search emails
gog gmail search "from:boss@company.com" --max 5
gog gmail search "subject:urgent" --max 10
gog gmail search "newer_than:7d" --max 20

# Get specific email by ID
gog gmail get <message-id>

# List unread only
gog gmail search "is:unread" --max 10

Send Emails

# Send simple email
gog gmail send --to "recipient@example.com" --subject "Hello" --body "Hi there!"

# Send with HTML body
gog gmail send --to "recipient@example.com" --subject "Report" --body "<h1>Report</h1><p>See attached</p>" --html

# Reply to email
gog gmail reply <message-id> --body "Thanks for the update!"

Manage Labels & Threads

# List labels
gog gmail labels list

# Add label to email
gog gmail modify <message-id> --add-labels "Important"

# Remove label
gog gmail modify <message-id> --remove-labels "Inbox"

# Mark as read/unread
gog gmail modify <message-id> --remove-labels "UNREAD"
gog gmail modify <message-id> --add-labels "UNREAD"

# Trash email
gog gmail trash <message-id>

Quick Reference: Gmail Search Operators

📅 Calendar Commands

View Events

# Today's events
gog calendar events primary --from "$(date -I)" --to "$(date -I)"

# Events for specific date range
gog calendar events primary --from "2026-04-01" --to "2026-04-30"

# Next 7 days
gog calendar events primary --from "$(date -I)" --to "$(date -I -d '+7 days')"

# List all calendars
gog calendar list

Create Events

# Simple event
gog calendar create primary --summary "Team Meeting" --from "2026-04-10T14:00:00" --to "2026-04-10T15:00:00"

# All-day event
gog calendar create primary --summary "Conference" --from "2026-04-15" --to "2026-04-17" --all-day

# With timezone
gog calendar create primary --summary "Call with EU team" --from "2026-04-10T09:00:00-04:00" --to "2026-04-10T10:00:00-04:00"

# With reminders
gog calendar create primary --summary "Important Meeting" --from "2026-04-10T14:00:00" --to "2026-04-10T15:00:00" --reminder="popup:15m" --reminder="email:1h"

# With attendees
gog calendar create primary --summary "Project Review" --from "2026-04-10T14:00:00" --to "2026-04-10T15:00:00" --attendees "colleague@example.com,manager@example.com"

# With Google Meet
gog calendar create primary --summary "Video Call" --from "2026-04-10T14:00:00" --to "2026-04-10T15:00:00" --with-meet

# Recurring event (weekly)
gog calendar create primary --summary "Weekly Standup" --from "2026-04-06T10:00:00" --to "2026-04-06T10:30:00" --rrule "RRULE:FREQ=WEEKLY;BYDAY=MO"

Update & Delete Events

# Update event
gog calendar update primary <event-id> --summary "Updated Title"

# Delete event
gog calendar delete primary <event-id>

Quick Reference: Recurrence Rules (RRULE)

📁 Drive Commands

Search & List Files

# List recent files
gog drive list --max 20

# Search by name
gog drive search "budget" --max 10

# Search by type
gog drive search "mimeType='application/vnd.google-apps.spreadsheet'" --max 10

# Search in specific folder
gog drive search "name contains 'report' and 'folder-id' in parents" --max 10

# Get file info
gog drive get <file-id>

Download & Upload

# Download file
gog drive download <file-id> --output ./local-file.pdf

# Upload file
gog drive upload ./local-file.pdf --name "Remote File Name"

# Upload to specific folder
gog drive upload ./document.pdf --parents "folder-id"

Organize Files

# Create folder
gog drive create-folder "New Folder Name"

# Move file to folder
gog drive move <file-id> --parents "new-folder-id"

# Share file
gog drive share <file-id> --email "colleague@example.com" --role "reader"

# Trash file
gog drive trash <file-id>

# Delete permanently
gog drive delete <file-id>

📊 Sheets Commands

Read Spreadsheets

# Get spreadsheet info
gog sheets get <spreadsheet-id>

# Read values from range
gog sheets values get <spreadsheet-id> --range "Sheet1!A1:D10"

# Read entire sheet
gog sheets values get <spreadsheet-id> --range "Sheet1"

Write to Spreadsheets

# Write values to range
gog sheets values update <spreadsheet-id> --range "Sheet1!A1:D2" --values '[["Header1","Header2"],["Data1","Data2"]]'

# Append values (adds to end)
gog sheets values append <spreadsheet-id> --range "Sheet1!A:A" --values '[["New Row Data"]]'

Create Spreadsheets

# Create new spreadsheet
gog sheets create --title "New Spreadsheet"

📝 Docs Commands

Create Documents

# Create new document
gog docs create --title "My Document"

# Create with initial content
gog docs create --title "Meeting Notes" --body "## Attendees\n- Alice\n- Bob\n\n## Notes\n- Discussed project timeline"

Read & Update

# Get document content
gog docs get <document-id>

# Update document
gog docs update <document-id> --body "New content for the document"

👥 Contacts Commands

List & Search Contacts

# List all contacts
gog contacts list --max 100

# Search contacts
gog contacts search "John" --max 10

Create Contacts

# Create new contact
gog contacts create --given-name "John" --family-name "Doe" --email "john.doe@example.com" --phone "+1-555-123-4567"

Troubleshooting

Common Issues

Debug Commands

# Check authentication status
gog auth list

# Validate tokens
gog auth list --check

# Show current account
gog auth show

# Verbose output for debugging
gog gmail list --max 1 -v

Pro Tips

# CLI: Get last 10 emails
gog gmail list --max 10

# CLI: Search unread emails
gog gmail search "is:unread" --max 10

# CLI: Search for a specific sender
gog gmail search "from:boss@company.com" --max 10

# CLI: Get calendar for today
gog calendar events primary --from "2026-04-07" --to "2026-04-07

# CLI: Create event
gog calendar create primary --summary "Meeting" --from "2026-04-07T14:00:00" --to "2026-04-07T15:00:00

# CLI: Search Drive
gog drive search "project" --max 20

# CLI: Upload file
gog upload ~/project-files/images.png

# CLI: Upload with GOG
gog upload /home/user/www/ai/gallery/images/magic_claw.png
gog upload /home/user/www/ai/gallery/images/magic_claw_icon.png

Quick Command Reference

# Gmail
gog gmail list --max 10
gog gmail search "is:unread" --max 10
gog gmail send --to "email@example.com" --subject "Subject" --body "Body"

# Calendar
gog calendar events primary --from "$(date -I)" --to "$(date -I)"
gog calendar create primary --summary "Event" --from "2026-04-10T14:00:00" --to "2026-04-10T15:00:00"

# Drive
gog drive list --max 20
gog drive search "filename" --max 10
gog drive upload ./file.pdf --name "Remote Name"

# Sheets
gog sheets values get <id> --range "Sheet1!A1:D10"
gog sheets create --title "New Sheet"

# Docs
gog docs create --title "New Document"
gog docs get <document-id>

# Contacts
gog contacts list --max 100
gog contacts search "John" --max 10