gog 🧭 — Google Workspace from the terminal

gog is one command-line client for Gmail, Calendar, Drive, Docs, Sheets, and the wider Google Workspace surface. It is built for people, scripts, CI, and agents that need explicit account routing, machine-readable output, and safety controls.

gog --readonly gmail search 'is:unread newer_than:7d' --max 10 --json
gog --readonly calendar events --today --json
gog --readonly drive audit sharing --parent <folderId> --json

For least-privilege Gmail authorization, use gog auth add [email protected] --services gmail --gmail-scope send for sending only, or --gmail-scope read-send to also read messages without mailbox-modification or settings-management permissions.

Install

Homebrew is the shortest path on macOS and Linux. Prebuilt macOS binaries require macOS 15 or later:

brew install openclaw/tap/gogcli
gog --version

With Go:

go install github.com/openclaw/gogcli/cmd/gog@latest
gog --version

Install scripts using the former github.com/steipete/gogcli module path should switch to github.com/openclaw/gogcli as shown above.

Docker images, Windows archives, raw macOS/Linux binaries, and source builds are covered in the install guide.

Quick start

Create a Desktop OAuth client in a Google Cloud project, download its JSON file, and authorize only the services you need:

gog auth credentials set ~/Downloads/client_secret_*.json
gog auth add [email protected] --services gmail,calendar,drive
export [email protected]
gog auth doctor --check
gog gmail search 'newer_than:7d' --max 10

gog auth [email protected] is shorthand for gog auth add [email protected], with the same flags.

For Gmail queries beginning with -, place all flags before --; see Search and Read.

The five-minute quickstart covers API enablement, the OAuth consent screen, weekly-token-expiry avoidance, headless authorization, and account defaults.

Work with Google services

Commands follow the resource you are working with. These are the common entry points; the examples and generated command index cover the full surface.

Work	Start with
Mail and calendars	gog gmail search, gog calendar events
Files and sharing	gog drive ls, gog drive audit sharing
Docs, Sheets, Slides, and Forms	gog docs, gog sheets, gog slides, gog forms
Contacts and tasks	gog contacts, gog tasks
Meetings and chat	gog meet, gog chat, gog zoom
Analytics and publishing	gog analytics, gog searchconsole, gog adsense, gog youtube
Workspace administration	gog admin, gog groups, gog keep
Discovery API fallback	gog api describe, gog api call

Generic API commands support service-hosted Discovery documents such as Meet v2 when the default central Directory returns 404. Explicit GOG_DISCOVERY_BASE_URL overrides retain their existing behavior.

GOG_GOOGLE_API_BASE_URL=http(s)://host[:port] sends Google API requests for https://googleapis.com and https://*.googleapis.com to a test server, emulator, proxy, or relay that adds credentials outside gog. Path and query are kept and the original host is sent as X-Forwarded-Host. While it is set, gog attaches no credentials to Google API requests (no OAuth, ADC, service-account, --access-token, or API-key credentials), does not need stored tokens, and refuses cross-origin redirects, so the relay handles any upstream redirects. --account still selects the account label. Use https for endpoints that are not on loopback. Discovery documents still use GOG_DISCOVERY_BASE_URL; gRPC clients such as the Pub/Sub pull used by gmail watch pull, Maps/Places API-key calls, and downloads from non-googleapis.com URLs are not redirected, and gog auth commands still talk to Google directly. Invalid values fail with a usage error.

Consumer Google accounts work with user-facing APIs. Admin Directory, Cloud Identity Groups, Chat, Keep, and domain-wide delegation require a managed Google Workspace domain. The Workspace Admin guide explains that setup.

Automate safely

--json emits structured output and --plain emits stable TSV. Prompts, progress, and warnings go to stderr. --no-input, --readonly, exact command allowlists, Gmail no-send policy, dry-run plans, and untrusted-content wrapping let the caller define a narrower execution boundary.

gog --account [email protected] \
  --enable-commands-exact gmail.search,gmail.get \
  --gmail-no-send --readonly --no-input --wrap-untrusted --json \
  gmail search 'newer_than:7d'

See Automation for output and exit-code contracts, and Safety Profiles for binaries with command policy and locked flag values baked in at build time.

Accounts and authentication

One installation can route among multiple Google accounts, named OAuth client projects, direct access tokens, Application Default Credentials, and Workspace service accounts. Tokens use the platform keyring by default; headless systems can use the encrypted file backend.

This is the beginning of the README. Read the rest at the original. Read the full README ↗