Table of Contents
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:
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
Installation
Bash (add to ~/.bashrc or ~/.bash_profile):
eval "$(google-gmail-tool completion bash)"
Zsh (add to ~/.zshrc):
eval "$(google-gmail-tool completion zsh)"
