Google’s suite of tools is genuinely useful. It’s also genuinely hostile to anyone who prefers a terminal over a browser tab. The web UI is fine for casual use, but the moment you want to script something — search your inbox, bulk-download Drive files, export a Sheet as PDF — you’re stuck reaching for the API directly, wrestling with OAuth flows and client libraries, or writing throwaway Python that you’ll never touch again.
gogcli by Peter Steinberger is a pragmatic solution to this. It’s a single Go binary called gog that wraps Gmail, Calendar, Drive, Contacts, Tasks, Sheets, Docs, and Slides under a consistent CLI interface. It’s MIT-licensed, Homebrew-installable, and released in December 2025 at version 0.1.0.
What It Actually Covers
The README undersells the scope. According to the project website, the supported surface area is:
- Gmail: search threads, send mail, manage labels, drafts, filters, settings, Pub/Sub watch
- Calendar: list/create/update events, respond to invites, detect conflicts, free/busy checks
- Drive: list, search, upload, download, export formats, manage permissions
- Sheets / Docs / Slides: read/write Sheets; export any of them to PDF, DOCX, PPTX, XLSX, or CSV via the Drive export API
- Contacts / People API: personal contacts, “other contacts”, Workspace directory (Workspace accounts only), your profile
- Tasks: tasklists and tasks with add/update/done/undo/delete/clear, pagination, JSON output
That’s a wide surface for a v0.1.0. The depth per service will inevitably vary, but coverage of export formats alone makes it worth investigating for anyone managing Google documents programmatically.
The OAuth Hurdle (You Won’t Escape It)
There’s no avoiding it: you need to set up a Google Cloud project with OAuth2 credentials before gog does anything. This is a Google-imposed requirement, not a design choice, and it’s a genuine friction point. Here’s the minimum path:
- Create a project at console.cloud.google.com
- Enable each API you need (Gmail, Calendar, Drive, People, etc.) individually
- Configure an OAuth consent screen and, if your app is in “Testing” mode, explicitly add yourself as a test user
- Create an OAuth client — type Desktop app — and download the JSON
Then:
gog auth credentials ~/Downloads/client_secret_....json
gog auth add you@gmail.com
The second command launches a browser OAuth flow. The resulting refresh token is stored in your OS keychain — Keychain on macOS, libsecret/GNOME Keyring on Linux, Credential Manager on Windows — via the 99designs/keyring library. This is the right call: tokens don’t live in a plaintext config file.
You can scope down at auth time to request only the APIs you need:
gog auth add you@gmail.com --services drive,calendar
If you later add a service and Google refuses to return a fresh refresh token (which it sometimes does), re-run with --force-consent. Multi-account support is built-in; gog auth list shows what’s configured.
For headless environments, there’s a --manual flag on gog auth add that skips the browser and gives you a URL to visit manually — useful for servers.
Design: Sensible Defaults, Clean Output
gog makes one important architectural decision correctly: data goes to stdout, human-readable hints go to stderr. This means piping works without suppressing useful feedback:
gog gmail search 'newer_than:7d' --max 50 --json | jq '.threads[] | .subject'
Output formats are text (tab-separated, default), --plain (for even simpler consumption), and --json. Colors are auto-detected and disabled when output is not a TTY or when --json is active. You can drive these via environment variables to avoid repeating flags everywhere:
export GOG_ACCOUNT=you@gmail.com
export GOG_OUTPUT=json
Set GOG_ACCOUNT once in your shell profile and most commands just work without any flags.
Commands You’ll Actually Use
A few concrete examples that illustrate the tool’s range:
# Inbox zero pipeline
gog gmail search 'is:unread newer_than:7d' --max 20 --json | jq '.threads[] | {id, subject, from}'
# Send a quick mail
gog gmail send --to colleague@example.com --subject "Draft attached" --body "See attached."
# List upcoming calendar events
gog calendar events primary --from 2026-02-15T00:00:00Z --to 2026-02-22T00:00:00Z --max 50
# Find PDFs in Drive
gog drive ls --query "mimeType='application/pdf'" --max 20
# Export a Google Sheet to PDF
gog sheets export <spreadsheetid> --format pdf --out ./report.pdf</spreadsheetid>
# Export a Doc to DOCX
gog docs export <docid> --format docx --out ./contract.docx</docid>
# Search contacts
gog contacts search "Jane" --max 20 --json
# Mark a task done
gog tasks update <tasklistid><taskid> --done</taskid></tasklistid>
The export commands are particularly useful. If you’re auto-generating Google Docs or Sheets and need to distribute them as PDFs without touching a browser, this plugs that gap cleanly.
Building from Source
If you prefer not to use the Homebrew tap or want to hack on it:
git clone https://github.com/steipete/gogcli.git
cd gogcli
make
./bin/gog --help
The project uses golangci-lint for linting and goimports + gofumpt for formatting. CI runs format checks, tests, and lint on every push. The go.mod is in the root; the binary entrypoint is cmd/gog, with implementation split under internal/.
Limitations Worth Knowing
It’s v0.1.0. The first release dropped in December 2025, and the project has 17 stars and 1 fork as of February 2026. Commit frequency is the real indicator of health to watch. Treat it as early-stage software and pin a version in any automation that depends on it.
Google Workspace vs. free Gmail. The Contacts directory search (gog contacts directory) only works with Workspace accounts. Free @gmail.com accounts will hit a permissions wall there — this is an API restriction, not a bug.
The OAuth setup tax is real. First-time setup takes 10–15 minutes even if you know your way around the GCP console. This is irreducible, but you only pay it once per Google account.
No write support for Docs/Slides yet. The website lists read/export for Docs and Slides, but write operations appear to be Drive/Sheets-only for now.
Who This Is For
gog is worth your time if you regularly interact with Google Workspace from scripts, CI pipelines, or just prefer a terminal over context-switching to a browser. The export functionality alone — turning Sheets and Docs into PDFs or Office formats from a shell one-liner — earns it a place in any automation toolbox that touches Google’s ecosystem.
If you’re building something heavier — a full integration with a backend service, a multi-user system — you’ll want to talk to the Google APIs directly with proper service account auth. gog is firmly a personal productivity and scripting tool, not a daemon or a library.
Inspired by Mario Zechner’s earlier trio of single-purpose CLIs (gmcli, gccli, gdcli), Steinberger merged the concept into one cohesive binary with better UX and a broader API surface. The foundation is solid. Whether it grows into a comprehensive tool depends entirely on ongoing maintenance, but it’s already useful today.
Links: GitHub · gogcli.sh · brew install steipete/tap/gogcli