gog-cli

name	gog-cli
description	Google Workspace CLI for Gmail, Calendar, Drive, Docs, Sheets, Tasks, and more

gog-cli Skill

Fast, script-friendly CLI for Google Workspace services: Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, Classroom, Contacts, Tasks, People, Groups, and Keep.

Prerequisites

# Install
brew install steipete/tap/gogcli

# Authenticate (requires OAuth credentials from Google Cloud Console)
gog auth credentials <path/to/client_secret.json>
gog auth add [e-mail] --services all

Core Principles

1. Always use --json for parsing command output - human-readable output is for display only
2. Verify before destructive operations - list/search before delete/modify
3. Use --force only when explicitly requested by user
4. Check account context with gog auth status when working across multiple accounts

Quick Reference

Service	List	Get	Create	Search
Gmail	gog gmail search "..."	gog gmail thread get <id>	gog gmail send ...	Same as list
Calendar	gog calendar events <cal>	gog calendar event <cal> <id>	gog calendar create <cal>	--query flag
Drive	gog drive ls	gog drive get <id>	gog drive upload <file>	gog drive search "..."
Tasks	gog tasks list <listId>	gog tasks get <list> <id>	gog tasks add <list>	N/A
Contacts	gog contacts list	gog contacts get <id>	gog contacts create	gog contacts search "..."

Common Workflows

Email Management

# Search unread emails
gog gmail search "is:unread" --json

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

# Send email with attachment
gog gmail send --to [e-mail] --subject "Subject" --body "Message" --attach file.pdf

# Reply to thread
gog gmail send --to [e-mail] --subject "Re: Subject" --body "Reply" --reply-to-message-id <msgId>

# Apply label
gog gmail thread modify <threadId> --add "Label Name"

Calendar Operations

# List today's events
gog calendar events primary --from "$(date +%Y-%m-%d)T00:00:00" --to "$(date +%Y-%m-%d)T23:59:59" --json

# Create event with attendees
gog calendar create primary --summary "Meeting" --from "2024-12-20T14:00:00" --to "2024-12-20T15:00:00" --attendees "[e-mail]"

# Check availability
gog calendar freebusy "[e-mail],[e-mail]" --from <start> --to <end> --json

# Accept invitation
gog calendar respond primary <eventId> --status accepted

File Operations

# Search files
gog drive search "quarterly report" --json

# Download file
gog drive download <fileId> --out ~/Downloads/

# Upload to folder
gog drive upload file.pdf --parent <folderId>

# Share file
gog drive share <fileId> --email [e-mail] --role writer

Spreadsheet Operations

# Read range
gog sheets read <spreadsheetId> "Sheet1!A1:D10" --json

# Write data (JSON array of arrays)
gog sheets write <spreadsheetId> "Sheet1!A1" --values '[["Name","Value"],["Alice",100]]'

# Append rows
gog sheets append <spreadsheetId> "Sheet1!A:B" --values '[["New","Row"]]'

Output Modes

Flag	Format	Use Case
(none)	Human-readable	Display to user
--json	JSON	Parsing, scripting
--plain	TSV	Shell piping

Multi-Account Usage

# Specify account per command
gog --account [e-mail] gmail search "is:unread"

# Set default via environment
export GOG_ACCOUNT=[e-mail]

# Use aliases
gog auth alias set work [e-mail]
gog --account work gmail search "is:unread"

Error Recovery

Error	Solution
Token expired	gog auth add [e-mail] --force-consent
Wrong scopes	Re-add with required services: --services gmail,calendar,drive
Rate limited	Wait and retry; use --max to limit batch sizes

Safety Guidelines

Destructive operations requiring confirmation:

• gog drive delete - moves to trash
• gog calendar delete - removes event
• gog gmail filters delete - removes filter rule

Prefer these safe patterns:

1. Search/list before modifying: gog gmail search "..." --json then modify
2. Use labels over delete: gog gmail thread modify <id> --add Archive --remove INBOX
3. Download before deleting: gog drive download <id> then gog drive delete <id>

References

• Command Reference - Complete command syntax
• Gmail Operations - Search syntax, sending, labels
• Calendar Operations - Events, availability, recurrence
• Drive & Docs - Files, Sheets, export
• Authentication - Multi-account, service accounts
• Configuration - Environment variables, output formats
• Other Services - Tasks, Contacts, Chat, Classroom