gog

Use gog for Gmail, Calendar, Chat, Classroom, Drive, Docs, Slides, Sheets, Forms, Apps Script, Contacts, Tasks, People, Admin, Groups, and Keep. Requires OAuth setup or service account auth.

Setup (once)

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

Set default account to avoid repeating --account:

export [email protected]

Agent Behavior Rules

• Always confirm before sending mail, creating events, or deleting anything.
• Prefer --json plus --no-input for scripting and automation.
• Use gog gmail search for threads; use gog gmail messages search when individual messages are needed.
• Prefer plain text for email. Use --body-file for multi-paragraph. Use --body-html only when rich formatting is required.
• --body does not unescape \ . For multi-line use a heredoc or --body-file - (stdin).
• Set GOG_ACCOUNT to avoid repeating --account on every command.
• Use GOG_HELP=full gog --help if you need to discover subcommands not documented here.

CRITICAL: Self-Discovery on Failure

The CLI evolves frequently. Flags and subcommands may change between versions. If any command fails (unknown flag, unknown command, wrong syntax):

1. Run gog \x3Cgroup> --help to see available subcommands and their aliases.
2. Run gog \x3Cgroup> \x3Csubcommand> --help to see the exact flags accepted.
3. Navigate deeper: gog \x3Cgroup> \x3Csub> \x3Csub> --help until you find the correct syntax.
4. Never assume a flag exists — verify with --help first if unsure.
5. Use gog schema \x3Ccommand> for machine-readable command/flag schema (JSON).

Example self-discovery flow:

# Command fails
gog calendar events create --title "Test"   # ERROR: unknown flag --title

# Discover correct subcommand
gog calendar --help                          # Shows: create (add,new) \x3CcalendarId> [flags]

# Discover correct flags
gog calendar create --help                   # Shows: --summary, --from, --to, etc.

# Use correct syntax
gog calendar create primary --summary "Test" --from 2026-04-04T21:00:00Z --to 2026-04-04T22:00:00Z

This self-discovery pattern applies to ALL command groups. Always fall back to --help navigation.

Global Flags

• -a, --account \x3Cemail|alias|auto> — Account override
• -j, --json — JSON stdout (best for parsing)
• -p, --plain — Stable TSV stdout (no colors)
• --results-only — JSON mode: emit only primary result (drops nextPageToken etc.)
• --select \x3Cfields> — JSON mode: select comma-separated fields (dot paths supported)
• -n, --dry-run — Do not make changes; print intended actions and exit
• -y, --force — Skip confirmations
• --no-input — Never prompt (CI/agent mode)
• -v, --verbose — Debug logging
• --color \x3Cauto|always|never>
• --out / --output — Output file path
• --out-dir / --output-dir — Output directory (attachments)
• --enable-commands \x3Ccsv> — Allowlist top-level commands (sandboxing)
• --version — Print version

Top-Level Aliases

These shortcuts avoid typing the full \x3Cgroup> \x3Ccommand> path:

• gog send → gog gmail send
• gog ls / gog list → gog drive ls
• gog search / gog find → gog drive search
• gog download / gog dl → gog drive download
• gog upload / gog up / gog put → gog drive upload
• gog open / gog browse → Print web URL for a Google ID
• gog login → gog auth add
• gog logout → gog auth remove
• gog status / gog st → gog auth status
• gog me / gog whoami → gog people me

Command Group Aliases

• gog cal → gog calendar
• gog drv → gog drive
• gog mail / gog email → gog gmail
• gog doc → gog docs
• gog slide → gog slides
• gog sheet → gog sheets
• gog form → gog forms
• gog contact → gog contacts
• gog task → gog tasks
• gog person → gog people
• gog group → gog groups
• gog class → gog classroom
• gog script / gog apps-script → gog appscript

Environment Variables

• GOG_ACCOUNT — Default account
• GOG_ACCESS_TOKEN — Direct access token (CI; ~1h, no refresh)
• GOG_CLIENT — OAuth client name
• GOG_JSON / GOG_PLAIN — Default output format
• GOG_COLOR — Color mode
• GOG_TIMEZONE — Default timezone (IANA, UTC, or local)
• GOG_ENABLE_COMMANDS — Command allowlist
• GOG_KEYRING_BACKEND — Force keyring (auto/keychain/file)
• GOG_KEYRING_PASSWORD — Password for file keyring (CI)

Authentication Commands

# Credentials
gog auth credentials \x3Cpath>
gog auth credentials list
gog --client \x3Cname> auth credentials \x3Cpath>
gog --client \x3Cname> auth credentials \x3Cpath> --domain example.com

# Add account
gog auth add \x3Cemail>
gog auth add \x3Cemail> --services gmail,calendar,drive,contacts,docs,sheets
gog auth add \x3Cemail> --services drive --drive-scope full|readonly|file
gog auth add \x3Cemail> --services gmail --gmail-scope full|readonly
gog auth add \x3Cemail> --services gmail --extra-scopes \x3Cscope-uri>
gog auth add \x3Cemail> --readonly
gog auth add \x3Cemail> --services user --force-consent

