Gog Cli
Configure Google OAuth and least-privilege scopes for gogcli so agents can reach Gmail, Calendar, Drive, Docs, and related user APIs safely.
Overview
gog-cli is an agent skill for the Build phase that documents gogcli Google OAuth setup, service selection, and least-privilege scopes for solo builder automations.
Install
npx skills add https://github.com/intellectronica/agent-skills --skill gog-cliWhat is this skill?
- Documents brew install, credentials JSON placement, and gog auth add/list/status flows.
- Requires Google Cloud Desktop app OAuth client JSON with APIs enabled for the task only.
- Lists current user vs workspace service-account service names and scope gotchas (Docs/Slides/Sheets + Drive).
- Explains --services user vs all alias and when to re-run --force-consent for refresh tokens.
- Provides least-privilege examples: gmail readonly, drive readonly, drive file scope.
Adoption & trust: 557 installs on skills.sh; 270 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need your agent to use Gmail or Drive via gogcli but OAuth client type, service lists, or missing Drive scopes keep breaking auth.
Who is it for?
Indie operators automating personal or small-business Google workflows through gogcli from Claude Code, Cursor, or Codex.
Skip if: Enterprise Workspace service-account admin provisioning without human OAuth, or integrations that should use official server-side Google APIs only.
When should I use this skill?
When configuring gogcli accounts, diagnosing Google auth failures, or choosing scopes for Gmail, Calendar, Drive, Docs, Sheets, or related services.
What do I get? / Deliverables
You end with credentials on disk, accounts linked with explicit services/scopes, and verifiable gog auth status the agent can rely on for CLI calls.
- Configured gog auth credentials and linked user account(s)
- Documented service and scope choices verified with gog auth list --check or status
Recommended Skills
Journey fit
Hooking a product or agent workflow to Google Workspace is classic Build-phase integration work. The skill is entirely about auth, services, and scope selection for gogcli—not frontend UI or launch distribution.
How it compares
CLI integration skill for gogcli auth—not a hosted MCP Google server and not a generic Gmail API SDK guide.
Common Questions / FAQ
Who is gog-cli for?
Solo builders and agent users who run gogcli locally and need correct Google OAuth credentials and scope wiring.
When should I use gog-cli?
During Build integrations when you first connect gogcli, debug auth failures, or add services like calendar, drive, or gmail with readonly scopes.
Is gog-cli safe to install?
It involves OAuth secrets and broad Google access if mis-scoped; review the Security Audits panel on this page and prefer readonly or file-level Drive scopes.
SKILL.md
READMESKILL.md - Gog Cli
# gogcli Authentication Reference Use this when configuring accounts, diagnosing auth failures, or selecting the right credential mode. ## Install and credentials ```bash brew install gogcli gog auth credentials set ~/Downloads/client_secret_....json gog auth credentials list gog auth add you@example.com --services gmail,calendar,drive gog auth list --check gog auth status ``` OAuth client credentials must be a Google Cloud "Desktop app" client JSON. Enable only the APIs needed for the task. ## Services and scopes Check the live service list before prescribing scopes: ```bash gog auth services gog auth services --markdown ``` Current user-service names include: ```text gmail, calendar, chat, classroom, drive, docs, slides, contacts, tasks, sheets, people, forms, appscript, ads ``` Workspace-only service-account services include: ```text groups, keep, admin ``` Important details: - `gog auth add` defaults to `--services user`. - `--services all` is a backwards-compatible alias for `user`, not "every Google API". - Docs uses Docs plus Drive scopes; Slides and Sheets also rely on Drive for copy/export flows. - Re-run with `--force-consent` when adding services or changing scope shape and Google does not return a new refresh token. Least-privilege examples: ```bash gog auth add you@example.com --services gmail --gmail-scope readonly gog auth add you@example.com --services drive --drive-scope readonly gog auth add you@example.com --services drive --drive-scope file gog auth add you@example.com --services gmail,drive --readonly gog auth add you@example.com --services gmail --extra-scopes https://www.googleapis.com/auth/gmail.labels ``` ## OAuth clients and account selection Use named clients for separate Google Cloud projects, organisations, or consent screens: ```bash gog --client work auth credentials set ~/Downloads/work-client.json gog --client work auth add you@company.com --services gmail,calendar gog --client work gmail search 'is:unread' ``` Domain mapping auto-selects a client for matching account emails: ```bash gog --client work auth credentials set ~/Downloads/work.json --domain company.com ``` Client resolution order: 1. `--client` or `GOG_CLIENT` 2. `account_clients` config mapping 3. `client_domains` config mapping 4. credentials file named after the email domain 5. `default` Account aliases: ```bash gog auth alias set work you@company.com gog --account work calendar events primary --today gog auth alias list gog auth alias unset work ``` `--account auto` asks gog to use the default account or the single stored token. ## Browser, manual, remote, and proxy auth Normal local browser flow: ```bash gog auth add you@example.com --services gmail,calendar ``` Manual flow for headless systems: ```bash gog auth add you@example.com --services gmail --manual ``` Remote two-step flow: ```bash gog auth add you@example.com --services gmail --remote --step 1 gog auth add you@example.com --services gmail --remote --step 2 --auth-url 'http://127.0.0.1:<port>/oauth2/callback?code=...&state=...' ``` Proxy/tunnel callback: ```bash gog auth add you@example.com --listen-addr 0.0.0.0:8080 --redirect-host gog.example.com gog auth manage --listen-addr 0.0.0.0:8080 --redirect-host gog.example.com ``` The redirect URI must match the OAuth client configuration. ## Direct tokens and ADC Direct short-lived token: ```bash gog --access-token "$(gcloud auth print-access-token)" gmail labels list GOG_ACCESS_TOKEN="$(gcloud auth print-access-token)" gog drive ls ``` Application Default Credentials mode is useful for Workload Identity, Cloud Run, and local `gcloud` ADC flows: ```bash GOG_AUTH_MODE=adc gog --json drive ls ``` Direct access tokens expire in about an hour and do not use stored refresh tokens. ## Keyring backend Tokens are stored in a keyring backend: - `auto` - platform default - `keychain` - macOS Keychain - `file` - encrypted on-disk store ```bash gog auth keyring gog auth keyring keychain gog