mxctl 0.3.0__tar.gz → 0.4.1__tar.gz

{mxctl-0.3.0 → mxctl-0.4.1}/.github/workflows/ci.yml

@@ -10,8 +10,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
       - run: pip install ruff
@@ -23,8 +23,8 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - run: pip install -e ".[dev]"

{mxctl-0.3.0 → mxctl-0.4.1}/.github/workflows/release.yml

@@ -7,12 +7,13 @@ on:
 
 permissions:
   contents: write
+  id-token: write
 
 jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Extract version from tag
         id: version
@@ -34,3 +35,9 @@ jobs:
           body_path: /tmp/release-notes.md
           draft: false
           prerelease: ${{ contains(github.ref, 'rc') || contains(github.ref, 'beta') }}
+
+      - name: Build package
+        run: pip install build && python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{mxctl-0.3.0 → mxctl-0.4.1}/ARCHITECTURE.md

@@ -33,7 +33,7 @@ src/mxctl/
         ├── manage.py                  # create-mailbox, delete-mailbox, empty-trash
         ├── batch.py                   # batch-read, batch-flag, batch-move, batch-delete
         ├── analytics.py               # stats, top-senders, digest, show-flagged
-        ├── setup.py                   # init (first-time setup wizard)
+        ├── setup.py                   # init, ai-setup (setup wizards)
         ├── system.py                  # check, headers, rules, junk, not-junk
         ├── composite.py               # export, thread, reply, forward
         ├── ai.py                      # summary, triage, context, find-related
@@ -85,6 +85,6 @@ Batch commands (`batch-read`, `batch-move`, `batch-delete`, `batch-flag`) log th
 
 ## Testing
 
-Tests live in `tests/` and use `unittest.mock` to mock AppleScript calls. No actual Mail.app interaction happens during testing. Run with `pytest`.
+Tests live in `tests/` and use `unittest.mock` to mock AppleScript calls. No actual Mail.app interaction happens during testing. Run with `pytest --cov` for coverage.
 
-The suite has 348 tests across 17 test files covering command parsing, AppleScript output parsing, error paths, date handling, formatting, config resolution, batch operations, undo logging, templates, AI classification logic, unsubscribe HTTP paths, Todoist integration, inbox tools, and bulk export.
+The suite has 678 tests (100% coverage) across 19 test files covering command parsing, AppleScript output parsing, error paths, date handling, formatting, config resolution, batch operations, undo logging, templates, AI classification logic, unsubscribe HTTP paths, Todoist integration, inbox tools, bulk export, and the public API module. Six unreachable defensive guards are marked with `# pragma: no cover`.

{mxctl-0.3.0 → mxctl-0.4.1}/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-02-27
+
+### Added
+
+- **Public Python API** — new `mxctl.api` module with 56 importable functions for programmatic access to Apple Mail. All command internals refactored to separate data retrieval from CLI presentation. External projects can now `from mxctl.api import get_messages, read_message` without any CLI or argparse dependency.
+
+### Changed
+
+- README cleanup — removed personal email from examples, trimmed redundant sections, tightened AI workflow documentation (488 → 434 lines)
+
+## [0.4.0] - 2026-02-25
+
+### Added
+
+- `ai-setup` command — interactive wizard to configure Claude Code, Cursor, or Windsurf to use mxctl; detects existing config files, previews the snippet before writing, supports `--json`
+- `ai-setup --print` flag — dump the raw snippet to stdout for piping into Ollama Modelfiles, Aider prompts, system prompt files, or clipboard
+- "Pointing Your AI Assistant to mxctl" section in README — `mxctl ai-setup` walkthrough plus manual snippet for Claude Code, Cursor, Windsurf, and local AI tools
+
 ## [0.3.0] - 2026-02-24
 
 ### Changed
@@ -16,7 +34,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **Version bump** — 0.2.0 → 0.3.0 (breaking: new binary name and command structure)
 - **Package name** — Python package renamed from `my_cli` to `mxctl`
 - **GitHub repo** — `Jscoats/my-apple-mail-cli` → `Jscoats/mxctl`
