gogcli (gog)
gog is a fast, script-friendly CLI for Google services. It is JSON-first, supports multiple accounts/OAuth clients, and has explicit guardrails for agent and CI usage.
Authoritative upstream: https://github.com/steipete/gogcli
This skill was refreshed against upstream gog v0.13.0 (2026-04-20). When exact syntax matters, run gog <command> --help or gog schema --json; the command surface moves quickly, rather inconveniently for anyone fond of stale notes.
Operating rules
- Prefer
gog --json ... | jq ... for inspection and scripting.
- Use
--plain only when stable TSV is more convenient than JSON.
- Use
--dry-run for supported mutating operations when preparing a change or when user intent is ambiguous.
- Use
--no-input in automation so commands fail instead of prompting.
- Use
--force only when the user asked for the destructive/public/send/admin operation or after you have clearly explained the effect.
- Do not repair OAuth, consent, keyring, or Workspace delegation problems silently. Show the exact command the user should run.
- Do not export tokens, print secrets, open public shares, add delegates/forwarding, send mail, suspend users, or permanently delete data unless the user explicitly requested that action.
- For agent runs that must not send mail, add
--gmail-no-send, set GOG_GMAIL_NO_SEND=1, or configure gog config no-send set <account>.
Install and auth
brew install gogcli
gog auth credentials set ~/Downloads/client_secret_....json
gog auth add you@example.com --services gmail,calendar,drive
gog auth list --check
Notes:
- Homebrew now uses
brew install gogcli; old tap examples are obsolete.
gog auth add defaults to --services user. Request the services needed for the task.
--services all is accepted only as a backwards-compatible alias for user; do not use it when you need every API.
- Use
--readonly, --drive-scope readonly|file|full, and --gmail-scope readonly|full for least privilege.
- Keep and Admin require Workspace service-account/domain-wide delegation. Google Chat, Groups, directory, and Classroom also have Workspace restrictions.
- For headless/CI, consider
--manual, --remote, --access-token, or GOG_AUTH_MODE=adc.
Read references/authentication.md for full auth patterns.
Global flags
--account, -a <email|alias|auto> # account selection
--client <name> # named OAuth client/token bucket
--access-token <token> # direct short-lived token; also GOG_ACCESS_TOKEN
--json, -j # machine-readable JSON
--plain, -p # stable TSV
--results-only # JSON primary result only
--select <fields> # best-effort JSON projection
--dry-run, -n # preview supported writes
--force, -y # skip confirmations
--no-input # never prompt
--enable-commands <csv> # allowlist top-level or dotted commands
--disable-commands <csv> # denylist top-level or dotted commands
--gmail-no-send # block Gmail send operations
--verbose, -v # debug logging
Useful command aliases:
gog send ... # alias for gog gmail send
gog ls # alias for gog drive ls
gog search "budget" # alias for gog drive search
gog download <fileId> # alias for gog drive download
gog upload ./file.pdf # alias for gog drive upload
gog me # alias for gog people me
gog status # alias for gog auth status
gog open <id-or-url> # best-effort Google web URL, offline
High-value workflows
Account selection
gog auth alias set work you@company.com
gog --account work gmail search 'is:unread newer_than:2d'
GOG_ACCOUNT=work gog calendar events primary --today
gog --client work auth credentials set ~/Downloads/work-client.json
gog --client work auth add you@company.com --services gmail,calendar
Gmail
gog --json gmail search 'is:unread newer_than:7d' | jq -r '.threads[].id'
gog gmail messages search 'from:alice@example.com has:attachment' --include-body
gog gmail messages search 'subject:report newer_than:30d' --full
gog gmail thread get <threadId> --download --out-dir ./attachments
gog gmail labels modify <threadId> --add Project --remove INBOX
gog gmail messages modify <messageId> --add STARRED
gog gmail send --to user@example.com --subject "Hello" --body-file ./body.txt
gog gmail forward <messageId> --to user@example.com --note "FYI"
For forwarding, autoreply, watch/Pub/Sub, filters, delegates, send-as, label colours, batch operations, and tracking, read references/gmail.md.
Calendar
gog calendar calendars
gog calendar events primary --today --weekday
gog calendar events --all --from "2026-04-25T00:00:00+02:00" --to "2026-04-26T00:00:00+02:00"
gog calendar freebusy --cal primary --from "2026-04-25T09:00:00+02:00" --to "2026-04-25T17:00:00+02:00"
gog calendar create primary --summary "Planning" --from "2026-04-25T14:00:00+02:00" --to "2026-04-25T14:30:00+02:00" --attendees "alice@example.com,bob@example.com" --with-meet
gog calendar respond primary <eventId> --status accepted --send-updates all
Use RFC3339 with timezone offsets for generated datetimes. Read references/calendar.md for aliases, subscriptions, secondary calendars, extended properties, Focus Time, OOO, working locations, team calendars, and conflict detection.
Drive, Docs, Sheets, Slides, Forms, Apps Script
gog drive search "invoice filetype:pdf" --max 20
gog drive upload ./report.md --convert-to doc --parent <folderId>
gog drive upload ./deck.pdf --replace <fileId> --name "Board Deck.pdf"
gog drive share <fileId> --to user --email editor@example.com --role commenter
gog docs write <docId> --file ./brief.md --replace --markdown
gog docs sed <docId> 's/status/{b c=green}approved/g' --dry-run
gog sheets update <spreadsheetId> 'Sheet1!A1' '[["Name","Score"],["Ada",98]]'
gog sheets chart list <spreadsheetId>
gog slides thumbnail <presentationId> <slideId> --out ./slide.png
gog forms responses list <formId> --max 20
gog appscript run <scriptId> myFunction --params '["arg1", 123]'
Read references/drive-docs.md for current file/content commands. For Docs sed formatting, read references/sedmat.md.
Other services
gog contacts search "Ada"
gog tasks lists
gog tasks add <tasklistId> --title "Weekly review" --due "2026-04-27" --repeat weekly
gog chat messages send spaces/<spaceId> --text "Build complete"
gog groups members engineering@example.com
gog admin users list --domain example.com
gog keep search "receipt"
Read references/other-services.md for Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep, and time utilities.
Scripting patterns
# Inspect shape first
gog --json gmail search 'is:unread' --max 3 | jq .
# Use pagination/all-pages where available
gog --json calendar events primary --from today --to tomorrow --all-pages
# Fail cleanly when a supported list command has no results
gog --json calendar events primary --query "unlikely query" --fail-empty
# Batch with xargs after checking output
gog --json gmail search 'older_than:1y label:newsletter' --max 200 | \
jq -r '.threads[].id' | \
xargs -n 50 gog gmail labels modify --remove INBOX
# Agent-safe command surface
GOG_ENABLE_COMMANDS=calendar.events,calendar.freebusy,tasks \
gog --no-input --json calendar events primary --today
Reference map
references/command-reference.md - generated command index from gog schema --json
references/authentication.md - OAuth clients, service accounts, scopes, keyrings, headless auth
references/configuration.md - config keys, environment variables, output modes, safety switches
references/gmail.md - Gmail search, read, send, labels, settings, watch, tracking, autoreply
references/calendar.md - Calendar listing, event writes, scheduling, special events, aliases
references/drive-docs.md - Drive, Docs, Sheets, Slides, Forms, Apps Script
references/sedmat.md - Docs sed/formatting DSL
references/other-services.md - Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep
1---
2name: gog-cli
3description: Use this skill whenever the user wants to operate Google Workspace from the command line with gog/gogcli, including Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep, auth, configuration, scripting, or agent-safe Google automation. Prefer this skill for Google account/file/mail/calendar work when the user mentions gog, gogcli, Google CLI, Gmail search/send, Calendar events, Drive files, Docs/Sheets/Slides editing, Forms, Apps Script, Workspace admin, or command-line Google automation.
4metadata:
5 source: https://skillmd.com/skills/gabrielmoreira/gog-cli
6---
7
8# gogcli (gog)
9
10`gog` is a fast, script-friendly CLI for Google services. It is JSON-first, supports multiple accounts/OAuth clients, and has explicit guardrails for agent and CI usage.
11
12Authoritative upstream: https://github.com/steipete/gogcli
13
14This skill was refreshed against upstream `gog` v0.13.0 (2026-04-20). When exact syntax matters, run `gog <command> --help` or `gog schema --json`; the command surface moves quickly, rather inconveniently for anyone fond of stale notes.
15
16## Operating rules
17
18- Prefer `gog --json ... | jq ...` for inspection and scripting.
19- Use `--plain` only when stable TSV is more convenient than JSON.
20- Use `--dry-run` for supported mutating operations when preparing a change or when user intent is ambiguous.
21- Use `--no-input` in automation so commands fail instead of prompting.
22- Use `--force` only when the user asked for the destructive/public/send/admin operation or after you have clearly explained the effect.
23- Do not repair OAuth, consent, keyring, or Workspace delegation problems silently. Show the exact command the user should run.
24- Do not export tokens, print secrets, open public shares, add delegates/forwarding, send mail, suspend users, or permanently delete data unless the user explicitly requested that action.
25- For agent runs that must not send mail, add `--gmail-no-send`, set `GOG_GMAIL_NO_SEND=1`, or configure `gog config no-send set <account>`.
26
27## Install and auth
28
29```bash
30brew install gogcli
31gog auth credentials set ~/Downloads/client_secret_....json
32gog auth add you@example.com --services gmail,calendar,drive
33gog auth list --check
34```
35
36Notes:
37
38- Homebrew now uses `brew install gogcli`; old tap examples are obsolete.
39- `gog auth add` defaults to `--services user`. Request the services needed for the task.
40- `--services all` is accepted only as a backwards-compatible alias for `user`; do not use it when you need every API.
41- Use `--readonly`, `--drive-scope readonly|file|full`, and `--gmail-scope readonly|full` for least privilege.
42- Keep and Admin require Workspace service-account/domain-wide delegation. Google Chat, Groups, directory, and Classroom also have Workspace restrictions.
43- For headless/CI, consider `--manual`, `--remote`, `--access-token`, or `GOG_AUTH_MODE=adc`.
44
45Read `references/authentication.md` for full auth patterns.
46
47## Global flags
48
49```bash
50--account, -a <email|alias|auto> # account selection
51--client <name> # named OAuth client/token bucket
52--access-token <token> # direct short-lived token; also GOG_ACCESS_TOKEN
53--json, -j # machine-readable JSON
54--plain, -p # stable TSV
55--results-only # JSON primary result only
56--select <fields> # best-effort JSON projection
57--dry-run, -n # preview supported writes
58--force, -y # skip confirmations
59--no-input # never prompt
60--enable-commands <csv> # allowlist top-level or dotted commands
61--disable-commands <csv> # denylist top-level or dotted commands
62--gmail-no-send # block Gmail send operations
63--verbose, -v # debug logging
64```
65
66Useful command aliases:
67
68```bash
69gog send ... # alias for gog gmail send
70gog ls # alias for gog drive ls
71gog search "budget" # alias for gog drive search
72gog download <fileId> # alias for gog drive download
73gog upload ./file.pdf # alias for gog drive upload
74gog me # alias for gog people me
75gog status # alias for gog auth status
76gog open <id-or-url> # best-effort Google web URL, offline
77```
78
79## High-value workflows
80
81### Account selection
82
83```bash
84gog auth alias set work you@company.com
85gog --account work gmail search 'is:unread newer_than:2d'
86GOG_ACCOUNT=work gog calendar events primary --today
87gog --client work auth credentials set ~/Downloads/work-client.json
88gog --client work auth add you@company.com --services gmail,calendar
89```
90
91### Gmail
92
93```bash
94gog --json gmail search 'is:unread newer_than:7d' | jq -r '.threads[].id'
95gog gmail messages search 'from:alice@example.com has:attachment' --include-body
96gog gmail messages search 'subject:report newer_than:30d' --full
97gog gmail thread get <threadId> --download --out-dir ./attachments
98gog gmail labels modify <threadId> --add Project --remove INBOX
99gog gmail messages modify <messageId> --add STARRED
100gog gmail send --to user@example.com --subject "Hello" --body-file ./body.txt
101gog gmail forward <messageId> --to user@example.com --note "FYI"
102```
103
104For forwarding, autoreply, watch/Pub/Sub, filters, delegates, send-as, label colours, batch operations, and tracking, read `references/gmail.md`.
105
106### Calendar
107
108```bash
109gog calendar calendars
110gog calendar events primary --today --weekday
111gog calendar events --all --from "2026-04-25T00:00:00+02:00" --to "2026-04-26T00:00:00+02:00"
112gog calendar freebusy --cal primary --from "2026-04-25T09:00:00+02:00" --to "2026-04-25T17:00:00+02:00"
113gog calendar create primary --summary "Planning" --from "2026-04-25T14:00:00+02:00" --to "2026-04-25T14:30:00+02:00" --attendees "alice@example.com,bob@example.com" --with-meet
114gog calendar respond primary <eventId> --status accepted --send-updates all
115```
116
117Use RFC3339 with timezone offsets for generated datetimes. Read `references/calendar.md` for aliases, subscriptions, secondary calendars, extended properties, Focus Time, OOO, working locations, team calendars, and conflict detection.
118
119### Drive, Docs, Sheets, Slides, Forms, Apps Script
120
121```bash
122gog drive search "invoice filetype:pdf" --max 20
123gog drive upload ./report.md --convert-to doc --parent <folderId>
124gog drive upload ./deck.pdf --replace <fileId> --name "Board Deck.pdf"
125gog drive share <fileId> --to user --email editor@example.com --role commenter
126gog docs write <docId> --file ./brief.md --replace --markdown
127gog docs sed <docId> 's/status/{b c=green}approved/g' --dry-run
128gog sheets update <spreadsheetId> 'Sheet1!A1' '[["Name","Score"],["Ada",98]]'
129gog sheets chart list <spreadsheetId>
130gog slides thumbnail <presentationId> <slideId> --out ./slide.png
131gog forms responses list <formId> --max 20
132gog appscript run <scriptId> myFunction --params '["arg1", 123]'
133```
134
135Read `references/drive-docs.md` for current file/content commands. For Docs sed formatting, read `references/sedmat.md`.
136
137### Other services
138
139```bash
140gog contacts search "Ada"
141gog tasks lists
142gog tasks add <tasklistId> --title "Weekly review" --due "2026-04-27" --repeat weekly
143gog chat messages send spaces/<spaceId> --text "Build complete"
144gog groups members engineering@example.com
145gog admin users list --domain example.com
146gog keep search "receipt"
147```
148
149Read `references/other-services.md` for Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep, and time utilities.
150
151## Scripting patterns
152
153```bash
154# Inspect shape first
155gog --json gmail search 'is:unread' --max 3 | jq .
156
157# Use pagination/all-pages where available
158gog --json calendar events primary --from today --to tomorrow --all-pages
159
160# Fail cleanly when a supported list command has no results
161gog --json calendar events primary --query "unlikely query" --fail-empty
162
163# Batch with xargs after checking output
164gog --json gmail search 'older_than:1y label:newsletter' --max 200 | \
165 jq -r '.threads[].id' | \
166 xargs -n 50 gog gmail labels modify --remove INBOX
167
168# Agent-safe command surface
169GOG_ENABLE_COMMANDS=calendar.events,calendar.freebusy,tasks \
170 gog --no-input --json calendar events primary --today
171```
172
173## Reference map
174
175- `references/command-reference.md` - generated command index from `gog schema --json`
176- `references/authentication.md` - OAuth clients, service accounts, scopes, keyrings, headless auth
177- `references/configuration.md` - config keys, environment variables, output modes, safety switches
178- `references/gmail.md` - Gmail search, read, send, labels, settings, watch, tracking, autoreply
179- `references/calendar.md` - Calendar listing, event writes, scheduling, special events, aliases
180- `references/drive-docs.md` - Drive, Docs, Sheets, Slides, Forms, Apps Script
181- `references/sedmat.md` - Docs sed/formatting DSL
182- `references/other-services.md` - Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep