gogcli

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:

check your calendar before scheduling?
search Gmail for context on a thread?
upload a generated report to Drive?
send a follow-up email?
create a doc from agent output?

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:[email protected]'

# 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 [email protected] \
  --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 [email protected]
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:

JSON everywhere: --json flag on every command
stable output: --plain mode for TSV that won’t break your parsers
no interactive prompts: --no-input mode for headless runs
allowlist commands: --enable-commands calendar,tasks sandboxes what an agent can do
multiple accounts: agents can operate as different users
error codes: proper exit codes for script flows

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 [email protected] \
  --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:

create OAuth2 credentials from Google Cloud Console
store them: gog auth credentials ~/Downloads/client_secret.json
authorize: gog auth add [email protected]
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:

agents can interact with your Google workspace
scripts can automate your Google workflows
you can pipe Google data through standard unix tools
version control works (commit the JSON output)
CI/CD can touch your Google services

compare to alternatives:

Google’s web UI: agent-hostile, requires browser automation
official client libraries: heavy, language-specific, verbose
zapier/IFTTT: proprietary platforms, not git-native
gogcli: terminal commands, JSON output, works everywhere

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

x-cli — terminal-native Twitter/X access (same philosophy)
AI Coding Assistants — agents that could use gogcli for context
markdown files are the new API layer — why plaintext tooling matters