skill-spotlightgoogle-workspacegmailclawhubopenclawproductivity

gog: The Google Workspace CLI That Finally Makes Gmail, Calendar, and Drive Scriptable

March 7, 2026·9 min read

Google's APIs are powerful and infamously painful to use. Getting programmatic access to your own Gmail or Calendar involves OAuth consent screens, GCP Console navigation, scope selection, redirect URIs, and token refresh logic — before you've written a single line of useful code.

gog by @steipete (Peter Steinberger) is a single binary that handles all of that and exposes Gmail, Calendar, Drive, Contacts, Sheets, Docs, Tasks, Chat, and more through a clean, consistent CLI. Its design philosophy is explicit: built for AI agents first, human usability second — JSON output by default for scripting, --no-input for non-interactive automation, and a command allowlist for sandboxed agent execution.

59,000+ downloads on ClawHub and 400 stars. It's the most-downloaded Google integration skill on the registry by a wide margin.

Why Not Just Use Google's MCP Integration?

The honest comparison: MCP integrations for Google Workspace tend to be token-heavy. They surface the raw API surface, which means verbose responses, nested JSON, and agents spending context budget on boilerplate.

gog takes a different approach — it's a purpose-built CLI where every command is designed to return exactly what an agent needs: compact, parseable output with sane defaults. You get gog gmail search 'newer_than:7d' --max 10 returning 10 recent emails as clean JSON, not a full API response envelope with headers, pagination metadata, and raw MIME.

One Hacker News discussion about the tool captured the sentiment: users prefer CLIs over MCPs for context efficiency — "MCPs consume more tokens while offering less precision than well-crafted command-line interfaces built for specific needs." For AI agent workflows, that difference compounds across hundreds of operations per session.

One-Time Setup

gog uses OAuth2. You need a Google Cloud project with the APIs enabled. This takes 10–15 minutes once; after that, credentials auto-refresh indefinitely.

Step 1: Install

# macOS
brew install steipete/tap/gogcli
 
# Arch Linux
yay -S gogcli
 
# From source
git clone https://github.com/steipete/gogcli.git && cd gogcli && make

Step 2: Create OAuth credentials

Go to console.cloud.google.com → APIs & Services → Library
Enable the APIs you need: Gmail, Calendar, Drive, People, Tasks, Sheets, Docs
Go to Credentials → Create Credentials → OAuth client ID → Desktop app
Download the JSON file

Step 3: Configure gog

# Register your credentials
gog auth credentials ~/Downloads/client_secret_xxx.json
 
# Add your account (opens browser for OAuth flow)
gog auth add you@gmail.com --services gmail,calendar,drive,contacts,sheets,docs
 
# Verify
gog auth list
gog auth list --check   # validate tokens

