mutt-wizard 0.1.2

Python starter for configuring neomutt with Gmail OAuth.

mutt-wizard

Configure neomutt with Gmail app passwords (default) or OAuth (optional), and generate mbsync/msmtp configuration files.

This repo focuses on a minimal setup for:

• Gmail app passwords (default, simple)
• Gmail OAuth (optional)
• neomutt account configs
• isync/mbsync sync
• msmtp sendmail

Table of contents

• Why this project
• What this tool creates
• Requirements
• Install
• Gmail app password (default, simplest)
• Gmail OAuth setup (optional)
• Why OAuth needs a plugin
• Non-Gmail account
• Sync mail
• Commands
• Reset (wipe everything created by mw)
• macOS notes
• Linux notes
• Troubleshooting

Why this project

Luke Smith’s original mutt-wizard is effectively unmaintained, and Gmail now requires OAuth or app passwords. This repo keeps the idea alive with a readable Python setup that works today.

What this tool creates

• ~/.config/mutt-wizard/ config root
• ~/.config/mutt-wizard/mbsyncrc
• ~/.config/mutt-wizard/msmtp/config
• ~/.config/mutt-wizard/tokens/ Gmail OAuth tokens
• ~/.config/mutt/accounts/*.muttrc
• ~/.config/mutt/muttrc (sourced once)
• ~/.local/share/mail/ Maildir storage

Requirements

Common:

• Python 3.10+
• neomutt
• isync (mbsync)
• msmtp
• ca-certificates
• pass + GPG (only for non-Gmail accounts)

Optional:

• notmuch
• lynx
• abook
• urlview
• mpv

Install

Use uv so the mw and mailsync entrypoints are consistent across macOS and Linux.

uv venv --clear && source .venv/bin/activate
uv pip install -e .

To install as global executables:

uv pip install .

or:

uv tool install .

Gmail app password (default, simplest)

This is the default for Gmail because it “just works” on macOS and Linux without requiring the XOAUTH2 plugin.

Requirements:

• 2FA enabled on your Google account
• an app password created in Google Account security

Add the account:

mw add --gmail --email [e-mail]
pass insert [e-mail]

Gmail OAuth setup (optional)

1. Create OAuth credentials in Google Cloud:
   • https://console.cloud.google.com/apis/credentials
   • Create OAuth client ID (Desktop app)
   • Download the JSON file
2. Ensure the Gmail API is enabled for the project.
3. If the consent screen is in Testing, add your Gmail address as a test user.

Then run:

mw add --gmail-oauth --email [e-mail] --client-secrets /path/to/client_secret.json

If your browser cannot open, add --no-browser and follow the console flow.

Why OAuth needs a plugin

mbsync uses Cyrus SASL for OAuth. On macOS/Homebrew, the XOAUTH2 SASL plugin is not bundled, so you must install it (or use app passwords).

Non-Gmail account

mw add --email [e-mail] --imap imap.example.com --smtp smtp.example.com

Passwords are read via pass. Example:

pass insert [e-mail]

Sync mail

mailsync
mailsync [e-mail]

mailsync runs mbsync -c ~/.config/mutt-wizard/mbsyncrc and runs notmuch new only if ~/.notmuch-config exists.

You can also run mbsync directly:

mbsync -c ~/.config/mutt-wizard/mbsyncrc -a

Commands

mw add --gmail --email [e-mail]
mw add --gmail-oauth --email [e-mail] --client-secrets /path/to/client_secret.json
mw add --email [e-mail] --imap imap.example.com --smtp smtp.example.com
mw list
mw oauth login --email [e-mail]
mw oauth token [e-mail]
mw reset
mailsync

Reset (wipe everything created by mw)

mw reset

This removes:

• ~/.config/mutt-wizard
• account muttrc files under ~/.config/mutt/accounts
• mw entries in ~/.config/mutt/muttrc
• maildirs under ~/.local/share/mail/<account>
• ~/.config/isyncrc symlink (if created)
• msmtp log created by mw

macOS notes

Install dependencies (Homebrew)

brew install neomutt isync msmtp pass gnupg notmuch lynx

Gmail XOAUTH2 SASL plugin (macOS only)

On macOS, Homebrew’s cyrus-sasl does not ship the XOAUTH2 plugin, so Gmail auth will fail unless you install it. This is a macOS/Homebrew limitation, not a Linux requirement.

If you see:

Error performing SASL authentication step: SASL(-1)

Install the plugin with the helper script (builds in a temp dir):

./scripts/install_xoauth2_macos.sh

After that, plain mailsync works with no flags because the path is written to ~/.config/mutt-wizard/env.

If you prefer not to build a plugin, use Gmail app password mode above.

you can run mailsync with the plugin path:

mailsync --sasl-path /opt/homebrew/lib/sasl2 [e-mail]

if its still not working, try setting the SASL_PATH environment variable:

export SASL_PATH=/opt/homebrew/lib/sasl2

Linux notes

Install dependencies (Debian/Ubuntu)

sudo apt install neomutt isync msmtp pass gnupg ca-certificates notmuch lynx

For Gmail XOAUTH2 support, also install:

sudo apt install libsasl2-modules

Install dependencies (Arch)

sudo pacman -S neomutt isync msmtp pass gnupg ca-certificates notmuch lynx

For Gmail XOAUTH2 support, install a SASL XOAUTH2 plugin (AUR example):

paru -S cyrus-sasl-xoauth2

Troubleshooting

403 access_denied on OAuth

• Ensure Gmail API is enabled for your Google Cloud project.
• Ensure OAuth consent screen is configured.
• If in Testing, add your Gmail as a test user.

SASL authentication failure

• macOS: install XOAUTH2 plugin with ./scripts/install_xoauth2_macos.sh
• Linux: install SASL XOAUTH2 modules (libsasl2-modules or distro equivalent)
• Ensure SASL_PATH points to the SASL plugin directory if needed.

notmuch error on mailsync

mailsync only runs notmuch if ~/.notmuch-config exists. Run notmuch setup if you want it enabled.