gogcli

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

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:

• Create a Cloud project
• OAuth clients
• OAuth consent screen
• API library
• Places API (New)
• YouTube Data API v3
• Apps Script user setting

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

# 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

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

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

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

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

Common user services:

• Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Meet, 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:

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:

• gmcli
• gccli
• gdcli

License

MIT