gogcli

name: gogcli description: "Google Workspace CLI for agents. Use gog to access Gmail, Calendar, Drive, Contacts, Tasks, Sheets, Docs, Slides, Forms, Chat, and more. Triggers on: 'check my email', 'what's on my calendar', 'search gmail', 'list calendar events', 'send email', 'check tasks', 'search drive', 'list contacts', 'create event', 'upload to drive', 'read spreadsheet', or any Google Workspace task."

gogcli — Google Workspace in the Terminal

gog is a fast, JSON-first CLI for the full Google Workspace suite. Always use --json for structured output when parsing results.

Environment

export GOG_ACCOUNT=joelhooks@gmail.com
export GOG_KEYRING_PASSWORD=$(secrets lease gog_keyring_password )

Both vars are required for every gog command. Lease the keyring password from agent-secrets before use.

Quick Reference

Gmail

# Search (default: threads)
gog gmail search 'newer_than:1d' --max 10 --json
gog gmail search 'is:unread' --max 20 --json
gog gmail search 'from:someone@example.com newer_than:7d' --max 10 --json

# Message-level search with bodies
gog gmail messages search 'is:unread' --max 5 --include-body --json

# Read thread
gog gmail thread get <threadId> --json

# Send
gog gmail send --to user@example.com --subject "Subject" --body "Body text"
gog gmail send --to user@example.com --subject "Hi" --body-html "<p>Hello</p>"

# Labels
gog gmail labels list --json
gog gmail thread modify <threadId> --add STARRED --remove INBOX

Calendar

# Today / this week
gog calendar events primary --today --json
gog calendar events primary --week --json
gog calendar events primary --tomorrow --json
gog calendar events primary --days 7 --json

# All calendars
gog calendar events --all --today --json

# Search
gog calendar search "meeting" --today --json

# Create event
gog calendar create primary \
  --summary "Meeting" \
  --from 2025-01-15T10:00:00Z \
  --to 2025-01-15T11:00:00Z \
  --attendees "alice@example.com"

# Check availability
gog calendar freebusy --calendars "primary" \
  --from 2025-01-15T00:00:00Z --to 2025-01-16T00:00:00Z --json

# List calendars
gog calendar calendars --json

Drive

gog drive ls --max 20 --json
gog drive search "invoice" --max 20 --json
gog drive upload ./file.pdf --parent <folderId>
gog drive download <fileId> --out ./file.pdf
gog drive mkdir "New Folder"

Tasks

gog tasks lists --json
gog tasks list <tasklistId> --max 50 --json
gog tasks add <tasklistId> --title "New task"
gog tasks done <tasklistId> <taskId>

Contacts

gog contacts search "Name" --max 10 --json
gog contacts list --max 50 --json

Sheets

gog sheets metadata <spreadsheetId> --json
gog sheets get <spreadsheetId> 'Sheet1!A1:B10' --json
gog sheets update <spreadsheetId> 'A1' 'val1|val2,val3|val4'
gog sheets append <spreadsheetId> 'Sheet1!A:C' 'new|row|data'

Docs / Slides

gog docs cat <docId>                           # Read doc as text
gog docs export <docId> --format pdf --out doc.pdf
gog slides export <presentationId> --format pdf --out deck.pdf

Chat (Workspace only)

gog chat spaces list --json
gog chat messages list spaces/<spaceId> --max 10 --json
gog chat dm send user@company.com --text "message"

Output Modes

Errors/progress go to stderr. Pipe --json output through jq for filtering.

Patterns

Batch Gmail search → summarize

gog gmail messages search 'is:unread newer_than:1d' --max 20 --include-body --json | jq '.messages[] | {from, subject, body}'

Find next free slot

gog calendar freebusy --calendars "primary" --from today --to tomorrow --json

Today's agenda

gog calendar events primary --today --json | jq '.events[] | {summary, start: .start.dateTime, end: .end.dateTime}'

Auth Setup (one-time)

If gog returns auth errors:

export GOG_KEYRING_PASSWORD=$(secrets lease gog_keyring_password )
gog auth add joelhooks@gmail.com --services user
# Complete OAuth in browser, then verify:
gog auth list --check

Troubleshooting

• "Secret not found": Keyring password not set. Export GOG_KEYRING_PASSWORD.
• "No auth for gmail": Need gog auth add <email> --services gmail (or user for all).
• 403 insufficient scopes: Re-auth with --force-consent to add missing scopes.
• Keychain locked: This system uses file backend. Set GOG_KEYRING_PASSWORD env var.