gogcli

gog is a script-friendly Google CLI for Gmail, Calendar, Drive, Docs, Sheets, Sites, Slides, Forms, Meet, Apps Script, Analytics, Search Console, Contacts, Tasks, People, Classroom, Chat, YouTube, and Workspace admin flows.

It is built for terminals, shell scripts, CI, and coding agents:

predictable --json and --plain output on stdout
human hints and progress on stderr
multiple Google accounts and OAuth clients
OAuth, direct access tokens, ADC, and Workspace service accounts
runtime command allowlists/denylists and baked safety-profile binaries
read-only audit/reporting commands for risky surfaces like Drive and Contacts
generated docs for every command

Rendered docs: https://gogcli.sh/

Start here:

Install

See the full Install guide for Homebrew, Docker, Windows ZIPs, source builds, and headless/container keyring setup.

Homebrew

brew install gogcli
gog --version

Docker

docker run --rm ghcr.io/openclaw/gogcli:latest version

Authenticated container runs should use a persistent config volume and the encrypted file keyring:

docker volume create gogcli-config

docker run --rm -it \
  -e GOG_KEYRING_BACKEND=file \
  -e GOG_KEYRING_PASSWORD \
  -v gogcli-config:/home/gog/.config/gogcli \
  ghcr.io/openclaw/gogcli:latest \
  auth add you@gmail.com --services gmail,calendar,drive

Windows

Download gogcli_<version>_windows_amd64.zip or gogcli_<version>_windows_arm64.zip from the latest release, extract gog.exe, and put that directory on PATH.

Build from source

git clone https://github.com/openclaw/gogcli.git
cd gogcli
make
./bin/gog --version

Source builds require the Go version declared in go.mod.

Quick Start

The full walkthrough lives in Quickstart. For named OAuth clients, remote OAuth, direct access tokens, ADC, and Workspace service accounts, see Auth clients.

Create a Google Cloud project, enable the APIs you need, create a Desktop OAuth client, then store that client JSON in gog.

gog auth credentials ~/Downloads/client_secret_....json
gog auth add you@gmail.com --services gmail,calendar,drive,docs,sheets,contacts
gog auth doctor --check

export GOG_ACCOUNT=you@gmail.com
gog gmail search 'newer_than:7d' --max 10

Useful Google setup links:

Enable APIs in the same Cloud project that owns your OAuth client. If Google returns accessNotConfigured, enable that API and retry after propagation.

Consumer gmail.com accounts work for normal user APIs such as Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Analytics, Search Console, Contacts/People, Tasks, and Classroom. Workspace-only APIs such as Admin Directory, Cloud Identity Groups, Chat, and Keep/domain-wide-delegation flows require a managed domain.

If your OAuth app is External + Testing, Google refresh tokens for user-data scopes can expire after 7 days. Publish the personal OAuth app if you want long-lived refresh tokens.

Daily Examples

Every command below has generated reference docs in the Command index. The feature guides linked under each section explain the workflow shape and safety notes.

Gmail

Docs: Gmail workflows, Gmail watch, email tracking, gog gmail.

# Search mail and get sanitized message content for agents/scripts.
gog gmail search 'from:boss newer_than:30d' --json
gog gmail get <messageId> --sanitize-content --json

# Export Gmail filters in the format the Gmail web UI can import.
gog gmail settings filters export --out filters.xml

# Hard block send operations during automation.
gog --gmail-no-send gmail drafts create --to you@example.com --subject test

Calendar

Docs: gog calendar, calendar create, calendar update, calendar move.

gog calendar events --today
gog calendar create --summary "Review" \
  --from "2026-05-06T10:00:00+02:00" \
  --to "2026-05-06T10:30:00+02:00"
gog calendar create primary --summary "Coffee" \
  --from "2026-05-06T10:00:00+02:00" \
  --to "2026-05-06T10:30:00+02:00" \
  --location-search "Elysian Coffee Vancouver"
gog calendar update primary <eventId> --with-meet
gog calendar move primary <eventId> team-calendar@example.com