# Headless / remote flows
gog auth add \x3Cemail> --services user --manual
gog auth add \x3Cemail> --services user --remote --step 1
gog auth add \x3Cemail> --services user --remote --step 2 --auth-url '\x3Curl>'
gog auth add \x3Cemail> --listen-addr 0.0.0.0:8080 --redirect-host gog.example.com

# Direct access token
gog --access-token "$(gcloud auth print-access-token)" gmail labels list

# Service accounts (Workspace domain-wide delegation)
gog auth service-account set \x3Cemail> --key \x3Cpath>
gog auth service-account status \x3Cemail>
gog auth service-account unset \x3Cemail>
gog auth keep \x3Cemail> --key \x3Cpath>

# Keyring
gog auth keyring
gog auth keyring file|keychain|auto

# Management
gog auth list
gog auth list --check
gog auth status
gog auth services
gog auth remove \x3Cemail>
gog auth manage
gog auth tokens

# Aliases
gog auth alias set \x3Calias> \x3Cemail>
gog auth alias list
gog auth alias unset \x3Calias>

Config Commands

gog config path
gog config list
gog config keys
gog config get \x3Ckey>
gog config set \x3Ckey> \x3Cvalue>
gog config unset \x3Ckey>

Config (JSON5) supports: keyring_backend, default_timezone, account_aliases, account_clients, client_domains.

Gmail

Search & Read

gog gmail search 'newer_than:7d' --max 10
gog gmail messages search 'in:inbox from:ryanair.com' --max 20
gog gmail messages search 'newer_than:7d' --max 3 --include-body --json
gog gmail thread get \x3CthreadId>
gog gmail thread get \x3CthreadId> --download
gog gmail thread get \x3CthreadId> --download --out-dir ./attachments
gog gmail get \x3CmessageId>
gog gmail get \x3CmessageId> --format metadata
gog gmail attachment \x3CmessageId> \x3CattachmentId>
gog gmail attachment \x3CmessageId> \x3CattachmentId> --out ./file.bin
gog gmail url \x3CthreadId>

Send & Compose

gog gmail send --to [email protected] --subject "Hi" --body "Hello"
gog gmail send --to [email protected] --subject "Hi" --body-file ./message.txt
gog gmail send --to [email protected] --subject "Hi" --body-file -
gog gmail send --to [email protected] --subject "Hi" --body "Plain" --body-html "\x3Cp>Hello\x3C/p>"
gog gmail send --reply-to-message-id \x3CmsgId> --quote --to [email protected] --subject "Re: Hi" --body "Reply"
gog gmail send --to [email protected] --subject "Hello" --body-html "\x3Cp>Hi!\x3C/p>" --track

Drafts

gog gmail drafts list
gog gmail drafts create --to [email protected] --subject "Draft" --body "Body"
gog gmail drafts create --reply-to-message-id \x3CmsgId> --quote --subject "Re: Hi" --body "Reply"
gog gmail drafts update \x3CdraftId> --subject "New" --body "Updated"
gog gmail drafts update \x3CdraftId> --to [email protected] --subject "New" --body "Updated"
gog gmail drafts update \x3CdraftId> --reply-to-message-id \x3CmsgId> --quote --subject "Re: Hi" --body "Reply"
gog gmail drafts update \x3CdraftId> --quote --subject "Re: Hi" --body "Reply"
gog gmail drafts send \x3CdraftId>

Thread & Message Modification

gog gmail thread modify \x3CthreadId> --add STARRED --remove INBOX
gog gmail labels modify \x3CthreadId> --add STARRED --remove INBOX
gog gmail batch delete \x3CmsgId1> \x3CmsgId2>
gog gmail batch modify \x3CmsgId1> \x3CmsgId2> --add STARRED --remove INBOX

Labels

gog gmail labels list
gog gmail labels get INBOX --json
gog gmail labels create "My Label"
gog gmail labels rename "Old Label" "New Label"
gog gmail labels delete \x3ClabelIdOrName>

Filters

gog gmail filters list
gog gmail filters create --from '[email protected]' --add-label 'Notifications'
gog gmail filters delete \x3CfilterId>
gog gmail filters export --out ./filters.json

Settings

gog gmail autoforward get
gog gmail autoforward enable --email [email protected]
gog gmail autoforward disable
gog gmail forwarding list
gog gmail forwarding add --email [email protected]
gog gmail sendas list
gog gmail sendas create --email [email protected]
gog gmail vacation get
gog gmail vacation enable --subject "Out of office" --message "..."
gog gmail vacation disable

Delegation (Workspace)

gog gmail delegates list
gog gmail delegates add --email [email protected]
gog gmail delegates remove --email [email protected]

Watch (Pub/Sub)

gog gmail watch start --topic projects/\x3Cp>/topics/\x3Ct> --label INBOX
gog gmail watch serve --bind 127.0.0.1 --token \x3Cshared> --hook-url \x3Curl>
gog gmail watch serve --bind 0.0.0.0 --verify-oidc --oidc-email \x3Csvc@...> --hook-url \x3Curl>
gog gmail watch serve --bind 127.0.0.1 --token \x3Cshared> --fetch-delay 5 --hook-url \x3Curl>
gog gmail watch serve --bind 127.0.0.1 --token \x3Cshared> --exclude-labels SPAM,TRASH --hook-url \x3Curl>
gog gmail history --since \x3ChistoryId>

Email Tracking

gog gmail track setup --worker-url https://gog-email-tracker.\x3Cacct>.workers.dev
gog gmail send --to [email protected] --subject "Hello" --body-html "\x3Cp>Hi!\x3C/p>" --track
gog gmail track opens \x3Ctracking_id>
gog gmail track opens --to [email protected]
gog gmail track status

Email Formatting Guide

• Prefer plain text for emails. Use --body-file for multi-paragraph (or --body-file - for stdin).
• Same --body-file pattern works for drafts and replies.
• --body does not unescape \ . For inline newlines, use a heredoc or $'Line 1\ \ Line 2'.
• Use --body-html only when rich formatting is needed.
• HTML tags: \x3Cp> paragraphs, \x3Cbr> line breaks, \x3Cstrong> bold, \x3Cem> italic, \x3Ca href="url"> links, \x3Cul>/\x3Cli> lists.
• --track requires exactly 1 recipient and --body-html. Use --track-split for per-recipient tracking.

Example (plain text via stdin):

gog gmail send --to [email protected] \
  --subject "Meeting Follow-up" \
  --body-file - \x3C\x3C'EOF'
Hi Name,

Thanks for meeting today. Next steps:
- Item one
- Item two

Best regards,
Your Name
EOF

Example (HTML):

gog gmail send --to [email protected] \
  --subject "Meeting Follow-up" \
  --body-html "\x3Cp>Hi Name,\x3C/p>\x3Cp>Next steps:\x3C/p>\x3Cul>\x3Cli>Item one\x3C/li>\x3Cli>Item two\x3C/li>\x3C/ul>\x3Cp>Best,\x3Cbr>Your Name\x3C/p>"

Calendar

List & View

gog calendar calendars
gog calendar subscribe \x3CcalendarId>
gog calendar acl \x3CcalendarId>
gog calendar colors
gog calendar time --timezone America/New_York
gog calendar users
gog calendar alias                    # Manage calendar aliases

# Events
gog calendar events \x3CcalendarId> --today
gog calendar events \x3CcalendarId> --tomorrow
gog calendar events \x3CcalendarId> --week
gog calendar events \x3CcalendarId> --days 3
gog calendar events \x3CcalendarId> --from today --to friday
gog calendar events \x3CcalendarId> --from today --to friday --weekday
gog calendar events \x3CcalendarId> --from \x3Ciso> --to \x3Ciso>
gog calendar events --all
gog calendar events --calendars 1,3
gog calendar events --cal Work --cal Personal

# Single event
gog calendar event \x3CcalendarId> \x3CeventId>
gog calendar get \x3CcalendarId> \x3CeventId>
gog calendar get \x3CcalendarId> \x3CeventId> --json

# Search
gog calendar search "meeting" --today
gog calendar search "meeting" --tomorrow
gog calendar search "meeting" --days 365
gog calendar search "meeting" --from \x3Ciso> --to \x3Ciso> --max 50

# Team
gog calendar team \x3Cgroup-email> --today
gog calendar team \x3Cgroup-email> --week
gog calendar team \x3Cgroup-email> --freebusy
gog calendar team \x3Cgroup-email> --query "standup"

Create & Update

gog calendar create \x3CcalendarId> --summary "Meeting" --from \x3Ciso> --to \x3Ciso>
gog calendar create \x3CcalendarId> --summary "Sync" --from \x3Ciso> --to \x3Ciso> --attendees "[email protected],[email protected]" --location "Zoom"
gog calendar create \x3CcalendarId> --summary "Meeting" --from \x3Ciso> --to \x3Ciso> --event-color 7
gog calendar create \x3CcalendarId> --summary "Meeting" --from \x3Ciso> --to \x3Ciso> --send-updates all
gog calendar create \x3CcalendarId> --summary "Pay" --from \x3Ciso> --to \x3Ciso> --rrule "RRULE:FREQ=MONTHLY;BYMONTHDAY=11" --reminder "email:3d" --reminder "popup:30m"
gog calendar create \x3CcalendarId> --summary "Meeting" --from \x3Ciso> --to \x3Ciso> --with-meet
gog calendar create \x3CcalendarId> --summary "Meeting" --from \x3Ciso> --to \x3Ciso> --description "Notes" --visibility private --transparency free
gog calendar create \x3CcalendarId> --summary "Meeting" --from \x3Ciso> --to \x3Ciso> --guests-can-invite --guests-can-modify --guests-can-see-others
gog calendar create \x3CcalendarId> --summary "Meeting" --from \x3Ciso> --to \x3Ciso> --attachment \x3Curl> --source-url \x3Curl> --source-title "Source"
gog calendar create \x3CcalendarId> --summary "Meeting" --from \x3Ciso> --to \x3Ciso> --private-prop key=value --shared-prop key=value

# Special types: Focus Time
gog calendar create primary --event-type focus-time --from \x3Ciso> --to \x3Ciso>
gog calendar create primary --event-type focus-time --from \x3Ciso> --to \x3Ciso> --focus-auto-decline --focus-decline-message "Focusing" --focus-chat-status "doNotDisturb"

# Special types: Out of Office
gog calendar create primary --event-type out-of-office --from \x3Cdate> --to \x3Cdate> --all-day
gog calendar create primary --event-type out-of-office --from \x3Cdate> --to \x3Cdate> --all-day --ooo-auto-decline --ooo-decline-message "I'm away"

# Special types: Working Location
gog calendar create primary --event-type working-location --working-location-type office --working-office-label "HQ" --from \x3Cdate> --to \x3Cdate>
gog calendar create primary --event-type working-location --working-location-type office --working-office-label "HQ" --working-building-id "B1" --working-floor-id "3" --working-desk-id "3A" --from \x3Cdate> --to \x3Cdate>
gog calendar create primary --event-type working-location --working-location-type home --from \x3Cdate> --to \x3Cdate>
gog calendar create primary --event-type working-location --working-location-type custom --working-custom-label "Coffee Shop" --from \x3Cdate> --to \x3Cdate>

# Shortcuts (same flags apply)
gog calendar focus-time --from \x3Ciso> --to \x3Ciso>
gog calendar focus-time --from \x3Ciso> --to \x3Ciso> --focus-auto-decline --focus-decline-message "Focusing" --focus-chat-status "doNotDisturb"
gog calendar out-of-office --from \x3Cdate> --to \x3Cdate> --all-day
gog calendar out-of-office --from \x3Cdate> --to \x3Cdate> --all-day --ooo-auto-decline --ooo-decline-message "I'm away"
gog calendar working-location --type office --office-label "HQ" --from \x3Cdate> --to \x3Cdate>
gog calendar working-location --type home --from \x3Cdate> --to \x3Cdate>
gog calendar working-location --type custom --custom-label "Coffee Shop" --from \x3Cdate> --to \x3Cdate>

# Update
gog calendar update \x3CcalendarId> \x3CeventId> --summary "Updated" --from \x3Ciso> --to \x3Ciso>
gog calendar update \x3CcalendarId> \x3CeventId> --event-color 4
gog calendar update \x3CcalendarId> \x3CeventId> --send-updates externalOnly
gog calendar update \x3CcalendarId> \x3CeventId> --add-attendee "[email protected],[email protected]"

# Delete
gog calendar delete \x3CcalendarId> \x3CeventId>
gog calendar delete \x3CcalendarId> \x3CeventId> --send-updates all --force

Invitations & Availability

gog calendar respond \x3CcalendarId> \x3CeventId> --status accepted|declined|tentative
gog calendar respond \x3CcalendarId> \x3CeventId> --status declined --send-updates externalOnly
gog calendar propose-time \x3CcalendarId> \x3CeventId>
gog calendar propose-time \x3CcalendarId> \x3CeventId> --open
gog calendar propose-time \x3CcalendarId> \x3CeventId> --decline --comment "Can we do 5pm?"
gog calendar freebusy --calendars "primary,[email protected]" --from \x3Ciso> --to \x3Ciso>
gog calendar freebusy --cal Work --from \x3Ciso> --to \x3Ciso>
gog calendar conflicts --calendars "primary,[email protected]" --today
gog calendar conflicts --all --today

Calendar Colors Reference

Use gog calendar colors to list. Add with --event-color \x3Cid>.

Calendar Notes

• Search defaults to 30 days ago through 90 days ahead unless --from/--to/--today/--week/--days is set.
• JSON output includes startDayOfWeek, endDayOfWeek, timezone, startLocal, endLocal convenience fields.
• Set GOG_CALENDAR_WEEKDAY=1 to default --weekday for event output.
• Default: no attendee notifications unless --send-updates is passed.
• --add-attendee adds without replacing existing attendees/RSVP state.

Time

gog time now
gog time now --timezone UTC

Drive

List & Search

gog drive ls --max 20
gog drive ls --parent \x3CfolderId> --max 20
gog drive ls --all --max 20
gog drive ls --no-all-drives
gog drive search "invoice" --max 20
gog drive search "invoice" --no-all-drives
gog drive search "mimeType = 'application/pdf'" --raw-query
gog drive get \x3CfileId>
gog drive url \x3CfileId>
gog drive copy \x3CfileId> "Copy Name"

