From 30bbbc890acb7c9934f5d5eca2aed76b1e3594cb Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:23:24 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 14 + README.md | 3 + commands/auth-check.md | 31 + commands/calendar-list.md | 40 ++ commands/drive-search.md | 39 ++ commands/mail-list.md | 37 ++ commands/mail-send.md | 45 ++ commands/task-list.md | 39 ++ plugin.lock.json | 69 ++ skills/google-gmail-tool/SKILL.md | 1006 +++++++++++++++++++++++++++++ 10 files changed, 1323 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/auth-check.md create mode 100644 commands/calendar-list.md create mode 100644 commands/drive-search.md create mode 100644 commands/mail-list.md create mode 100644 commands/mail-send.md create mode 100644 commands/task-list.md create mode 100644 plugin.lock.json create mode 100644 skills/google-gmail-tool/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9af3f40 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "google-gmail-tool", + "description": "google-gmail-tool-plugin", + "version": "0.1.0", + "author": { + "name": "Dennis Vriend" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..82294f9 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# google-gmail-tool + +google-gmail-tool-plugin diff --git a/commands/auth-check.md b/commands/auth-check.md new file mode 100644 index 0000000..336a3c3 --- /dev/null +++ b/commands/auth-check.md @@ -0,0 +1,31 @@ +--- +description: Verify OAuth credentials and API access +argument-hint: +--- + +Verify Google OAuth credentials and API access. + +## Usage + +```bash +google-gmail-tool auth check [-v|-vv|-vvv] +``` + +## Environment Variables + +- `GOOGLE_GMAIL_TOOL_CREDENTIALS_JSON`: Full OAuth2 credentials as JSON +- `GOOGLE_GMAIL_TOOL_CREDENTIALS`: Path to credentials JSON file + +## Examples + +```bash +# Check authentication status +google-gmail-tool auth check + +# Check with verbose output +google-gmail-tool auth check -vv +``` + +## Output + +Returns status for Gmail, Calendar, Tasks, and Drive API access. diff --git a/commands/calendar-list.md b/commands/calendar-list.md new file mode 100644 index 0000000..39e97ad --- /dev/null +++ b/commands/calendar-list.md @@ -0,0 +1,40 @@ +--- +description: List calendar events with time filtering +argument-hint: timerange +--- + +List calendar events with optional filtering. + +## Usage + +```bash +google-gmail-tool calendar list [--today] [--this-week] [--query "TEXT"] +``` + +## Arguments + +- `--today`: Events for today +- `--tomorrow`: Events for tomorrow +- `--this-week`: Events this week (Monday-Sunday) +- `--days N`: Events for next N days +- `--query "TEXT"`: Search query (title, description, location) +- `-n N`: Max results (default: 100) +- `--text`: Output in text format +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +## Examples + +```bash +# List this week's events +google-gmail-tool calendar list --this-week + +# Find meetings about project +google-gmail-tool calendar list --query "project meeting" + +# Today's events in text format +google-gmail-tool calendar list --today --text +``` + +## Output + +Returns JSON array with id, summary, start, end, location, attendees. diff --git a/commands/drive-search.md b/commands/drive-search.md new file mode 100644 index 0000000..4d5b8f7 --- /dev/null +++ b/commands/drive-search.md @@ -0,0 +1,39 @@ +--- +description: Search Google Drive files and folders +argument-hint: name +--- + +Search for files and folders in Google Drive. + +## Usage + +```bash +google-gmail-tool drive search [--name "NAME"] [--type TYPE] +``` + +## Arguments + +- `--name "NAME"`: Search by file/folder name +- `--type TYPE`: Filter by type (document, spreadsheet, folder, pdf) +- `--owner me|others|anyone`: Filter by owner +- `--shared`: Show only shared files +- `-n N`: Max results (default: 50) +- `--text`: Output in text format +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +## Examples + +```bash +# Search by name +google-gmail-tool drive search --name "report" + +# Find PDFs I own +google-gmail-tool drive search --type pdf --owner me + +# Find shared spreadsheets +google-gmail-tool drive search --type spreadsheet --shared +``` + +## Output + +Returns JSON array with id, name, mimeType, size, modified, webViewLink. diff --git a/commands/mail-list.md b/commands/mail-list.md new file mode 100644 index 0000000..9740b7a --- /dev/null +++ b/commands/mail-list.md @@ -0,0 +1,37 @@ +--- +description: List Gmail messages with filtering options +argument-hint: query +--- + +List Gmail messages or threads with optional filtering. + +## Usage + +```bash +google-gmail-tool mail list [--query "QUERY"] [--today] [-n N] [--text] +``` + +## Arguments + +- `--query "QUERY"`: Gmail search query (optional) +- `--today`: Filter emails from today only +- `-n N`: Max results (default: 50, max: 500) +- `--text`: Output in text format +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +## 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" + +# List with JSON output +google-gmail-tool mail list --query "from:team@company.com" -n 10 +``` + +## Output + +Returns JSON array with id, threadId, snippet, from, to, subject, date. diff --git a/commands/mail-send.md b/commands/mail-send.md new file mode 100644 index 0000000..58384e0 --- /dev/null +++ b/commands/mail-send.md @@ -0,0 +1,45 @@ +--- +description: Send email via Gmail API +argument-hint: to subject body +--- + +Send an email message via Gmail. + +## Usage + +```bash +google-gmail-tool mail send --to "EMAIL" --subject "SUBJECT" --body "BODY" +``` + +## Arguments + +- `--to EMAIL`: Recipient email (required) +- `--subject TEXT`: Email subject (required) +- `--body TEXT`: Email body (required) +- `--cc EMAIL`: CC recipients (optional) +- `--bcc EMAIL`: BCC recipients (optional) +- `--html`: Send as HTML instead of plain text +- `--dry-run`: Preview without sending +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +## Examples + +```bash +# Send plain text email +google-gmail-tool mail send \ + --to "user@example.com" \ + --subject "Meeting Notes" \ + --body "Here are the notes..." + +# Send HTML email with CC +google-gmail-tool mail send \ + --to "user@example.com" \ + --cc "team@example.com" \ + --subject "Report" \ + --body "

Report

" \ + --html +``` + +## Output + +Returns success confirmation with message ID. diff --git a/commands/task-list.md b/commands/task-list.md new file mode 100644 index 0000000..1e928e0 --- /dev/null +++ b/commands/task-list.md @@ -0,0 +1,39 @@ +--- +description: List Google Tasks with filtering +argument-hint: filter +--- + +List Google Tasks with status and date filtering. + +## Usage + +```bash +google-gmail-tool task list [--completed] [--incomplete] [--today] +``` + +## Arguments + +- `--completed`: Show only completed tasks +- `--incomplete`: Show only incomplete tasks +- `--today`: Tasks due today +- `--overdue`: Tasks past due date +- `-n N`: Max results (default: 100) +- `--text`: Output in text format +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +## Examples + +```bash +# List all tasks +google-gmail-tool task list + +# Show incomplete tasks due today +google-gmail-tool task list --incomplete --today + +# Show overdue tasks +google-gmail-tool task list --overdue +``` + +## Output + +Returns JSON array with id, title, notes, due, status, updated. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..229e5a4 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,69 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:dnvriend/google-gmail-tool:plugins/google-gmail-tool", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "51ef8eba6c649d55cd22b80dfc698da8e895ccb7", + "treeHash": "e874b64c4cd68daf9fec6cb8a6c3f13382cb054f32f5f3657aa1ecaa77465a1f", + "generatedAt": "2025-11-28T10:16:36.249253Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "google-gmail-tool", + "description": "google-gmail-tool-plugin", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "6ba13dda849745fd50857d383a4757ef4f3d4e9caa77cb7740d02ce22d8ae988" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "f7858a3698adef0a8589913439e47bba48912880f26548bf1dc2722876c26edd" + }, + { + "path": "commands/mail-list.md", + "sha256": "a378f73be1db046d2db6997db3d675ef54ddd90a8ea216fb200222697bd71ba2" + }, + { + "path": "commands/task-list.md", + "sha256": "104e7838d732540661d025c23815a194c2c6a6ece3abfb4a9a9d52fa87e5887d" + }, + { + "path": "commands/mail-send.md", + "sha256": "00460ba10ad7fe9463a901a94ebff45315cde8e3d1fd6265b749daf808c6062a" + }, + { + "path": "commands/drive-search.md", + "sha256": "d4410960dbe5364c77e441d7326e70c0ea2750b7db15fe95e05764222c9185b7" + }, + { + "path": "commands/calendar-list.md", + "sha256": "cb1558e665f3d3c11beef7b0b4452ebe6ba58c386db1fbf36dd93884465df041" + }, + { + "path": "commands/auth-check.md", + "sha256": "a31ee045c6a6472a0dd9737bff7f4c41b6cf0714a469bc7ce2336a1b35896507" + }, + { + "path": "skills/google-gmail-tool/SKILL.md", + "sha256": "b2a9275470da4fbee208d1e7a16843ace81800b62254d015b07208a88a76afc9" + } + ], + "dirSha256": "e874b64c4cd68daf9fec6cb8a6c3f13382cb054f32f5f3657aa1ecaa77465a1f" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/google-gmail-tool/SKILL.md b/skills/google-gmail-tool/SKILL.md new file mode 100644 index 0000000..7ad3bfd --- /dev/null +++ b/skills/google-gmail-tool/SKILL.md @@ -0,0 +1,1006 @@ +--- +name: skill-google-gmail-tool +description: Access Google Gmail, Calendar, Tasks, Drive APIs +--- + +# 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 + +
+📧 Gmail Commands (Click to expand) + +### 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@example.com` - Sender +- `to:email@example.com` - 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:team@company.com" -n 10 + +# Find emails with attachments +google-gmail-tool mail list --query "has:attachment" --text + +# Complex query +google-gmail-tool mail list \ + --query "from:john@example.com subject:report after:2025/01/01" \ + --message-mode +``` + +**Output (JSON):** +```json +[ + { + "id": "19a90f13e3c7af52", + "threadId": "19a90f13e3c7af52", + "snippet": "Meeting notes from...", + "from": "sender@example.com", + "to": "recipient@example.com", + "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 "user@example.com" \ + --subject "Meeting Notes" \ + --body "Here are the notes from today's meeting..." + +# Send HTML email with CC +google-gmail-tool mail send \ + --to "user@example.com" \ + --cc "team@example.com" \ + --subject "Weekly Report" \ + --body "

Report

Details...

" \ + --html + +# Preview without sending +google-gmail-tool mail send \ + --to "user@example.com" \ + --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/--/ +├── 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:important@example.com" + +# Export without attachments +google-gmail-tool mail export-obsidian \ + --query "subject:report" \ + --no-download-attachments +``` + +
+ +
+📅 Calendar Commands (Click to expand) + +### 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` / `-f FORMAT`: Output format (json, text) +- `--text`: Shorthand for `--format text` +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# List this week's events (default) +google-gmail-tool calendar list + +# Today's events +google-gmail-tool calendar list --today + +# Next 7 days +google-gmail-tool calendar list --days 7 + +# Search for meetings +google-gmail-tool calendar list --query "team meeting" + +# Custom date range +google-gmail-tool calendar list \ + --range-start 2025-11-20 \ + --range-end 2025-11-27 +``` + +**Output (JSON):** +```json +[ + { + "id": "event123", + "summary": "Team Meeting", + "start": "2025-11-20T10:00:00Z", + "end": "2025-11-20T11:00:00Z", + "location": "Conference Room A", + "attendees": ["user1@example.com", "user2@example.com"] + } +] +``` + +--- + +### calendar create - Create calendar event + +Create a new calendar event with optional attendees and Google Meet. + +**Usage:** +```bash +google-gmail-tool calendar create [OPTIONS] +``` + +**Options:** +- `--title TEXT` / `-t TEXT`: Event title (required) +- `--start DATETIME`: Start datetime (YYYY-MM-DD HH:MM) +- `--end DATETIME`: End datetime (YYYY-MM-DD HH:MM) +- `--date YYYY-MM-DD`: Date for all-day event +- `--all-day`: Create all-day event (requires `--date`) +- `--location TEXT` / `-l TEXT`: Event location +- `--description TEXT` / `-d TEXT`: Event description +- `--attendees EMAILS` / `-a EMAILS`: Comma-separated attendee emails +- `--add-meet`: Add Google Meet video conferencing +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Create simple event +google-gmail-tool calendar create \ + --title "Team Meeting" \ + --start "2025-11-20 10:00" \ + --end "2025-11-20 11:00" + +# Create event with Google Meet +google-gmail-tool calendar create \ + --title "Remote Standup" \ + --start "2025-11-21 09:00" \ + --end "2025-11-21 09:30" \ + --add-meet + +# Create all-day event +google-gmail-tool calendar create \ + --title "Conference" \ + --date "2025-11-25" \ + --all-day + +# Create event with attendees +google-gmail-tool calendar create \ + --title "Project Review" \ + --start "2025-11-22 14:00" \ + --end "2025-11-22 15:00" \ + --location "Room 301" \ + --attendees "user1@example.com,user2@example.com" +``` + +--- + +### calendar export-obsidian - Export calendar to Obsidian + +Export calendar events to Obsidian daily notes as checklist items. + +**Usage:** +```bash +google-gmail-tool calendar export-obsidian [OPTIONS] +``` + +**Options:** +- `--today`: Export today's events +- `--this-week`: Export this week's events (default) +- `--date YYYY-MM-DD`: Export specific date +- `--range-start YYYY-MM-DD`: Start of custom range +- `--range-end YYYY-MM-DD`: End of custom range +- `--query "TEXT"`: Filter events by search query +- `--obsidian-root PATH`: Obsidian vault root path +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Smart Merge Logic:** +- Preserves checked-off items +- Updates event times if changed +- Removes cancelled events +- Adds new events + +**Examples:** +```bash +# Export today's schedule +google-gmail-tool calendar export-obsidian --today + +# Export this week to daily notes +google-gmail-tool calendar export-obsidian --this-week + +# Export filtered events +google-gmail-tool calendar export-obsidian --query "meeting" +``` + +
+ +
+✅ Task Commands (Click to expand) + +### task list - List Google Tasks + +List Google Tasks with status and date filtering. + +**Usage:** +```bash +google-gmail-tool task list [OPTIONS] +``` + +**Options:** +- `--completed`: Show only completed tasks +- `--incomplete`: Show only incomplete tasks (default) +- `--show-all`: Show both completed and incomplete +- `--today`: Tasks due today +- `--overdue`: Tasks past due date +- `--max-results N` / `-n N`: Maximum results (default: 100) +- `--format FORMAT` / `-f FORMAT`: Output format (json, text) +- `--text`: Shorthand for `--format text` +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# List incomplete tasks (default) +google-gmail-tool task list + +# Show all tasks including completed +google-gmail-tool task list --show-all + +# Tasks due today +google-gmail-tool task list --today + +# Overdue tasks +google-gmail-tool task list --overdue + +# First 10 incomplete tasks +google-gmail-tool task list --incomplete -n 10 +``` + +**Output (JSON):** +```json +[ + { + "id": "task123", + "title": "Review PR #456", + "notes": "Check code quality and tests", + "due": "2025-11-20", + "status": "needsAction", + "updated": "2025-11-19T15:30:00Z" + } +] +``` + +--- + +### task create - Create new task + +Create a new Google Task with optional notes and due date. + +**Usage:** +```bash +google-gmail-tool task create [OPTIONS] +``` + +**Options:** +- `--title TEXT` / `-t TEXT`: Task title (required) +- `--notes TEXT` / `-n TEXT`: Task notes/description +- `--due YYYY-MM-DD` / `-d YYYY-MM-DD`: Due date +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Create minimal task +google-gmail-tool task create --title "Review PR #123" + +# Create task with due date +google-gmail-tool task create \ + --title "Submit report" \ + --due "2025-11-25" + +# Create task with notes +google-gmail-tool task create \ + --title "Team meeting prep" \ + --notes "Prepare slides and agenda" \ + --due "2025-11-20" +``` + +--- + +### task complete - Mark tasks as completed + +Mark one or more tasks as completed. + +**Usage:** +```bash +google-gmail-tool task complete TASK_ID [TASK_ID...] [OPTIONS] +``` + +**Options:** +- `TASK_ID`: One or more task IDs (space-separated) +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Complete single task +google-gmail-tool task complete abc123xyz + +# Complete multiple tasks +google-gmail-tool task complete abc123 def456 ghi789 + +# Pipeline with jq +TASK_ID=$(google-gmail-tool task list -n 1 | jq -r '.[0].id') +google-gmail-tool task complete "$TASK_ID" +``` + +--- + +### task export-obsidian - Export tasks to Obsidian + +Export Google Tasks to Obsidian daily notes as checklist items. + +**Usage:** +```bash +google-gmail-tool task export-obsidian [OPTIONS] +``` + +**Options:** +- `--today`: Export tasks due today +- `--this-week`: Export tasks due this week +- `--date YYYY-MM-DD`: Export tasks for specific date +- `--range-start YYYY-MM-DD`: Start of custom range +- `--range-end YYYY-MM-DD`: End of custom range +- `--obsidian-root PATH`: Obsidian vault root path +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Smart Merge Logic:** +- Preserves checked-off items +- Updates task details if changed +- Removes completed tasks (optional) +- Adds new tasks + +**Examples:** +```bash +# Export today's tasks +google-gmail-tool task export-obsidian --today + +# Export this week's tasks +google-gmail-tool task export-obsidian --this-week + +# Export custom date range +google-gmail-tool task export-obsidian \ + --range-start 2025-11-20 \ + --range-end 2025-11-27 +``` + +
+ +
+📁 Drive Commands (Click to expand) + +### drive list - List Drive files + +List files in Google Drive with filtering and sorting. + +**Usage:** +```bash +google-gmail-tool drive list [OPTIONS] +``` + +**Options:** +- `--query "TEXT"`: Drive query string +- `--max-results N` / `-n N`: Maximum results (default: 50) +- `--folder FOLDER_ID`: List files in specific folder +- `--order-by FIELD`: Sort by field (name, createdTime, modifiedTime desc) +- `--format FORMAT` / `-f FORMAT`: Output format (json, text) +- `--text`: Shorthand for `--format text` +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# List 50 most recent files +google-gmail-tool drive list + +# List files in folder +google-gmail-tool drive list --folder 0ALlMmd1yT2TNUk9PVA + +# Sort by name +google-gmail-tool drive list --order-by name -n 20 +``` + +**Output (JSON):** +```json +[ + { + "id": "1abc...xyz", + "name": "document.pdf", + "mimeType": "application/pdf", + "size": "1048576", + "modifiedTime": "2025-11-20T10:30:00Z", + "webViewLink": "https://drive.google.com/..." + } +] +``` + +--- + +### drive search - Search Drive files + +Search for files and folders with common filters. + +**Usage:** +```bash +google-gmail-tool drive search [OPTIONS] +``` + +**Options:** +- `--name "TEXT"`: Search by file/folder name +- `--type TYPE`: Filter by type (document, spreadsheet, presentation, folder, pdf, image) +- `--owner OWNER`: Filter by owner (me, others, anyone) +- `--shared`: Show only shared files +- `--max-results N` / `-n N`: Maximum results (default: 50) +- `--format FORMAT` / `-f FORMAT`: Output format (json, text) +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Search by name +google-gmail-tool drive search --name "report" + +# Find PDFs I own +google-gmail-tool drive search --type pdf --owner me + +# Find shared spreadsheets +google-gmail-tool drive search --type spreadsheet --shared + +# Complex search +google-gmail-tool drive search \ + --name "2025" \ + --type document \ + --owner me \ + -n 100 +``` + +--- + +### drive upload-file - Upload file to Drive + +Upload a local file to Google Drive. + +**Usage:** +```bash +google-gmail-tool drive upload-file LOCAL_PATH [PARENT_ID] [OPTIONS] +``` + +**Options:** +- `LOCAL_PATH`: Local file path (required) +- `PARENT_ID`: Parent folder ID (optional, defaults to My Drive root) +- `--name NAME`: Drive file name (defaults to local filename) +- `--description TEXT`: File description +- `--mime-type TYPE`: Override MIME type +- `--force` / `-f`: Skip duplicate check +- `--format FORMAT`: Output format (json, text) +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Upload to My Drive root +google-gmail-tool drive upload-file document.pdf + +# Upload to specific folder +google-gmail-tool drive upload-file report.pdf 0ALlMmd1yT2TNUk9PVA + +# Upload with custom name +google-gmail-tool drive upload-file data.csv \ + --name "Sales Report 2025.csv" +``` + +--- + +### drive download - Download file from Drive + +Download a file from Google Drive to local filesystem. + +**Usage:** +```bash +google-gmail-tool drive download FILE_ID OUTPUT_PATH [OPTIONS] +``` + +**Options:** +- `FILE_ID`: Drive file ID (required) +- `OUTPUT_PATH`: Local output path (required) +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Download file +google-gmail-tool drive download 1abc...xyz document.pdf + +# Download to specific directory +google-gmail-tool drive download 1abc...xyz ~/Downloads/report.pdf +``` + +
+ +
+🔐 Authentication Commands (Click to expand) + +### auth check - Verify credentials + +Verify Google OAuth credentials and API access. + +**Usage:** +```bash +google-gmail-tool auth check [-v|-vv|-vvv] +``` + +**Environment Variables:** +- `GOOGLE_GMAIL_TOOL_CREDENTIALS_JSON`: Full OAuth2 credentials as JSON string +- `GOOGLE_GMAIL_TOOL_CREDENTIALS`: Path to OAuth2 credentials JSON file + +**Validates:** +- OAuth credential format and validity +- Access token refresh capability +- Gmail API access +- Calendar API access +- Tasks API access +- Drive API access + +**Examples:** +```bash +# Check authentication +google-gmail-tool auth check + +# Check with debug output +google-gmail-tool auth check -vv +``` + +**Output:** +``` +🔐 Checking Google OAuth credentials... +✓ Credentials loaded successfully +✓ Gmail API access granted +✓ Calendar API access granted +✓ Tasks API access granted +✓ Drive API access granted +``` + +--- + +### auth login - Complete OAuth flow + +Complete OAuth flow to generate authorized credentials. + +**Usage:** +```bash +google-gmail-tool auth login [OPTIONS] +``` + +**Options:** +- `--client-id ID`: OAuth Client ID +- `--client-secret SECRET`: OAuth Client Secret +- `--json-file PATH`: Path to client secret JSON (alternative) +- `--output PATH` / `-o PATH`: Output file for credentials (default: `~/.config/google-gmail-tool/credentials.json`) +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Login with client ID and secret +google-gmail-tool auth login \ + --client-id "123...apps.googleusercontent.com" \ + --client-secret "GOCSPX-..." + +# Login with JSON file +google-gmail-tool auth login \ + --json-file ~/Downloads/client_secret.json + +# Custom output location +google-gmail-tool auth login \ + --json-file ~/Downloads/client_secret.json \ + --output ~/.credentials/google.json +``` + +
+ +
+⚙️ Advanced Features (Click to expand) + +### Multi-Level Verbosity + +Control logging detail with `-v/-vv/-vvv` flags: + +- **No flag** (WARNING): Only critical issues +- **`-v`** (INFO): High-level operations, important events +- **`-vv`** (DEBUG): Detailed operations, API calls, validation steps +- **`-vvv`** (TRACE): Full request/response, library internals + +**Examples:** +```bash +# Normal mode (warnings only) +google-gmail-tool mail list + +# Info level +google-gmail-tool mail list -v + +# Debug level +google-gmail-tool mail list -vv + +# Trace level (includes Google API internals) +google-gmail-tool mail list -vvv +``` + +--- + +### Shell Completion + +Install tab completion for bash, zsh, or fish: + +**Bash:** +```bash +eval "$(google-gmail-tool completion bash)" +# Or add to ~/.bashrc +``` + +**Zsh:** +```bash +eval "$(google-gmail-tool completion zsh)" +# Or add to ~/.zshrc +``` + +**Fish:** +```bash +google-gmail-tool completion fish > ~/.config/fish/completions/google-gmail-tool.fish +``` + +--- + +### Output Formats + +All commands support JSON and text output: + +**JSON (default):** +```bash +google-gmail-tool mail list | jq '.[] | .subject' +``` + +**Text (human-readable):** +```bash +google-gmail-tool mail list --text +``` + +--- + +### Pipeline Integration + +Designed for Unix pipeline integration: + +**Examples:** +```bash +# Extract email subjects +google-gmail-tool mail list | jq -r '.[] | .subject' + +# Count unread messages +google-gmail-tool mail list --query "is:unread" | jq 'length' + +# Complete first incomplete task +TASK_ID=$(google-gmail-tool task list -n 1 | jq -r '.[0].id') +google-gmail-tool task complete "$TASK_ID" + +# Search and download Drive file +FILE_ID=$(google-gmail-tool drive search --name "report" | jq -r '.[0].id') +google-gmail-tool drive download "$FILE_ID" report.pdf +``` + +
+ +
+🔧 Troubleshooting (Click to expand) + +### Common Issues + +**Issue: "Credentials not found"** +```bash +# Error +[ERROR] Credentials not found +``` + +**Solution:** +1. Set credentials environment variable: + ```bash + export GOOGLE_GMAIL_TOOL_CREDENTIALS=~/.config/google-gmail-tool/credentials.json + ``` +2. Or use `auth login` to generate credentials: + ```bash + google-gmail-tool auth login --json-file ~/Downloads/client_secret.json + ``` + +--- + +**Issue: "API access denied"** + +**Solution:** +1. Check API is enabled in Google Cloud Console +2. Verify OAuth scopes include required permissions +3. Re-run auth check: + ```bash + google-gmail-tool auth check -vv + ``` + +--- + +**Issue: "Token expired"** + +**Solution:** +Credentials include refresh token, should auto-refresh. If not: +```bash +# Re-authenticate +google-gmail-tool auth login --json-file ~/Downloads/client_secret.json +``` + +--- + +**Issue: "Obsidian export fails"** + +**Solution:** +1. Set `OBSIDIAN_ROOT` environment variable: + ```bash + export OBSIDIAN_ROOT=~/Documents/ObsidianVault + ``` +2. Or use `--obsidian-root` flag: + ```bash + google-gmail-tool mail export-obsidian --obsidian-root ~/Documents/ObsidianVault + ``` + +### Getting Help + +```bash +# Main help +google-gmail-tool --help + +# Command group help +google-gmail-tool mail --help +google-gmail-tool calendar --help + +# Specific command help +google-gmail-tool mail list --help +google-gmail-tool task create --help +``` + +
+ +## Exit Codes + +- `0`: Success +- `1`: General error (authentication, API error, validation failure) +- `2`: Not found (message/event/task/file not found) + +## Output Formats + +**JSON (default):** +- Agent-friendly structured data +- Suitable for parsing with jq +- Consistent schema across commands + +**Text (--text flag):** +- Human-readable format +- Tabular or list output +- Good for terminal viewing + +## Best Practices + +1. **Use Environment Variables**: Set `GOOGLE_GMAIL_TOOL_CREDENTIALS` and `OBSIDIAN_ROOT` for convenience +2. **Enable Verbosity for Debugging**: Use `-vv` or `-vvv` when troubleshooting +3. **JSON Output for Scripts**: Default JSON output is ideal for automation +4. **Obsidian Integration**: Use export commands to maintain synchronized notes +5. **Pipeline with jq**: Combine with jq for powerful data processing +6. **Shell Completion**: Install completion for better CLI experience + +## Resources + +- **GitHub**: https://github.com/dnvriend/google-gmail-tool +- **Google Cloud Console**: https://console.cloud.google.com/apis/credentials +- **Gmail Search Syntax**: https://support.google.com/mail/answer/7190 +- **Obsidian**: https://obsidian.md