gog · diff
git:20260622.0e31064 to git:20260913.0fe7e6c
16 added, 0 removed. Audit A to A.
---
name: gog
description: "Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs."
homepage: https://gogcli.sh
metadata:
{
"openclaw":
{
"emoji": "🎮",
"requires": { "bins": ["gog"] },
"install":
[
{
"id": "brew",
"kind": "brew",
"formula": "gogcli",
"bins": ["gog"],
"label": "Install gog (brew)",
},
],
},
}
---
# gog
Use `gog` for Gmail/Calendar/Drive/Contacts/Sheets/Docs. Requires OAuth setup.
+ Prefer an already-authorized host account: run the requested `gog` command first. Enter setup only after an authentication error. Never ask for passwords, client secrets, or refresh tokens in chat.
+
Setup (once)
- `gog auth credentials /path/to/client_secret.json`
- `gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets`
- `gog auth list`
+
+ Remote / headless Gateway hosts
+
+ When the Gateway host has no local browser display:
+
+ 1. Prefer a live callback listener on the Gateway host. From the machine with the browser, forward the exact callback port (`ssh -L <port>:127.0.0.1:<port> user@gateway-host`), open the authorization URL `gog` prints, and let the redirect complete on that forwarded port.
+ 2. When a live listener is unavailable, the operator picks one paste-mode path in a trusted shell on the Gateway host. Callback URLs must never enter chat or agent tool input:
+ - `--manual`: the operator pastes the full redirect URL into `gog`'s interactive prompt.
+ - `--remote --step 1`: prints `auth_url` (and `state_reused`) then exits. After browser consent, the operator runs `--remote --step 2 --auth-url <callback-url>` in the trusted shell. A failed `localhost` page load after consent is expected.
+ 3. Keep the same resolved config context across remote steps: `GOG_CONFIG_DIR` takes precedence over `--home`, which takes precedence over `GOG_HOME`. Also preserve `--client`, services/scopes, redirect URI, and consent options. Matching unexpired manual state may be reused (`state_reused=true`).
+ 4. If desktop keyring is unavailable, configure the file backend (`gog auth keyring file`) and set `GOG_KEYRING_PASSWORD` in the Gateway environment so non-interactive agent/`--no-input` runs can read tokens. `gog auth doctor` reports when the password is missing.
+ 5. Callback received is not the same as token stored. If token exchange or identity lookup fails behind a proxy, restart from step 1 after the operator approves scoped egress or proxy exceptions for the required Google endpoints. Do not bypass host network policy or reuse failed or expired state.
+
+ For diagnostics, inspect every entry reported by `gog auth list --check`; its exit status does not prove every stored token is valid. Likewise, inspect the status reported by `gog auth doctor` rather than relying only on its exit code.
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 you@example.com`
- Gmail send (plain): `gog gmail send --to a@b.com --subject "Hi" --body "Hello"`
- Gmail send (multi-line): `gog gmail send --to a@b.com --subject "Hi" --body-file ./message.txt`
- Gmail send (stdin): `gog gmail send --to a@b.com --subject "Hi" --body-file -`
- Gmail send (HTML): `gog gmail send --to a@b.com --subject "Hi" --body-html "<p>Hello</p>"`
- Gmail draft: `gog gmail drafts create --to a@b.com --subject "Hi" --body-file ./message.txt`
- Gmail send draft: `gog gmail drafts send <draftId>`
- Gmail reply: `gog gmail send --to a@b.com --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):
```bash
gog gmail send --to recipient@example.com \
--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):
```bash
gog gmail send --to recipient@example.com \
--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=you@gmail.com` 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.