gog-cli

Original：🇺🇸 English
Translated

This skill provides comprehensive instructions for using gogcli (gog), a fast, script-friendly CLI for Google Workspace services including Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, Classroom, Contacts, Tasks, People, Groups, and Keep. This skill should be used when the user wants to interact with Google services via the command line, including reading/sending email, managing calendar events, working with Google Drive files, managing classroom courses, or any other Google Workspace operations. The skill assumes gog is installed and authorised.

7installs
Sourceintellectronica/agent-skills
Added on

NPX Install

npx skill4agent add intellectronica/agent-skills gog-cli

Tags

Translated version includes tags in frontmatter
gogcligoogle-workspacecli-toolscript-automationmulti-account-management

SKILL.md Content

View Translation Comparison →

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 user@gmail.com --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

bash
--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

bash
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

bash
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

bash
# 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

bash
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

bash
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

bash
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

bash
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

bash
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

bash
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

bash
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

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

Classroom

bash
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

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

Environment Variables

bash
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

bash
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

bash
# 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:
ErrorCauseSolution
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:
bash
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