gog-extended#

Complete reference for the gog CLI with focus on advanced Gmail operations (full email bodies, attachments, complex searches).

Setup (one-time)#

bash

gog auth credentials /path/to/client_secret.json
gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets
gog auth list

Gmail Operations#

Search & Browse#

• Search threads (one row per thread): bash

  gog gmail search 'newer_than:7d' --max 10
  gog gmail search 'from:sender@example.com' --max 20
  
  

• Search individual messages (ignores threading, returns all matches): bash

  gog gmail messages search "in:inbox from:ryanair.com" --max 20 --account you@example.com
  gog gmail messages search 'subject:invoice' --max 50
  
  

Read Full Email Content (Critical for Automation)#

This is the key difference from basic search — retrieve the complete email body, headers, and content:

bash

# Full email with HTML body (recommended for parsing and automation)
gog gmail get <messageId> --format=full --account you@example.com

# Metadata only (faster, no body)
gog gmail get <messageId> --format=metadata --account you@example.com

# Raw RFC 2822 format (MIME encoded)
gog gmail get <messageId> --format=raw --account you@example.com

Recommendation: Use --format=full (default) which returns HTML-formatted email bodies. HTML preserves structure, links, and formatting better than raw RFC 2822, making it easier to parse and extract data programmatically.

Example workflow (extracting order details from email):

bash

# 1. Find the message
gog gmail messages search 'from:order@example.com subject:confirmation' --max 1 --account you@example.com

# 2. Extract the message ID from results
# 3. Read full content (returns HTML body for easy parsing)
gog gmail get <messageId> --format=full --account you@example.com

# 4. Parse HTML for data (grep, sed, or HTML parser)
gog gmail get <messageId> --format=full --account you@example.com | grep -i "order\|price\|quantity"

The HTML format makes it easier to identify structure (tables, divs, links) and extract data without dealing with raw MIME encoding.

Download Attachments#

bash

gog gmail attachment <messageId> <attachmentId>

Get attachment IDs from gog gmail get <messageId> --format=full output.

Send Emails#

• Plain text: bash

  gog gmail send --to a@b.com --subject "Hi" --body "Hello"
  
  

• Multi-line (via file): bash

  gog gmail send --to a@b.com --subject "Hi" --body-file ./message.txt
  
  

• Multi-line (via stdin): bash

  gog gmail send --to a@b.com --subject "Hi" --body-file - <<'EOF'
  Hi there,
  
  This is a test.
  
  Cheers
  EOF
  
  

• HTML: bash

  gog gmail send --to a@b.com --subject "Hi" --body-html "<p>Hello</p>"
  
  

Drafts#

bash

gog gmail drafts create --to a@b.com --subject "Hi" --body-file ./message.txt
gog gmail drafts send <draftId>

Reply to Messages#

bash

gog gmail send --to a@b.com --subject "Re: Hi" --body "Reply" --reply-to-message-id <msgId>

Gmail History (Last Changes)#

bash

gog gmail history --max 100

Gmail URL Links#

bash

gog gmail url <threadId> ...

Prints direct Gmail web URLs.

Calendar Operations#

List Events#

bash

gog calendar events <calendarId> --from 2026-01-01T00:00:00Z --to 2026-12-31T23:59:59Z

Create Event#

bash

gog calendar create <calendarId> --summary "Meeting" --from 2026-03-30T10:00:00Z --to 2026-03-30T11:00:00Z

With color (IDs 1–11):

bash

gog calendar create <calendarId> --summary "Important" --from 2026-03-30T10:00:00Z --to 2026-03-30T11:00:00Z --event-color 4

Update Event#

bash

gog calendar update <calendarId> <eventId> --summary "New Title" --event-color 7

View Color Palette#

bash

gog calendar colors

Color IDs:

• 1: #a4bdfc (blue)
• 2: #7ae7bf (teal)
• 3: #dbadff (purple)
• 4: #ff887c (red)
• 5: #fbd75b (yellow)
• 6: #ffb878 (orange)
• 7: #46d6db (cyan)
• 8: #e1e1e1 (gray)
• 9: #5484ed (dark blue)
• 10: #51b749 (green)
• 11: #dc2127 (dark red)

Drive Operations#

bash

gog drive search "filename:report.pdf" --max 10
gog drive search "in:starred" --max 20

Contacts#

bash

gog contacts list --max 20
gog contacts list --max 50 --json

Sheets#

Read Data#

bash

gog sheets get <sheetId> "Tab!A1:D10" --json
gog sheets metadata <sheetId> --json

Update Data#

bash

gog sheets update <sheetId> "Tab!A1:B2" --values-json '[["A","B"],["1","2"]]' --input USER_ENTERED

Append Data#

bash

gog sheets append <sheetId> "Tab!A:C" --values-json '[["x","y","z"]]' --insert INSERT_ROWS

Clear Data#

bash

gog sheets clear <sheetId> "Tab!A2:Z"

Docs#

Export#

bash

gog docs export <docId> --format txt --out /tmp/doc.txt
gog docs export <docId> --format pdf --out /tmp/doc.pdf

Read (cat)#

bash

gog docs cat <docId>

Advanced Flags#

Common Flags#

• --account you@gmail.com — Target specific account (required when multiple accounts configured)
• --json — Output JSON (best for scripting)
• --plain — Stable TSV format (no colors)
• --dry-run — Preview changes without executing
• --force — Skip confirmations
• --no-input — Never prompt (useful for CI/automation)
• --verbose — Enable verbose logging

Environment Variable#

Avoid repeating --account by setting:

bash

export GOG_ACCOUNT=you@gmail.com

Then:

bash

gog gmail search 'newer_than:7d'  # Uses GOG_ACCOUNT automatically

Gmail Query Syntax#

Powerful search operators for gog gmail search and gog gmail messages search:

• newer_than:7d — Last 7 days
• before:2026-03-30 — Before date
• after:2026-03-20 — After date
• from:sender@example.com — From specific sender
• to:recipient@example.com — To specific recipient
• subject:keywords — Subject contains
• in:inbox — In inbox (also: sent, draft, starred, important)
• is:unread — Unread messages
• has:attachment — Has attachment
• filename:document.pdf — Attachment name
• label:custom_label — Custom labels

Complex queries:

bash

gog gmail search 'from:billing@example.com subject:invoice after:2026-03-01'
gog gmail search 'in:inbox is:unread has:attachment'

Notes#

• Search vs Messages: gog gmail search returns one row per thread; use gog gmail messages search when you need every individual email.
• Multi-account: When multiple accounts are configured, always specify --account email@domain.com.
• Token efficiency: For scripting, use --json output and parse programmatically.
• Email body extraction: Use gog gmail get <messageId> --format=full to retrieve complete email content (critical for automation like order tracking, invoice extraction, etc.).
• Docs are read-only in gog: In-place edits require a separate Docs API client; gog supports export and read-only operations.