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

Input Validation

The secure implementation (gmail-cli-secure.py) validates all inputs:

• ✅ Email addresses checked against RFC 5322 format
• ✅ File paths validated to prevent path traversal
• ✅ Sensitive files blocked from attachments
• ✅ Text fields sanitized to prevent injection attacks

Safe Usage Example

# ✅ SAFE: Properly quoted and validated
EMAIL="user@example.com"
SUBJECT="Monthly Report"
BODY="Please review"
FILE="/path/to/document.pdf"

# Validate before using
[[ -f "$FILE" ]] || exit 1

./.codebuddy/bin/gmail-cli-wrapper send --to "$EMAIL" --subject "$SUBJECT" \
    --body "$BODY" --attach "$FILE"

❌ Unsafe Practices

# DON'T DO THIS: Never use untrusted input directly
read -p "Enter recipient: " RECIPIENT
./.codebuddy/bin/gmail-cli-wrapper send --to "$RECIPIENT" --subject "Test"

# DON'T DO THIS: Sending sensitive files
./.codebuddy/bin/gmail-cli-wrapper send --to "user@example.com" \
    --subject "Keys" --attach ~/.ssh/id_rsa  # ❌ DANGER!

Notes

• OAuth2 Required: You must complete OAuth2 authentication before using the tool
• Google Account Access: Requires a Google account with Gmail enabled
• API Permissions: Recommended scopes: gmail.readonly + gmail.send (NOT gmail.modify)
• Rate Limits: Subject to Gmail API rate limits (usually sufficient for normal use)
• Security: Tokens are stored locally in ~/.gmail-cli/; must have 600 permissions
• First Time Setup: Setup requires creating a Google Cloud project and OAuth2 credentials (see SETUP.md)
• Token Rotation: Revoke tokens every 30-90 days or after device loss
• Shared Systems: Extra caution on shared computers - use restrictive permissions!

Troubleshooting

• Authentication fails: Try ./.codebuddy/bin/gmail-cli-wrapper auth --reset to re-authenticate
• Package errors: Install packages with pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib
• Credentials not found: Make sure ~/.gmail-cli/credentials.json exists (see SETUP.md)
• Permission denied: Ensure the wrapper has execute permissions: chmod +x ./.codebuddy/bin/gmail-cli-wrapper

📚 Documentation

• SECURITY.md - 🔒 READ THIS FIRST - Comprehensive security guide
• SETUP.md - Detailed setup instructions with Google Cloud Console configuration
• README.md - Quick start guide and feature overview
• gmail-cli-secure.py - Reference implementation with input validation
• email/skill.md - Alternative SMTP-based email sending (simpler but less features)

🛡️ Security Checklist

Before using Gmail CLI, verify:

• Installed using install.sh script (virtual environment + security audit)
• ~/.gmail-cli/ has 700 permissions
• credentials.json has 600 permissions
• token.pickle has 600 permissions
• .gitignore configured to exclude sensitive files
• Using minimal OAuth2 scopes (readonly + send, NOT modify)
• Read SECURITY.md for best practices
• Understand how to revoke tokens if compromised