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:

1. Install gog: brew install steipete/tap/gogcli
2. Store OAuth credentials: gog auth credentials <path-to-credentials.json>
3. Add account: gog auth add [email protected] --services all

Do not attempt to resolve authentication issues automatically. Provide the user with the relevant command and let them handle it.

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 [email protected] 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:[email protected] 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 [email protected] --subject "Hello" --body "Message"

# With HTML and attachments
gog gmail send --to [email protected] --subject "Report" \
  --body-html "<h1>Report</h1>" --attach ~/report.pdf

# Reply
gog gmail send --to [email protected] --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 "[email protected],[email protected]" \
  --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 [email protected] --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 "[email protected]"
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 [email protected]
gog config list

Environment Variables

GOG_ACCOUNT=[email protected]      # 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 [email protected] gmail search "is:unread"
gog auth alias set work [email protected]
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 [email protected] --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