gog — Google Workspace from the terminal

One binary. Task-first commands. Predictable automation.

gog gives people, scripts, CI, and coding agents one CLI for Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Meet, Apps Script, Analytics, Search Console, Contacts, Tasks, Classroom, Chat, YouTube, and Workspace admin.

# Find mail, inspect today's calendar, and audit a Drive folder.
gog --account you@gmail.com --readonly gmail search 'is:unread newer_than:7d' --max 10
gog --account you@gmail.com --readonly calendar events --today
gog --account you@gmail.com --readonly drive audit sharing --parent <folderId> --json

# Make automation parseable, non-interactive, read-only, and unable to send Gmail.
gog --readonly --gmail-no-send --no-input --json gmail search 'label:inbox'

Why gog

Google APIs expose resources and methods. Real work crosses them. gog keeps the raw capability, then adds the workflow and operational contracts a durable CLI needs:

• Task-first workflows: search and sanitize mail, resolve calendar names, audit Drive sharing, edit Docs, append Sheet tables, build Slides, manage Workspace users, and back up accounts.
• Automation that composes: stable --json and --plain stdout; prompts, progress, and warnings on stderr; documented exit codes; --no-input for CI.
• Many identities, one install: account aliases, named OAuth clients, direct access tokens, ADC, OS/encrypted-file keyrings, and Workspace service accounts.
• Agent safety with explicit boundaries: runtime --readonly, command allow/deny rules, --gmail-no-send, untrusted-content wrapping, dry-run plans, baked safety-profile binaries, and a typed MCP server that is read-only by default.
• A discoverable contract: gog schema --json, generated reference pages for every command, and schema-generated service skills for agent workflows.

Read Why gog for the design tradeoffs, or go straight to: Install · Quickstart · Auth · Command index · Automation · Agent skills · MCP.

Rendered docs: https://gogcli.sh/. gog is open source and not affiliated with Google.

Install

See the full Install guide for Homebrew, Docker, Windows ZIPs, source builds, and headless/container keyring setup.

Homebrew

brew install openclaw/tap/gogcli
gog --version

Docker

docker run --rm ghcr.io/openclaw/gogcli:latest version

Authenticated container runs should use a persistent GOG_HOME directory and the encrypted file keyring:

docker volume create gogcli-state

docker run --rm -it \
  -e GOG_HOME=/persist/gogcli \
  -e GOG_KEYRING_BACKEND=file \
  -e GOG_KEYRING_PASSWORD \
  -v gogcli-state:/persist/gogcli \
  ghcr.io/openclaw/gogcli:latest \
  auth add you@gmail.com --services gmail,calendar,drive

Windows

Download gogcli_<version>_windows_amd64.zip or gogcli_<version>_windows_arm64.zip from the latest release, extract gog.exe, and put that directory on PATH.

Build from source

git clone https://github.com/openclaw/gogcli.git
cd gogcli
make
./bin/gog --version

Source builds require the Go version declared in go.mod.

Quick Start

The full walkthrough lives in Quickstart. For named OAuth clients, remote OAuth, direct access tokens, ADC, and Workspace service accounts, see Auth clients.

Create a Google Cloud project, enable the APIs you need, create a Desktop OAuth client, then store that client JSON in gog.

gog auth credentials ~/Downloads/client_secret_....json
gog auth add you@gmail.com --services gmail,calendar,drive,docs,sheets,contacts
gog auth doctor --check

export GOG_ACCOUNT=you@gmail.com
gog gmail search 'newer_than:7d' --max 10

Useful Google setup links:

• Create a Cloud project
• OAuth clients
• OAuth consent screen
• API library
• Places API (New)
• Drive Labels API
• Photos Library API
• Photos Picker API
• Google Analytics Admin API
• Google Analytics Data API
• Google Search Console API
• YouTube Data API v3
• Apps Script user setting

Enable APIs in the same Cloud project that owns your OAuth client. If Google returns accessNotConfigured, enable that API and retry after propagation.

Consumer gmail.com accounts work for normal user APIs such as Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Analytics, Search Console, Contacts/People, Tasks, and Classroom. Workspace-only APIs such as Admin Directory, Cloud Identity Groups, Chat, and Keep/domain-wide-delegation flows require a managed domain.

Avoid the seven-day OAuth expiry

If your OAuth app is External with publishing status Testing, Google refresh tokens for user-data scopes can expire after seven days. For a personal CLI app, publish it before the final authorization:

1. Open Google Auth Platform → Audience in the same Cloud project that owns your Desktop OAuth client.
2. Under Publishing status, click Publish app, then Confirm. This changes the app to In production; it does not submit the app for Google verification.
3. If you already authorized while the app was in Testing, replace that token once, preserving the services you use:

bash gog auth add you@gmail.com --services gmail,calendar,drive,docs,sheets,contacts --force-consent gog auth doctor --check

An unverified personal app can run In production, but sensitive scopes show an unverified-app warning and are subject to a lifetime 100-user cap. Public apps should complete Google's OAuth verification. See Google's refresh-token expiration rules and unverified-app limits.

Daily Examples

Every command below has generated reference docs in the Command index. The feature guides linked under each section explain the workflow shape and safety notes.

Gmail

Docs: Gmail workflows, Gmail watch, email tracking, gog gmail.

# Search mail and get sanitized message content for agents/scripts.
gog gmail search 'from:boss newer_than:30d' --json
gog gmail get <messageId> --sanitize-content --json

# Export Gmail filters in the format the Gmail web UI can import.
gog gmail settings filters export --out filters.xml

