Gmail OAuth Setup

Set up Gmail API access via gog CLI with manual OAuth flow. Use when setting up Gmail integration, renewing expired OAuth tokens, or troubleshooting Gmail authentication on headless servers.

Security Scan

The skill's code and instructions match its stated purpose (helping perform a headless Gmail OAuth flow), but the registry metadata omits dependencies and environment variables the skill actually requires and it asks the user to store sensitive values in shell config — these mismatches and minor security practice issues warrant caution.

Purpose & Capability

The name/description and the included script legitimately implement a headless Gmail OAuth flow for use with the gog CLI. However, the registry metadata claims no required binaries/env vars/config paths while the SKILL.md and script clearly require the gog CLI, python3, curl, and a gog credentials file at ~/.config/gogcli/credentials.json. That metadata omission is inconsistent and should have been declared.

Instruction Scope

SKILL.md instructions remain within the stated purpose: guide creation of Google Cloud credentials, generate an auth URL, exchange the code for tokens, and import tokens into gog. The script reads the local gog credentials file and exchanges codes with Google's OAuth token endpoint. It does not contact unknown third-party endpoints or attempt to read unrelated system state.

Install Mechanism

There is no install spec (instruction-only), which is the lowest-risk install model. The README suggests installing gog via brew but the skill does not automatically fetch or execute remote code beyond the provided script.

Credentials

The registry declares no required env vars, yet the SKILL.md and script rely on GOG_KEYRING_PASSWORD (optional, but used for non-interactive import) and expect gog credentials in ~/.config/gogcli/credentials.json. The script also assumes python3 and curl exist. Sensitive items (a keyring password) are encouraged to be exported to shell rc files in the documentation — that is a security practice concern and should have been explicitly declared in metadata.

Persistence & Privilege

The skill does not request persistent platform privileges (always:false), does not modify other skills or system-wide agent settings, and does not attempt to self-enable or store credentials beyond importing tokens into the user's gog keyring (expected behavior for the stated purpose).

What to consider before installing

This skill appears to do what it claims: it helps perform a headless Gmail OAuth flow and imports refresh tokens into the gog CLI. Before installing or running it: 1) Inspect the provided script yourself (or have someone you trust do so) — the source is 'unknown'. 2) Ensure you have the required binaries (gog, python3, curl) even though the registry metadata doesn't list them. 3) Prefer entering GOG_KEYRING_PASSWORD interactively rather than putting it in .bashrc; if you must store it, use a secure secret store, not plaintext in shell rc files. 4) Confirm ~/.config/gogcli/credentials.json is your own downloaded client_secret JSON (do not run the script with credentials from untrusted sources). 5) Run the script in an isolated environment (temporary VM/container) if you are unsure of the origin. If the metadata were corrected to declare required binaries, config path, and the GOG_KEYRING_PASSWORD env var, my concerns would drop and confidence would increase.

Headless-friendly OAuth flow for Gmail API access using gog CLI.

Prerequisites

• gog CLI installed (brew install steipete/tap/gogcli)
• Google Cloud project with OAuth credentials (Desktop app type)
• Gmail API enabled in the project

Quick Setup

1. Create Google Cloud Project & Credentials

1. Go to https://console.cloud.google.com
2. Create a new project (or select existing)
3. Enable Gmail API: APIs & Services → Library → search "Gmail API" → Enable
4. Configure OAuth consent screen: APIs & Services → OAuth consent screen
   • Choose "External" user type
   • Fill in app name, user support email
   • Add scopes: gmail.modify (or others as needed)
   • Important: Click "PUBLISH APP" for permanent tokens (see Troubleshooting)
5. Create credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID
   • Application type: Desktop app
   • Download the JSON file

2. Configure gog

gog auth credentials /path/to/client_secret.json
gog auth keyring file  # Use file-based keyring for headless
export GOG_KEYRING_PASSWORD="your-password"  # Add to .bashrc

3. Run Auth Flow

Run scripts/gmail-auth.sh interactively, or:

# Generate URL
scripts/gmail-auth.sh --url

# User opens URL, approves, copies code from localhost redirect
# Exchange code (do this quickly - codes expire in minutes!)
scripts/gmail-auth.sh --exchange CODE EMAIL

4. Verify

gog gmail search 'is:unread' --max 5 --account [e-mail]

Troubleshooting

"Access blocked: [app] has not completed the Google verification process"

Cause: App is in "Testing" mode and the Gmail account isn't a test user.

Solutions (choose one):

1. Publish the app (recommended):

   • Google Cloud Console → APIs & Services → OAuth consent screen
   • Click "PUBLISH APP" → Confirm
   • No Google review needed for personal use
   • Tokens become permanent

2. Add test user:

   • OAuth consent screen → Test users → + ADD USERS
   • Add the Gmail address you're authorizing
   • Tokens still expire in 7 days

"Google hasn't verified this app" warning screen

This is normal for personal apps. Click:

1. Advanced (bottom left)
2. Go to [app name] (unsafe)

Safe to proceed since you own the app.

Token expires in 7 days

Cause: App is in "Testing" mode.

Fix: Publish the app (see above). Published apps get permanent refresh tokens.

"invalid_request" or "invalid_grant" errors

Causes:

• Authorization code expired (they only last a few minutes)
• Code was already used
• Redirect URI mismatch

Fix: Generate a fresh auth URL and complete the flow quickly. Paste the code immediately after getting it.

"redirect_uri_mismatch" error

Cause: The redirect URI in the token exchange doesn't match what was used in the auth URL.

Fix: This script uses http://localhost. Make sure both the auth URL and exchange use the same redirect URI.

Page hangs after approving permissions (mobile)

Cause: Browser trying to connect to localhost which doesn't exist on phone.

Fix:

• Use a desktop browser instead
• Or tap the address bar while it's "hanging" - the URL contains the code
• The URL will look like: http://localhost/?code=4/0ABC...

Multiple permission checkboxes causing hangs

Cause: Too many OAuth scopes requested.

Fix: Use minimal scopes. gmail.modify alone is usually sufficient and shows just one permission.

Can't find project in Google Cloud Console

Cause: Signed into wrong Google account.

Fix: Check which account owns the project:

• Click profile icon (top right)
• Switch accounts
• Check project dropdown for each account

"invalid_request" with oob redirect (new projects)

Cause: Google deprecated urn:ietf:wg:oauth:2.0:oob for OAuth clients created after 2022.

Fix: Use http://localhost redirect instead (this script's default). After approval, browser redirects to localhost with code in URL.

Scopes Reference

Scope	Access
gmail.modify	Read, send, delete, manage labels (recommended)
gmail.readonly	Read only
gmail.send	Send only
gmail.compose	Create drafts, send

Files

• scripts/gmail-auth.sh — Interactive auth helper

Tips

• Publish your app — Avoids test user limits and 7-day token expiry
• Exchange codes quickly — They expire in minutes
• Use desktop browser — Mobile browsers can be finicky with localhost redirects
• One scope is enough — gmail.modify covers most use cases