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 you@example.com --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 you@gmail.com --services gmail,calendar,drive
export GOG_ACCOUNT=you@gmail.com
gog auth doctor --check
gog gmail search 'newer_than:7d' --max 10

gog auth you@gmail.com is shorthand for gog auth add you@gmail.com, 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 you@gmail.com \
  --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.

gog auth list --check
gog auth alias set work you@company.com
gog --account work gmail search 'is:unread'

See OAuth clients for client selection and service accounts, and Paths and State for GOG_HOME, XDG paths, and keyring storage.

Discover the contract

Running gog with no arguments shows the executable path, a short description, and local auth/config status. Use gog --help for the command overview. When JSON output is selected through the environment, the no-args view emits only the status JSON object.

The running binary generates its command schema, reference pages, and agent skills from the same command tree:

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

gog mcp exposes a typed stdio MCP server without a generic shell or command bridge. It is read-only by default; writes require explicit command and tool authorization. See the MCP guide.

Supported OAuth services

The generated table below records the user OAuth and Workspace service-account surface. gog auth services reports the same information from the installed binary.

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 + URL Inspection
adsense	no	AdSense Management API	https://www.googleapis.com/auth/adsense.readonly	Consumer OAuth; explicit opt-in with --services adsense; read-only
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; --photos-scope=append adds upload and album create
photospicker	no	Photos Picker API	https://www.googleapis.com/auth/photospicker.mediaitems.readonly	Consumer OAuth; explicit opt-in with --services photospicker; selected media only

Documentation

gog drive get <fileId> --fields id,trashed --json preserves "trashed": false. The default metadata also includes false starred and hasThumbnail values. Conditionally absent fields (shared, ownedByMe, writersCanShare, and hasAugmentedPermissions) and nested booleans retain the SDK's omission behavior; use gog drive raw when you need the exact API response.

• Overview and guides
• Examples
• Command index
• Gmail workflows
• Drive audits
• AdSense accounts and reports
• Docs, Sheets, and Slides guides
• Changelog

gog is open source and is not affiliated with Google.

Credits

Inspired by Mario Zechner's gmcli, gccli, and gdcli.

Development

The project requires the Go version declared in go.mod.

make build
make test
make ci

See live testing for opt-in Google API smoke tests and releasing for the maintainer workflow.

License

MIT