gog-advanced

Use gog (gogcli) for Google Workspace: Gmail, Calendar, Drive, Contacts, Sheets, Docs.

This skill is optimized for agent reliability:

• Prefer list/inspect first, don’t assume resource IDs.
• Prefer --json for parsing; treat human tables as fallback.
• For “agenda / today / tomorrow / this week” questions: search across ALL calendars by default.
• For write actions (send email, create/update events, modify Drive/Sheets/Docs): confirm intent and summarize the exact action first.

Prereqs / Setup (once)

1. Store OAuth client credentials:

• gog auth credentials /path/to/client_secret.json

1. Add an account (request only needed services):

• gog auth add you@gmail.com --services gmail,calendar,drive,contacts,sheets,docs

1. Make account default to avoid repeating flags:

• export GOG_ACCOUNT=you@gmail.com

Notes:

• CLI help is discoverable: gog --help, gog calendar --help, etc.
• gog supports multiple accounts; use --account or GOG_ACCOUNT. (Prefer env var.)

Global agent rules (non-negotiable)

1. Calendar agenda queries

   • If user asks “what’s on my calendar today / tomorrow / this week / next N days”:
     • Run: gog calendar events --all --today|--tomorrow|--week|--days N --json
     • If results are empty, only then troubleshoot (timezone, account, auth status).
   • Only use a specific calendarId if the user explicitly asks for a specific calendar or name.

2. Calendar identification

   • If you need a calendarId (because the user wants a specific calendar):
     • Run: gog calendar calendars --json
     • Match by calendar name/summary and then query that calendarId.

3. Timezone

   • For date-scoped queries, be explicit with --today/--tomorrow/--week/--days when possible.
   • If user’s timezone matters or results look off, check with:
     • gog calendar time --timezone <IANA_TZ>
   • Prefer returning times in user-local timezone if JSON includes localized fields.

4. Writes require confirmation

   • Before:
     • gog gmail send ...
     • gog calendar create ...
     • gog calendar update ...
     • any Sheets update/append/clear
   • Do a “plan” message: recipients/calendar, subject/summary, time range, and ask for “yes”.

High-signal command recipes

Calendar: “What’s on my calendar today?”

Default: all calendars.

• gog calendar events --all --today --json

Tomorrow / week / next 3 days:

• gog calendar events --all --tomorrow --json
• gog calendar events --all --week --json
• gog calendar events --all --days 3 --json

Search events across time window (keyword):

• gog calendar search "standup" --days 30 --json
• gog calendar search "meeting" --from 2026-02-01T00:00:00Z --to 2026-03-01T00:00:00Z --max 50 --json

Specific calendar (only when asked):

1. Find calendarId:

• gog calendar calendars --json

1. Query it:

• gog calendar events <calendarId> --today --json

Gmail: search + read + send (confirm sends)

Search:

• gog gmail search 'newer_than:7d' --max 10 --json
• gog gmail search 'from:boss@example.com newer_than:30d' --max 20 --json

Send (REQUIRES CONFIRMATION FIRST):

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

Drive: find files

• gog drive search "invoice" --max 10 --json

Contacts: list/search

• gog contacts list --max 50 --json

Sheets: safe read/write (confirm writes)

Read:

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

Update (REQUIRES CONFIRMATION FIRST):

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

Append (REQUIRES CONFIRMATION FIRST):

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

Clear (REQUIRES CONFIRMATION FIRST):

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

Docs: export/cat

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

Troubleshooting checklist (fast)

If calendar results look wrong or empty:

1. Confirm account:

• gog auth status

1. List calendars to confirm visibility:

• gog calendar calendars --json

1. Ensure you used all-calendars for agenda:

• gog calendar events --all --today --json

1. If still empty, verify timezone assumptions:

• gog calendar time --timezone <IANA_TZ>