diff options
Diffstat (limited to 'mutt/.config/mutt/README.md')
| -rw-r--r-- | mutt/.config/mutt/README.md | 168 |
1 files changed, 111 insertions, 57 deletions
diff --git a/mutt/.config/mutt/README.md b/mutt/.config/mutt/README.md index 4938f78..a25d70b 100644 --- a/mutt/.config/mutt/README.md +++ b/mutt/.config/mutt/README.md @@ -1,69 +1,123 @@ -# Luke's mutt Wizard for automatic Neomutt and OfflineIMAP configuration! +# mutt-wizard - +Get this great stuff without effort: -Mutt is one of the most rewarding programs one can use, but can be a pain in the ass to configure. Since my job is making power-user tools available for the masses I want to create a tool that automates most of mutt configuration so that users can simply give their email address and get a /comfy/ setup. At that, I don't just want a mutt wizard, but an offlineIMAP wizard, so users can easily access their mail offline as well, and a wizard that makes it easy to store passwords securely using gpg. +- A full-featured and autoconfigured email client on the terminal with neomutt +- Mail stored offline so you can view and write email while away from internet and keep backups -The mutt-wizard is all of this in a simple ncurses menu. It's really just a little bash script, but one that can save countless people thousands of combined manhours of frustratingly trying to get all the moving pieces working together. +Specifically, this wizard: -## User interface +- Determines your email server's IMAP and SMTP servers and ports +- Creates dotfiles for `neomutt`, `isync`, and `msmtp` appropriate for your email address +- Encrypts and stores locally your password for easy remote access, accessible only by your GPG key +- Handles as many as nine separate email accounts automatically +- Auto-creates bindings to switch between accounts or between mailboxes +- Can automatically set mail updates as often as you want to sync your mail and update you when new mail arrives +- Provides sensible defaults and an attractive appearance for the neomutt email client +- If mutt-wizard doesn't know your server's IMAP/SMTP info by default, it will prompt you for them and will put them in all the right places. -The system takes an email and autodetect its server settings, generating a muttrc and offlineimaprc profile automatically. If it can't do so, it simply prompts you for these (which you can easily look up) and will put them all in the right places. You get: - -+ Automatic configuration of mutt and offlineimap. -+ Automatic encryption and safe storage of passwords which are used by mutt and offlineimap when necessary. -+ Multiple account management in mutt: jump from account to account with the `i` prefix in mutt: `i1`: first email account, `i5`: fifth, etc. -+ Easy movement to mail folders in mutt: `gi`: go to inbox, `gs` to sent mail, `ga` to archive, `gS` to spam, `gd` to drafts, etc. -+ Some default controls and colors. This system is going to be integrated into my [public auto-rice script](https://larbs.xyz) so I want it to look pretty and be usable out the box. -+ An optional autosync script that will smartly run offlineimap when connected to the internet at what interval you want and will notify you with a ding when new mail arrives. - -### Will it work on my email? (95% yes) - -Yes! At this point, the only problems are the unexpected ones. Please try it, and if you do run into problems, email me at [luke@lukesmith.xyz](mailto:luke@lukesmith.xyz)! I've tried the system personally on Gmail, Teknik.io, cock.li and Yandex, while others have tried other providers. - -One email provider which I think will *not* work (and will never work) is Proton Mail, but that's only because they require encryption through their web client IIRC. - -Note also that Gmail and some providers require you to enable sign-ins from third-party (or as they call it "less secure") applications to be able to load mail with mutt and offlineimap. Be sure to enable that! - -## Installation and Dependencies - -`dialog`, `neomutt` and `offlineimap` should be installed. You also need to have a GPG public/private key pair for the wizard to automatically store your passwords. The whole repo should be cloned to `~/.config/mutt/`. (If you have a previous mutt folder, you'll want to back it up or delete it first.) +## Install and Use ``` -git clone https://github.com/LukeSmithxyz/mutt-wizard.git ~/.config/mutt +git clone https://github.com/LukeSmithxyz/mutt-wizard +cd mutt-wizard +sudo make install ``` -You will want to delete or rename your current `~/.offlineimaprc` as well, as although you can later modify the `~/.offlineimaprc` produced by the script, you must have no file there the first time you add your first account or the wizard will assume some settings are already set which aren't. - -Just run `mutt-wizard.sh` and choose to add an account. After you do so, you may run `offlineimap` to begin the mailsync, and you will be able to run neomutt and see your mail. -If mutt doesn't immediately work properly run the `Redetect mailboxes` option, then open mutt. This may be necessary for some accounts. - -### Non-essential dependencies - -The automatically deployed configs will look for certain programs for certain extra abilities. Consider installing the following for the extra functionality. +User of Arch-based distros can also install mutt-wizard from the AUR as [mutt-wizard-git](https://aur.archlinux.org/packages/mutt-wizard-git/). -+ `urlview` -- Detecting and following links with `ctrl-u` -+ `mupdf` -- for viewing attached pdfs (`v` to view attachments, then select .pdf) -+ `notmuch` -- for mail searching and indexing set to `ctrl-f`. Be sure to run `notmuch setup`. Remember your mail is in `~/.mail/` when you configure notmuch. -+ `w3m` and/or `w3mimg` -- for viewing images. Like .pdfs, view in the attachments menu. -+ A cron manager if you want the autosync feature. -+ `iproute2mac` for Mac users who want the autosync feature. -+ `mpv` if you want the autosync feature to notify you with a ding on new mail. +*NOTE:* If you have used an older version of mutt-wizard, especially when it used to use `offlineimap`, you need to remove your old configs. Back anything up that's important and run: -### "Wait? The script asks for my passwords?" - -Look at the code. The script takes the passwords you give it, encrypts them immediately with your own GPG key, and shreds the leftovers. Nothing malicious; it's all there! If it makes you comfortable you can even run the script offline at first. - -## You can help! - -If you use mutt with a particular host or domain, put your server information in `domains.csv`! This will make everyone else who uses your email provider's life much easier! - -Or you can help monetarily via [Patreon](https://patreon.com/lukesmith) or [Paypal](https://paypal.me/LukeMSmith)! - -## Notes - -Mail is stored in `~/.mail`. mutt configs and caches for each account are in `~/.config/mutt/accounts/`. Encypted passwords are in `~/.config/mutt/credentials`. A "personal" muttrc, with the macros for switching accounts and the default config is in `~/.config/mutt/personal.muttrc`. - -## Todo +``` +rm -rf ~/.config/mutt ~/.msmtprc ~/.config/msmtp ~/.offlineimap ~/.offlineimaprc ~/.config/offlineimap ~/.mbsyncrc +``` -* Expand the list of server information in `domains.csv`, possibly porting the Thunderbird autoconfigure settings. +The mutt-wizard is run with the command `mw`. It also installs the `mailsync` command. Once everything is setup, you'll use `neomutt` to access your mail. + +- `mw add` -- add a new email account +- `mw ls` -- list existing accounts +- `mw pass` -- revise an account's password +- `mw delete` -- deleted an added account +- `mw purge` -- delete all accounts and settings +- `mw cron` -- toggle/configure a cronjob to sync mail + +## Dependencies + +- `neomutt` - the email client. +- `isync` - downloads and syncs the mail. (required at install) +- `msmtp` - sends the email. +- `pass` - safely encrypts passwords (required at install) + +There's a chance of errors if you use a slow-release distro like Ubuntu, Debian or Mint. If you get errors in `neomutt`, install the most recent version manually or manually remove the offending lines in the config in `/usr/share/mutt-wizard/mutt-wizard.muttrc`. + +### Optional + +- `lynx` - view HTML email in neomutt. +- `notmuch` - index and search mail. Install it and run `notmuch setup`, tell it that your mail is in `~/.local/share/mail/` (although `mw` will do this automatically if you haven't set notmuch up before). You can run it in mutt with `ctrl-f`. Run `notmuch new` to process new mail, although the included `mailsync` script does this for you. +- `libnotify`/`libnotify-bin` - allows notifications when syncthing mail with `mailsync` +- `abook` - a terminal-based address book. Pressing tab while typing an address to send mail to will suggest contacts that are in your abook. +- A cron manager - if you want to enable the auto-sync feature. +- `pam-gnupg` - this is a more general program that I use. It automatically logs you into your GPG key on login so you will never need to input your password once logged on to your system. Check the repo and directions out [here](https://github.com/cruegge/pam-gnupg). +- `urlview` - outputs urls in mail to browser. + +## Neomutt user interface + +To give you an example of the interface, here's an idea: + +- `m` - send mail (uses your default `$EDITOR` to write) +- `j`/`k` and `d`/`u` - vim-like bindings to go down and up (or `d`/`u` to go down/up a page). +- `l` - open mail, or attachment page or attachment +- `h` - the opposite of `l` +- `r`/`R` - reply/reply all to highlighted mail +- `s` - save selected mail or selected attachment +- `gs`,`gi`,`ga`,`gd`,`gS` - Press `g` followed by another letter to change mailbox: `s`ent, `i`nbox, `a`rchive, `d`rafts, `S`pam, etc. +- `M` and `C` - For `M`ove and `C`opy: follow them with one of the mailbox letters above, i.e. `MS` means "move to Spam". +- `i#` - Press `i` followed by a number 1-9 to go to a different account. If you add 9 accounts via mutt-wizard, they will each be assigned a number. +- `a` to add address/person to abook and `Tab` while typing address to complete one from book. +- `?` - see all keyboard shortcuts +- `ctrl-j`/`ctrl-k` - move up and down in sidebar, `ctrl-o` opens mailbox. +- `ctrl-b` - open a menu to select a url you want to open in you browser. +## New stuff and improvements since the original release + +- `isync`/`mbsync` has replaced `offlineimap` as the backend. Offlineimap was error-prone, bloated, used obsolete Python 2 modules and required separate steps to install the system. +- `mw` is now an installed program instead of just a script needed to be kept in your mutt folder. +- `dialog` is no longer used (le bloat) and the interface is simply text commands. +- More autogenerated shortcuts that allow quickly moving and copying mail between boxes. +- More elegant attachment handling. Image/video/pdf attachments without relying on the neomutt instance. +- abook integration by default. +- The messy template files and other directories have been moved or removed, leaving a clean config folder. +- msmtp configs moved to `~/.config/` and mail default location moved to `~/.local/share/mail/`, reducing mess in `~`. +- `pass` is used as a password manager instead of separately saving passwords. +- Script is POSIX sh compliant. +- Error handling for the many people who don't read or follow directions. Less errors generally. +- Addition of a manual `man mw` + +## Help the Project! + +- Try mutt-wizard out on weird machines and weird email addresses and report any errors. +- Open a PR to add new server information into `domains.csv` so their users can more easily use mutt-wizard. +- If nothing else, [Donate!](https://paypal.me/LukeMSmith) + +See Luke's website [here](https://lukesmith.xyz). Email him at [luke@lukesmith.xyz](mailto:luke@lukesmith.xyz). + +mutt-wizard is free/libre software, licensed under the GPLv3. + +## Details for Tinkerers + +- The critical `mutt`/`neomutt` files are in `~/.config/mutt/`. +- Put whatever global settings you want in `muttrc`. mutt-wizard will add some lines to this file which you shouldn't remove unless you know what you're doing, but you can move them up/down over your personal config lines if you need to. If you get binding conflict errors in mutt, you might need to do this. +- Each of the accounts that mutt-wizard generates will have custom settings set in a separate file in `accounts/`. You can edit these freely if you want to tinker with settings specific to an account. +- In `/usr/share/mutt-wizard` are several global config files, including `mutt-wizard`'s default settings. You can overwride this in your `muttrc` if you wish. + +## Watch out for these things: +- Gmail accounts can now create 'App Password' to use with """less secure""" applications. This password is single use (ie. for setup) and will be stored and encrypted locally. Enabling third-party applications requires turning off two-factor authentication and this will circumvent that. You might also need to manually "Enable IMAP" in the settings. +- Protonmail accounts will require you to set up "Protonmail Bridge" to access PM's IMAP and SMTP servers. Configure that before running mutt-wizard. +- Protonmail bridge is prone to timing out. Watch out for this while adding an account. If the bridge times out, try again. +- If you have a university email, or enterprise-hosted email for work, there might be other hurdles or two-factor authentication you have to jump through. Some, for example, will want you to create a separate IMAP password, etc. + - `isync` is not fully UTF-8 compatible, so non-Latin characters may be garbled (although sync should succeed). `mw` will also not autocreate mailbox shortcuts since it is looking for English mailbox names. I strongly recommend you to set your email language to English on your mail server to avoid these problems. + +## To-do + +- Add ~~Mac OS~~/BSD compatibility (the script is confired to work for Mac OS now) +- ~~Out-of-the-box compatibility with Protonmail Bridge~~ (I believe this is done, but more bug-testing is welcome since I don't have PM) +- Option to keep configuration for accounts that failed to connect (maybe) |