Drive

Docs: Drive audits, raw API dumps, gog drive, drive changes, drive activity.

# Read-only folder audits.
gog drive tree --parent <folderId> --depth 2
gog drive du --parent <folderId> --max 20 --json
gog drive inventory --parent <folderId> --json

# Ask Drive for non-default fields.
gog drive get <fileId> --fields 'id,name,mimeType,size,owners,emailAddress' --json

# Track changes and audit activity.
gog drive changes start-token
gog drive changes list --token <token> --json
gog drive activity query --file <fileId> --actions edit,share --from 2026-01-01T00:00:00Z --json

# Lossless raw API JSON.
gog drive raw <fileId> --pretty

Contacts

Docs: contacts dedupe, JSON contact updates, gog contacts.

gog contacts search alice --json
gog contacts export --all --out contacts.vcf

# Preview only: no merge/delete/update call is made.
gog contacts dedupe --json
gog contacts dedupe --match email,phone,name --dry-run

Docs

Docs: Google Docs editing, sed-style document edits, gog docs.

gog docs write <docId> --append --markdown --text '## Status'
gog docs format <docId> --match Status --bold --font-size 18
gog docs add-tab <docId> --title "Notes"
gog docs find-replace <docId> old new --tab "Notes" --dry-run
gog docs raw <docId> --pretty

Sheets

Docs: Sheets tables, Sheets formatting, gog sheets.

gog sheets get <spreadsheetId> 'Sheet1!A1:D20' --json
gog sheets table list <spreadsheetId>
gog sheets table append <spreadsheetId> Tasks 'Ship README|done'
gog sheets table clear <spreadsheetId> Tasks
gog sheets conditional-format add <spreadsheetId> 'Sheet1!A2:A100' \
  --type text-contains \
  --expr blocked \
  --format-json '{"backgroundColor":{"red":1,"green":0.84,"blue":0.84}}'
gog sheets banding set <spreadsheetId> 'Sheet1!A1:D100'

Slides and Forms

Docs: Slides from Markdown, template replacement, gog slides, gog forms.

gog slides create-from-markdown "Weekly update" --content-file slides.md
gog slides insert-text <presentationId> <objectId> "New text"
gog forms update <formId> --quiz=true
gog forms add-question <formId> --title "What is 2+2?" --type radio -o 1 -o 4 --correct 4 --points 1
gog forms publish <formId>
gog forms responses list <formId> --json
gog forms raw <formId> --pretty

YouTube

Docs: gog youtube, youtube channels, youtube videos, youtube activities.

gog config set youtube_api_key YOUR_API_KEY
gog yt channels list --id UC_x5XG1OV2P6uZZ5FSM9Ttw --json
gog yt videos list --chart mostPopular --region US --max 5
gog yt activities list --mine -a you@gmail.com

Analytics and Search Console

Docs: gog analytics, analytics report, gog searchconsole, searchconsole query.

gog analytics accounts --all --json
gog analytics report 123456789 --from 7daysAgo --to today --dimensions date,country --metrics activeUsers,sessions
gog searchconsole sites
gog searchconsole query sc-domain:example.com --from 2026-02-01 --to 2026-02-07 --dimensions query,page --filter query:contains:gog
gog searchconsole sitemaps submit sc-domain:example.com https://example.com/sitemap.xml --force

Backup

Docs: Backup, gog backup.

gog backup init --repo ~/Backups/gog
gog backup push --services gmail,calendar,contacts,drive
gog backup verify
gog backup export --gmail-format markdown --out ~/Exports/gog

See docs/backup.md before running broad or unattended backup jobs.

Output and Automation

Docs: Safety Profiles, gog schema, gog config no-send.

Use --json for structured output and --plain for stable TSV. Prompts, progress, and warnings go to stderr so stdout stays parseable.

gog --json gmail search 'has:attachment newer_than:90d' --max 50 |
  jq -r '.threads[].id'

gog --plain calendar events --today

Useful global flags:

