gogcli

gog is a script-friendly Google CLI for Gmail, Calendar, Drive, Docs, Sheets, Sites, Slides, Forms, Meet, Apps Script, Analytics, Search Console, Contacts, Tasks, People, Classroom, Chat, YouTube, and Workspace admin flows.

It is built for terminals, shell scripts, CI, and coding agents:

• predictable --json and --plain output on stdout
• human hints and progress on stderr
• multiple Google accounts and OAuth clients
• OAuth, direct access tokens, ADC, and Workspace service accounts
• runtime command allowlists/denylists and baked safety-profile binaries
• read-only audit/reporting commands for risky surfaces like Drive and Contacts
• generated docs for every command

Rendered docs: https://gogcli.sh/

Start here:

• Install
• Quickstart
• Auth clients and service accounts
• Command index
• Gmail watch / Pub/Sub push (https://gogcli.sh/watch.html)

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 config volume and the encrypted file keyring:

docker volume create gogcli-config

docker run --rm -it \
  -e GOG_KEYRING_BACKEND=file \
  -e GOG_KEYRING_PASSWORD \
  -v gogcli-config:/home/gog/.config/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
• 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.

If your OAuth app is External + Testing, Google refresh tokens for user-data scopes can expire after 7 days. Publish the personal OAuth app if you want long-lived refresh tokens.

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

Calendar

Docs: gog calendar, calendar create, calendar update, calendar move, 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 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 appointments

Drive

Docs: Drive audits, raw API dumps, gog drive, drive changes, 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 activity query --file <fileId> --actions edit,share --from 2026-01-01T00:00:00Z --json

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

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

Contacts

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

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

# Preview only: no merge/delete/update call is made.
gog contacts dedupe --json
gog contacts dedupe --match email,phone,name --dry-run

Docs

Docs: Google Docs editing, sed-style document edits, gog docs.

gog docs write <docId> --append --markdown --text '## Status'
gog docs format <docId> --match Status --bold --font-size 18
gog docs insert-page-break <docId> --at-end
gog docs insert-table <docId> --rows 3 --cols 2 --at-end
gog docs add-tab <docId> --title "Notes"
gog docs tabs add <docId> --title "Notes"
gog docs find-replace <docId> old new --tab "Notes" --dry-run
gog docs raw <docId> --pretty

Sheets

Docs: Sheets batch updates, Sheets tables, Sheets formatting, gog sheets.

gog sheets get <spreadsheetId> 'Sheet1!A1:D20' --json
gog sheets batch-update <spreadsheetId> --data-json @updates.json --json
gog sheets table list <spreadsheetId>
gog sheets table append <spreadsheetId> Tasks 'Ship README|done'
gog sheets table clear <spreadsheetId> Tasks
gog sheets conditional-format add <spreadsheetId> 'Sheet1!A2:A100' \
  --type text-contains \
  --expr blocked \
  --format-json '{"backgroundColor":{"red":1,"green":0.84,"blue":0.84}}'
gog sheets banding set <spreadsheetId> 'Sheet1!A1:D100'

Slides and Forms

Docs: Slides from Markdown, template replacement, gog slides, gog forms.

gog slides create-from-markdown "Weekly update" --content-file slides.md
gog slides insert-text <presentationId> <objectId> "New text"
gog forms update <formId> --quiz=true
gog forms add-question <formId> --title "What is 2+2?" --type radio -o 1 -o 4 --correct 4 --points 1
gog forms questions add <formId> --title "What is 2+2?" --type radio -o 1 -o 4 --correct 4 --points 1
gog forms publish <formId>
gog forms responses list <formId> --json
gog forms raw <formId> --pretty

YouTube

Docs: gog youtube, youtube channels, youtube videos, youtube activities.

gog config set youtube_api_key YOUR_API_KEY
gog yt channels list --id UC_x5XG1OV2P6uZZ5FSM9Ttw --json
gog yt videos list --chart mostPopular --region US --max 5
gog yt activities list --mine -a you@gmail.com

For API-key reads, enable YouTube Data API v3 on the key's Google Cloud project and make sure API-key restrictions allow YouTube Data API calls. Authenticated --mine reads use OAuth instead.

Analytics and Search Console

Docs: gog analytics, analytics report, gog searchconsole, searchconsole query.

gog analytics accounts --all --json
gog analytics report 123456789 --from 7daysAgo --to today --dimensions date,country --metrics activeUsers,sessions
gog searchconsole sites
gog searchconsole query sc-domain:example.com --from 2026-02-01 --to 2026-02-07 --dimensions query,page --filter query:contains:gog
gog searchconsole sitemaps submit sc-domain:example.com https://example.com/sitemap.xml --force

Backup

Docs: Backup, gog backup.

gog backup init --repo ~/Backups/gog
gog backup push --services gmail,calendar,contacts,drive
gog backup verify
gog backup export --gmail-format markdown --out ~/Exports/gog

See docs/backup.md before running broad or unattended backup jobs.

Output and Automation

Docs: Safety Profiles, gog schema, gog config no-send.

Use --json for structured output and --plain for stable TSV. Prompts, progress, and warnings go to stderr so stdout stays parseable.

gog --json gmail search 'has:attachment newer_than:90d' --max 50 |
  jq -r '.threads[].id'

gog --plain calendar events --today

Useful global flags:

• --account <email|alias|auto>: select an account
• --client <name>: select a stored OAuth client
• --json: JSON stdout
• --plain: stable parseable text stdout
• --wrap-untrusted: in JSON/raw output, wrap fetched free-text fields with external untrusted-content markers for LLM/agent consumption
• --dry-run: print intended actions where a command supports planning
• --no-input: fail instead of prompting
• --force: confirm destructive operations
• --enable-commands <csv>: allow only selected command paths
• --disable-commands <csv>: block selected command paths
• --gmail-no-send: block Gmail send operations

For coding agents or CI, prefer:

gog --account you@gmail.com \
  --enable-commands gmail.search,gmail.get,drive.ls,docs.cat \
  --gmail-no-send \
  --wrap-untrusted \
  --json \
  gmail search 'newer_than:7d'

For stricter agent deployments, build or download a baked safety-profile binary. See docs/safety-profiles.md.

Auth and Accounts

Docs: Auth clients, gog auth, auth add, auth doctor, auth service-account.

OAuth clients

Store a Desktop OAuth client once:

gog auth credentials ~/Downloads/client_secret_....json
gog auth add you@gmail.com --services gmail,calendar,drive

Use named clients when different accounts should use different Cloud projects:

gog --client work auth credentials ~/Downloads/work-client.json
gog --client work auth add you@company.com
gog auth credentials list

See docs/auth-clients.md for client selection rules, domain mapping, remote OAuth, direct access tokens, ADC, and service accounts.

Account selection

gog auth list --check
gog auth alias set work you@company.com

gog --account work gmail search 'is:unread'
export GOG_ACCOUNT=you@gmail.com
gog calendar events --today

Keyring backends

By default gog uses the best OS keyring available. For headless or container runs, use the encrypted file backend and inject GOG_KEYRING_PASSWORD from the current shell or secret store.

gog auth keyring
gog auth keyring file
GOG_KEYRING_BACKEND=file GOG_KEYRING_PASSWORD=... gog auth list --check

For systemd services, gateways, and coding agents, set the same variables on the service or agent process itself. A successful shell check does not mean the agent subprocess inherited GOG_KEYRING_PASSWORD; verify through the actual agent entrypoint with gog auth doctor --check --no-input.

Use GOG_HOME=/persist/gogcli to keep config, data, state, and cache under one portable root, or set GOG_CONFIG_DIR, GOG_DATA_DIR, GOG_STATE_DIR, and GOG_CACHE_DIR individually for split lifetimes. These overrides are above XDG paths and are useful in containers, CI, and agent sandboxes.

Never commit OAuth client JSON files, refresh tokens, service-account keys, or file-keyring passwords.

Workspace service accounts

Workspace admins can configure domain-wide delegation and then store a service-account key for the user to impersonate:

gog auth service-account set user@company.com --key ~/Downloads/service-account.json
gog --account user@company.com auth status

Service accounts are mainly useful for Workspace Admin, Groups, Keep, and domain-wide automation. They do not replace normal OAuth for consumer Gmail accounts.

Services

Docs: Command index, Workspace Admin, gog auth services.

Common user services:

• Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Meet, Zoom, Apps Script
• Analytics and Search Console
• Contacts, People, Tasks, Classroom
• Chat for Workspace accounts
• Backup and local utility commands

Workspace/admin services:

• Admin Directory
• Cloud Identity Groups
• Keep with domain-wide delegation

Admin Directory includes Workspace user creation from the CLI:

gog --account admin@example.com admin users create ada@example.com \
  --first-name Ada \
  --last-name Lovelace \
  --password 'TempPass123!' \
  --change-password \
  --ou /Engineering

Omit --password to generate a temporary password. See docs/workspace-admin.md for service-account setup, user cleanup, recovery fields, organizational units, and group examples.

Workspace organizational units are covered too:

gog --account admin@example.com admin orgunits list --type all
gog --account admin@example.com admin orgunits create Engineering --parent /

Generated service scope table:

Service	User	APIs	Scopes	Notes
gmail	yes	Gmail API	https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/gmail.settings.basic https://www.googleapis.com/auth/gmail.settings.sharing
calendar	yes	Calendar API	https://www.googleapis.com/auth/calendar
chat	yes	Chat API	https://www.googleapis.com/auth/chat.spaces https://www.googleapis.com/auth/chat.messages https://www.googleapis.com/auth/chat.memberships https://www.googleapis.com/auth/chat.users.readstate.readonly https://www.googleapis.com/auth/chat.messages.reactions.create https://www.googleapis.com/auth/chat.messages.reactions.readonly
classroom	yes	Classroom API	https://www.googleapis.com/auth/classroom.courses https://www.googleapis.com/auth/classroom.rosters https://www.googleapis.com/auth/classroom.coursework.students https://www.googleapis.com/auth/classroom.coursework.me https://www.googleapis.com/auth/classroom.courseworkmaterials https://www.googleapis.com/auth/classroom.announcements https://www.googleapis.com/auth/classroom.topics https://www.googleapis.com/auth/classroom.guardianlinks.students https://www.googleapis.com/auth/classroom.profile.emails https://www.googleapis.com/auth/classroom.profile.photos
drive	yes	Drive API	https://www.googleapis.com/auth/drive
driveactivity	yes	Drive Activity API	https://www.googleapis.com/auth/drive.activity.readonly	Read-only audit/activity scope; authorize with --services driveactivity
drivelabels	yes	Drive Labels API	https://www.googleapis.com/auth/drive.labels.readonly	Read-only Drive label schema; authorize with --services drivelabels
docs	yes	Docs API, Drive API	https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/documents	Export/copy/create via Drive
slides	yes	Slides API, Drive API	https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/presentations	Create/edit presentations
contacts	yes	People API	https://www.googleapis.com/auth/contacts https://www.googleapis.com/auth/contacts.other.readonly https://www.googleapis.com/auth/directory.readonly	Contacts + other contacts + directory
tasks	yes	Tasks API	https://www.googleapis.com/auth/tasks
sheets	yes	Sheets API, Drive API	https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/spreadsheets	Export via Drive
people	yes	People API	profile	OIDC profile scope
forms	yes	Forms API	https://www.googleapis.com/auth/forms.body https://www.googleapis.com/auth/forms.responses.readonly
sites	yes	Drive API	https://www.googleapis.com/auth/drive	New Google Sites are exposed as Drive files
meet	yes	Meet REST API	https://www.googleapis.com/auth/meetings.space.created https://www.googleapis.com/auth/meetings.space.readonly https://www.googleapis.com/auth/meetings.space.settings
appscript	yes	Apps Script API	https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.processes
analytics	yes	Analytics Admin API, Analytics Data API	https://www.googleapis.com/auth/analytics.readonly	GA4 account summaries + reporting
searchconsole	yes	Search Console API	https://www.googleapis.com/auth/webmasters	Search Analytics + sitemap management
ads	yes	Google Ads API	https://www.googleapis.com/auth/adwords	OAuth scope only
groups	no	Cloud Identity API	https://www.googleapis.com/auth/cloud-identity.groups.readonly	Workspace only
keep	no	Keep API	https://www.googleapis.com/auth/keep	Workspace only; service account (domain-wide delegation)
admin	no	Admin SDK Directory API	https://www.googleapis.com/auth/admin.directory.user https://www.googleapis.com/auth/admin.directory.group https://www.googleapis.com/auth/admin.directory.group.member	Workspace only; service account with domain-wide delegation required
youtube	yes	YouTube Data API v3	https://www.googleapis.com/auth/youtube.readonly	Most read operations also work with API key only (config youtube_api_key or GOG_YOUTUBE_API_KEY)
photos	yes	Photos Library API	https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata	Read-only app-created media only after Google Photos Library API scope changes

Regenerate the table with:

go run scripts/gen-auth-services-md.go

Documentation

• Overview — rendered at https://gogcli.sh/
• Install — https://gogcli.sh/install.html
• Quickstart — https://gogcli.sh/quickstart.html
• Command index — https://gogcli.sh/commands/
• Gmail workflows — https://gogcli.sh/gmail-workflows.html
• Gmail watch — https://gogcli.sh/watch.html
• Drive audits — https://gogcli.sh/drive-audits.html
• Docs editing — https://gogcli.sh/docs-editing.html
• Sheets tables and Sheets formatting
• Safety profiles — command guards and baked safe binaries
• Auth clients — OAuth clients, account mapping, and service accounts
• Workspace Admin — Workspace user, org unit, and group administration
• Backup — encrypted Google account backups
• CHANGELOG.md: release notes

Every command also has help built in:

gog --help
gog gmail --help
gog drive inventory --help
gog schema --json

Development

make tools
make build
make fmt
make lint
make test
make ci

Generated command docs:

make docs-commands
make docs-site
open dist/docs-site/index.html

Live Google API smoke tests are opt-in:

scripts/live-test.sh --fast --account you@gmail.com
GOG_IT_ACCOUNT=you@gmail.com go test -tags=integration ./internal/integration

See docs/RELEASING.md for the release checklist.

Credits

Inspired by Mario Zechner's original Google CLIs:

• gmcli
• gccli
• gdcli

License

MIT