For read-only access (recommended for agents that shouldn't modify data):

gog auth add you@gmail.com --services gmail,calendar --gmail-scope readonly --drive-scope readonly

For remote/headless setups (CI, VPS, no browser):

gog auth add you@gmail.com --manual
# Follow the URL, paste the redirect URL back

Environment Variable Setup for Agents

export GOG_ACCOUNT=you@gmail.com      # default account
export GOG_JSON=1                      # always output JSON
export GOG_ENABLE_COMMANDS=gmail,calendar,drive  # restrict to safe subset

Gmail

# Search — uses Gmail's full query syntax
gog gmail search 'newer_than:7d'
gog gmail search 'from:boss@company.com is:unread'
gog gmail search 'subject:"invoice" has:attachment'
gog gmail search 'newer_than:7d' --max 20 --json
 
# Read a message
gog gmail messages get <messageId>
 
# Send email
gog gmail send --to recipient@example.com \
               --subject "Weekly report" \
               --body "Here's the summary..."
 
# Send with file attachment
gog gmail send --to team@example.com \
               --subject "Report" \
               --body "See attached" \
               --attach ./report.pdf
 
# Send with read tracking
gog gmail send --to client@example.com --subject "Proposal" --body "..." --track
 
# List labels, filters, drafts
gog gmail labels list
gog gmail filters list
gog gmail drafts list
 
# Vacation responder
gog gmail vacation get
 
# Push notifications (Pub/Sub)
gog gmail watch

Calendar

# List upcoming events
gog calendar events list
 
# Check specific calendar
gog calendar events list --calendar work@company.com
 
# Create an event
gog calendar events create \
  --title "Team standup" \
  --time "2026-03-10T09:00:00" \
  --duration 30 \
  --attendees "alice@co.com,bob@co.com"
 
# Update an event
gog calendar events update <eventId> --title "New title"
 
# Check someone's availability
gog calendar freebusy colleague@company.com
 
# Detect scheduling conflicts
gog calendar conflicts
 
# Free/busy query for scheduling agents
gog calendar freebusy alice@co.com bob@co.com \
  --from 2026-03-10T08:00:00 \
  --to 2026-03-10T18:00:00 \
  --json

Drive

# List files
gog drive list
gog drive list --folder <folderId>
 
# Search
gog drive search "Q1 report"
gog drive search "mimeType='application/vnd.google-apps.document'"
 
# Download
gog drive download <fileId>
gog drive download <fileId> --format pdf    # export Google Doc as PDF
 
# Upload
gog drive upload ./report.xlsx
 
# Permissions
gog drive permissions list <fileId>
 
# Shared drives
gog drive shared-drives list

Sheets

# Read a range
gog sheets read <spreadsheetId> "Sheet1!A1:E10"
 
# Write data
gog sheets write <spreadsheetId> "Sheet1!A1" '[["Name","Score"],["Alice",95],["Bob",87]]'
 
# Insert rows
gog sheets insert-rows <spreadsheetId> <sheetId> 2   # insert before row 2
 
# Read cell notes
gog sheets read-notes <spreadsheetId>

Docs & Slides

# Extract text from a Google Doc
gog docs text <docId>
 
# Export to PDF or other formats
gog docs export <docId> --format pdf
gog docs export <docId> --format docx
 
# Sed-style document editing (find and replace)
gog docs sedmat <docId> 's/old text/new text/g'
 
# Slides
gog slides export <presentationId> --format pptx
gog slides create --title "Q1 Results"

Contacts & Tasks

# Contacts
gog contacts search "John"
gog contacts create --name "Jane Smith" --email "jane@example.com"
gog contacts directory list        # Workspace directory (all org members)
gog contacts other-contacts list
 
# Tasks
gog tasks lists                    # list all task lists
gog tasks get <tasklistId>         # tasks in a list
gog tasks add <tasklistId> "Review PR #234"
gog tasks done <tasklistId> <taskId>
gog tasks delete <tasklistId> <taskId>

Chat

# List spaces (channels, DMs, group conversations)
gog chat spaces list
 
# Read messages
gog chat messages list --space <spaceId>
gog chat messages search "deployment"
 
# Send a message
gog chat messages send --space <spaceId> "Build complete ✓"
 
# List threads
gog chat threads list --space <spaceId>

Agent-Specific Features

Command Allowlist (Sandboxing)

Restrict which top-level commands an agent can use:

export GOG_ENABLE_COMMANDS=gmail,calendar,tasks
# Agent can only use: gog gmail ..., gog calendar ..., gog tasks ...
# Drive, Sheets, Chat, etc. are blocked

This is particularly useful when giving an agent access to your account but wanting to limit its blast radius — an email-focused agent shouldn't be able to modify Drive files.

Non-Interactive Mode

gog --no-input gmail search 'is:unread'

Prevents any interactive prompts. Essential for automated pipelines where there's no TTY.

Multiple Accounts

# Add a work account with a separate OAuth client
gog --client work auth credentials ~/Downloads/work-credentials.json
gog --client work auth add you@yourcompany.com
 
# Switch between accounts
gog --account you@gmail.com gmail search 'is:unread'
gog --account you@yourcompany.com calendar events list
 
# Or set aliases
# In ~/.config/gogcli/config.json:
# account_aliases: { "work": "you@yourcompany.com", "personal": "me@gmail.com" }
gog --account work calendar events list

JSON Output for Scripting

gog gmail search 'newer_than:1d' --json | jq '.[] | {from: .from, subject: .subject}'
gog calendar events list --json | jq '.[] | select(.start.dateTime > "2026-03-10")'

Real Automation Patterns

Morning Briefing Agent

#!/bin/bash
# Collect morning context for an AI agent
 
echo "=== UNREAD EMAIL ==="
gog gmail search 'is:unread newer_than:12h' --max 20 --json
 
echo "=== TODAY'S CALENDAR ==="
gog calendar events list --json
 
echo "=== PENDING TASKS ==="
gog tasks get <myTasklistId> --json

Meeting Scheduler Agent

An agent that checks availability and creates events:

# 1. Check availability of all attendees
gog calendar freebusy alice@co.com bob@co.com \
  --from "2026-03-10T08:00:00" --to "2026-03-10T18:00:00" --json
 
# 2. Create event at the first free slot
gog calendar events create \
  --title "Project sync" \
  --time "2026-03-10T14:00:00" \
  --duration 45 \
  --attendees "alice@co.com,bob@co.com" \
  --json

Drive File Monitoring

# Find files modified in the last 24 hours
gog drive search "modifiedTime > '2026-03-06'" --json | \
  jq '.[] | {name: .name, modified: .modifiedTime, owner: .owners[0].displayName}'

Multiple Accounts & Service Accounts

For Workspace admins or users with multiple Google accounts, gog supports parallel configurations:

// ~/.config/gogcli/config.json
{
  "keyring_backend": "file",
  "default_timezone": "UTC",
  "account_aliases": {
    "work": "work@company.com",
    "personal": "me@gmail.com"
  },
  "account_clients": {
    "work@company.com": "work"
  }
}

For fully automated workflows (no human OAuth flow), set up a service account with domain-wide delegation in Google Workspace Admin Console:

gog auth service-account set admin@yourdomain.com \
  --key ~/Downloads/service-account.json

Installation via ClawHub

clawhub install gog

After installing, run the one-time auth setup:

gog auth credentials ~/Downloads/client_secret.json
gog auth add you@gmail.com --services gmail,calendar,drive,contacts,sheets,docs
gog auth list --check    # confirm everything is working

Before installing, verify the skill's current security status at clawhub.ai/skills.

Frequently Asked Questions

Does it work with personal Gmail accounts (not Workspace)?

Yes. Most features work with personal Gmail. Some features — Classroom, Keep, domain-wide delegation, Groups, directory listing — require a Google Workspace (paid) account.

Is the OAuth setup really that complicated?

The one-time setup takes 10–15 minutes. The main friction is the GCP Console (creating a project, enabling APIs, creating credentials). Once done, tokens auto-refresh and you won't need to touch it again.

Can an agent modify my emails or calendar without me knowing?

Only if you grant write scopes. Use --gmail-scope readonly and --drive-scope readonly at auth time to give agents read-only access. The GOG_ENABLE_COMMANDS allowlist further restricts which services are accessible per session.

How does it handle multiple Google accounts?

gog supports named OAuth clients and account aliases. You can maintain separate credentials for personal and work accounts and switch between them via flag (--account work) or environment variable (GOG_ACCOUNT=work).

Is there a difference between gog and the official Google Workspace CLI?

Yes. gog (gogcli by steipete) is a community-built CLI that prioritizes AI agent ergonomics: compact output, command allowlists, consistent flags across services. The official googleworkspace/cli is dynamically generated from Google's Discovery Service and has broader API coverage, but is less polished for agent use.

← Back to Blog