gmail-cli: Cross-Platform Email from the Command Line

A zero-dependency Python tool that lets you send emails from the command line using Gmail SMTP. Install with a single command, configure once, and send emails from scripts, automation workflows, or AI agents.

The Problem

Sending emails from the command line has traditionally been painful:

• Complex setup: Configuring sendmail, postfix, or msmtp requires system-level changes
• Deliverability issues: Self-hosted mail servers often land in spam folders
• Platform fragmentation: Different tools for different operating systems
• Dependency hell: Many solutions require installing additional libraries

I needed a simple way to send emails from automation scripts, AI agents, and CI/CD pipelines without wrestling with mail server configuration. Gmail's SMTP servers have excellent deliverability, and App Passwords provide secure authentication without exposing your main account password.

The Solution

gmail-cli is a single Python file with zero external dependencies that works on any system with Python 3. It uses Gmail's SMTP servers for reliable delivery and stores credentials securely in your home directory.

One-Line Installation

macOS / Linux

curl -sSL https://colinknapp.com/tools/gmail-cli/install.sh | bash

Windows PowerShell

iwr -useb https://colinknapp.com/tools/gmail-cli/install.ps1 | iex

The installer downloads the script to ~/.local/bin (Unix) or %LOCALAPPDATA%\gmail-cli (Windows) and adds it to your PATH.

Setup: Gmail App Password

Gmail requires an App Password for SMTP access (your regular password won't work with 2FA enabled). Here's how to set one up:

1. Go to myaccount.google.com/apppasswords
2. Enable 2-Step Verification if you haven't already
3. Generate an App Password for "Mail"
4. Run gmail-cli configure and enter your Gmail address and the App Password

gmail-cli configure

Gmail CLI Configuration
----------------------------------------

You'll need a Gmail App Password:
1. Go to https://myaccount.google.com/apppasswords
2. Enable 2-Step Verification if needed
3. Generate an App Password for 'Mail'

Gmail address: yourname@gmail.com
App Password (will be stored locally): xxxx xxxx xxxx xxxx

Configuration saved to /home/user/.config/gmail-cli/config.json

Usage Examples

Simple Email

gmail-cli send recipient@example.com -s "Hello" -b "Hi there!"

Email with Attachments

gmail-cli send recipient@example.com \
  -s "Weekly Report" \
  -b "Please find the report attached." \
  -a report.pdf \
  -a data.csv

Pipe Content from stdin

cat logfile.txt | gmail-cli send admin@example.com -s "Server Logs"

Test Connection

gmail-cli test

Testing connection for yourname@gmail.com...
Success! Connection and authentication working.

Real-World Use Case: AI Agent Email

I built this tool specifically for use with AI coding agents like Cursor. When I need to send an email with PDF attachments, the AI agent can compose and send it directly:

gmail-cli send recipient@example.com \
  -s "Documents Attached" \
  -b "Hi,

Please find the requested documents attached.

Best regards,
Your Name" \
  -a document1.pdf \
  -a document2.pdf

This enables end-to-end automation: the AI can generate documents, create PDFs, and send them via email without human intervention.

Technical Implementation

Architecture

• Single file: No dependencies beyond Python 3's standard library
• SMTP over TLS: Secure connection to smtp.gmail.com:587
• Local config: Credentials stored in ~/.config/gmail-cli/config.json with 600 permissions
• MIME support: Proper multipart messages for attachments

Security Considerations

• Uses Gmail App Passwords (not your main password)
• Config file has restricted permissions (Unix: 600)
• TLS encryption for all SMTP communication
• App Passwords can be revoked individually without affecting your main account

Cross-Platform Support

The tool handles platform differences automatically:

• macOS/Linux: Config in ~/.config/gmail-cli/, installed to ~/.local/bin/
• Windows: Config in %APPDATA%\gmail-cli\, installed to %LOCALAPPDATA%\gmail-cli\ with a .bat wrapper

Command Reference

Integration with Automation

gmail-cli works seamlessly with:

• Shell scripts: Send notifications from cron jobs or build scripts
• CI/CD pipelines: Email deployment reports or test results
• AI agents: Enable LLM-powered assistants to send emails on your behalf
• Monitoring: Alert on system events or threshold breaches

Example: Daily Backup Report

#!/bin/bash
# backup-report.sh - Run daily via cron

BACKUP_LOG="/var/log/backup.log"
RECIPIENT="admin@example.com"

if [ -f "$BACKUP_LOG" ]; then
    cat "$BACKUP_LOG" | gmail-cli send "$RECIPIENT" \
        -s "Daily Backup Report - $(date +%Y-%m-%d)"
fi

Why Not Use Existing Tools?

gmail-cli provides the simplicity of a CLI tool with the reliability of Gmail's infrastructure, wrapped in a zero-dependency package that works everywhere Python runs.

Observations

1. One-liner installs work: The curl | bash pattern, while controversial, dramatically lowers friction for developer tools
2. Gmail SMTP is reliable: Google's servers have excellent deliverability and uptime
3. App Passwords are underrated: They provide scoped access without exposing your main credentials
4. Cross-platform matters: A tool that works identically on macOS, Linux, and Windows saves documentation and support effort
5. AI agents need email: As LLM-powered automation grows, simple programmatic email becomes increasingly valuable

Get Started

Install gmail-cli and start sending emails from your terminal:

# Install (macOS/Linux)
curl -sSL https://colinknapp.com/tools/gmail-cli/install.sh | bash

# Configure
gmail-cli configure

# Send your first email
gmail-cli send yourself@gmail.com -s "Test" -b "It works!"