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-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add WarrenZhu050413/Warren-Claude-Code-Plugin-Marketplace.

Contents

Discovered from source

Commands 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

  1. Search past emails to recipient to extract greeting/tone/sign-off patterns
  2. Check email styles with gmail styles list to match context
  3. Always test to fuchengwarrenzhu@gmail.com before real sends

Workflow

  1. Draft email to /tmp/email/{descriptive_name}.txt
  2. Open file for user review with open /tmp/email/{name}.txt
  3. Test send: gmail send --to fuchengwarrenzhu@gmail.com --subject "..." --body "$(cat /tmp/email/{name}.txt)" --yolo
  4. 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

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Gmail API:
    • Go to "APIs & Services" > "Enable APIs and Services"
    • Search for "Gmail API" and enable it
  4. Create OAuth2 credentials:
    • Go to "Credentials" > "Create Credentials" > "OAuth client ID"
    • Application type: Desktop app
    • Name: "Gmail CLI" (or any name)
    • Click "Create"
  5. Download the credentials JSON file
  6. 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:

  1. Open your browser for Google authentication
  2. Ask you to grant Gmail access to the CLI
  3. 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:

  1. ~/.gmaillm/oauth-keys.json (recommended)
  2. ${CLAUDE_PLUGIN_ROOT}/credentials/oauth-keys.json (plugin mode)
  3. ~/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

More from WarrenZhu050413/Warren-Claude-Code-Plugin-Marketplace

All 3