Upload & Download

gog drive upload ./file.pdf --parent \x3CfolderId>
gog drive upload ./file.pdf --replace \x3CfileId>
gog drive upload ./report.docx --convert
gog drive upload ./chart.png --convert-to sheet
gog drive upload ./report.docx --convert --name report.docx
gog drive download \x3CfileId> --out ./file.bin
gog drive download \x3CfileId> --format pdf --out ./exported.pdf
gog drive download \x3CfileId> --format docx --out ./doc.docx
gog drive download \x3CfileId> --format pptx --out ./slides.pptx

Organize

gog drive mkdir "Folder"
gog drive mkdir "Folder" --parent \x3CparentId>
gog drive rename \x3CfileId> "New Name"
gog drive move \x3CfileId> --parent \x3CdestId>
gog drive delete \x3CfileId>
gog drive delete \x3CfileId> --permanent

Permissions & Sharing

gog drive permissions \x3CfileId>
gog drive share \x3CfileId> --to user --email [email protected] --role reader|writer
gog drive share \x3CfileId> --to domain --domain example.com --role reader
gog drive unshare \x3CfileId> --permission-id \x3CpermId>
gog drive drives --max 100

Docs

gog docs info \x3CdocId>
gog docs cat \x3CdocId>
gog docs cat \x3CdocId> --max-bytes 10000
gog docs cat \x3CdocId> --tab "Notes"
gog docs cat \x3CdocId> --all-tabs
gog docs create "My Doc"
gog docs create "My Doc" --file ./doc.md
gog docs create "My Doc" --pageless
gog docs copy \x3CdocId> "Copy"
gog docs list-tabs \x3CdocId>

# Export
gog docs export \x3CdocId> --format pdf|docx|txt|md|html --out ./file

# Edit
gog docs update \x3CdocId> --text "Append text"
gog docs update \x3CdocId> --text "Tab text" --tab-id t.notes
gog docs update \x3CdocId> --file ./insert.txt --index 25 --pageless
gog docs write \x3CdocId> --text "Replace all"
gog docs write \x3CdocId> --text "Tab replace" --tab-id t.notes
gog docs write \x3CdocId> --file ./body.txt --append --pageless
gog docs find-replace \x3CdocId> "old" "new"
gog docs find-replace \x3CdocId> "old" "new" --tab-id t.notes

# Sed-style editing (sedmat syntax)
gog docs sed \x3CdocId> 's/pattern/replacement/g'
gog docs sed \x3CdocId> 's/hello/**hello**/'              # bold
gog docs sed \x3CdocId> 's/hello/*hello*/'                 # italic
gog docs sed \x3CdocId> 's/hello/~~hello~~/'               # strikethrough
gog docs sed \x3CdocId> 's/hello/`hello`/'                 # monospace
gog docs sed \x3CdocId> 's/hello/__hello__/'               # underline
gog docs sed \x3CdocId> 's/word/[word](https://url)/'     # link
gog docs sed \x3CdocId> 's/{{IMG}}/![](https://url/img.png)/'
gog docs sed \x3CdocId> 's/{{IMG}}/![](https://url/img.jpg){width=600}/'
gog docs sed \x3CdocId> 's/{{TABLE}}/|3x4|/'              # 3-row 4-col table
gog docs sed \x3CdocId> 's/|1|[A1]/**Name**/'             # set cell
gog docs sed \x3CdocId> 's/|1|[1,*]/**&**/'               # bold entire row
gog docs sed \x3CdocId> 's/|1|[row:+2]//'                 # insert row
gog docs sed \x3CdocId> 's/|1|[col:$+]//'                 # append column

Slides

gog slides info \x3CpresentationId>
gog slides create "My Deck"
gog slides copy \x3CpresentationId> "Copy"
gog slides list-slides \x3CpresentationId>
gog slides add-slide \x3CpresentationId> ./slide.png --notes "Speaker notes"
gog slides update-notes \x3CpresentationId> \x3CslideId> --notes "Updated"
gog slides replace-slide \x3CpresentationId> \x3CslideId> ./new.png --notes "New"
gog slides export \x3CpresentationId> --format pdf|pptx --out ./file
gog slides create-from-markdown "Deck" --content-file ./slides.md
gog slides create-from-template \x3CtemplateId> "Report" --replace "name=John" --replace "date=2026-02-15"
gog slides create-from-template \x3CtemplateId> "Report" --replacements replacements.json

Sheets

Read & Metadata

gog sheets metadata \x3CspreadsheetId>
gog sheets get \x3CspreadsheetId> 'Sheet1!A1:B10'
gog sheets get \x3CspreadsheetId> 'Sheet1!A1:D10' --json
gog sheets get \x3CspreadsheetId> MyNamedRange

