gogcli

gog is a script-friendly Google CLI for Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Contacts, Tasks, People, Classroom, Chat, 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

Install

Homebrew

brew install gogcli
gog --version

Docker

docker run --rm ghcr.io/steipete/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/steipete/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/steipete/gogcli.git
cd gogcli
make
./bin/gog --version

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

Quick Start

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, 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

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

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 update primary <eventId> --with-meet
gog calendar move primary <eventId> team-calendar@example.com

Drive

# 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

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

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

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

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

gog slides create-from-markdown "Weekly update" --content-file slides.md
gog slides insert-text <presentationId> <objectId> "New text"
gog forms responses list <formId> --json
gog forms raw <formId> --pretty

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

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

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

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

Common user services:

Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script
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

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`
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`
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`
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

Regenerate the table with:

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

Documentation

docs/index.md: docs overview (rendered at https://gogcli.sh/)
docs/quickstart.md: five-minute setup walkthrough
docs/commands/README.md: generated command index
docs/safety-profiles.md: command guards and baked safe binaries
docs/auth-clients.md: OAuth clients, account mapping, and service accounts
docs/sheets-tables.md: structured Sheets tables
docs/backup.md: 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 973 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

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 24

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

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 24

Uh oh!

Contributors

Uh oh!

Languages