-- Test suite expanded to 422 tests
+
+### Added
+
+- **Published to PyPI** — `pip install mxctl` now works
+- **100% test coverage** — 655 tests across 20 test files (up from 422), measured with pytest-cov
+- **5 demo GIFs** — main commands, init wizard, AI triage, batch delete, newsletter unsubscribe (all scripted with fictional data)
+- **Feature comparison table** — "Why Not X?" section with mxctl vs mutt vs Gmail API vs raw AppleScript
+- **Automated release workflow** — `release.yml` creates GitHub Release with changelog on tag push
+- **Pre-commit hooks** — ruff check + ruff format run on every commit
+- **Dependabot** — weekly updates for pip and GitHub Actions dependencies
+- **pytest-cov** — coverage reporting in CI and locally
+- **Ruff config** — `[tool.ruff]` in pyproject.toml with 7 rule sets (E, F, W, I, UP, B, SIM)
+- **PyPI classifiers** — 12 classifiers and 7 keywords for discoverability
+- **Centered README header** — styled `<h1>` with 5 badges (PyPI, CI, Python, coverage, license)
+- **README table of contents** — 14 sections linked
 
 ## [0.2.0] - 2026-02-22
 

{mxctl-0.3.0 → mxctl-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mxctl
-Version: 0.3.0
+Version: 0.4.1
 Summary: Apple Mail from your terminal
 Project-URL: Homepage, https://github.com/Jscoats/mxctl
 Project-URL: Repository, https://github.com/Jscoats/mxctl
@@ -30,16 +30,25 @@ Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# mxctl
+<p align="center">
+  <img src="demo/splash.png" alt="mxctl — Apple Mail from your terminal" width="700">
+</p>
+
+<h1 align="center">
+  <code>mxctl</code>
+</h1>
 
-[![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)
+<p align="center">
+  <a href="https://pypi.org/project/mxctl/"><img src="https://img.shields.io/pypi/v/mxctl.svg" alt="PyPI"></a>
+  <a href="https://github.com/Jscoats/mxctl/actions/workflows/ci.yml"><img src="https://github.com/Jscoats/mxctl/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+  <a href="https://github.com/Jscoats/mxctl"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage: 100%"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
+</p>
 
 > 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.
+**50+ 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">
@@ -62,7 +71,7 @@ Description-Content-Type: text/markdown
 
 ## Key Features
 
-- **49 Commands** - Everything from basic operations to advanced batch processing
+- **50+ 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
@@ -75,10 +84,10 @@ Description-Content-Type: text/markdown
 
 ```bash
 # Requires Python 3.10+ and macOS
-pip install git+https://github.com/Jscoats/mxctl
+pip install mxctl
 
 # Or with uv (faster)
-uv tool install git+https://github.com/Jscoats/mxctl
+uv tool install mxctl
 ```
 
 Then run the setup wizard — it detects your Mail.app accounts, configures Gmail mailbox translation, and optionally connects Todoist:
@@ -126,7 +135,7 @@ Inbox Overview
 ------------------------------------------
   iCloud             3 unread   (47 total)
   Work Email         12 unread  (203 total)
-  Johnny.Coats84@gmail.com  0 unread  (18 total)
+  Personal Gmail     0 unread   (18 total)
 ------------------------------------------
   Total              15 unread
 ```
@@ -169,6 +178,7 @@ Triage -- 15 Unread Messages
 
 ### Setup
 - `init` - First-time setup wizard (auto-detects Mail accounts, configures default account and optional Todoist token)
+- `ai-setup` - Configure your AI assistant to use mxctl (Claude Code, Cursor, Windsurf, Ollama, and others)
 
 ### Account & Mailbox Management
 - `inbox` - Overview of all accounts with unread counts
@@ -304,13 +314,6 @@ 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
@@ -323,8 +326,6 @@ mxctl export "Work" --to ~/Documents/mail/ -a "Work Email"
 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
@@ -340,13 +341,40 @@ mxctl draft --to client@company.com --template "meeting-followup"
 
 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
+### Pointing Your AI Assistant to mxctl
+
+For an AI assistant to use mxctl effectively, it needs to know the tool is available. The fastest way is the built-in setup command:
+
 ```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"
+mxctl ai-setup
 ```
 
+It walks you through selecting your AI assistant (Claude Code, Cursor, or Windsurf), previews the snippet it will write, and asks for confirmation before touching any file. Run it once; skip it any time you don't need it.
+
+#### Manual setup
+
+Prefer to configure it yourself? Run `mxctl ai-setup --print` to get the raw snippet, then paste it into your assistant's context file (`~/.claude/CLAUDE.md`, `.cursorrules`, `.windsurfrules`, etc.).
+
+#### Local AI (Ollama, LM Studio, Aider, etc.)
+
+Use `--print` to get the raw snippet for piping:
+
+```bash
+mxctl ai-setup --print | pbcopy              # clipboard
+mxctl ai-setup --print >> ~/Modelfile         # Ollama
+mxctl ai-setup --print > .aider.prompt.md     # Aider
+```
+
+For a one-off session, `mxctl --help` gives any AI the full command reference.
+
+### With Claude Code
+
+Just ask in natural language:
+
+> *"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
@@ -361,12 +389,11 @@ mxctl triage --json | llm "Draft responses for the urgent items"
 # Unread count for your status bar
 mxctl count
 
-# Export to JSON for any workflow
-mxctl inbox --json | jq '.accounts[].unread_count'
+# Every command supports --json
+mxctl inbox --json | jq '.[].unread'
+mxctl search "invoice" --json | jq '.[].subject'
 ```
 
-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.
@@ -399,7 +426,7 @@ The AI analyzes which newsletters you actually read vs. ignore, then unsubscribe
 
 Built with modern Python patterns:
 - **Zero runtime dependencies** (stdlib only)
-- **Comprehensive test suite** (422 tests)
+- **Comprehensive test suite** (678 tests)
 - **Modular command structure** (16 focused modules)
 - **AppleScript bridge** for Mail.app communication
 - **Three-tier account resolution** (explicit flag -> config default -> last-used)
@@ -408,14 +435,18 @@ 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.
+| | **mxctl** | **mutt/neomutt** | **Gmail/Outlook API** | **Raw AppleScript** |
+|---|---|---|---|---|
+| **Approach** | Extends Mail.app | Replaces Mail.app | Per-provider SDK | DIY scripting |
+| **Multi-account** | Any account in Mail.app | Config per account | Separate auth per provider | Manual per account |
+| **macOS integration** | Notifications, Rules, Continuity | None (terminal-only) | None | Partial |
+| **Structured output** | `--json` on every command | Text only | JSON (provider-specific) | Raw text |
+| **AI-ready** | Built for it (triage, summary) | No | Build it yourself | No |
+| **Batch + undo** | Built-in with rollback | No undo | Build it yourself | No |
+| **Setup** | `pip install mxctl && mxctl init` | Extensive config | OAuth flows + API keys | Write your own scripts |
+| **Dependencies** | Zero (stdlib only) | Varies | SDK + auth libraries | None |
 
-**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.
+**In short:** mutt replaces Mail.app (you lose macOS integration). Provider APIs lock you into one service. Raw AppleScript works but you're building everything from scratch. mxctl gives you 50+ structured commands on top of the Mail.app you already use.
 
 ## Contributing
 
@@ -425,10 +456,6 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 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)

{mxctl-0.3.0 → mxctl-0.4.1}/README.md

@@ -1,13 +1,22 @@
-# mxctl
+<p align="center">
+  <img src="demo/splash.png" alt="mxctl — Apple Mail from your terminal" width="700">
+</p>
+
+<h1 align="center">
+  <code>mxctl</code>
+</h1>
 
-[![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)
+<p align="center">
+  <a href="https://pypi.org/project/mxctl/"><img src="https://img.shields.io/pypi/v/mxctl.svg" alt="PyPI"></a>
+  <a href="https://github.com/Jscoats/mxctl/actions/workflows/ci.yml"><img src="https://github.com/Jscoats/mxctl/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+  <a href="https://github.com/Jscoats/mxctl"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage: 100%"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
+</p>
 
 > 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.
+**50+ 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">
@@ -30,7 +39,7 @@
 
 ## Key Features
 
-- **49 Commands** - Everything from basic operations to advanced batch processing
+- **50+ 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
@@ -43,10 +52,10 @@
 
 ```bash
 # Requires Python 3.10+ and macOS
-pip install git+https://github.com/Jscoats/mxctl
+pip install mxctl
 
 # Or with uv (faster)
-uv tool install git+https://github.com/Jscoats/mxctl
+uv tool install mxctl
 ```
 
 Then run the setup wizard — it detects your Mail.app accounts, configures Gmail mailbox translation, and optionally connects Todoist:
@@ -94,7 +103,7 @@ Inbox Overview
 ------------------------------------------
   iCloud             3 unread   (47 total)
   Work Email         12 unread  (203 total)
-  Johnny.Coats84@gmail.com  0 unread  (18 total)
+  Personal Gmail     0 unread   (18 total)
 ------------------------------------------
   Total              15 unread
 ```
@@ -137,6 +146,7 @@ Triage -- 15 Unread Messages
 
 ### Setup
 - `init` - First-time setup wizard (auto-detects Mail accounts, configures default account and optional Todoist token)
+- `ai-setup` - Configure your AI assistant to use mxctl (Claude Code, Cursor, Windsurf, Ollama, and others)
 
 ### Account & Mailbox Management
 - `inbox` - Overview of all accounts with unread counts
@@ -272,13 +282,6 @@ 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
@@ -291,8 +294,6 @@ mxctl export "Work" --to ~/Documents/mail/ -a "Work Email"
 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
@@ -308,13 +309,40 @@ mxctl draft --to client@company.com --template "meeting-followup"
 
 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
+### Pointing Your AI Assistant to mxctl
+
+For an AI assistant to use mxctl effectively, it needs to know the tool is available. The fastest way is the built-in setup command:
+
 ```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"
+mxctl ai-setup
 ```
 
+It walks you through selecting your AI assistant (Claude Code, Cursor, or Windsurf), previews the snippet it will write, and asks for confirmation before touching any file. Run it once; skip it any time you don't need it.
+
+#### Manual setup
+
+Prefer to configure it yourself? Run `mxctl ai-setup --print` to get the raw snippet, then paste it into your assistant's context file (`~/.claude/CLAUDE.md`, `.cursorrules`, `.windsurfrules`, etc.).
+
+#### Local AI (Ollama, LM Studio, Aider, etc.)
+
+Use `--print` to get the raw snippet for piping:
+
+```bash
+mxctl ai-setup --print | pbcopy              # clipboard
+mxctl ai-setup --print >> ~/Modelfile         # Ollama
+mxctl ai-setup --print > .aider.prompt.md     # Aider
+```
+
+For a one-off session, `mxctl --help` gives any AI the full command reference.
+
+### With Claude Code
+
+Just ask in natural language:
+
+> *"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
@@ -329,12 +357,11 @@ mxctl triage --json | llm "Draft responses for the urgent items"
 # Unread count for your status bar
 mxctl count
 
-# Export to JSON for any workflow
-mxctl inbox --json | jq '.accounts[].unread_count'
+# Every command supports --json
+mxctl inbox --json | jq '.[].unread'
+mxctl search "invoice" --json | jq '.[].subject'
 ```
 
-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.
@@ -367,7 +394,7 @@ The AI analyzes which newsletters you actually read vs. ignore, then unsubscribe
 
 Built with modern Python patterns:
 - **Zero runtime dependencies** (stdlib only)
-- **Comprehensive test suite** (422 tests)
+- **Comprehensive test suite** (678 tests)
 - **Modular command structure** (16 focused modules)
 - **AppleScript bridge** for Mail.app communication
 - **Three-tier account resolution** (explicit flag -> config default -> last-used)
@@ -376,14 +403,18 @@ 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.
+| | **mxctl** | **mutt/neomutt** | **Gmail/Outlook API** | **Raw AppleScript** |
+|---|---|---|---|---|
+| **Approach** | Extends Mail.app | Replaces Mail.app | Per-provider SDK | DIY scripting |
+| **Multi-account** | Any account in Mail.app | Config per account | Separate auth per provider | Manual per account |
+| **macOS integration** | Notifications, Rules, Continuity | None (terminal-only) | None | Partial |
+| **Structured output** | `--json` on every command | Text only | JSON (provider-specific) | Raw text |
+| **AI-ready** | Built for it (triage, summary) | No | Build it yourself | No |
+| **Batch + undo** | Built-in with rollback | No undo | Build it yourself | No |
+| **Setup** | `pip install mxctl && mxctl init` | Extensive config | OAuth flows + API keys | Write your own scripts |
+| **Dependencies** | Zero (stdlib only) | Varies | SDK + auth libraries | None |
 
-**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.
+**In short:** mutt replaces Mail.app (you lose macOS integration). Provider APIs lock you into one service. Raw AppleScript works but you're building everything from scratch. mxctl gives you 50+ structured commands on top of the Mail.app you already use.
 
 ## Contributing
 
@@ -393,10 +424,6 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 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)

{mxctl-0.3.0 → mxctl-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mxctl"
-version = "0.3.0"
+version = "0.4.1"
 description = "Apple Mail from your terminal"
 readme = "README.md"
 requires-python = ">=3.10"