Create & Export

gog sheets create "My Sheet" --sheets "Sheet1,Sheet2"
gog sheets copy \x3CspreadsheetId> "Copy"
gog sheets export \x3CspreadsheetId> --format pdf|xlsx --out ./file

Write & Modify

gog sheets update \x3CspreadsheetId> 'A1' 'val1|val2,val3|val4'
gog sheets update \x3CspreadsheetId> 'A1' --values-json '[["a","b"],["c","d"]]'
gog sheets update \x3CspreadsheetId> 'Sheet1!A1:B2' --values-json '[["A","B"],["1","2"]]' --input USER_ENTERED
gog sheets update \x3CspreadsheetId> 'Sheet1!A1:C1' 'data' --copy-validation-from 'Sheet1!A2:C2'
gog sheets update \x3CspreadsheetId> MyNamedRange 'new|row|data'
gog sheets append \x3CspreadsheetId> 'Sheet1!A:C' 'new|row|data'
gog sheets append \x3CspreadsheetId> 'Sheet1!A:C' --values-json '[["x","y","z"]]' --insert INSERT_ROWS
gog sheets append \x3CspreadsheetId> 'Sheet1!A:C' 'data' --copy-validation-from 'Sheet1!A2:C2'
gog sheets append \x3CspreadsheetId> MyNamedRange 'new|row|data'
gog sheets clear \x3CspreadsheetId> 'Sheet1!A1:B10'
gog sheets clear \x3CspreadsheetId> MyNamedRange

Find/Replace, Notes & Links

gog sheets find-replace \x3CspreadsheetId> "old" "new"
gog sheets find-replace \x3CspreadsheetId> "old" "new" --sheet Sheet1 --match-entire
gog sheets find-replace \x3CspreadsheetId> "old" "new" --sheet Sheet1 --regex
gog sheets notes \x3CspreadsheetId> 'Sheet1!A1:B10'
gog sheets update-note \x3CspreadsheetId> 'Sheet1!A1' --note ''
gog sheets links \x3CspreadsheetId> 'Sheet1!A1:B10'

Formatting

gog sheets format \x3CspreadsheetId> 'Sheet1!A1:B2' --format-json '{"textFormat":{"bold":true}}' --format-fields 'userEnteredFormat.textFormat.bold'
gog sheets format \x3CspreadsheetId> MyNamedRange --format-json '...' --format-fields '...'
gog sheets merge \x3CspreadsheetId> 'Sheet1!A1:B2'
gog sheets unmerge \x3CspreadsheetId> 'Sheet1!A1:B2'
gog sheets number-format \x3CspreadsheetId> 'Sheet1!C:C' --type CURRENCY --pattern '$#,##0.00'
gog sheets freeze \x3CspreadsheetId> --rows 1 --cols 1
gog sheets resize-columns \x3CspreadsheetId> 'Sheet1!A:C' --auto
gog sheets resize-rows \x3CspreadsheetId> 'Sheet1!1:10' --height 36
gog sheets read-format \x3CspreadsheetId> 'Sheet1!A1:B2'
gog sheets read-format \x3CspreadsheetId> 'Sheet1!A1:B2' --effective

Named Ranges

gog sheets named-ranges \x3CspreadsheetId>
gog sheets named-ranges get \x3CspreadsheetId> MyRange
gog sheets named-ranges add \x3CspreadsheetId> MyRange 'Sheet1!A1:B2'
gog sheets named-ranges add \x3CspreadsheetId> MyCols 'Sheet1!A:C'
gog sheets named-ranges update \x3CspreadsheetId> MyRange --name NewName
gog sheets named-ranges delete \x3CspreadsheetId> MyRange

Structure

gog sheets insert \x3CspreadsheetId> "Sheet1" rows 2 --count 3
gog sheets insert \x3CspreadsheetId> "Sheet1" cols 3 --after
gog sheets add-tab \x3CspreadsheetId> \x3CtabName>
gog sheets rename-tab \x3CspreadsheetId> \x3ColdName> \x3CnewName>
gog sheets delete-tab \x3CspreadsheetId> \x3CtabName>
gog sheets delete-tab \x3CspreadsheetId> \x3CtabName> --force

Sheets Notes

• Values can be passed via --values-json (recommended) or as inline pipe-delimited rows.
• Use --input USER_ENTERED so Sheets parses formulas/numbers; default is RAW.
• Named ranges work in get, update, append, clear, and format.

Forms

gog forms get \x3CformId>
gog forms create --title "Check-in" --description "Friday update"
gog forms update \x3CformId> --title "Sync" --quiz true
gog forms add-question \x3CformId> --title "What shipped?" --type paragraph --required
gog forms move-question \x3CformId> 3 1
gog forms delete-question \x3CformId> 2 --force
gog forms responses list \x3CformId> --max 20
gog forms responses get \x3CformId> \x3CresponseId>
gog forms watch create \x3CformId> --topic projects/\x3Cp>/topics/\x3Ct>
gog forms watch list \x3CformId>
gog forms watch renew \x3CformId> \x3CwatchId>
gog forms watch delete \x3CformId> \x3CwatchId>

