mxctl 0.3.0__py3-none-any.whl

mxctl/util/formatting.py

@@ -0,0 +1,52 @@
+"""Output formatting helpers."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import NoReturn
+
+
+def truncate(s: str, max_length: int) -> str:
+    """Truncate a string with ellipsis."""
+    if not s or len(s) <= max_length:
+        return s or ""
+    return s[: max_length - 3] + "..."
+
+
+def _convert_dates_with_keys(obj: object, key: str | None = None) -> object:
+    """Recursively convert AppleScript dates to ISO 8601, using key context."""
+    if isinstance(obj, dict):
+        return {k: _convert_dates_with_keys(v, k) for k, v in obj.items()}
+    elif isinstance(obj, list):
+        return [_convert_dates_with_keys(item, key) for item in obj]
+    elif isinstance(obj, str) and key and "date" in key.lower():
+        # Apply date conversion only for keys containing "date"
+        # Import here to avoid circular dependency
+        from mxctl.util.dates import parse_applescript_date
+
+        return parse_applescript_date(obj)
+    else:
+        return obj
+
+
+def output(text: str, *, json_data: object = None, use_json: bool = False) -> None:
+    """Print text output, or JSON if --json was passed."""
+    if use_json and json_data is not None:
+        # Convert AppleScript dates to ISO 8601 before serializing
+        converted_data = _convert_dates_with_keys(json_data)
+        print(json.dumps(converted_data, indent=2, default=str))
+    else:
+        print(text)
+
+
+def format_output(args: object, text: str, *, json_data: object = None) -> None:
+    """Extract use_json from args and call output(). DRY wrapper for commands."""
+    use_json = getattr(args, "json", False)
+    output(text, json_data=json_data, use_json=use_json)
+
+
+def die(msg: str, code: int = 1) -> NoReturn:
+    """Print error and exit."""
+    print(f"Error: {msg}", file=sys.stderr)
+    sys.exit(code)

mxctl/util/mail_helpers.py

@@ -0,0 +1,192 @@
+"""Shared helper functions for mail commands to eliminate code duplication."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from argparse import Namespace
+from email.utils import parseaddr
+
+from mxctl.config import CONFIG_FILE, DEFAULT_MAILBOX, get_gmail_accounts, resolve_account
+from mxctl.util.applescript import escape
+from mxctl.util.formatting import die
+
+# Friendly name → Gmail IMAP folder name
+GMAIL_MAILBOX_MAP: dict[str, str] = {
+    "trash": "[Gmail]/Trash",
+    "spam": "[Gmail]/Spam",
+    "junk": "[Gmail]/Spam",
+    "sent": "[Gmail]/Sent Mail",
+    "sent messages": "[Gmail]/Sent Mail",
+    "archive": "[Gmail]/All Mail",
+    "all mail": "[Gmail]/All Mail",
+    "drafts": "[Gmail]/Drafts",
+    "starred": "[Gmail]/Starred",
+    "important": "[Gmail]/Important",
+}
+
+
+def resolve_mailbox(account: str, mailbox: str) -> str:
+    """Translate friendly mailbox names to Gmail IMAP names when applicable.
+
+    If the account is configured as a Gmail account and the mailbox name
+    matches a known alias, returns the correct [Gmail]/... folder name.
+    Otherwise returns the mailbox unchanged.
+
+    Examples:
+        resolve_mailbox("ASU Gmail", "Spam")   -> "[Gmail]/Spam"
+        resolve_mailbox("ASU Gmail", "Trash")  -> "[Gmail]/Trash"
+        resolve_mailbox("iCloud", "Trash")     -> "Trash"
+        resolve_mailbox("ASU Gmail", "[Gmail]/Spam") -> "[Gmail]/Spam"  (passthrough)
+        resolve_mailbox("ASU Gmail", "INBOX")  -> "INBOX"  (passthrough)
+    """
+    if account not in get_gmail_accounts():
+        return mailbox
+    # Already a [Gmail]/... path or INBOX — pass through unchanged
+    if mailbox.startswith("[Gmail]/") or mailbox.upper() == "INBOX":
+        return mailbox
+    return GMAIL_MAILBOX_MAP.get(mailbox.lower(), mailbox)
+
+
+def resolve_message_context(args: Namespace) -> tuple[str, str, str, str]:
+    """Resolve and escape account/mailbox from args.
+
+    Returns tuple: (account, mailbox, acct_escaped, mb_escaped)
+    Dies if account is not set.
+    """
+    account = resolve_account(getattr(args, "account", None))
+    if not account:
+        if not os.path.isfile(CONFIG_FILE):
+            die("No account configured. Run `mxctl init` to get started.")
+        else:
+            die("No default account set. Run `mxctl init` to configure one, or use -a ACCOUNT.")
+    if not os.path.isfile(CONFIG_FILE):
+        print(f"Note: No config file found. Using last-used account '{account}'. Run `mxctl init` to create a config.", file=sys.stderr)
+    mailbox = getattr(args, "mailbox", None) or DEFAULT_MAILBOX
+    mailbox = resolve_mailbox(account, mailbox)
+
+    acct_escaped = escape(account)
+    mb_escaped = escape(mailbox)
+
+    return account, mailbox, acct_escaped, mb_escaped
+
+
+def parse_email_headers(raw: str) -> dict[str, str | list[str]]:
+    """Parse raw email headers into a dict (multi-value keys become lists)."""
+    headers: dict[str, str | list[str]] = {}
+    current_key: str | None = None
+    for line in raw.split("\n"):
+        if ": " in line and not line.startswith(" ") and not line.startswith("\t"):
+            key, _, val = line.partition(": ")
+            current_key = key
+            if key in headers:
+                if isinstance(headers[key], list):
+                    headers[key].append(val)
+                else:
+                    headers[key] = [headers[key], val]
+            else:
+                headers[key] = val
+        elif current_key and (line.startswith(" ") or line.startswith("\t")):
+            if isinstance(headers[current_key], list):
+                headers[current_key][-1] += " " + line.strip()
+            else:
+                headers[current_key] += " " + line.strip()
+    return headers
+
+
+def extract_email(sender_str: str) -> str:
+    """Extract email address from sender string.
+
+    Examples:
+        "John Doe <john@example.com>" -> "john@example.com"
+        "jane@example.com" -> "jane@example.com"
+        "<admin@site.org>" -> "admin@site.org"
+    """
+    _, email = parseaddr(sender_str)
+    return email if email else sender_str
+
+
+def extract_display_name(sender: str) -> str:
+    """Extract the display name from a sender string.
+
+    Examples:
+        '"John Doe" <john@example.com>' -> 'John Doe'
+        'John Doe <john@example.com>'   -> 'John Doe'
+        'jane@example.com'              -> 'jane@example.com'
+    """
+    if "<" in sender:
+        return sender.split("<")[0].strip().strip('"')
+    return sender
+
+
+def parse_message_line(
+    line: str,
+    fields: list[str],
+    separator: str,
+) -> dict | None:
+    """Parse a single FIELD_SEPARATOR-delimited AppleScript output line into a dict.
+
+    Args:
+        line: A single raw output line from AppleScript.
+        fields: Ordered list of field names corresponding to each split part.
+            The last field name absorbs all remaining parts (useful when a field
+            like 'body' or 'content' may itself contain the separator).
+        separator: The field separator string (typically FIELD_SEPARATOR).
+
+    Returns:
+        A dict mapping field names to string values, or None if the line has
+        fewer parts than required (i.e. len(fields) fields).
+
+    Special coercions applied automatically:
+        - Fields named 'id' or ending in '_id': coerced to int when the value
+          is a digit string, otherwise kept as-is.
+        - Fields named 'read', 'flagged', 'junk', 'deleted', 'forwarded',
+          'replied': coerced to bool (True when value lower() == 'true').
+
+    Example::
+        parse_message_line(line, ["id", "subject", "sender", "date"], SEP)
+        # -> {"id": 42, "subject": "Hello", "sender": "...", "date": "..."}
+    """
+    parts = line.split(separator)
+    if len(parts) < len(fields):
+        return None
+
+    _BOOL_FIELDS = {"read", "flagged", "junk", "deleted", "forwarded", "replied"}
+    result: dict = {}
+    for i, name in enumerate(fields):
+        if i == len(fields) - 1:
+            # Last field absorbs remaining parts
+            raw = separator.join(parts[i:])
+        else:
+            raw = parts[i]
+
+        if name == "id" or name.endswith("_id"):
+            result[name] = int(raw) if raw.isdigit() else raw
+        elif name in _BOOL_FIELDS:
+            result[name] = raw.lower() == "true"
+        else:
+            result[name] = raw
+
+    return result
+
+
+def normalize_subject(subject: str) -> str:
+    """Normalize email subject by removing Re:/Fwd:/Fw:/AW:/SV:/VS: prefixes.
+
+    Handles international reply prefixes:
+    - Re: (English/most languages)
+    - Fwd/Fw: (English forward)
+    - AW: (German - Antwort)
+    - SV: (Swedish/Norwegian - Svar)
+    - VS: (Finnish - Vastaus)
+
+    Handles multiple nested prefixes like "Re: Re: Fwd: Original Subject".
+    """
+    # Loop to handle multiple nested prefixes
+    while True:
+        normalized = re.sub(r'^(Re|Fwd|Fw|AW|SV|VS):\s*', '', subject, flags=re.IGNORECASE).strip()
+        if normalized == subject:
+            break
+        subject = normalized
+    return subject