# Hard block send operations during automation.
gog --gmail-no-send gmail drafts create --to you@example.com --subject test

Permanent deletion with gog gmail batch delete requires the broader https://mail.google.com/ OAuth scope. The command reports an exact gog auth add ... --extra-scopes https://mail.google.com/ --force-consent reauthorization command when a known stored grant lacks it. Prefer gog gmail trash unless permanent deletion is intentional.

Calendar

Docs: gog calendar, calendar create, calendar update, calendar move, calendar delete-calendar, calendar unsubscribe, Zoom setup.

gog calendar events --today
gog calendar create --summary "Review" \
  --from "2026-05-06T10:00:00+02:00" \
  --to "2026-05-06T10:30:00+02:00"
gog calendar create primary --summary "Coffee" \
  --from "2026-05-06T10:00:00+02:00" \
  --to "2026-05-06T10:30:00+02:00" \
  --location-search "Elysian Coffee Vancouver"
gog calendar update primary <eventId> --with-meet
gog calendar update primary <eventId> \
  --attachment 'https://drive.google.com/open?id=<fileId>'
# Repeated --attachment values replace all attachments; an empty value clears them.
gog calendar update primary <eventId> --attachment ''
gog zoom auth setup
gog calendar create primary --summary "Client sync" \
  --from "2026-05-06T11:00:00+02:00" \
  --to "2026-05-06T11:30:00+02:00" \
  --with-zoom
gog calendar move primary <eventId> team-calendar@example.com
gog calendar create-calendar "Project calendar" --timezone Europe/London
gog calendar delete-calendar <calendarId> --force
gog calendar subscribe en.uk#holiday@group.v.calendar.google.com
gog calendar unsubscribe en.uk#holiday@group.v.calendar.google.com --force

Google Calendar appointment schedules are not exposed by the Calendar API, so gog cannot list or manage them.

Drive

Docs: Drive audits, polling, raw API dumps, gog drive, drive changes, drive revisions, drive activity.

# Read-only folder audits.
gog drive tree --parent <folderId> --depth 2
gog drive du --parent <folderId> --max 20 --json
gog drive inventory --parent <folderId> --json
gog drive audit sharing --parent <folderId> --internal-domain example.com --json
gog drive audit user clawdbot@gmail.com --parent <folderId> --json
gog drive bulk remove-public --parent <folderId> --dry-run
gog drive share <fileId> --to user --email person@example.com --notify --dry-run
gog drive labels list --json
gog drive labels file list <fileId> --json
gog drive labels file apply <fileId> <labelId> --text fieldId=value
# Drive Labels requires a Google Workspace customer.

# Ask Drive for non-default fields.
gog drive get <fileId> --fields 'id,name,mimeType,size,owners,emailAddress' --json

# Track changes and audit activity.
gog drive changes start-token
gog drive changes list --token <token> --json
gog drive changes poll --state-file ~/.local/state/gog/drive-changes.json --json
gog drive changes serve --state-file ~/.local/state/gog/drive-serve.json \
  --channel-token-file ~/.config/gog/drive-channel-token --auto-renew \
  --webhook-url https://example.com/drive-changes
gog drive revisions list <fileId> --all --json
gog drive revisions get <fileId> <revisionId> --json
gog drive activity query --file <fileId> --actions edit,share --from 2026-01-01T00:00:00Z --json

# The Drive API exposes revision metadata and provider export links. For native
# Docs Editors files, it does not expose complete editor history or historical bodies.

# Lossless raw API JSON.
gog drive raw <fileId> --pretty

Maps

Docs: gog maps, maps places.

gog maps places search "Elysian Coffee Vancouver" --json
gog maps places details <placeId> --json
gog maps directions --origin "Vancouver, BC" --destination "Seattle, WA" --json
gog maps distance --origins "Vancouver BC" --destinations "Seattle WA" --json
gog maps geocode "1600 Amphitheatre Parkway, Mountain View, CA" --json
gog maps reverse-geocode --lat=37.422 --lng=-122.084 --json

Use comma-separated maps distance --origins/--destinations for multiple locations. If an address itself contains commas, pass it without commas or use a Place ID/lat,lng value to avoid splitting it.

Photos

Docs: gog photos and Photos Picker workflows.

Google Photos Library API access is limited to app-created media through photoslibrary.readonly.appcreateddata, and the Photos Library API must be enabled on the OAuth project used for gog auth add.

gog photos list --json
gog photos search --media-type PHOTO --from 2026-01-01 --to 2026-01-31 --json
gog photos download <mediaItemId> --out photo.jpg

For user-selected private media, enable the Photos Picker API and authorize its separate explicit-opt-in service. It is not included in the default user service set.

gog auth add you@gmail.com --services photospicker
gog photos picker create --max-items 20 --open --json
gog photos picker wait <sessionId> --json
gog photos picker list <sessionId> --all --json
gog photos picker download <sessionId> <mediaItemId> --out photo.jpg
gog photos picker delete <sessionId>

Contacts

Docs: contacts dedupe, JSON contact updates, gog contacts.

```bash gog contacts search alice --json gog contacts export --all --out contacts.vcf

Preview by default.

gog contacts dedupe --json gog contacts dedupe --match email,phone,name

Inspect the mutation plan, then apply with confirmation.

gog contacts dedupe --apply --dry-run --json gog contacts dedupe --apply

Scope automation to exact reviewed contact resources.

gog contacts dedupe --resource people/123 --resource people/456 --apply --fo