zhongwei/gh-warrenzhu050413-warren-claude-code-plugin-marketplace-gmail-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:05:24 +08:00
commit 8b82a349e4
5 changed files with 300 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
commands/gmail.md Normal file
View File

@@ -0,0 +1,117 @@
---
description: Guide for using the gmail CLI to send, search, and manage emails
---
# Gmail CLI Usage Guide
Use the `gmail` CLI for all email operations.
## Quick Reference
### Search & Discovery
```bash
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
```bash
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
```bash
# 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
```bash
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
```bash
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
```bash
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
```bash
# 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

119
commands/setup.md Normal file
View File

@@ -0,0 +1,119 @@
---
description: Set up Gmail CLI authentication with OAuth2
---
# 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](https://console.cloud.google.com/apis/credentials)
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`:
```bash
mkdir -p ~/.gmaillm
mv ~/Downloads/client_secret_*.json ~/.gmaillm/oauth-keys.json
chmod 600 ~/.gmaillm/oauth-keys.json
```
## Step 2: Install gmaillm
```bash
# Install from source
cd /Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/gmail-integration-plugin/scripts/gmaillm
make install
```
## Step 3: Authenticate
Run the setup command:
```bash
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:**
```bash
gmail setup-auth --port 8081
```
## Step 4: Verify Installation
```bash
gmail verify
```
Expected output:
```
Gmail API authentication: OK
```
## Troubleshooting
### "Credentials file is empty" Error
```bash
# Re-run authentication
python3 -m gmaillm.setup_auth
# If port is blocked
python3 -m gmaillm.setup_auth --port 9999
```
### "Address already in use" Error
```bash
# 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:
```bash
gmail --install-completion
exec $SHELL
```
## Related Commands
- `/gmail` - Usage guide for gmail CLI