gogcli

Table of content

every cloud service wants you trapped in their web UI. Google is particularly aggressive about this — Gmail’s interface alone has more features than most operating systems. gogcli is the escape hatch.

what it is

gogcli (1,922 ★) by Peter Steinberger is a terminal-native interface to the entire Google Suite. not just Gmail — the whole stack. calendar, drive, contacts, tasks, sheets, forms, docs, slides, chat, classroom, keep, groups, apps script. everything.

JSON-first output means every command is scriptable. multiple account support means you can juggle work/personal/side-project identities without browser profile hell. least-privilege auth means you only grant the scopes you actually need.

built by someone who clearly got tired of opening Gmail in a browser for the 10,000th time.

why it matters

AI agents don’t have hands. they can’t click through Google’s labyrinthine web UIs. but they can execute shell commands and parse JSON.

gogcli turns your entire Google workspace into an API surface that agents can interact with directly. need an agent to:

all of it becomes terminal commands. which means all of it becomes agent-accessible.

this isn’t just convenience. it’s infrastructure. the same commands you run manually become the primitives your agents use. no translation layer, no API wrapper, no “export this so the agent can see it” dance.

how it works

authenticate once (OAuth2), get auto-refreshing tokens stored securely in your OS keychain. then it’s just commands:

# search gmail
gog gmail search 'newer_than:7d from:important@client.com'

# today's calendar
gog calendar events --today --json

# upload to drive
gog drive upload ./report.pdf --parent <folder-id>

# create a doc
gog docs create "meeting notes"

# send email
gog gmail send --to someone@example.com \
  --subject "follow-up" \
  --body-file ./message.txt

# list tasks
gog tasks list <tasklistId>

# search contacts
gog contacts search "ada"

JSON output for everything means you can pipe to jq, feed into scripts, or hand directly to an agent’s context window. plain-text output (TSV) for when you want tab-delimited data.

multiple accounts via aliases:

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

service account support for Workspace means domain-wide delegation works. keep (notes) requires this, since it’s Workspace-only.

least-privilege scopes: you can authorize with only --services gmail,calendar or request --readonly to prevent write operations. no “grant us access to everything” nonsense.

agent-friendly design

the CLI was clearly built with automation in mind:

example agent workflow:

# agent checks calendar for conflicts
CONFLICTS=$(gog calendar conflicts --today --json)

# agent searches email for context
THREAD=$(gog gmail search "project:launch" --max 1 --json)

# agent drafts response
gog gmail drafts create \
  --to team@company.com \
  --subject "re: launch timing" \
  --body "$(cat agent-response.txt)"

the command allowlist is especially clever. you can restrict an agent to only calendar/tasks operations, preventing it from sending emails or deleting files:

export GOG_ENABLE_COMMANDS=calendar,tasks
# agent can only touch calendar and tasks now

install

# homebrew
brew install steipete/tap/gogcli

# or build from source
git clone https://github.com/steipete/gogcli.git
cd gogcli
make
./bin/gog --help

setup flow:

  1. create OAuth2 credentials from Google Cloud Console
  2. store them: gog auth credentials ~/Downloads/client_secret.json
  3. authorize: gog auth add you@gmail.com
  4. test: gog gmail labels list

headless/remote server setup via --manual or --remote flows. no browser required on the server.

fits the self.md thesis

the self.md thesis says: your repo is your operating system. tools that speak plain text and git win.

gogcli fits this perfectly. it doesn’t try to be a platform. it’s a translator. it takes Google’s maze of web UIs and flattens them into shell commands that output structured text.

which means:

compare to alternatives:

this is what “personal AI OS” looks like in practice: your cloud services become terminal primitives. your agents speak the same language you do.