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> --jsonFor 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:
brew install openclaw/tap/gogcli
gog --versionWith Go:
go install github.com/openclaw/gogcli/cmd/gog@latest
gog --versionInstall 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 10The 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.
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
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 inventorygog 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.modifyhttps://www.googleapis.com/auth/gmail.settings.basichttps://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.spaceshttps://www.googleapis.com/auth/chat.messageshttps://www.googleapis.com/auth/chat.membershipshttps://www.googleapis.com/auth/chat.users.readstate.readonlyhttps://www.googleapis.com/auth/chat.messages.reactions.createhttps://www.googleapis.com/auth/chat.messages.reactions.readonly |
|
| classroom | yes | Classroom API | https://www.googleapis.com/auth/classroom.courseshttps://www.googleapis.com/auth/classroom.rostershttps://www.googleapis.com/auth/classroom.coursework.studentshttps://www.googleapis.com/auth/classroom.coursework.mehttps://www.googleapis.com/auth/classroom.courseworkmaterialshttps://www.googleapis.com/auth/classroom.announcementshttps://www.googleapis.com/auth/classroom.topicshttps://www.googleapis.com/auth/classroom.guardianlinks.studentshttps://www.googleapis.com/auth/classroom.profile.emailshttps://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/drivehttps://www.googleapis.com/auth/documents |
Export/copy/create via Drive |
| slides | yes | Slides API, Drive API | https://www.googleapis.com/auth/drivehttps://www.googleapis.com/auth/presentations |
Create/edit presentations |
| contacts | yes | People API | https://www.googleapis.com/auth/contactshttps://www.googleapis.com/auth/contacts.other.readonlyhttps://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/drivehttps://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.bodyhttps://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.createdhttps://www.googleapis.com/auth/meetings.space.readonlyhttps://www.googleapis.com/auth/meetings.space.settings |
|
| appscript | yes | Apps Script API | https://www.googleapis.com/auth/script.projectshttps://www.googleapis.com/auth/script.deploymentshttps://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.userhttps://www.googleapis.com/auth/admin.directory.grouphttps://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 |
| 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
- 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 ciSee live testing for opt-in Google API smoke tests and releasing for the maintainer workflow.
