Repository navigation
Description
Problem
Currently, gog auth add only allows scope selection via predefined service bundles (--services) and coarse-grained toggles (--readonly, --drive-scope, --gmail-scope). This makes it impossible to compose mixed permission sets like:
gmail.readonly(read emails) +gmail.labels(manage labels only) — without granting fullgmail.modifycalendar.readonly(read events) +calendar.calendarlist(manage calendar subscriptions) — without fullcalendardrive.readonly+drive.metadata(organize folders) — without fulldrive
This is a real pain point for AI assistant use cases where least-privilege access matters: you want the agent to read emails and manage labels, but absolutely not be able to send or delete anything.
Proposed Solution
Add an --extra-scopes flag (or --scopes) that accepts a comma-separated list of raw Google API scope URIs to append to the scopes derived from --services:
# Read emails only, but also allow managing labels
gog auth add user@example.com \
--services gmail \
--gmail-scope=readonly \
--extra-scopes="https://www.googleapis.com/auth/gmail.labels"
# Read calendar, but allow managing calendar list subscriptions
gog auth add user@example.com \
--services calendar \
--readonly \
--extra-scopes="https://www.googleapis.com/auth/calendar.calendarlist"Resulting scopes would be:
https://www.googleapis.com/auth/gmail.readonly ← from --gmail-scope=readonly
https://www.googleapis.com/auth/gmail.labels ← from --extra-scopes
Why Not Just Expose Per-Service Scope Flags?
The --gmail-scope approach (PR #113) is great for binary full/readonly choices. But Google's API surface has dozens of granular sub-scopes per service (e.g., calendar.events.readonly, calendar.calendarlist, calendar.freebusy, drive.metadata.readonly, drive.activity.readonly, gmail.labels, etc.). Maintaining a separate flag for each is not scalable.
An --extra-scopes escape hatch gives power users full control without the maintenance burden.
References
- Google Calendar scopes: https://developers.google.com/workspace/calendar/api/auth
- Google Drive scopes: https://developers.google.com/workspace/drive/api/guides/api-specific-auth
- Google Gmail scopes: https://developers.google.com/gmail/api/auth/scopes
- Related: feat(gmail): Add --gmail-scope=readonly option for gmail.readonly scope #110 (gmail readonly scope — merged in fix(auth): add gmail readonly scope and fix drive readonly accumulation #113)
Use Case (Real World)
I'm using gog with an AI assistant (OpenClaw) that manages my Google Workspace. I want to grant:
| Service | Read | Write |
|---|---|---|
| Gmail | ✅ gmail.readonly |
✅ gmail.labels only |
| Calendar | ✅ calendar.readonly |
✅ calendar.calendarlist (subscribe/unsubscribe) |
| Drive | ✅ drive.readonly |
✅ drive.metadata (organize into folders) |
This is currently impossible without granting broader scopes (gmail.modify, calendar, drive) and relying on the tool's self-restraint — which is not a real security boundary.
Thank you for this excellent tool! 🙏
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Activity
steipete commentedon Apr 27, 2026
Fixed on current
main.gog auth addsupports--extra-scopesand remote auth guidance preserves it for step 2.Proof on
main:internal/cmd/auth_add.gohas theExtraScopesflag and scope append handling.TestAuthAddCmd_ExtraScopesand remote step guidance coverage.Closing as completed.