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

Flag	Use
--json	Structured JSON to stdout (always prefer for parsing)
--plain	Stable TSV (tabs, no colors)
(none)	Human-readable table

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.