Manage Google Workspace (Gmail, Calendar, Drive, Contacts, Sheets, Docs) with the gog CLI

How to use

The metadata declares that gog can be installed with the gogcli Homebrew formula.

Docs supports export, cat, and copy; in-place edits require a Docs API client, which is not part of gog.

Run the setup steps once: gog auth credentials /path/to/client_secret.json, gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets, and gog auth list. When sending Gmail, prefer plain text: pass multi-paragraph messages with --body-file (or --body-file - for stdin), and the same --body-file pattern also works for drafts and replies. Note that --body does not unescape \n, so for inline newlines use a heredoc or $'Line 1\n\nLine 2'; use --body-html only when you need rich formatting. For example, a plain-text message can be sent via stdin, and an HTML list can be sent with --body-html instead. For Calendar, use gog calendar colors to see all available event colors (IDs 1–11) and add colors to events with the --event-color <id> flag; the color IDs from the gog calendar colors output are: 1: #a4bdfc, 2: #7ae7bf, 3: #dbadff, 4: #ff887c, 5: #fbd75b, 6: #ffb878, 7: #46d6db, 8: #e1e1e1, 9: #5484ed, 10: #51b749, and 11: #dc2127.

Setup is performed once, starting with gog auth credentials /path/to/client_secret.json.

Setup then continues with gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets.

Finish setup with gog auth list.

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>

Use gog calendar colors to see all available event colors (IDs 1–11).

Add colors to events with the --event-color <id> flag.

Event color IDs come from the gog calendar colors output.

Color ID 1 is #a4bdfc.

Color ID 2 is #7ae7bf.

Color ID 3 is #dbadff.

Color ID 4 is #ff887c.

Color ID 5 is #fbd75b.

Color ID 6 is #ffb878.

Color ID 7 is #46d6db.

Color ID 8 is #e1e1e1.

Color ID 9 is #5484ed.

Color ID 10 is #51b749.

Color ID 11 is #dc2127.

Prefer plain text when sending Gmail; use --body-file for multi-paragraph messages (or --body-file - for stdin).

The 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.

A plain-text message can be sent via stdin as shown in the example.

  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

An HTML list can be sent with --body-html as shown in the example.

  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>"

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.

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.