gmcli — Claude Code skill: manage Gmail from the terminal
gmcli — a skill that gives your AI agent command-line access to Gmail. Search messages, read threads, send emails, manage drafts, and handle labels and attachments directly from your code.
MIT 160 installs ★ 2,663 updated 2026-06-06
npx skills add badlogic/pi-skills --skill gmcli -a claude-codeWhat gmcli does
gmcli provides a command-line interface for Gmail operations. The agent can search emails with Gmail query syntax, fetch complete threads with full message history, send emails with a subject and body, view and apply labels, list and manage drafts, and download attachments. All commands run through the standard Gmail search language.
Setup requires a one-time Google Cloud project configuration: create a project, enable the Gmail API, set up an OAuth desktop application, and download the credentials JSON file. Once configured with gmcli accounts credentials and gmcli accounts add <email>, tokens are stored locally in ~/.gmcli/. Attachments go to ~/.gmcli/attachments/.
After installation for your chosen platform, the agent has full Gmail access—from searching to managing drafts and labels.
What it helps with
- search emails by subject, sender, or date range
- fetch and read entire email threads with message history
- compose and send emails with subject and body
- manage draft emails and Gmail labels
- retrieve and process email attachments
Example prompts for the agent
- Find me emails from the manager about next week's meeting
- Show me the full thread for message ID 17abc4d9e5f6g7h8
- Send an email to [email protected] titled 'Report ready' saying I've uploaded the file
How to install gmcli
1Skills CLI (Vercel)
npx skills add badlogic/pi-skills --skill gmcli -a claude-code2Manually: put the files in place
~/.claude/skills/gmcli/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gmcli/
1Skills CLI (Vercel)
npx skills add badlogic/pi-skills --skill gmcli -a codex2Manually: put the files in place
.agents/skills/gmcli/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add badlogic/pi-skills --skill gmcli -a cursor2Manually: put the files in place
.cursor/skills/gmcli/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install badlogic/pi-skills gmcli2Manually: put the files in place
.github/skills/gmcli/SKILL.md1Skills CLI (Vercel)
npx skills add badlogic/pi-skills --skill gmcli -a gemini-cli2Platform CLI
gemini skills install https://github.com/badlogic/pi-skills --path gmcliManually: put the files in place
.devin/skills/gmcli/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add badlogic/pi-skills --skill gmcli -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about gmcli
How do I install gmcli in Claude Code?
Run npx skills add badlogic/pi-skills --skill gmcli -a claude-code. The skill will be available at ~/.claude/skills/gmcli/SKILL.md.
What's required before first use?
Create a project in Google Cloud Console, enable the Gmail API, add test email addresses, create a desktop OAuth application, and download the credentials JSON. Then run gmcli accounts credentials ~/path/to/credentials.json and gmcli accounts add <email>.
Where are credentials and attachments stored?
Credentials and account tokens live in ~/.gmcli/, and downloaded attachments go to ~/.gmcli/attachments/.
Source text
SKILL.md · MIT
--- name: gmcli description: Gmail CLI for searching emails, reading threads, sending messages, managing drafts, and handling labels/attachments. --- # Gmail CLI Command-line interface for Gmail operations. ## Installation ```bash npm install -g @mariozechner/gmcli ``` ## Setup ### Google Cloud Console (one-time) 1. [Create a new project](https://console.cloud.google.com/projectcreate) (or select existing) 2. [Enable the Gmail API](https://console.cloud.google.com/apis/api/gmail.googleapis.com) 3. [Set app name](https://console.cloud.google.com/auth/branding) in OAuth branding 4. [Add test users](https://console.cloud.google.com/auth/audience) (all Gmail addresses you want to use) 5. [Create OAuth client](https://console.cloud.google.com/auth/clients): - Click "Create Client" - Application type: "Desktop app" - Download the JSON file ### Configure gmcli First check if already configured: ```bash gmcli accounts list ``` If no accounts, guide the user through setup: 1. Ask if they have a Google Cloud project with Gmail API enabled 2. If not, walk them through the Google Cloud Console steps above 3. Have them download the OAuth credentials JSON 4. Run: `gmcli accounts credentials ~/path/to/credentials.json` 5. Run: `gmcli accounts add <email>` (use `--manual` for browserless OAuth) ## Usage Run `gmcli --help` for full command reference. Common operations: - `gmcli <email> search "<query>"` - Search emails using Gmail query syntax - `gmcli <email> thread <threadId>` - Read a thread with all messages - `gmcli <email> send --to <emails> --subject <s> --body <b>` - Send email - `gmcli <email> labels list` - List all labels - `gmcli <email> drafts list` - List drafts ## Data Storage - `~/.gmcli/credentials.json` - OAuth client credentials - `~/.gmcli/accounts.json` - Account tokens - `~/.gmcli/attachments/` - Downloaded attachments
© badlogic · MIT · badlogic/pi-skills