gog

name	gog
description	Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.
homepage	https://gogcli.sh

gog

Use gog for Gmail/Calendar/Drive/Contacts/Sheets/Docs. Requires OAuth setup.

Setup (once)

• gog auth credentials /path/to/client_secret.json
• gog auth add [e-mail] --services gmail,calendar,drive,contacts,docs,sheets
• gog auth list

Headless / token-refresh recovery

• gog auth status only confirms local config/credential presence. It does NOT prove the refresh token is still good.
• If real API calls fail with invalid_grant, re-run auth instead of trusting auth status.
• For remote/headless reauth, use a two-step flow that prints a browser URL:
  • Step 1: gog auth add [e-mail] --remote --step=1 --services=drive,docs --readonly --json --no-input
  • Extract auth_url from the JSON and send that exact URL to the user.
  • Tell the user to approve access and then paste back the full final redirected URL from the browser address bar.
  • Step 2: gog auth add [e-mail] --remote --step=2 --auth-url 'PASTED_REDIRECT_URL' --services=drive,docs --readonly --json --no-input
• Important: step 2 must be run with the same auth-shaping flags as step 1 (--services, --readonly, --drive-scope, --gmail-scope, --force-consent, and any redirect override), or gog will reject it with manual auth state mismatch.
• If Google lands on a localhost callback error page after approval, that's expected in this flow; the user should still copy the full URL.
• Use the narrowest --services set you need (drive,docs is enough for reading a Google Doc itinerary).
• Debugging remote auth state failures:
  • gog stores remote/manual step-1 state under ~/.config/gogcli/oauth-manual-state-<STATE>.json.
  • manual auth state missing means that file is absent/expired (TTL is about 10 minutes) or unreadable.
  • manual auth state mismatch usually means the cached file's client, scopes, force_consent, or redirect_uri does not exactly match the step-2 invocation / pasted redirect URL.
  • You can inspect or reconstruct that JSON file in emergencies using the returned state value, exact scopes from a --dry-run, and the redirect URI from the pasted callback URL, then rerun step 2 with matching flags.

Common commands

• Gmail search: gog gmail search 'newer_than:7d' --max 10
• Gmail messages search (per email, ignores threading): gog gmail messages search "in:inbox from:ryanair.com" --max 20 --account [e-mail]
• Gmail send (plain): gog gmail send --to [e-mail] --subject "Hi" --body "Hello"
• Gmail send (multi-line): gog gmail send --to [e-mail] --subject "Hi" --body-file ./message.txt
• Gmail send (stdin): gog gmail send --to [e-mail] --subject "Hi" --body-file -
• Gmail send (HTML): gog gmail send --to [e-mail] --subject "Hi" --body-html "<p>Hello</p>"
• Gmail draft: gog gmail drafts create --to [e-mail] --subject "Hi" --body-file ./message.txt
• Gmail send draft: gog gmail drafts send <draftId>
• Gmail reply: gog gmail send --to [e-mail] --subject "Re: Hi" --body "Reply" --reply-to-message-id <msgId>
• Calendar list events: gog calendar events <calendarId> --from <iso> --to <iso>
• Calendar create event: gog calendar create <calendarId> --summary "Title" --from <iso> --to <iso>
• Calendar create with color: gog calendar create <calendarId> --summary "Title" --from <iso> --to <iso> --event-color 7
• Calendar update event: gog calendar update <calendarId> <eventId> --summary "New Title" --event-color 4
• Calendar show colors: gog calendar colors
• Drive search: gog drive search "query" --max 10
• Contacts: gog contacts list --max 20
• Sheets get: gog sheets get <sheetId> "Tab!A1:D10" --json
• Sheets update: gog sheets update <sheetId> "Tab!A1:B2" --values-json '[["A","B"],["1","2"]]' --input USER_ENTERED
• Sheets append: gog sheets append <sheetId> "Tab!A:C" --values-json '[["x","y","z"]]' --insert INSERT_ROWS
• Sheets clear: gog sheets clear <sheetId> "Tab!A2:Z"
• Sheets metadata: gog sheets metadata <sheetId> --json
• Docs export: gog docs export <docId> --format txt --out /tmp/doc.txt
• Docs cat: gog docs cat <docId>

Calendar Colors

• Use gog calendar colors to see all available event colors (IDs 1-11)
• Add colors to events with --event-color <id> flag
• Event color IDs (from gog calendar colors output):
  • 1: #a4bdfc
  • 2: #7ae7bf
  • 3: #dbadff
  • 4: #ff887c
  • 5: #fbd75b
  • 6: #ffb878
  • 7: #46d6db
  • 8: #e1e1e1
  • 9: #5484ed
  • 10: #51b749
  • 11: #dc2127

Email Formatting

• Prefer plain text. Use --body-file for multi-paragraph messages (or --body-file - for stdin).

• Same --body-file pattern works for drafts and replies.

• --body does not unescape \n. If you need inline newlines, use a heredoc or $'Line 1\n\nLine 2'.

• Use --body-html only when you need rich formatting.

• HTML tags: <p> for paragraphs, <br> for line breaks, <strong> for bold, <em> for italic, <a href="url"> for links, <ul>/<li> for lists.

• Example (plain text via stdin):

  gog gmail send --to [e-mail] \
    --subject "Meeting Follow-up" \
    --body-file - <<'EOF'
  Hi Name,
  
  Thanks for meeting today. Next steps:
  - Item one
  - Item two
  
  Best regards,
  Your Name
  EOF
  

• Example (HTML list):

  gog gmail send --to [e-mail] \
    --subject "Meeting Follow-up" \
    --body-html "<p>Hi Name,</p><p>Thanks for meeting today. Here are the next steps:</p><ul><li>Item one</li><li>Item two</li></ul><p>Best regards,<br>Your Name</p>"
  

Notes

• Set GOG_ACCOUNT=[e-mail] to avoid repeating --account.
• For scripting, prefer --json plus --no-input.
• Sheets values can be passed via --values-json (recommended) or as inline rows.
• Docs supports export/cat/copy. In-place edits require a Docs API client (not in gog).
• Confirm before sending mail or creating events.
• gog gmail search returns one row per thread; use gog gmail messages search when you need every individual email returned separately.