400 lines
13 KiB
Markdown
400 lines
13 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
brew install gogcli
|
|
gog --version
|
|
```
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
docker run --rm ghcr.io/steipete/gogcli:latest version
|
|
```
|
|
|
|
Authenticated container runs should use a persistent config volume and the
|
|
encrypted file keyring:
|
|
|
|
```bash
|
|
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](https://github.com/steipete/gogcli/releases), extract
|
|
`gog.exe`, and put that directory on `PATH`.
|
|
|
|
### Build from source
|
|
|
|
```bash
|
|
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`.
|
|
|
|
```bash
|
|
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](https://console.cloud.google.com/projectcreate)
|
|
- [OAuth clients](https://console.cloud.google.com/auth/clients)
|
|
- [OAuth consent screen](https://console.cloud.google.com/auth/branding)
|
|
- [API library](https://console.cloud.google.com/apis/library)
|
|
- [Apps Script user setting](https://script.google.com/home/usersettings)
|
|
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](docs/safety-profiles.md).
|
|
|
|
## Auth and Accounts
|
|
|
|
### OAuth clients
|
|
|
|
Store a Desktop OAuth client once:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](docs/auth-clients.md) for client selection rules,
|
|
domain mapping, remote OAuth, direct access tokens, ADC, and service accounts.
|
|
|
|
### Account selection
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
<!-- auth-services:start -->
|
|
| Service | User | APIs | Scopes | Notes |
|
|
| --- | --- | --- | --- | --- |
|
|
| gmail | yes | Gmail API | `https://www.googleapis.com/auth/gmail.modify`<br>`https://www.googleapis.com/auth/gmail.settings.basic`<br>`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`<br>`https://www.googleapis.com/auth/chat.messages`<br>`https://www.googleapis.com/auth/chat.memberships`<br>`https://www.googleapis.com/auth/chat.users.readstate.readonly` | |
|
|
| classroom | yes | Classroom API | `https://www.googleapis.com/auth/classroom.courses`<br>`https://www.googleapis.com/auth/classroom.rosters`<br>`https://www.googleapis.com/auth/classroom.coursework.students`<br>`https://www.googleapis.com/auth/classroom.coursework.me`<br>`https://www.googleapis.com/auth/classroom.courseworkmaterials`<br>`https://www.googleapis.com/auth/classroom.announcements`<br>`https://www.googleapis.com/auth/classroom.topics`<br>`https://www.googleapis.com/auth/classroom.guardianlinks.students`<br>`https://www.googleapis.com/auth/classroom.profile.emails`<br>`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`<br>`https://www.googleapis.com/auth/documents` | Export/copy/create via Drive |
|
|
| slides | yes | Slides API, Drive API | `https://www.googleapis.com/auth/drive`<br>`https://www.googleapis.com/auth/presentations` | Create/edit presentations |
|
|
| contacts | yes | People API | `https://www.googleapis.com/auth/contacts`<br>`https://www.googleapis.com/auth/contacts.other.readonly`<br>`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`<br>`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`<br>`https://www.googleapis.com/auth/forms.responses.readonly` | |
|
|
| appscript | yes | Apps Script API | `https://www.googleapis.com/auth/script.projects`<br>`https://www.googleapis.com/auth/script.deployments`<br>`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`<br>`https://www.googleapis.com/auth/admin.directory.group`<br>`https://www.googleapis.com/auth/admin.directory.group.member` | Workspace only; service account with domain-wide delegation required |
|
|
<!-- auth-services:end -->
|
|
|
|
Regenerate the table with:
|
|
|
|
```bash
|
|
go run scripts/gen-auth-services-md.go
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [docs/index.md](docs/index.md): docs overview (rendered at <https://gogcli.sh/>)
|
|
- [docs/quickstart.md](docs/quickstart.md): five-minute setup walkthrough
|
|
- [docs/commands/README.md](docs/commands/README.md): generated command index
|
|
- [docs/safety-profiles.md](docs/safety-profiles.md): command guards and baked safe binaries
|
|
- [docs/auth-clients.md](docs/auth-clients.md): OAuth clients, account mapping, and service accounts
|
|
- [docs/sheets-tables.md](docs/sheets-tables.md): structured Sheets tables
|
|
- [docs/backup.md](docs/backup.md): encrypted Google account backups
|
|
- [CHANGELOG.md](CHANGELOG.md): release notes
|
|
|
|
Every command also has help built in:
|
|
|
|
```bash
|
|
gog --help
|
|
gog gmail --help
|
|
gog drive inventory --help
|
|
gog schema --json
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
make tools
|
|
make build
|
|
make fmt
|
|
make lint
|
|
make test
|
|
make ci
|
|
```
|
|
|
|
Generated command docs:
|
|
|
|
```bash
|
|
make docs-commands
|
|
make docs-site
|
|
open dist/docs-site/index.html
|
|
```
|
|
|
|
Live Google API smoke tests are opt-in:
|
|
|
|
```bash
|
|
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](docs/RELEASING.md) for the release checklist.
|
|
|
|
## Credits
|
|
|
|
Inspired by Mario Zechner's original Google CLIs:
|
|
|
|
- [gmcli](https://github.com/badlogic/gmcli)
|
|
- [gccli](https://github.com/badlogic/gccli)
|
|
- [gdcli](https://github.com/badlogic/gdcli)
|
|
|
|
## License
|
|
|
|
MIT
|