--account <email|alias|auto>: select an account
--client <name>: select a stored OAuth client
--json: JSON stdout
--plain: stable parseable text stdout
--dry-run: print intended actions where a command supports planning
--no-input: fail instead of prompting
--force: confirm destructive operations
--enable-commands <csv>: allow only selected command paths
--disable-commands <csv>: block selected command paths
--gmail-no-send: block Gmail send operations

For coding agents or CI, prefer:

gog --account you@gmail.com \
  --enable-commands gmail.search,gmail.get,drive.ls,docs.cat \
  --gmail-no-send \
  --json \
  gmail search 'newer_than:7d'

For stricter agent deployments, build or download a baked safety-profile binary. See docs/safety-profiles.md.

Auth and Accounts

Docs: Auth clients, gog auth, auth add, auth doctor, auth service-account.

OAuth clients

Store a Desktop OAuth client once:

gog auth credentials ~/Downloads/client_secret_....json
gog auth add you@gmail.com --services gmail,calendar,drive

Use named clients when different accounts should use different Cloud projects:

gog --client work auth credentials ~/Downloads/work-client.json
gog --client work auth add you@company.com
gog auth credentials list

See docs/auth-clients.md for client selection rules, domain mapping, remote OAuth, direct access tokens, ADC, and service accounts.

Account selection

gog auth list --check
gog auth alias set work you@company.com

gog --account work gmail search 'is:unread'
export GOG_ACCOUNT=you@gmail.com
gog calendar events --today

Keyring backends

By default gog uses the best OS keyring available. For headless or container runs, use the encrypted file backend and inject GOG_KEYRING_PASSWORD from the current shell or secret store.

gog auth keyring
gog auth keyring file
GOG_KEYRING_BACKEND=file GOG_KEYRING_PASSWORD=... gog auth list --check

For systemd services, gateways, and coding agents, set the same variables on the service or agent process itself. A successful shell check does not mean the agent subprocess inherited GOG_KEYRING_PASSWORD; verify through the actual agent entrypoint with gog auth doctor --check --no-input.

Never commit OAuth client JSON files, refresh tokens, service-account keys, or file-keyring passwords.

Workspace service accounts

Workspace admins can configure domain-wide delegation and then store a service-account key for the user to impersonate:

gog auth service-account set user@company.com --key ~/Downloads/service-account.json
gog --account user@company.com auth status

Service accounts are mainly useful for Workspace Admin, Groups, Keep, and domain-wide automation. They do not replace normal OAuth for consumer Gmail accounts.

Services

Docs: Command index, Workspace Admin, gog auth services.

Common user services:

Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Meet, Apps Script
Analytics and Search Console
Contacts, People, Tasks, Classroom
Chat for Workspace accounts
Backup and local utility commands

Workspace/admin services:

Admin Directory
Cloud Identity Groups
Keep with domain-wide delegation

Admin Directory includes Workspace user creation from the CLI:

gog --account admin@example.com admin users create ada@example.com \
  --first-name Ada \
  --last-name Lovelace \
  --password 'TempPass123!' \
  --change-password \
  --ou /Engineering

Omit --password to generate a temporary password. See docs/workspace-admin.md for service-account setup, user cleanup, recovery fields, organizational units, and group examples.

Workspace organizational units are covered too:

gog --account admin@example.com admin orgunits list --type all
gog --account admin@example.com admin orgunits create Engineering --parent /

Generated service scope table:

