Joelclaw gogcli

Google Workspace CLI for agents. Use gog to access Gmail, Calendar, Drive, Contacts, Tasks, Sheets, Docs, Slides, Forms, Chat, and more. Triggers on: 'check my email', 'what's on my calendar', 'search gmail', 'list calendar events', 'send email', 'check tasks', 'search drive', 'list contacts', 'create event', 'upload to drive', 'read spreadsheet', or any Google Workspace task.

install

source · Clone the upstream repo

git clone https://github.com/joelhooks/joelclaw

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/joelhooks/joelclaw "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/gogcli" ~/.claude/skills/joelhooks-joelclaw-gogcli && rm -rf "$T"

manifest: skills/gogcli/SKILL.md

source content

gogcli — Google Workspace in the Terminal

gog

is a fast, JSON-first CLI for the full Google Workspace suite. Always use

--json

for structured output when parsing results.

Environment

export GOG_ACCOUNT=joelhooks@gmail.com
export GOG_KEYRING_PASSWORD=$(secrets lease gog_keyring_password )

Both vars are required for every

gog

command. Lease the keyring password from agent-secrets before use.

Quick Reference

Gmail

# Search (default: threads)
gog gmail search 'newer_than:1d' --max 10 --json
gog gmail search 'is:unread' --max 20 --json
gog gmail search 'from:someone@example.com newer_than:7d' --max 10 --json

# Message-level search with bodies
gog gmail messages search 'is:unread' --max 5 --include-body --json

# Read thread
gog gmail thread get <threadId> --json

# Send
gog gmail send --to user@example.com --subject "Subject" --body "Body text"
gog gmail send --to user@example.com --subject "Hi" --body-html "<p>Hello</p>"

# Labels
gog gmail labels list --json
gog gmail thread modify <threadId> --add STARRED --remove INBOX

Calendar

# Today / this week
gog calendar events primary --today --json
gog calendar events primary --week --json
gog calendar events primary --tomorrow --json
gog calendar events primary --days 7 --json

# All calendars
gog calendar events --all --today --json

# Search
gog calendar search "meeting" --today --json

# Create event
gog calendar create primary \
  --summary "Meeting" \
  --from 2025-01-15T10:00:00Z \
  --to 2025-01-15T11:00:00Z \
  --attendees "alice@example.com"

# Check availability
gog calendar freebusy --calendars "primary" \
  --from 2025-01-15T00:00:00Z --to 2025-01-16T00:00:00Z --json

# List calendars
gog calendar calendars --json

Drive

gog drive ls --max 20 --json
gog drive search "invoice" --max 20 --json
gog drive upload ./file.pdf --parent <folderId>
gog drive download <fileId> --out ./file.pdf
gog drive mkdir "New Folder"

Tasks

gog tasks lists --json
gog tasks list <tasklistId> --max 50 --json
gog tasks add <tasklistId> --title "New task"
gog tasks done <tasklistId> <taskId>

Contacts

gog contacts search "Name" --max 10 --json
gog contacts list --max 50 --json

Sheets

gog sheets metadata <spreadsheetId> --json
gog sheets get <spreadsheetId> 'Sheet1!A1:B10' --json
gog sheets update <spreadsheetId> 'A1' 'val1|val2,val3|val4'
gog sheets append <spreadsheetId> 'Sheet1!A:C' 'new|row|data'

Docs / Slides

gog docs cat <docId>                           # Read doc as text
gog docs export <docId> --format pdf --out doc.pdf
gog slides export <presentationId> --format pdf --out deck.pdf

Chat (Workspace only)

gog chat spaces list --json
gog chat messages list spaces/<spaceId> --max 10 --json
gog chat dm send user@company.com --text "message"

Output Modes

Flag	Use
`--json`	Structured JSON to stdout (always prefer for parsing)
`--plain`	Stable TSV (tabs, no colors)
(none)	Human-readable table

Errors/progress go to stderr. Pipe

--json

output through

jq

for filtering.

Patterns

Batch Gmail search → summarize

gog gmail messages search 'is:unread newer_than:1d' --max 20 --include-body --json | jq '.messages[] | {from, subject, body}'

Find next free slot

gog calendar freebusy --calendars "primary" --from today --to tomorrow --json

Today's agenda

gog calendar events primary --today --json | jq '.events[] | {summary, start: .start.dateTime, end: .end.dateTime}'

Auth Setup (one-time)

gog

returns auth errors:

export GOG_KEYRING_PASSWORD=$(secrets lease gog_keyring_password )
gog auth add joelhooks@gmail.com --services user
# Complete OAuth in browser, then verify:
gog auth list --check

Troubleshooting

"Secret not found": Keyring password not set. Export
```
GOG_KEYRING_PASSWORD
```
.

"No auth for gmail": Need

gog auth add <email> --services gmail

(or

user

for all).

403 insufficient scopes: Re-auth with
```
--force-consent
```
to add missing scopes.
Keychain locked: This system uses
```
file
```
backend. Set
```
GOG_KEYRING_PASSWORD
```
env var.