Apps Script

gog appscript get \x3CscriptId>
gog appscript content \x3CscriptId>
gog appscript create --title "Helpers"
gog appscript create --title "Bound" --parent-id \x3CdriveFileId>
gog appscript run \x3CscriptId> myFunction --params '["arg1", 123, true]'
gog appscript run \x3CscriptId> myFunction --dev-mode

Contacts

Personal & Other Contacts

gog contacts list --max 50
gog contacts search "Ada" --max 50
gog contacts get people/\x3CresourceName>
gog contacts get [email protected]
gog contacts other list --max 50
gog contacts other search "John" --max 50

Create & Update

gog contacts create --given "John" --family "Doe" --email "[email protected]" --phone "+1234567890" --address "Address" --relation "spouse=Jane"
gog contacts update people/\x3CresourceName> --given "Jane" --email "[email protected]" --address "Address" --birthday "1990-05-12" --notes "Note" --relation "friend=Bob"
gog contacts get people/\x3CresourceName> --json | jq '...' | gog contacts update people/\x3CresourceName> --from-file -
gog contacts delete people/\x3CresourceName>

Workspace Directory

gog contacts directory list --max 50
gog contacts directory search "Jane" --max 50

Tasks

# Lists
gog tasks lists --max 50
gog tasks lists create \x3Ctitle>

# Tasks
gog tasks list \x3CtasklistId> --max 50
gog tasks get \x3CtasklistId> \x3CtaskId>
gog tasks add \x3CtasklistId> --title "Task"
gog tasks add \x3CtasklistId> --title "Weekly" --due 2025-02-01 --repeat weekly --repeat-count 4
gog tasks add \x3CtasklistId> --title "Daily" --due 2025-02-01 --repeat daily --repeat-until 2025-02-05
gog tasks add \x3CtasklistId> --title "Biweekly" --due 2025-02-01 --recur-rrule "FREQ=WEEKLY;INTERVAL=2" --repeat-count 3
gog tasks update \x3CtasklistId> \x3CtaskId> --title "New title"
gog tasks done \x3CtasklistId> \x3CtaskId>
gog tasks undo \x3CtasklistId> \x3CtaskId>
gog tasks delete \x3CtasklistId> \x3CtaskId>
gog tasks clear \x3CtasklistId>

Tasks Notes: Google Tasks treats due dates as date-only. --repeat*/--recur* materialize concrete tasks (not true API recurrence).

Chat (Workspace only)

# Spaces
gog chat spaces list
gog chat spaces find "Engineering"
gog chat spaces create "Engineering" --member [email protected] --member [email protected]

# Messages
gog chat messages list spaces/\x3CspaceId> --max 5
gog chat messages list spaces/\x3CspaceId> --thread \x3CthreadId>
gog chat messages list spaces/\x3CspaceId> --unread
gog chat messages send spaces/\x3CspaceId> --text "Done!" --thread spaces/\x3CspaceId>/threads/\x3CthreadId>

# Reactions
gog chat messages reactions list spaces/\x3CspaceId>/messages/\x3CmsgId>
gog chat messages react spaces/\x3CspaceId>/messages/\x3CmsgId> "👍"
gog chat messages reactions delete spaces/\x3CspaceId>/messages/\x3CmsgId>/reactions/\x3CreactionId>

# Threads & DMs
gog chat threads list spaces/\x3CspaceId>
gog chat dm space [email protected]
gog chat dm send [email protected] --text "ping"

Classroom (Workspace for Education)

Courses

gog classroom courses list
gog classroom courses list --role teacher
gog classroom courses get \x3CcourseId>
gog classroom courses create --name "Math 101"
gog classroom courses update \x3CcourseId> --name "Math 102"
gog classroom courses archive \x3CcourseId>
gog classroom courses unarchive \x3CcourseId>
gog classroom courses url \x3CcourseId>

Roster & Members

gog classroom roster \x3CcourseId>
gog classroom roster \x3CcourseId> --students
gog classroom students add \x3CcourseId> \x3CuserId>
gog classroom teachers add \x3CcourseId> \x3CuserId>

Coursework & Materials

gog classroom coursework list \x3CcourseId>
gog classroom coursework get \x3CcourseId> \x3CcourseworkId>
gog classroom coursework create \x3CcourseId> --title "HW1" --type ASSIGNMENT --state PUBLISHED
gog classroom coursework update \x3CcourseId> \x3CcourseworkId> --title "Updated"
gog classroom coursework assignees \x3CcourseId> \x3CcourseworkId> --mode INDIVIDUAL_STUDENTS --add-student \x3CstudentId>
gog classroom materials list \x3CcourseId>
gog classroom materials create \x3CcourseId> --title "Syllabus" --state PUBLISHED