Service	User	APIs	Scopes	Notes
gmail	yes	Gmail API	`https://www.googleapis.com/auth/gmail.modify` `https://www.googleapis.com/auth/gmail.settings.basic` `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` `https://www.googleapis.com/auth/chat.messages` `https://www.googleapis.com/auth/chat.memberships` `https://www.googleapis.com/auth/chat.users.readstate.readonly`
classroom	yes	Classroom API	`https://www.googleapis.com/auth/classroom.courses` `https://www.googleapis.com/auth/classroom.rosters` `https://www.googleapis.com/auth/classroom.coursework.students` `https://www.googleapis.com/auth/classroom.coursework.me` `https://www.googleapis.com/auth/classroom.courseworkmaterials` `https://www.googleapis.com/auth/classroom.announcements` `https://www.googleapis.com/auth/classroom.topics` `https://www.googleapis.com/auth/classroom.guardianlinks.students` `https://www.googleapis.com/auth/classroom.profile.emails` `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
docs	yes	Docs API, Drive API	`https://www.googleapis.com/auth/drive` `https://www.googleapis.com/auth/documents`	Export/copy/create via Drive
slides	yes	Slides API, Drive API	`https://www.googleapis.com/auth/drive` `https://www.googleapis.com/auth/presentations`	Create/edit presentations
contacts	yes	People API	`https://www.googleapis.com/auth/contacts` `https://www.googleapis.com/auth/contacts.other.readonly` `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` `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` `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` `https://www.googleapis.com/auth/meetings.space.readonly` `https://www.googleapis.com/auth/meetings.space.settings`
appscript	yes	Apps Script API	`https://www.googleapis.com/auth/script.projects` `https://www.googleapis.com/auth/script.deployments` `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
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.user` `https://www.googleapis.com/auth/admin.directory.group` `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)

Regenerate the table with:

go run scripts/gen-auth-services-md.go

Documentation

Overview — rendered at https://gogcli.sh/
Install — https://gogcli.sh/install.html
Quickstart — https://gogcli.sh/quickstart.html
Command index — https://gogcli.sh/commands/
Gmail workflows — https://gogcli.sh/gmail-workflows.html
Gmail watch — https://gogcli.sh/watch.html
Drive audits — https://gogcli.sh/drive-audits.html
Docs editing — https://gogcli.sh/docs-editing.html
Sheets tables and Sheets formatting
Safety profiles — command guards and baked safe binaries
Auth clients — OAuth clients, account mapping, and service accounts
Workspace Admin — Workspace user, org unit, and group administration
Backup — encrypted Google account backups
CHANGELOG.md: release notes

Every command also has help built in:

gog --help
gog gmail --help
gog drive inventory --help
gog schema --json

Development

make tools
make build
make fmt
make lint
make test
make ci

Generated command docs:

make docs-commands
make docs-site
open dist/docs-site/index.html

Live Google API smoke tests are opt-in:

scripts/live-test.sh --fast --account you@gmail.com
GOG_IT_ACCOUNT=you@gmail.com go test -tags=integration ./internal/integration

See docs/RELEASING.md for the release checklist.

Credits

Inspired by Mario Zechner's original Google CLIs:

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 1,007 Commits
.agents/skills/gog		.agents/skills/gog
.githooks		.githooks
.github		.github
cmd		cmd
docs		docs
internal		internal
safety-profiles		safety-profiles
scripts		scripts
testdata		testdata
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
.lefthook.yml		.lefthook.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
PR_DESCRIPTION.md		PR_DESCRIPTION.md
README.md		README.md
build-safe.sh		build-safe.sh
go.mod		go.mod
go.sum		go.sum

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

gogcli

Install

Homebrew

Docker

Windows

Build from source

Quick Start

Daily Examples

Gmail

Calendar

Drive

Contacts

Docs

Sheets

Slides and Forms

YouTube

Analytics and Search Console

Backup

Output and Automation

Auth and Accounts

OAuth clients

Account selection

Keyring backends

Workspace service accounts

Services

Documentation

Development

Credits

License

About

Uh oh!

Releases 25

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

gogcli

Install

Homebrew

Docker

Windows

Build from source

Quick Start

Daily Examples

Gmail

Calendar

Drive

Contacts

Docs

Sheets

Slides and Forms

YouTube

Analytics and Search Console

Backup

Output and Automation

Auth and Accounts

OAuth clients

Account selection

Keyring backends

Workspace service accounts

Services

Documentation

Development

Credits

License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 25

Uh oh!

Contributors

Uh oh!

Languages