google-workspace-ops

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](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](../vault/) -- see [references/auth-setup.md](references/auth-setup.md#credential-management) 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.

| Operation Type | Examples | Autonomous? | |---------------|----------|-------------| | Read / List / Search | gmail messages list, drive ls, calendar list, docs cat | YES — run freely | | Send / Create | gmail send, docs create, calendar create, drive upload | NO — ask user first | | Modify / Update | gmail modify, sheets update, docs write, contacts update | NO — ask user first | | Delete / Trash | gmail trash, drive trash, tasks delete | NO — ask user first | | Draft | gmail drafts create | YES — drafts are safe, not sent |

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.

| Flag | Short | Purpose | When to Use | |------|-------|---------|-------------| | --json | -j | JSON output to stdout | Always for agent use -- structured, parseable | | --plain | -p | TSV output (no colors) | When piping to awk/cut | | --results-only | | Drop envelope (nextPageToken etc.) | Cleaner JSON for single-page results | | --select=FIELDS | | Pick only needed fields (dot paths) | Reduce token cost on large responses | | --account=EMAIL | -a | Target specific account | Multi-account setups | | --dry-run | -n | Preview without executing | Always before destructive ops | | --force | -y | Skip confirmations | Non-interactive pipelines | | --no-input | | Fail instead of prompting | Agent automation (never interactive) | | --verbose | -v | Debug logging | Troubleshooting |

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

Services Overview

| Service | Command | Aliases | Key Operations | |---------|---------|---------|----------------| | Gmail | gog gmail | mail, email | search, get, send, thread, labels, drafts, batch | | Calendar | gog calendar | cal | events, create, search, conflicts, freebusy | | Drive | gog drive | drv | ls, search, upload, download, share, mkdir | | Docs | gog docs | doc | create, cat, write, insert, find-replace | | Slides | gog slides | slide | create, create-from-markdown, export, read-slide | | Sheets | gog sheets | sheet | get, update, append, clear, format, metadata | | Contacts | gog contacts | contact | search, list, create, update | | Tasks | gog tasks | task | lists, list, add, done, update | | Chat | gog chat | | spaces, messages, threads, dm | | People | gog people | person | me, search, get, relations | | Forms | gog forms | form | get, create, responses | | Groups | gog groups | group | list, members | | Classroom | gog classroom | class | courses, students, coursework, submissions | | Apps Script | gog appscript | script | get, content, run, create | | Keep | gog keep | | list, get, search (Workspace only) |

Top-level shortcuts (save keystrokes):

| Shortcut | Expands To | |----------|------------| | gog send | gog gmail send | | gog ls | gog drive ls | | gog search | gog drive search | | gog download | gog drive download | | gog upload | gog drive upload | | gog login | gog auth add | | gog logout | gog auth remove | | gog status | gog auth status | | gog me / gog whoami | gog people me |

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 "person@example.com" --subject "Meeting notes" --body "Here are the notes..." --dry-run

# Then send
gog send --to "person@example.com" --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"