skill-google-gmail-tool

What this skill does

# When to use
- Access Gmail messages, send emails, export to Obsidian
- Manage Google Calendar events and export schedules
- Work with Google Tasks and to-do lists
- Search, upload, download Google Drive files

# Google Gmail Tool Skill

## Purpose

The `google-gmail-tool` is a professional CLI that provides comprehensive access to Google services including Gmail, Calendar, Tasks, and Drive. It enables agent-friendly JSON output, human-readable text formats, multi-level verbosity logging, and seamless Obsidian integration.

## When to Use This Skill

**Use this skill when:**
- Reading or sending Gmail messages programmatically
- Managing calendar events and schedules
- Working with Google Tasks and to-do lists
- Searching, uploading, or downloading files from Google Drive
- Exporting Google data to Obsidian markdown notes
- Automating Google service workflows

**Do NOT use this skill for:**
- Direct Google API programming (this is a CLI wrapper)
- Google Workspace admin tasks (requires different APIs)
- Real-time synchronization (uses polling-based access)

## CLI Tool: google-gmail-tool

A CLI that provides access to Google services with OAuth2 authentication, supporting Gmail, Calendar, Tasks, and Drive operations.

### Installation

```bash
# Clone repository
git clone https://github.com/dnvriend/google-gmail-tool.git
cd google-gmail-tool

# Install globally with uv
uv tool install .

# Verify installation
google-gmail-tool --version
```

### Prerequisites

- **Python**: 3.14 or higher
- **OAuth Credentials**: Google Cloud Console OAuth 2.0 Client ID (Desktop application)
- **Environment Variables**:
  - `GOOGLE_GMAIL_TOOL_CREDENTIALS`: Path to credentials JSON file
  - `GOOGLE_GMAIL_TOOL_CREDENTIALS_JSON`: Full OAuth2 credentials as JSON string
  - `OBSIDIAN_ROOT`: Path to Obsidian vault (for export commands)

### Quick Start

```bash
# 1. Get OAuth credentials from Google Cloud Console
# Visit: https://console.cloud.google.com/apis/credentials

# 2. Set credentials environment variable
export GOOGLE_GMAIL_TOOL_CREDENTIALS=~/.config/google-gmail-tool/credentials.json

# 3. Verify authentication
google-gmail-tool auth check

# 4. List Gmail threads
google-gmail-tool mail list --today

# 5. List calendar events
google-gmail-tool calendar list --this-week
```

## Progressive Disclosure

<details>
<summary><strong>📧 Gmail Commands (Click to expand)</strong></summary>

### mail list - List Gmail messages or threads

List Gmail messages or threads with optional filtering, supporting full Gmail search syntax.

**Usage:**
```bash
google-gmail-tool mail list [OPTIONS]
```

**Options:**
- `--query "TEXT"`: Gmail search query (supports full Gmail search syntax)
- `--today`: Filter emails from today only
- `--max-results N` / `-n N`: Maximum results (default: 50, max: 500)
- `--format FORMAT` / `-f FORMAT`: Output format (json, text)
- `--text`: Shorthand for `--format text`
- `--message-mode`: List individual messages instead of threads
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)

**Gmail Search Operators:**
- `is:unread`, `is:read`, `is:starred` - Message status
- `has:attachment`, `filename:pdf` - Attachments
- `from:[email protected]` - Sender
- `to:[email protected]` - Recipient
- `subject:keyword` - Subject line
- `after:YYYY/MM/DD`, `before:YYYY/MM/DD` - Date range
- `older_than:2d`, `newer_than:1m` - Relative dates
- `label:important`, `in:inbox` - Labels

**Examples:**
```bash
# List 50 most recent threads
google-gmail-tool mail list

# Find unread emails from today
google-gmail-tool mail list --today --query "is:unread"

# Search for specific sender
google-gmail-tool mail list --query "from:[email protected]" -n 10

# Find emails with attachments
google-gmail-tool mail list --query "has:attachment" --text

# Complex query
google-gmail-tool mail list \
    --query "from:[email protected] subject:report after:2025/01/01" \
    --message-mode
```