mxctl-0.3.0.dist-info/METADATA

@@ -0,0 +1,439 @@
+Metadata-Version: 2.4
+Name: mxctl
+Version: 0.3.0
+Summary: Apple Mail from your terminal
+Project-URL: Homepage, https://github.com/Jscoats/mxctl
+Project-URL: Repository, https://github.com/Jscoats/mxctl
+Project-URL: Issues, https://github.com/Jscoats/mxctl/issues
+Project-URL: Changelog, https://github.com/Jscoats/mxctl/blob/main/CHANGELOG.md
+Author: Jscoats
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apple-mail,applescript,cli,email,macos,productivity,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mxctl
+
+[![CI](https://github.com/Jscoats/mxctl/actions/workflows/ci.yml/badge.svg)](https://github.com/Jscoats/mxctl/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![Coverage: 87%](https://img.shields.io/badge/coverage-87%25-yellowgreen.svg)](https://github.com/Jscoats/mxctl)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+> Apple Mail from your terminal.
+
+**49 commands.** Triage with AI, batch-process newsletters, turn emails into Todoist tasks — all from the terminal. Every command supports `--json` for scripting and AI workflows. Zero external dependencies.
+
+<p align="center">
+  <img src="demo/demo.gif" alt="mxctl demo — inbox, triage, summary, and batch operations" width="700">
+</p>
+
+## Table of Contents
+
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Example Output](#example-output)
+- [Command Categories](#command-categories)
+- [Requirements](#requirements)
+- [Usage Tips](#usage-tips)
+- [Built for AI Workflows](#built-for-ai-workflows)
+- [AI Demos](#ai-demos)
+- [Architecture](#architecture)
+- [Why Not X?](#why-not-x)
+- [Contributing](#contributing)
+
+## Key Features
+
+- **49 Commands** - Everything from basic operations to advanced batch processing
+- **Any Account, One Interface** - iCloud, Gmail, Outlook, Exchange, IMAP -- whatever Mail.app has, this works with
+- **Gmail Mailbox Translation** - Automatically maps standard names (`Trash`, `Spam`, `Sent`) to Gmail's `[Gmail]/...` paths
+- **Built for AI Workflows** - Every command supports `--json` output designed for AI assistants to read and act on
+- **Todoist Integration** - Turn any email into a task with `mxctl to-todoist` (project, priority, due date)
+- **Batch Operations with Undo** - Process hundreds of emails safely with rollback support
+- **Zero Dependencies** - Pure Python stdlib, no external packages required
+- **Works with Your Existing Setup** - Doesn't replace Mail.app, extends it
+
+## Installation
+
+```bash
+# Requires Python 3.10+ and macOS
+pip install git+https://github.com/Jscoats/mxctl
+
+# Or with uv (faster)
+uv tool install git+https://github.com/Jscoats/mxctl
+```
+
+Then run the setup wizard — it detects your Mail.app accounts, configures Gmail mailbox translation, and optionally connects Todoist:
+
+<p align="center">
+  <img src="demo/init-demo.gif" alt="mxctl init — setup wizard detecting accounts, configuring Gmail, and connecting Todoist" width="700">
+</p>
+
+## Quick Start
+
+```bash
+# First time? Set up your default account
+mxctl init
+
+# See what's in your inbox
+mxctl inbox
+
+# Smart summary of unread emails (concise, one-liner per email)
+mxctl summary
+
+# Triage unread emails by urgency
+mxctl triage
+
+# Search for messages
+mxctl search "project update" --sender
+
+# Mark all unread as read (with undo support!)
+mxctl batch-read -m INBOX
+
+# Oops, undo that
+mxctl undo
+
+# Create email from template
+mxctl draft --to colleague@company.com --template "weekly-update"
+
+# Send email to Todoist as a task
+mxctl to-todoist 123 --project Work
+```
+
+## Example Output
+
+### `mxctl inbox`
+```
+Inbox Overview
+------------------------------------------
+  iCloud             3 unread   (47 total)
+  Work Email         12 unread  (203 total)
+  Johnny.Coats84@gmail.com  0 unread  (18 total)
+------------------------------------------
+  Total              15 unread
+```
+
+### `mxctl triage`
+```
+Triage -- 15 Unread Messages
+==========================================
+
+[URGENT -- 2]
+  #4821  Sarah Johnson       Re: Contract review deadline TODAY
+  #4819  boss@company.com    Q4 budget approval needed
+
+[PEOPLE -- 5]
+  #4820  mom@gmail.com       Thanksgiving plans?
+  #4818  john.smith@work.com Project kickoff Thursday?
+  #4817  recruiter@corp.com  Opportunity at TechCorp
+  #4815  friend@gmail.com    Weekend hiking trip
+  #4814  alice@work.com      Coffee catch-up?
+
+[NOTIFICATIONS -- 8]
+  #4816  GitHub              [mxctl] PR #12 merged
+  #4813  noreply@bank.com    Statement available
+  ... and 6 more
+```
+
+### `mxctl summary`
+```
+15 unread -- iCloud + Work Email
+
+* Contract review deadline TODAY -- Sarah Johnson (urgent, reply needed)
+* Q4 budget approval -- boss@company.com (action required)
+* Thanksgiving plans -- mom@gmail.com (personal, low urgency)
+* Project kickoff Thursday -- john.smith@work.com (confirm attendance)
+* PR #12 merged -- GitHub notification (no action needed)
+* 10 more notifications and newsletters
+```
+
+## Command Categories
+
+### Setup
+- `init` - First-time setup wizard (auto-detects Mail accounts, configures default account and optional Todoist token)
+
+### Account & Mailbox Management
+- `inbox` - Overview of all accounts with unread counts
+- `accounts` - List all mail accounts
+- `mailboxes` - List mailboxes in an account
+- `create-mailbox`, `delete-mailbox` - Manage folders
+- `count` - Unread message count (for scripting and status bars)
+- `empty-trash` - Empty trash with confirmation dialog
+
+### Message Operations
+- `list` - List messages with filters (unread, date range)
+- `read` - Display full message
+- `search` - Find messages by subject/sender
+- `mark-read`, `mark-unread`, `flag`, `unflag` - Message actions
+- `move`, `delete` - Organize messages
+- `junk`, `not-junk` - Mark as spam / restore from spam (moves to INBOX)
+- `open` - Open message in Mail.app GUI
+- `unsubscribe` - Unsubscribe from mailing lists via List-Unsubscribe header (supports one-click RFC 8058)
+- `attachments`, `save-attachment` - Handle attachments
+
+### AI-Ready Features
+- `summary` - Ultra-concise summaries optimized for AI assistants
+- `triage` - Smart categorization by urgency (flagged -> people -> notifications)
+- `context` - Thread messages with parent/child relationships
+- `find-related` - Discover similar messages
+- `process-inbox` - Diagnostic inbox categorization
+
+### Batch Operations
+- `batch-read` - Mark all unread as read
+- `batch-flag` - Flag all from sender
+- `batch-move` - Move messages by sender
+- `batch-delete` - Delete messages by sender and/or age
+- `undo`, `undo --list` - Rollback batch operations
+
+### Analytics & Tools
+- `stats` - Message statistics for timeframe
+- `top-senders` - Most frequent senders
+- `digest` - Grouped unread summary
+- `show-flagged` - List flagged messages
+- `weekly-review` - Past 7 days summary
+- `clean-newsletters` - Archive/delete newsletter subscriptions
+
+### System
+- `check` - Trigger Mail.app to fetch new mail
+- `headers` - Full email header analysis (SPF, DKIM, DMARC, hop count, return path)
+- `rules` - List, enable, or disable mail rules
+
+### Compose & Templates
+- `draft` - Create email draft (supports templates)
+- `templates list/create/show/delete` - Manage email templates
+- `reply`, `forward` - Create response drafts
+- `thread` - Show full conversation thread for a message
+
+### Integrations
+- `to-todoist` - Send email to Todoist as task
+- `export` - Export messages as markdown (use `--to` for destination path/directory)
+
+## Requirements
+
+- **macOS 12 or later** (uses AppleScript to communicate with Mail.app)
+- **Python 3.10+**
+- **Mail.app** with at least one configured account
+- **Permissions:** First run will prompt for Mail.app automation permission in System Settings
+- **Note:** Mail.app will be launched automatically if it is not already running -- this is normal macOS/AppleScript behavior
+
+## Usage Tips
+
+### Multi-Account Support
+
+Works with any combination of iCloud, Gmail, Outlook, Exchange, or custom IMAP accounts -- whatever you have configured in Mail.app.
+
+```bash
+# Commands default to your primary account (set during init)
+mxctl list
+
+# Switch accounts with -a
+mxctl list -a "Work Email"
+mxctl list -a "Personal"
+
+# Commands like inbox, summary, and triage scan ALL accounts automatically
+mxctl inbox
+```
+
+**Three-tier account resolution:** Commands use the first available: (1) explicit `-a` flag, (2) default account from config, (3) last-used account from state.
+
+### Gmail Mailbox Translation
+
+Gmail uses non-standard mailbox names (`[Gmail]/Spam` instead of `Junk`, `[Gmail]/Sent Mail` instead of `Sent Messages`, etc.). If you tag your Gmail accounts during `mxctl init`, the CLI auto-translates standard names so you don't have to remember Gmail's conventions.
+
+```bash
+# These just work -- no need to type [Gmail]/... paths
+mxctl list -a "Work Gmail" -m Trash     # -> [Gmail]/Trash
+mxctl list -a "Work Gmail" -m Spam      # -> [Gmail]/Spam
+mxctl list -a "Work Gmail" -m Sent      # -> [Gmail]/Sent Mail
+mxctl list -a "Work Gmail" -m Archive   # -> [Gmail]/All Mail
+
+# iCloud and other accounts pass through unchanged
+mxctl list -a "iCloud" -m Trash         # -> Trash (no translation)
+```
+
+Supported translations: `Trash`, `Spam`/`Junk`, `Sent`/`Sent Messages`, `Archive`/`All Mail`, `Drafts`, `Starred`, `Important`.
+
+### Todoist Integration
+
+Turn any email into a Todoist task without leaving the terminal. The task includes the email subject, sender, and a link back to the message.
+
+```bash
+# Set up during init, or add manually to ~/.config/mxctl/config.json
+mxctl init  # step 3 prompts for your Todoist API token
+
+# Send an email to Todoist
+mxctl to-todoist 123
+
+# With project and priority
+mxctl to-todoist 123 --project "Work" --priority 3
+
+# With a due date (natural language)
+mxctl to-todoist 123 --due "next Monday"
+```
+
+To get your token: [Todoist Settings -> Integrations -> Developer](https://todoist.com/prefs/integrations)
+
+### Short Message Aliases
+
+Listing commands assign short numbers starting from `[1]` -- no more copying 5-digit IDs:
+
+```bash
+mxctl list                    # Shows [1], [2], [3]...
+mxctl read 1                  # Read message [1]
+mxctl flag 2                  # Flag message [2]
+mxctl move 3 --to Archive     # Move message [3]
+```
+
+Aliases update each time you run a listing command (`list`, `inbox`, `search`, `triage`, `summary`, etc.). Full message IDs still work if you prefer them. JSON output includes both `id` (real) and `alias` (short number).
+
+### JSON Output for Automation
+```bash
+# Every command supports --json
+mxctl inbox --json | jq '.accounts[0].unread_count'
+mxctl search "invoice" --json | jq '.[].subject'
+```
+
+### Export Messages
+```bash
+# Export a single message
+mxctl export 123 --to ~/Documents/mail/ -a "iCloud"
+
+# Bulk export all messages in a mailbox
+mxctl export "Work" --to ~/Documents/mail/ -a "Work Email"
+
+# Bulk export messages after a date
+mxctl export "INBOX" --to ~/Documents/mail/ -a "iCloud" --after 2026-01-01
+```
+
+Note: The destination flag is `--to` (not `--dest`).
+
+### Email Templates
+```bash
+# Create a template
+mxctl templates create "meeting-followup" \
+  --subject "Re: {original_subject}" \
+  --body "Thanks for the meeting today..."
+
+# Use it
+mxctl draft --to client@company.com --template "meeting-followup"
+```
+
+## Built for AI Workflows
+
+Every command supports `--json`, making your inbox data available to any AI assistant. Commands like `summary`, `triage`, and `context` are specifically designed to give AI a structured understanding of your inbox in seconds.
+
+### With Claude Code
+```bash
+# Just ask Claude to check your mail
+"Run mxctl triage and tell me what's urgent"
+"Summarize my unread mail and create Todoist tasks for anything that needs action"
+```
+
+### With any AI tool
+```bash
+# Pipe structured data to any LLM CLI
+mxctl summary --json | llm "What needs my attention?"
+
+# Feed triage results to AI for prioritization
+mxctl triage --json | llm "Draft responses for the urgent items"
+```
+
+### For scripting and automation
+```bash
+# Unread count for your status bar
+mxctl count
+
+# Export to JSON for any workflow
+mxctl inbox --json | jq '.accounts[].unread_count'
+```
+
+The CLI is the bridge between Mail.app and whatever tools you use -- AI, scripts, or both.
+
+## AI Demos
+
+These demos show how an AI assistant (like Claude Code) uses mxctl to manage your inbox conversationally. You say what you want in plain English, and the AI picks the right commands, checks before acting, and reports back.
+
+### Inbox triage and drafting
+
+The AI triages your inbox, marks newsletters as read, flags important messages for follow-up, and drafts a reply to your mom -- all from a single request.
+
+<p align="center">
+  <img src="demo/ai-demo.gif" alt="AI assistant triaging inbox, flagging messages, and drafting a reply" width="700">
+</p>
+
+### Bulk sender cleanup
+
+The AI finds your noisiest senders, dry-runs the deletes so you can see what would be removed, then cleans up 60 marketing emails in seconds. Everything is undoable with `mxctl undo`.
+
+<p align="center">
+  <img src="demo/batch-delete-demo.gif" alt="AI assistant finding top spammy senders and batch-deleting 60 messages" width="700">
+</p>
+
+### Newsletter unsubscribe
+
+The AI analyzes which newsletters you actually read vs. ignore, then unsubscribes from the ones with 0% open rate while leaving the ones you engage with. One-click unsubscribe when the header supports it, browser fallback when it doesn't.
+
+<p align="center">
+  <img src="demo/unsubscribe-demo.gif" alt="AI assistant analyzing newsletter read rates and unsubscribing from unread ones" width="700">
+</p>
+
+## Architecture
+
+Built with modern Python patterns:
+- **Zero runtime dependencies** (stdlib only)
+- **Comprehensive test suite** (422 tests)
+- **Modular command structure** (16 focused modules)
+- **AppleScript bridge** for Mail.app communication
+- **Three-tier account resolution** (explicit flag -> config default -> last-used)
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture documentation.
+
+## Why Not X?
+
+**Why not mutt or neomutt?**
+Mutt replaces Mail.app -- you lose native macOS notifications, calendar event detection, FaceTime/iMessage continuity, and Rules. This CLI *extends* Mail.app rather than replacing it: your mail is still managed natively, but now also scriptable from the terminal.
+
+**Why not the Gmail API or Outlook API?**
+Those are per-provider -- separate SDKs, separate auth flows, separate data models. `mxctl` works with any account configured in Mail.app (iCloud, Gmail, Outlook, Exchange, custom IMAP) through a single unified interface. Add a new account to Mail.app and it just works.
+
+**Why not raw AppleScript or Hammerspoon?**
+You could wire this up yourself -- but this gives you 49 structured commands with `--json` output, batch operations with undo, template support, Todoist integration, and an AI-ready interface, all without writing a single line of AppleScript. The hard parts (field parsing, timeout handling, account resolution, error recovery) are already done.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+Built to automate email workflows without leaving the terminal.
+
+## Contact
+
+- **GitHub:** [@Jscoats](https://github.com/Jscoats)
+- **Issues:** [Report bugs or request features](https://github.com/Jscoats/mxctl/issues)
+
+---
+
+**Like this project?** Star it on GitHub and share it with fellow terminal enthusiasts!