gogcli (gog) CLI

A fast, script-friendly CLI for Google Workspace services with JSON-first output and multi-account support.

Repository: https://github.com/steipete/gogcli

Prerequisites

This skill assumes gog is installed and authorised. If commands fail with authentication errors, inform the user they need to:

• Install gog: brew install steipete/tap/gogcli


• Store OAuth credentials: gog auth credentials <path-to-credentials.json>


• Add account: gog auth add user@gmail.com --services all

Supported Services

Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat (Workspace), Classroom, Contacts, Tasks, People, Groups (Workspace), Keep (Workspace, service account only).

Quick Reference

Global Flags

--account <email>    # Select account
--client <name>      # Select OAuth client
--json               # JSON output
--plain              # TSV output (for scripting)
--force              # Skip confirmations
--no-input           # Fail instead of prompting

Common Patterns

gog --account work@example.com gmail search "is:unread"  # Use specific account
gog gmail search "is:unread" --json | jq '.threads[].id' # JSON for parsing
gog gmail search "is:unread" --plain | cut -f1           # Plain for shell
gog gmail search "is:unread" --max 10 --page <token>     # Pagination

Gmail

Search and Read

gog gmail search "is:unread from:boss@example.com newer_than:7d"
gog gmail messages search "is:unread" --include-body
gog gmail thread get <threadId>
gog gmail get <messageId> --format full

Send Email

# Basic send
gog gmail send --to user@example.com --subject "Hello" --body "Message"
# With HTML and attachments
gog gmail send --to user@example.com --subject "Report" \
  --body-html "<h1>Report</h1>" --attach ~/report.pdf
# Reply
gog gmail send --to user@example.com --subject "Re: Original" \
  --body "Reply" --reply-to-message-id <messageId>

Labels

gog gmail labels list
gog gmail labels create "Project/Subproject"
gog gmail thread modify <threadId> --add "Label" --remove INBOX

For full Gmail reference including drafts, filters, vacation, delegates, tracking, and watch, see references/gmail.md.

Calendar

Events

gog calendar events primary --from "2024-12-01" --to "2024-12-31" --weekday
gog calendar events primary --query "meeting"
# Create event
gog calendar create primary --summary "Meeting" \
  --from "2024-12-20T14:00:00" --to "2024-12-20T15:00:00"
# With attendees and recurrence
gog calendar create primary --summary "Weekly Standup" \
  --from "2024-12-20T09:00:00" --to "2024-12-20T09:30:00" \
  --attendees "alice@example.com,bob@example.com" \
  --rrule "FREQ=WEEKLY;BYDAY=MO,WE,FR"
# Respond
gog calendar respond primary <eventId> --status accepted

Special Event Types

gog calendar focus-time create primary --from DT --to DT --auto-decline
gog calendar ooo create primary --from DT --to DT --decline-message "Away"
gog calendar working-location create primary --from DT --to DT --location home

For full Calendar reference, see references/calendar.md.

Drive, Docs, Sheets, Slides

Drive

gog drive ls --parent <folderId>
gog drive search "quarterly report"
gog drive download <fileId> --out ~/Downloads/
gog drive upload ~/report.pdf --parent <folderId>
gog drive mkdir "New Folder" --parent <folderId>
gog drive share <fileId> --email user@example.com --role writer

Sheets

gog sheets read <spreadsheetId> "Sheet1!A1:D10"
gog sheets write <spreadsheetId> "Sheet1!A1:B2" --values '[["Name","Age"],["Alice",30]]'
gog sheets append <spreadsheetId> "Sheet1!A:B" --values '[["Bob",25]]'
gog sheets format <spreadsheetId> "Sheet1!A1:D1" --bold --bg-color "#FFCC00"

Export

gog docs export <documentId> --format pdf --out ~/doc.pdf
gog slides export <presentationId> --format pptx --out ~/slides.pptx

For full Drive/Docs/Sheets/Slides reference, see references/drive-docs.md.

Tasks

gog tasks lists
gog tasks list <tasklistId>
gog tasks add <tasklistId> --title "Buy groceries" --due "2024-12-20"
gog tasks add <tasklistId> --title "Weekly review" --due "2024-12-20" --repeat weekly
gog tasks done <tasklistId> <taskId>

Contacts

gog contacts search "john"
gog contacts create --given "John" --family "Doe" --email "john@example.com"
gog contacts directory search "smith"  # Workspace

Classroom

gog classroom courses --state ACTIVE
gog classroom students <courseId>
gog classroom coursework create <courseId> --title "Homework" --type ASSIGNMENT --due "2024-12-31T23:59:59Z"
gog classroom submissions grade <courseId> <courseworkId> <submissionId> --grade 95

For Classroom, Chat, Contacts, Tasks, People, Groups, Keep, see references/other-services.md.

Configuration

Config Locations

• macOS: ~/Library/Application Support/gogcli/config.json
• Linux: ~/.config/gogcli/config.json
• Windows: %AppData%\gogcli\config.json

Settings

gog config set default_timezone America/New_York
gog config set default_account user@gmail.com
gog config list

Environment Variables

GOG_ACCOUNT=user@gmail.com      # Default account
GOG_CLIENT=work                 # OAuth client
GOG_JSON=1                      # Default JSON output
GOG_PLAIN=1                     # Default plain output
GOG_TIMEZONE=America/New_York   # Display timezone
GOG_ENABLE_COMMANDS=calendar,tasks  # Command allowlist

For full configuration, see references/configuration.md.

Multi-Account Usage

gog --account work@example.com gmail search "is:unread"
gog auth alias set work work@example.com
gog --account work gmail search "is:unread"
gog auth list --check

For authentication including service accounts, see references/authentication.md.

Scripting

# JSON processing
gog gmail search "is:unread" --json | jq -r '.threads[].id'
# Batch operations
gog gmail search "older_than:30d" --json | \
  jq -r '.threads[].id' | \
  xargs -I {} gog gmail thread modify {} --add Archive --remove INBOX
# Non-interactive
gog gmail send --to user@example.com --subject "Test" --body "Hi" --force

Troubleshooting

If commands fail, inform the user of the likely cause:

| Error | Cause | Solution |
|-------|-------|----------|
| no credentials | OAuth not configured | gog auth credentials <file> |
| token expired | Auth invalid | gog auth add <email> --force-consent |
| insufficient scope | Missing permissions | gog auth add <email> --services <services> |
| command not found | Not installed | brew install steipete/tap/gogcli |

Status checks:

gog auth list --check
gog auth status

Reference Files

• references/command-reference.md - Complete command specification
• references/authentication.md - Auth, credentials, multi-account
• references/configuration.md - Config and environment variables
• references/gmail.md - Gmail operations
• references/calendar.md - Calendar operations
• references/drive-docs.md - Drive, Docs, Sheets, Slides
• references/other-services.md - Classroom, Chat, Contacts, Tasks, People, Groups, Keep