**Output (JSON):**
```json
[
  {
    "id": "19a90f13e3c7af52",
    "threadId": "19a90f13e3c7af52",
    "snippet": "Meeting notes from...",
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Meeting Notes",
    "date": "2025-11-20T10:30:00Z"
  }
]
```

---

### mail send - Send email via Gmail

Send emails via Gmail API with support for HTML, CC, BCC, and attachments.

**Usage:**
```bash
google-gmail-tool mail send [OPTIONS]
```

**Options:**
- `--to EMAIL`: Recipient email (required)
- `--subject TEXT`: Email subject (required)
- `--body TEXT`: Email body (required)
- `--from EMAIL`: Sender email (optional, uses default)
- `--cc EMAIL`: CC recipients (comma-separated)
- `--bcc EMAIL`: BCC recipients (comma-separated)
- `--html`: Send as HTML instead of plain text
- `--dry-run`: Preview email without sending
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)

**Examples:**
```bash
# Send plain text email
google-gmail-tool mail send \
    --to "[email protected]" \
    --subject "Meeting Notes" \
    --body "Here are the notes from today's meeting..."

# Send HTML email with CC
google-gmail-tool mail send \
    --to "[email protected]" \
    --cc "[email protected]" \
    --subject "Weekly Report" \
    --body "<h1>Report</h1><p>Details...</p>" \
    --html

# Preview without sending
google-gmail-tool mail send \
    --to "[email protected]" \
    --subject "Test" \
    --body "Test email" \
    --dry-run
```

---

### mail get - Get email message details

Retrieve detailed information about a specific Gmail message.

**Usage:**
```bash
google-gmail-tool mail get MESSAGE_ID [OPTIONS]
```

**Options:**
- `MESSAGE_ID`: Gmail message ID (required)
- `--format FORMAT` / `-f FORMAT`: Output format (json, text)
- `--include-body`: Include full message body
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)

**Examples:**
```bash
# Get message metadata
google-gmail-tool mail get 19a90f13e3c7af52

# Get message with full body
google-gmail-tool mail get 19a90f13e3c7af52 --include-body

# Text format output
google-gmail-tool mail get 19a90f13e3c7af52 --include-body --format text
```

---

### mail export-obsidian - Export Gmail to Obsidian

Export Gmail threads to Obsidian markdown notes with attachments.

**Usage:**
```bash
google-gmail-tool mail export-obsidian [OPTIONS]
```

**Options:**
- `--query "TEXT"`: Gmail search query
- `--today`: Export emails from today only
- `--max-results N` / `-n N`: Maximum threads to export
- `--obsidian-root PATH`: Obsidian vault root path (or use `OBSIDIAN_ROOT` env var)
- `--download-attachments`: Download email attachments (default)
- `--no-download-attachments`: Skip downloading attachments
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)

**Obsidian Structure:**
```
$OBSIDIAN_ROOT/emails/<timestamp>-<sender>-<subject>/
├── thread.md                 # Thread with all messages
└── attachments/              # Downloaded attachments
    ├── document.pdf
    └── image.png
```

**Examples:**
```bash
# Export today's emails
google-gmail-tool mail export-obsidian --today

# Export specific threads
google-gmail-tool mail export-obsidian --query "from:[email protected]"

# Export without attachments
google-gmail-tool mail export-obsidian \
    --query "subject:report" \
    --no-download-attachments
```

</details>

<details>
<summary><strong>📅 Calendar Commands (Click to expand)</strong></summary>

### calendar list - List calendar events

List calendar events with time range and query filtering.

**Usage:**
```bash
google-gmail-tool calendar list [OPTIONS]
```

**Options:**
- `--today`: Events for today
- `--tomorrow`: Events for tomorrow
- `--this-week`: Events this week (Monday-Sunday, default)
- `--next-week`: Events next week
- `--days N`: Events for next N days
- `--date YYYY-MM-DD`: Events for specific date
- `--range-start YYYY-MM-DD`: Start of custom range
- `--range-end YYYY-MM-DD`: End of custom range
- `--query "TEXT"`: Free-text search (title, description, location)
- `--max-results N` / `-n N`: Maximum results (default: 100)
- `--format FORMAT` /