Gmail CLI integration for composing, sending, searching, and managing emails
- version
- 1.0.0
- GitHub stars
- 7
Install
/plugin install gmail-plugin@warren-claude-code-plugin-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add WarrenZhu050413/Warren-Claude-Code-Plugin-Marketplace.
Contents
Discovered from sourceCommands 2
Gmail CLI Usage Guide
Use the gmail CLI for all email operations.
Quick Reference
Search & Discovery
gmail search "to:person@example.com" --max 10 # Emails to someone
gmail search "from:person@example.com" --max 10 # Emails from someone
gmail search "subject:keyword after:2024/10/01" # By subject + date
gmail search "has:attachment filename:pdf" # With attachments
gmail list --folder INBOX --max 10 # List inbox
gmail folders # List all folders/labels
Read & View
gmail read <message_id> # Summary view
gmail read <message_id> --full # Full content
gmail read <message_id> --full-thread # Full with thread context
gmail thread <message_id> # View entire thread
gmail thread <message_id> --strip-quotes # Thread without quoted content
Send & Reply
# Send from file (preferred for composed emails)
gmail send --to user@example.com --subject "X" --body "$(cat /tmp/email/draft.txt)"
gmail send --to user@example.com --subject "X" --body "$(cat /tmp/email/draft.txt)" --attachment file.pdf
# Send inline (for quick messages)
gmail send --to user@example.com --subject "X" --body "Y"
gmail reply <message_id> --body "Reply text"
gmail reply <message_id> --body "Reply" --reply-all
Email Styles
gmail styles list # List all styles
gmail styles show professional-formal # View specific style
gmail styles validate style-name # Validate format
Common styles: professional-formal, professional-friendly, casual-friend, brief-reply
Email Groups
gmail groups list # List all groups
gmail groups show team # Show group members
gmail groups add team person@example.com # Add member
gmail send --to @team --subject "X" --body "Y" # Use group
Workflows
gmail workflows list # List workflows
gmail workflows run clear # Run interactively
gmail workflows start clear # Start programmatic (JSON)
gmail workflows continue <token> archive # Continue with action
Gmail Search Operators
People: from:, to:, cc:, bcc:
Date: after:YYYY/MM/DD, before:YYYY/MM/DD, newer_than:7d, older_than:30d
Status: is:unread, is:starred, is:important, is:read
Content: subject:keyword, has:attachment, has:drive, filename:pdf
Size: larger:10M, smaller:5M
Boolean: OR, - (NOT), () (grouping)
Examples:
- All correspondence:
to:person@example.com OR from:person@example.com - Recent thread:
subject:project after:2024/10/01 - Unread important:
is:unread is:important - With PDF:
has:attachment filename:pdf
Composing Emails - Best Practices
Before Writing
- Search past emails to recipient to extract greeting/tone/sign-off patterns
- Check email styles with
gmail styles listto match context - Always test to fuchengwarrenzhu@gmail.com before real sends
Workflow
- Draft email to
/tmp/email/{descriptive_name}.txt - Open file for user review with
open /tmp/email/{name}.txt - Test send:
gmail send --to fuchengwarrenzhu@gmail.com --subject "..." --body "$(cat /tmp/email/{name}.txt)" --yolo - After user confirms, send to real recipient
Configuration
- Config directory:
~/.gmaillm/ - Email styles:
~/.gmaillm/email-styles/ - Email groups:
~/.gmaillm/email-groups.json - Credentials:
~/.gmaillm/credentials.json
Troubleshooting
# Verify setup
gmail verify
# Check account status
gmail status
# Re-authenticate if needed
gmail setup-auth
Related Commands
/gmail:setup- Set up Gmail CLI authentication
Gmail CLI Setup
This command guides you through setting up the gmail CLI for the first time.
Prerequisites
You need OAuth2 credentials from Google Cloud Console.
Step 1: Get OAuth2 Credentials
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API:
- Go to "APIs & Services" > "Enable APIs and Services"
- Search for "Gmail API" and enable it
- Create OAuth2 credentials:
- Go to "Credentials" > "Create Credentials" > "OAuth client ID"
- Application type: Desktop app
- Name: "Gmail CLI" (or any name)
- Click "Create"
- Download the credentials JSON file
- Save it as
~/.gmaillm/oauth-keys.json:mkdir -p ~/.gmaillm mv ~/Downloads/client_secret_*.json ~/.gmaillm/oauth-keys.json chmod 600 ~/.gmaillm/oauth-keys.json
Step 2: Install gmaillm
# Install from source
cd ~/.claude/plugins/gmail-plugin/scripts/gmaillm
make install
Step 3: Authenticate
Run the setup command:
gmail setup-auth
This will:
- Open your browser for Google authentication
- Ask you to grant Gmail access to the CLI
- Save credentials to
~/.gmaillm/credentials.json
If port 8080 is in use:
gmail setup-auth --port 8081
Step 4: Verify Installation
gmail verify
Expected output:
Gmail API authentication: OK
Troubleshooting
"Credentials file is empty" Error
# Re-run authentication
python3 -m gmaillm.setup_auth
# If port is blocked
python3 -m gmaillm.setup_auth --port 9999
"Address already in use" Error
# Kill any existing auth processes
pkill -f "gmaillm.setup_auth"
# Try a different port
gmail setup-auth --port 8081
OAuth Keys Location
The CLI searches for OAuth keys in this order:
~/.gmaillm/oauth-keys.json(recommended)${CLAUDE_PLUGIN_ROOT}/credentials/oauth-keys.json(plugin mode)~/Desktop/OAuth2/gcp-oauth.keys.json(fallback)
File Structure After Setup
~/.gmaillm/
├── oauth-keys.json # OAuth2 client secrets (0600)
├── credentials.json # Saved credentials (0600)
├── email-groups.json # Email distribution groups
├── output-style.json # Output formatting preferences
└── email-styles/ # Email style templates
├── professional-formal.md
├── professional-friendly.md
└── casual-friend.md
Optional: Shell Completion
Enable tab completion for faster typing:
gmail --install-completion
exec $SHELL
Related Commands
/gmail- Usage guide for gmail CLI
Sponsors
Details
- Marketplace
- WarrenZhu050413/Warren-Claude-Code-Plugin-Marketplace
- Source
- gmail-plugin
- Category
- Community
