google-gmail-tool

Table of Contents

• About
• Use Cases
• Features
• Installation
• Shell Completion
• Configuration
• Usage
  • Authentication
• Development
• Resources
• License

About

What is google-gmail-tool?

google-gmail-tool provides programmatic access to Google services through an agent-friendly CLI. Built with modern Python tooling (uv, mise, click) and designed for both human operators and AI agents.

Supported Services:

• Gmail API - Read, send, export emails
• Google Calendar API - Full CRUD operations for events
• Google Tasks API - Complete task management
• Google Drive API - Full file and folder management (upload, download, create, rename, move, delete)

Why a CLI-First Tool?

This tool emphasizes:

• 🤖 Agent-Friendly Design: Structured commands and self-documenting help enable AI agents (like Claude Code) to discover features and self-correct when commands fail (ReAct loops)
• 🔧 Composable Architecture: JSON output to stdout, logs to stderr for easy piping and integration with automation workflows
• 🧩 Reusable Building Blocks: Commands serve as building blocks for MCP servers, Claude Code skills, shell scripts, or custom automation pipelines
• 📦 Dual-Mode Operation: Use as a CLI tool or import as a Python library for programmatic access
• ✅ Production Quality: Type-safe (mypy strict), comprehensive error handling, tested, and documented

Use Cases

• 📚 Knowledge Base Management: Export Gmail threads and Calendar events to markdown for Obsidian vaults
• 💻 Source Code Intelligence: Archive project communications and documentation to version control
• 🔍 Semantic Search: Build RAG systems with email and calendar data
• 🎯 Automation: Create workflows for email processing, calendar sync, and file management
• 🤖 AI Agent Integration: Provide Google API access to AI assistants and automation agents

Features

• ✅ OAuth2 Authentication: Secure credential management via environment variables
• ✅ API Access Verification: Test Gmail, Calendar, Tasks, and Drive permissions with visual feedback (✓/✗)
• ✅ Agent-Friendly CLI: Self-documenting help with inline examples for discovery and self-correction
• ✅ Drive Operations: Full CRUD support - upload, download, create, rename, move, delete files and folders
• ✅ Parallel Uploads: Multi-threaded folder uploads with progress bars (tqdm)
• ✅ Safety First: Duplicate detection, trash by default, confirmation prompts with force flags
• ✅ Type-Safe: Strict mypy checking for reliability
• ✅ Production Ready: Comprehensive error handling with actionable messages
• ✅ Modern Tooling: Built with uv, mise, and click

Installation

Prerequisites

• Python 3.14 or higher
• uv package manager
• Google Cloud Project with OAuth 2.0 credentials

Install from source

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

# Install globally with uv
uv tool install .

Install with mise (recommended for development)

cd google-gmail-tool
mise trust
mise install
uv sync
uv tool install .

Verify installation

google-gmail-tool --version
google-gmail-tool --help

Shell Completion

Enable tab completion for all commands, options, and arguments in your shell.

Supported Shells

• Bash (≥4.4)
• Zsh
• Fish

Installation

Bash (add to ~/.bashrc or ~/.bash_profile):

eval "$(google-gmail-tool completion bash)"

Zsh (add to ~/.zshrc):

eval "$(google-gmail-tool completion zsh)"