From 48ad2b16fceeda83483e5e7b6e40ffe78b25fbcc Mon Sep 17 00:00:00 2001
From: Alexander Payne <alex@alexanderwhitestone.com>
Date: Sun, 26 Apr 2026 22:15:44 -0400
Subject: [PATCH] [EMAIL-6] Configure himalaya CLI on Mac for terminal email

Add himalaya configuration template and Hermes .env email variables.

- Add config/himalaya/config.toml.example with IMAP/SMTP settings
- Add EMAIL_* environment variables to .env.example for agent access
- Provides template for Gmail and generic providers
- Enables himalaya envelope list and message send workflows

Closes #321
---
 .env.example                        | 27 ++++++++++++++++
 config/himalaya/config.toml.example | 48 +++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 .env.example
 create mode 100644 config/himalaya/config.toml.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 00000000..73a81dce
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,27 @@
+# Hermes Agent Environment Variables
+# Copy to ~/.hermes/.env and configure for your environment.
+
+# =============================================================================
+# Email Configuration (Himalaya CLI + Agent Email Access)
+# =============================================================================
+# These variables allow Hermes agents to access email via the configured
+# IMAP/SMTP server. They mirror the credentials used in ~/.config/himalaya/config.toml
+
+# IMAP Settings
+EMAIL_IMAP_HOST=imap.example.com
+EMAIL_IMAP_PORT=993
+EMAIL_IMAP_USERNAME=YOUR_EMAIL@example.com
+EMAIL_IMAP_PASSWORD=APP_PASSWORD
+EMAIL_IMAP_SSL=true
+
+# SMTP Settings
+EMAIL_SMTP_HOST=smtp.example.com
+EMAIL_SMTP_PORT=587
+EMAIL_SMTP_USERNAME=YOUR_EMAIL@example.com
+EMAIL_SMTP_PASSWORD=APP_PASSWORD
+EMAIL_SMTP_STARTTLS=true
+
+# Default From address (must match SMTP username)
+EMAIL_FROM=YOUR_EMAIL@example.com
+# Default mailbox to poll
+EMAIL_MAILBOX=INBOX
diff --git a/config/himalaya/config.toml.example b/config/himalaya/config.toml.example
new file mode 100644
index 00000000..de70e8c6
--- /dev/null
+++ b/config/himalaya/config.toml.example
@@ -0,0 +1,48 @@
+# Himalaya Email Client Configuration Template
+# Copy to ~/.config/himalaya/config.toml and fill in real values.
+# See: https://github.com/soywod/himalaya
+
+[default]
+# Default sender address (must match SMTP username)
+from = "YOUR_EMAIL@example.com"
+# Default mailbox to check
+mailbox = "INBOX"
+
+[imap]
+# IMAP server host (e.g., imap.gmail.com, imap.fastmail.com, outlook.office365.com)
+host = "imap.example.com"
+# IMAP port (993 for SSL/TLS, 143 for STARTTLS)
+port = 993
+# IMAP username (usually full email address)
+username = "YOUR_EMAIL@example.com"
+# App-specific password recommended (not your main account password)
+password = "YOUR_APP_PASSWORD"
+# Use SSL/TLS (true for port 993, false for STARTTLS)
+ssl = true
+
+[smtp]
+# SMTP server host (e.g., smtp.gmail.com, smtp.fastmail.com, smtp.office365.com)
+host = "smtp.example.com"
+# SMTP port (587 for STARTTLS, 465 for SSL/TLS)
+port = 587
+# SMTP username (usually full email address)
+username = "YOUR_EMAIL@example.com"
+# App-specific password
+password = "YOUR_APP_PASSWORD"
+# Use STARTTLS (true for port 587)
+starttls = true
+
+[imap.gmail]
+# Example Gmail config (uncomment to use)
+# host = "imap.gmail.com"
+# port = 993
+# username = "your.email@gmail.com"
+# password = "APP_PASSWORD"
+# ssl = true
+
+[smtp.gmail]
+# host = "smtp.gmail.com"
+# port = 587
+# username = "your.email@gmail.com"
+# password = "APP_PASSWORD"
+# starttls = true