Google Workspace Ops

Automates Google Workspace work using the gog CLI with machine-parseable JSON output, from email and calendar operations to Drive/docs/sheets workflows. Use it when you need repeatable workspace automation, but avoid it for non-Google services or ad hoc UI workflows.

Terminology used in this file:

• OAuth: Google's delegated login/authorization flow used to grant CLI access without sharing your password.
• GCP: Google Cloud Platform, where you create the project and OAuth credentials.
• RFC3339: Standard date-time format used by Google APIs (for example, 2026-02-18T09:00:00+00:00).

Setup

brew tap steipete/tap
brew install gogcli
gog login YOUR_EMAIL --services all

• Claude Code: copy this skill folder into .claude/skills/google-workspace-ops/
• Codex CLI: append this SKILL.md content to your project's root AGENTS.md

For the full installation walkthrough (prerequisites, OAuth setup, verification, troubleshooting), see references/installation-guide.md.

Credential management: GOG_KEYRING_PASSWORD is required for all gog operations using the file-based keyring (headless/SSH environments, or desktop when opting out of system keychain). We strongly recommend managing it via the vault skill -- see references/auth-setup.md for all options including vault, custom secret managers, and plain export.

Staying Updated

This skill ships with an UPDATES.md changelog and UPDATE-GUIDE.md for your AI agent.

After installing, tell your agent: "Check UPDATES.md in the google-workspace-ops skill for any new features or changes."

When updating, tell your agent: "Read UPDATE-GUIDE.md and apply the latest changes from UPDATES.md."

Follow UPDATE-GUIDE.md so customized local files are diffed before any overwrite.

Quick Start

Run one read-only Gmail flow end-to-end:

gog auth status
gog gmail search "is:unread" --max 5 --json --no-input
gog gmail thread get THREAD_ID --json --no-input

Use this baseline pattern for automation:

• read/list/search: --json --no-input
• send/create/modify/delete: run --dry-run first, then ask user approval

Decision Tree: When to Use gog

Need to interact with Google Workspace?
  |
  +-- Is it email? (read, search, send, labels, drafts)
  |     YES --> gog gmail ...
  |
  +-- Is it calendar? (events, create, conflicts, freebusy)
  |     YES --> gog calendar ...
  |
  +-- Is it files? (search, upload, download, share)
  |     YES --> gog drive ...
  |
  +-- Is it document editing? (create, read, write Google Docs)
  |     YES --> gog docs ...
  |
  +-- Is it presentations? (create from markdown, export)
  |     YES --> gog slides ...
  |
  +-- Is it spreadsheets? (read cells, update, append)
  |     YES --> gog sheets ...
  |
  +-- Is it people? (contacts, directory search, tasks)
        YES --> gog contacts / gog tasks / gog people ...

Rule of thumb: if it touches Google Workspace, gog is the right entry point.

Security: Approval Rules

State-modifying operations require explicit user approval before execution.

The rule is simple: if an action changes workspace state visible to others or is hard to undo, get approval first. Reading is okay.

Automation and scripts should present intent (recipient, subject, summary, account, target IDs) and wait for explicit confirmation before send/modify/delete operations.

Global Flags (All Commands)

Every gog command accepts these flags. Know them -- they control output format and safety.

Agent-critical pattern: use --json --no-input for automation. JSON keeps automation deterministic. --no-input prevents prompt hangs.

Services Overview

Top-level shortcuts (save keystrokes):

10x Workflows

These are the highest-leverage patterns. Use these before inventing new scripts.

1. Read and Summarize Recent Emails

# Get last 5 unread emails with full content
gog gmail search "is:unread" --max 5 --json | jq '.[].messages[0] | {subject: .subject, from: .from, snippet: .snippet}'

# Get a specific thread with all messages
gog gmail thread get THREAD_ID --json

2. Send Email (with Safety)

# Preview first (dry-run)
gog send --to "[email protected]" --subject "Meeting notes" --body "Here are the notes..." --dry-run

# Then send
gog send --to "[email protected]" --subject "Meeting notes" --body "Here are the notes..." --no-input

3. Today's Calendar at a Glance

# Today's events across all calendars
gog cal events --today --all --json

# This week
gog cal events --week --json

# Next 3 days
gog cal events --days 3 --json

4. Create Calendar Event from Natural Language

# The agent translates natural language to RFC3339 times
gog cal create primary \
  --summary "Team standup" \
  --from "2026-02-18T09:00:00+00:00" \
  --to "2026-02-18T09:30:00+00:00" \
  --description "Daily sync" \
  --with-meet \
  --json

5. Search Drive and Get Links

# Full-text search
gog search "quarterly report" --max 5 --json | jq '.[].webViewLink'

# List files in a folder
gog ls --parent FOLDER_ID --json

6. Create a Google Doc from Markdown

# Create doc with markdown content
gog docs create "Meeting Notes 2026-02-17" --file notes.md --json

# Or write markdown to existing doc
gog docs write DOC_ID --file notes.md --replace --markdown

7. Read a Google Doc as Plain Text

# Dump doc as text (great for agent consumption)
gog docs cat DOC_ID

# Read specific tab
gog docs cat DOC_ID --tab "Notes"

# All tabs
gog docs cat DOC_ID --all-tabs

8. Create Slides from Markdown

# One command: markdown -> Google Slides
gog slides create-from-markdown "Q1 Review" --content-file presentation.md --json

9. Spreadsheet Operations

# Read a range
gog sheets get SHEET_ID "Sheet1!A1:D10" --json

# Append a row
gog sheets append SHEET_ID "Sheet1!A:D" "value1" "value2" "value3" "value4"

# Update specific cells
gog sheets update SHEET_ID "Sheet1!B2" "new value"

10. Multi-Service Pipeline

# Find a doc, read it, email a summary
DOC_ID=$(gog search "project brief" --max 1 --json | jq -r '.[0].id')
CONTENT=$(gog docs cat "$DOC_ID")
gog send --to "[email protected]" --subject "Project Brief Summary" --body "$CONTENT" --no-input

Output Modes

gog supports three output modes. Choose based on consumer.

For automation: always --json. Add --results-only to trim envelopes.

Field selection reduces token use:

# Only get subject and date from emails
gog gmail search "is:unread" --json --select "subject,date,from"

Exit Codes

Stable exit codes for automation.

Agent error handling pattern:

gog gmail search "is:unread" --json --fail-empty
EXIT=$?
if [ $EXIT -eq 3 ]; then echo "No unread emails"; fi
if [ $EXIT -eq 4 ]; then echo "Auth expired -- run: gog login EMAIL"; fi
if [ $EXIT -eq 7 ]; then sleep 5 && retry; fi

Multi-Account

gog supports multiple Google accounts. Use -a EMAIL to target a specific account.

# List authenticated accounts
gog auth list

# Target specific account
gog gmail search "is:unread" -a [email protected] --json
gog cal events --today -a [email protected] --json

# Set default account
gog config set default_account [email protected]

Common Gotchas

Error Handling

Anti-Patterns

Sandboxed / CI Environments

gog makes HTTPS calls to Google APIs. In sandboxed or CI environments, ensure network access is available.

If your sandbox blocks outbound HTTPS, gog commands will fail with network errors. Ensure your environment allows connections to *.googleapis.com.

Bundled Resources Index