Submissions

gog classroom submissions list \x3CcourseId> \x3CcourseworkId>
gog classroom submissions get \x3CcourseId> \x3CcourseworkId> \x3CsubmissionId>
gog classroom submissions grade \x3CcourseId> \x3CcourseworkId> \x3CsubmissionId> --grade 85
gog classroom submissions return \x3CcourseId> \x3CcourseworkId> \x3CsubmissionId>
gog classroom submissions turn-in \x3CcourseId> \x3CcourseworkId> \x3CsubmissionId>
gog classroom submissions reclaim \x3CcourseId> \x3CcourseworkId> \x3CsubmissionId>

Announcements & Topics

gog classroom announcements list \x3CcourseId>
gog classroom announcements create \x3CcourseId> --text "Welcome!"
gog classroom announcements update \x3CcourseId> \x3CannouncementId> --text "Updated"
gog classroom announcements assignees \x3CcourseId> \x3CannouncementId> --mode INDIVIDUAL_STUDENTS --add-student \x3CstudentId>
gog classroom topics list \x3CcourseId>
gog classroom topics create \x3CcourseId> --name "Unit 1"
gog classroom topics update \x3CcourseId> \x3CtopicId> --name "Unit 2"

Invitations & Guardians

gog classroom invitations list
gog classroom invitations create \x3CcourseId> \x3CuserId> --role student
gog classroom invitations accept \x3CinvitationId>
gog classroom guardians list \x3CstudentId>
gog classroom guardians get \x3CstudentId> \x3CguardianId>
gog classroom guardians delete \x3CstudentId> \x3CguardianId>
gog classroom guardian-invitations list \x3CstudentId>
gog classroom guardian-invitations create \x3CstudentId> --email [email protected]
gog classroom profile get
gog classroom profile get \x3CuserId>

People

gog people me
gog people get people/\x3CuserId>
gog people search "Ada Lovelace" --max 5
gog people relations
gog people relations people/\x3CuserId> --type manager

Keep (Workspace only)

gog keep list --account [email protected]
gog keep get \x3CnoteId> --account [email protected]
gog keep search \x3Cquery> --account [email protected]
gog keep create --title "Todo" --item "Milk" --item "Eggs" --account [email protected]
gog keep create --title "Note" --text "Remember" --account [email protected]
gog keep delete \x3CnoteId> --account [email protected] --force
gog keep attachment \x3CattachmentName> --account [email protected] --out ./file.bin

Admin (Workspace only)

gog admin users list --domain example.com
gog admin users get [email protected]
gog admin users create [email protected] --given Ada --family Lovelace --password 'TempPass123!'
gog admin users suspend [email protected] --force
gog admin groups list --domain example.com
gog admin groups members list [email protected]
gog admin groups members add [email protected] [email protected] --role MEMBER
gog admin groups members remove [email protected] [email protected] --force

Groups (Workspace)

gog groups list
gog groups members [email protected]

Agent Commands

# Run gog as an autonomous agent (MCP / tool-use mode)
gog agent --help                      # discover all agent sub-flags
gog agent run --instructions "..."    # run agent with instructions
gog agent run --instructions-file ./plan.md

Schema & Utilities

gog schema                            # list available schemas
gog schema \x3Cresource>                 # show schema for a resource
gog open \x3Curl>                        # open a Google resource URL
gog exit-codes                        # list all exit codes and meanings

Shell Completions

gog completion bash > $(brew --prefix)/etc/bash_completion.d/gog
gog completion zsh > "${fpath[1]}/_gog"
gog completion fish > ~/.config/fish/completions/gog.fish
gog completion powershell | Out-String | Invoke-Expression
gog completion powershell >> $PROFILE

Output Formats

• Default: human-friendly tables with colors on TTY.
• --plain: stable TSV (tabs preserved; best for piping).
• --json: JSON on stdout (best for scripting).
• Hints/progress go to stderr. Colors auto-disabled for --json/--plain.

Best Practices & Gotchas

• Always confirm before sending mail, creating events, or deleting resources.
• gog gmail search returns one row per thread; use gog gmail messages search when you need every individual message.
• For multi-line email bodies, always use --body-file. --body treats content as a single line.
• Sheets --values-json is recommended over pipe-delimited inline syntax.
• Docs supports export/cat/copy/write/sed. In-place structural edits use gog docs sed (sedmat syntax).
• Calendar --send-updates is opt-in: no notifications sent by default.
• Service account domain delegation takes precedence over OAuth when configured.
• gog supports command allowlists (--enable-commands / GOG_ENABLE_COMMANDS) for sandboxed agent runs.
• Credentials stored in OS keyring or encrypted local storage. Use GOG_KEYRING_BACKEND=file + GOG_KEYRING_PASSWORD for CI.