documents/dev/gog.md

Table of Contents

Gog — Google Workspace CLI

CLI for accessing Gmail, Calendar, Drive, Contacts, Docs, and Sheets from the terminal.

Installation

brew install gogcli/tap/gogcli

OAuth Setup

GCP Project

  • Project: general-ai-testing (general-ai-testing-451915)
  • OAuth Client: Desktop app type, named "gog CLI"
  • Consent Screen: Testing mode, test user: dominick.pham@gmail.com

Credentials File

~/.config/gog/client_secret_598032504491-8b54ss1d7mr30gi8r2nhc3pp8vj9ulgp.apps.googleusercontent.com.json

Auth Flow

# Register the client secret
gog auth credentials ~/.config/gog/client_secret_*.json

# Authenticate (opens browser for OAuth consent)
gog auth add dominick.pham@gmail.com --services gmail,calendar,drive,contacts,docs,sheets

Auth Data Location

  • Credentials config: ~/Library/Application Support/gogcli/credentials.json
  • OAuth tokens: ~/Library/Application Support/gogcli/

Authorized Account

  • Email: dominick.pham@gmail.com
  • Services: calendar, contacts, docs, drive, gmail, sheets
  • Auth: OAuth 2.0 with refresh token

Basic Usage

Auth Management

gog auth list                          # List authenticated accounts
gog auth remove <email>                # Remove an account

Gmail

gog gmail list                         # List recent messages
gog gmail list --max-results 20        # Control count
gog gmail send --to "x@y.com" --subject "Hi" --body "Hello"
gog gmail search "subject:meeting"     # Search messages

Calendar

gog calendar list                      # Upcoming events
gog calendar list --max-results 10     # Limit results
gog calendar list --time-min "2026-05-13T00:00:00Z"

Drive

gog drive list                         # Recent files
gog drive search "query"               # Search files
gog drive download <file-id>           # Download file

Contacts

gog contacts list                      # List contacts
gog contacts search "name"             # Search contacts

Docs & Sheets

gog docs list                          # List recent docs
gog sheets list                        # List recent sheets

Troubleshooting

OAuth Callback Refused

If the browser redirects to 127.0.0.1:<port> and gets "connection refused":

  1. Copy the full callback URL from the browser's address bar
  2. Paste it in the terminal where gog auth add is running
  3. The local server is already listening and will pick it up

Testing Mode Block

If Google rejects auth with a verification error:

  • Go to GCP Console → APIs & Services → OAuth consent screen
  • Add your email as a Test user under Testing mode
  • Wait a minute and retry

Wrong Project / Account

The OAuth client must be in a GCP project owned by the Google account you're authenticating. If auth fails or the consent screen isn't accessible, check the project ownership.

History

  • 2026-05-13: Initial setup under general-ai-testing project
    • First attempt used wrong GCP project (qwestly-gmail-addon)
    • Migrated to general-ai-testing which Dom owns personally