Gmail

gmail-cli

Use ./.codebuddy/bin/gmail-cli-wrapper to interact with Gmail. This tool allows you to read, send, and manage Gmail messages directly from the chat.

Note: The wrapper script ensures commands run within an isolated Python virtual environment for security.

⚠️ Security Warning

CRITICAL: This tool accesses your Gmail account. Follow security best practices:

• ✅ ALWAYS set file permissions: chmod 700 ~/.gmail-cli && chmod 600 ~/.gmail-cli/*
• ✅ NEVER commit credentials.json or token.pickle to git
• ✅ Use the secure installation script: bash .codebuddy/skills/gmail/install.sh
• ✅ Review SECURITY.md for comprehensive security guidance
• ⚠️ Extra caution on shared systems - other users may access your credentials if permissions are wrong!

Setup

Recommended: Use the secure installation script:

cd .codebuddy/skills/gmail
bash install.sh

This script will:

• Create isolated Python virtual environment
• Install dependencies with security audit
• Set secure file permissions (700/600)
• Guide you through OAuth2 setup

Manual Setup (if needed):

Before using, you must authenticate with Google OAuth2. Run the following command in the terminal:

./.codebuddy/bin/gmail-cli-wrapper auth

This will:

1. Open a browser window for Google OAuth2 authentication
2. Request permissions to access your Gmail account
3. Store credentials locally for future use

Important: You need to set up OAuth2 credentials first. See SETUP.md for detailed instructions.

Common Commands

Authentication

• Authenticate: ./.codebuddy/bin/gmail-cli-wrapper auth
• Reset authentication: ./.codebuddy/bin/gmail-cli-wrapper auth --reset

Reading Emails

• List recent emails: ./.codebuddy/bin/gmail-cli-wrapper list --max 10
• List unread emails: ./.codebuddy/bin/gmail-cli-wrapper list --unread
• Search emails: ./.codebuddy/bin/gmail-cli-wrapper list --query "subject:meeting"
• Read specific email: ./.codebuddy/bin/gmail-cli-wrapper read <message-id>

Sending Emails

• Send email: ./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" --subject "Hello" --body "Message text"
• Send with CC: ./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" --cc "other@example.com" --subject "Hello" --body "Message"
• Send with attachment: ./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" --subject "Files" --body "See attached" --attach /path/to/file.pdf
• Multiple attachments: ./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" --subject "Files" --body "Documents" --attach file1.pdf file2.docx

Search Query Examples

Gmail CLI supports advanced search queries similar to Gmail's web interface:

• "from:john@example.com" - Emails from a specific sender
• "subject:invoice" - Emails with "invoice" in subject
• "has:attachment" - Emails with attachments
• "is:unread" - Unread emails
• "after:2024/01/01" - Emails after a specific date
• "to:me cc:boss@company.com" - Emails to you with CC to boss
• "newer_than:2d" - Emails from last 2 days

Example:

./.codebuddy/bin/gmail-cli-wrapper list --query "from:client@company.com subject:invoice has:attachment"

Configuration

Configuration and credentials are stored in:

• ~/.gmail-cli/credentials.json - OAuth2 credentials (from Google Cloud Console)
• ~/.gmail-cli/token.pickle - Access token (auto-generated and auto-refreshed)

Prerequisites

Before using this tool, you need to:

1. Install Python 3.7+
2. Install required packages: pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib
3. Set up OAuth2 credentials from Google Cloud Console (see SETUP.md)

🔒 Security Best Practices

File Permissions (MANDATORY)

# Secure the credential directory
chmod 700 ~/.gmail-cli

# Secure credential files
chmod 600 ~/.gmail-cli/credentials.json
chmod 600 ~/.gmail-cli/token.pickle

# Verify permissions
ls -la ~/.gmail-cli/
# Should show: drwx------ for directory, -rw------- for files