discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
openclaw/gogcli · source
Snapshot 0 · 2026-11-04T12:47:28Z · Go · MIT
Content fingerprint
ba3ca079c32fee912761678361a05383586ef97358aec3d60e34acfcb11bc3abGitHub description at capture
Google Workspace in your terminal.
README at capture
# gog 🧭 — Google Workspace from the terminal  [](https://github.com/openclaw/gogcli/actions/workflows/ci.yml) [](https://github.com/openclaw/gogcli/releases/latest) [](https://go.dev/) [](LICENSE) [](https://github.com/openclaw/homebrew-tap) `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. ```bash 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: ```bash brew install openclaw/tap/gogcli gog --version ``` With Go: ```bash 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](docs/install.md). ## Quick start Create a Desktop OAuth client in a [Google Cloud project](https://console.cloud.google.com/auth/clients), download its JSON file, and authorize only the services you need: ```bash 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](docs/gmail-workflows.md#search-and-read). The [five-minute quickstart](docs/quickstart.md) 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](docs/examples.md) and generated [command index](docs/commands/README.md) 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](docs/workspace-admin.md) 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. ```bash 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](docs/automation.md) for output and exit-code contracts, and [Safety Profiles](docs/safety-profiles.md) 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. ```bash gog auth list --check gog auth alias set work you@company.com gog --account work gmail search 'is:unread' ``` See [OAuth clients](docs/auth-clients.md) for client selection and service accounts, and [Paths and State](docs/paths.md) 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: ```bash 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](docs/mcp.md). ## 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. The default `user`/`all-user` set excludes `ads`. Google treats authorizing an app for Google Ads as a sensitive action and can block consent behind a mandatory passkey enrollment. Add it only when you need it: `gog auth add you@example.com --services user,ads`. <!-- auth-services:start --> | Service | User | APIs | Scopes | Notes | | --- | --- | --- | --- | --- | | gmail | yes | Gmail API | `https://www.googleapis.com/auth/gmail.modify`<br>`https://www.googleapis.com/auth/gmail.settings.basic`<br>`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`<br>`https://www.googleapis.com/auth/chat.messages`<br>`https://www.googleapis.com/auth/chat.memberships`<br>`https://www.googleapis.com/auth/chat.users.readstate.readonly`<br>`https://www.googleapis.com/auth/chat.messages.reactions.create`<br>`https://www.googleapis.com/auth/chat.messages.reactions.readonly` | | | classroom | yes | Classroom API | `https://www.googleapis.com/auth/classroom.courses`<br>`https://www.googleapis.com/auth/classroom.rosters`<br>`https://www.googleapis.com/auth/classroom.coursework.students`<br>`https://www.googleapis.com/auth/classroom.coursework.me`<br>`https://www.googleapis.com/auth/classroom.courseworkmaterials`<br>`https://www.googleapis.com/auth/classroom.announcements`<br>`https://www.googleapis.com/auth/classroom.topics`<br>`https://www.googleapis.com/auth/classroom.guardianlinks.students`<br>`https://www.googleapis.com/auth/classroom.profile.emails`<br>`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`<br>`https://www.googleapis.com/auth/documents` | Export/copy/create via Drive | | slides | yes | Slides API, Drive API | `https://www.googleapis.com/auth/drive`<br>`https://www.googleapis.com/auth/presentations` | Create/edit presentations | | contacts | yes | People API | `https://www.googleapis.com/auth/contacts`<br>`https://www.googleapis.com/auth/contacts.other.readonly`<br>`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`<br>`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`<br>`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`<br>`https://www.googleapis.com/auth/meetings.space.readonly`<br>`https://www.googleapis.com/auth/meetings.space.settings` | | | appscript | yes | Apps Script API | `https://www.googleapis.com/auth/script.projects`<br>`https://www.googleapis.com/auth/script.deployments`<br>`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 | no | Google Ads API | `https://www.googleapis.com/auth/adwords` | Explicit opt-in with --services ads; Google may require a passkey to authorize Google Ads access | | 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`<br>`https://www.googleapis.com/auth/admin.directory.group`<br>`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 | <!-- auth-services:end --> ## 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](https://gogcli.sh/) - [Examples](docs/examples.md) - [Command index](docs/commands/README.md) - [Gmail workflows](docs/gmail-workflows.md) - [Drive audits](docs/drive-audits.md) - [AdSense accounts and reports](docs/adsense.md) - [Docs, Sheets, and Slides guides](docs/index.md#pick-your-path) - [Changelog](CHANGELOG.md) `gog` is open source and is not affiliated with Google. ## Credits Inspired by Mario Zechner's [gmcli](https://github.com/badlogic/gmcli), [gccli](https://github.com/badlogic/gccli), and [gdcli](https://github.com/badlogic/gdcli). ## Development The project requires the Go version declared in `go.mod`. ```bash make build make test make ci ``` See [live testing](docs/live-testing.md) for opt-in Google API smoke tests and [releasing](docs/RELEASING.md) for the maintainer workflow. ## License [MIT](LICENSE)