gog

name	gog
description	Google Workspace from the terminal — Gmail (search, read, summarize, draft, send) and Google Sheets (read, write, update, append), plus Calendar/Drive/Docs. Use this whenever the task involves the user's Google account.
metadata	{"crablite":{"requires":{"bins":["gog"]}}}

gog — Gmail & Google Sheets

Drive Google Workspace by shelling out to the gog CLI with the exec tool. Requires a one-time OAuth setup (see the end). Prefer --json output for anything you need to parse.

⚠️ Sending policy (read this first)

• Never send an email without explicit user confirmation. Default to creating a DRAFT, show the user exactly what you'll send (recipient, subject, body), and only send after they clearly say yes.
• The same applies to creating calendar events. Read/search freely; write/send only after a "yes".

Gmail

• Search threads: gog gmail search 'newer_than:7d from:[e-mail]' --max 10
• Search individual messages (ignores threading): gog gmail messages search "in:inbox is:unread" --max 20
• Read a message: gog gmail messages get <messageId> (or open a thread: gog gmail threads get <threadId>)
• Draft (preferred): gog gmail drafts create --to [e-mail] --subject "Hi" --body-file - <<'EOF' … EOF
• Send a draft after confirmation: gog gmail drafts send <draftId>
• Send directly (only after explicit confirmation): gog gmail send --to [e-mail] --subject "Hi" --body "Hello"
• Reply: gog gmail send --to [e-mail] --subject "Re: Hi" --body "..." --reply-to-message-id <msgId>
• Multi-line/HTML bodies: use --body-file - (stdin heredoc) for plain text, or --body-html "<p>…</p>".

To summarize a conversation: gog gmail threads get <threadId> --json, read the messages, and write a concise summary. Offer to draft a reply.

Google Sheets

• Read a range: gog sheets get <sheetId> "Tab!A1:D20" --json
• Update a range: gog sheets update <sheetId> "Tab!A1:B2" --values-json '[["A","B"],["1","2"]]' --input USER_ENTERED
• Append rows: gog sheets append <sheetId> "Tab!A:C" --values-json '[["x","y","z"]]' --insert INSERT_ROWS
• Clear a range: gog sheets clear <sheetId> "Tab!A2:Z"
• Sheet metadata (tab names/ids): gog sheets metadata <sheetId> --json

Tips

• Set GOG_ACCOUNT=[e-mail] to avoid repeating --account.
• For scripting, add --json --no-input.
• If a command fails with an auth error, the user needs to run the one-time setup below.

One-time setup (the user does this once)

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

client_secret.json is a Google Cloud OAuth Desktop app credential. Tokens are stored in gog's encrypted keyring (persisted in the crablite state volume in Docker).