gmail-setup

Stars0

Forks0

UpdatedJuly 25, 2026 at 11:44

Connect a Gmail account to this machine, and diagnose it when Gmail calls start failing. Use when the user wants to set up, connect, or authorize Gmail; when they add a second account; when they ask why email stopped working; or when any gmail command returns auth_required, auth_expired, scope_insufficient, client_invalid, or api_not_enabled. Covers the one-time Google Cloud project and OAuth client, the login flow, multiple accounts as profiles, and `gmail doctor`.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

hec-ovi

hec-ovi/gmail-skill

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

More from this repository

same repository

gmail-draft

hec-ovi/gmail-skill

Prepare Gmail messages without sending them: create, update, list, send, and delete drafts, with attachments. Use when the user asks to draft, prepare, or write up an email, to save something for later, to revise a draft, or to send one they already approved. Prefer this over sending directly whenever the exact wording has not been agreed yet: a draft is reviewable in Gmail and costs nothing to throw away.

2026-07-250

gmail-organize

hec-ovi/gmail-skill

Organize the user's Gmail: apply and remove labels, archive, mark read or unread, star, move to trash or restore, and manage the label list itself. Use when the user asks to label, tag, file, sort, archive, clean up, triage, or clear their inbox, to mark mail as read, to star something, or to delete or restore messages. Works on single messages or whole threads.

2026-07-250

gmail-read

hec-ovi/gmail-skill

Search and read the user's Gmail: find messages, open one or a whole thread, and list or download attachments. Use when the user asks what is in their inbox, whether someone emailed them, to check or summarize mail, to find a message about a topic or from a person, to read a thread, or to save a file someone sent. Read-only: it never sends, labels, or deletes anything.

2026-07-250

gmail-send

hec-ovi/gmail-skill

Send Gmail: a new message, a threaded reply, or a forward, with file attachments. Use when the user asks to send, email, reply to, answer, or forward something, or to send a file or document to someone. Sending is irreversible, so this always previews first and waits for an explicit go-ahead. If the wording is not settled yet, draft it instead.

2026-07-250

name	gmail-setup
description	Connect a Gmail account to this machine, and diagnose it when Gmail calls start failing. Use when the user wants to set up, connect, or authorize Gmail; when they add a second account; when they ask why email stopped working; or when any gmail command returns auth_required, auth_expired, scope_insufficient, client_invalid, or api_not_enabled. Covers the one-time Google Cloud project and OAuth client, the login flow, multiple accounts as profiles, and `gmail doctor`.
allowed-tools	Bash(gmail doctor:) Bash(gmail whoami:) Bash(gmail --version)

gmail-setup

Gmail access here is OAuth against the user's own Google Cloud project. Nothing works until that project exists and consent has been granted once.

Run gmail doctor first, every time. It checks the whole chain (runtime, OAuth client, token, scopes, egress, two live API calls) and every failing check names the exact command or console page that fixes it. Do not guess from an error message when one command gives you the diagnosis.

gmail doctor              # full check, exits 2 if anything failed
gmail doctor --quick      # local files only, no network
gmail doctor --json       # the Envelope, for programmatic checks

Is it already set up?

gmail whoami              # the account, live, or "not logged in"

First-time setup

The Google Cloud half is a browser task the user has to do themselves. Point them at the "Google Cloud setup" section of the project README rather than retyping it; it is roughly ten minutes and produces one file.

Two things that go wrong constantly and are worth stating up front:

The OAuth client must be application type Desktop app. A Web client has no loopback redirect and consent can never complete. gmail doctor fails the oauth-client check with this if they picked wrong.
The Cloud project must stay in Testing with the user added as a test user. Gmail's gmail.modify scope is "restricted", and a Published project with a restricted scope hard-blocks at consent with "Access blocked: has not completed the Google verification process" and no way to click through. The cost of Testing is that refresh tokens expire after 7 days, so roughly weekly they re-run gmail login --force. That is the correct trade for a personal tool.

Once ~/.config/gmail-skill/credentials.json exists:

gmail login               # opens the browser, writes the token, prints the account
gmail doctor              # confirm

Logging in

gmail login                          # no-op if a usable token is already there
gmail login --force                  # re-consent: after 7 days, or after a scope change
gmail login --read-only              # gmail.readonly only; this account can never send
gmail login --profile work           # a second account
gmail logout --profile work          # forget it locally
gmail logout --revoke                # and revoke the grant at Google

--force is the answer to almost every auth failure. Google issues a fresh refresh token and a token carrying every scope.

Headless or over SSH

gmail login starts a loopback listener and opens a browser. On a box with no browser, pin the port and forward it from the machine that has one:

ssh -L 8765:localhost:8765 user@host      # on the laptop
gmail login --port 8765 --no-browser      # on the host, then open the printed URL

Google's device-code flow is not an option: it does not accept Gmail scopes.

Several accounts

One OAuth client, one token file per profile. Every command takes --profile, and $GMAIL_SKILL_PROFILE sets the default.

gmail login --profile work
gmail --profile work search "is:unread"

Reading a failure

Code	What happened	What to do
`auth_required`	No token for this profile	`gmail login`
`auth_expired`	Refresh token dead: 7-day Testing expiry, password reset, or revoked	`gmail login --force`
`scope_insufficient`	Token predates a scope this verb needs	`gmail login --force`
`client_invalid`	No client JSON, or it is a Web client	README setup; the type must be Desktop app
`api_not_enabled`	Gmail API off for the Cloud project	Enable Gmail API in the console
`rate_limited`	Per-minute quota	Retriable. Wait, then batch fewer messages
`quota_exceeded`	Daily budget or the account send cap	Not retriable today

Where things live

~/.config/gmail-skill/ (or $GMAIL_SKILL_HOME), directory 0700: credentials.json is the OAuth client, <profile>.token.json is a live Gmail session at 0600. Never copy either into a repo, a chat, or a bug report. gmail doctor --json is already redacted: it carries no token and no client secret.