mu-wizard

shell script to easily configure mu4e accounts on Emacs
git clone git://git.ckyln.com/mu-wizard
Log | Files | Refs | LICENSE

README.org (5634B)


      1 #+TITLE: mu-wizard
      2 #+AUTHOR: Cem Keylan
      3 #+STARTUP: indent
      4 
      5 =mu-wizard= is a shell script to auto-configure email accounts for =mu4e=
      6 similar in function to =mutt-wizard=. It uses =isync= to synchronize mail
      7 accounts, =msmtp= to send mail and creates individual Lisp profiles for each
      8 account. It is still WIP. Expect breaking changes until the first release.
      9 
     10 * Table of Contents                                            :TOC:noexport:
     11 - [[#dependencies][Dependencies]]
     12 - [[#installation][Installation]]
     13   - [[#initiating-password-managers][Initiating password managers]]
     14 - [[#usage][Usage]]
     15   - [[#emacs-configuration][Emacs Configuration]]
     16   - [[#domains-file][Domains file]]
     17   - [[#overrides][Overrides]]
     18 - [[#notes][Notes]]
     19   - [[#isync-deprecation-notice][Isync Deprecation Notice]]
     20   - [[#protonmail][Protonmail]]
     21   - [[#google][Google]]
     22   - [[#forcing-a-password-manager][Forcing a password manager]]
     23 
     24 * Dependencies
     25 
     26 - =isync= (for offline mail storage)
     27 - =mu=    (or =maildir-utils= depending on your distribution)
     28 - =msmtp= (for sending mails)
     29 - Password manager (=pass=, [[https://github.com/dylanaraps/pash][pash]], and [[https://github.com/cemkeylan/pm][pm]] is supported)
     30 
     31 * Installation
     32 
     33 In order to install =mu-wizard=, clone this repository and build =mu-wizard=.
     34 
     35 #+BEGIN_SRC sh
     36   git clone https://github.com/cemkeylan/mu-wizard.git
     37   cd mu-wizard
     38   make install
     39 #+END_SRC
     40 
     41 Users of Arch Linux based distributions can install =mu-wizard= through the AUR
     42 package [[https://aur.archlinux.org/packages/mu-wizard-git][mu-wizard-git]]. This package is not maintained by me.
     43 
     44 #+BEGIN_SRC sh
     45   yay -S mu-wizard-git
     46 #+END_SRC
     47 
     48 ** Initiating password managers
     49 
     50 All of the password managers require some sort of initializing before you can
     51 store your passwords. This must be done *before* you run ~muw~ for the first
     52 time. You will need to have a GnuPG key for all of the password managers
     53 supported by ~muw~. You can create a GPG key by running ~gpg --gen-key~, or
     54 ~gpg --full-gen-key~.
     55 
     56 See the documentation of your password manager for more information on setting
     57 up your password manager, below are simple instructions enough to get you going.
     58 
     59 *** pass
     60 
     61 In order to initiate pass, do the following:
     62 
     63 #+BEGIN_SRC sh
     64   pass init yourgpgmail@example.com
     65 #+END_SRC
     66 
     67 *** pash
     68 
     69 In order to use pash, add the following to your =.bashrc= (or what have you):
     70 
     71 #+BEGIN_SRC sh
     72   export PASH_KEYID=yourgpgmail@example.com
     73 #+END_SRC
     74 
     75 *** pm
     76 
     77 In order to use pm, add the following to your =.bashrc= (or what have you):
     78 
     79 #+BEGIN_SRC sh
     80   export PM_GPG_USER=yourgpgmail@example.com
     81 #+END_SRC
     82 
     83 * Usage
     84 
     85 The wizard is called by running ~muw~. The commands below are available to use:
     86 
     87 #+BEGIN_SRC sh :results raw :exports results
     88 ./bin/muw --help | sed -E '/^Commands:/,/^$/!d;/Commands:/d;/^$/d;s|^ *([a-zA-Z-]*) *(.*)$|- =\1= :: \2|'
     89 #+END_SRC
     90 
     91 #+RESULTS:
     92 - =add= :: Add and autoconfigure an email address
     93 - =delete= :: Pick an account to delete
     94 - =list= :: List configured accounts
     95 - =purge= :: Purge all configuration
     96 - =sync= :: Sync mail for accounts
     97 - =mu-init= :: Run 'mu init' with the configured accounts
     98 - =data= :: Output system data directory and exit
     99 
    100 You can run ~muw COMMAND --help~ for learning more about the usage of the
    101 command. The entire documentation can be found on manual pages.
    102 
    103 ** Emacs Configuration
    104 
    105 Emacs will not be loading the configurations, you will need to set it manually.
    106 In your init file, you may choose to load the configuration in the following
    107 ways.
    108 
    109 #+BEGIN_SRC emacs-lisp
    110   (load-file "~/.config/mu4e/mu4e-config.el")
    111 #+END_SRC
    112 
    113 #+BEGIN_SRC emacs-lisp
    114   (add-to-list 'load-path "~/.config/mu4e")
    115   (require 'mu4e-config)
    116 #+END_SRC
    117 
    118 #+BEGIN_SRC emacs-lisp
    119   (use-package mu4e-config
    120     :after mu4e
    121     :load-path "~/.config/mu4e")
    122 #+END_SRC
    123 
    124 ** Domains file
    125 
    126 =mu-wizard= doesn't come with a predefined =domains.csv= file, but it can use
    127 one if it is found on =/usr/share/mu-wizard/domains.csv= (or whatever your share
    128 directory is, see ~muw data~). =mu-wizard= also saves the domain information
    129 that you when creating an account on your configuration directory, so you don't
    130 have to retype every detail when creating a second account with the same domain.
    131 
    132 ** Overrides
    133 
    134 Domain-level overrides are possible by adding a shell file to either the share
    135 directory or the user configuration directory. See [[file:overrides/protonmail.com][overrides/protonmail.com]]
    136 for an example override.
    137 
    138 * Notes
    139 
    140 ** Isync Deprecation Notice
    141 
    142 =isync= version 1.4.0 outputs the following deprecation notice for the mbsync
    143 configuration.
    144 
    145 #+BEGIN_QUOTE
    146 Notice: Master/Slave are deprecated; use Far/Near instead.
    147 #+END_QUOTE
    148 
    149 You can fix this by running the command:
    150 
    151 #+begin_src sh
    152 sed -i 's|^Slave |Near |;s|^Master |Far |' "$HOME/.mbsyncrc"
    153 #+end_src
    154 
    155 ** Protonmail
    156 
    157 =mu-wizard= supports protonmail. If you are using one of the default domains,
    158 you don't have to do anything. If you are using an alternative domain, you can
    159 link the protonmail.com override to your personal domain. Here is an example:
    160 
    161 #+BEGIN_SRC sh
    162   ln -sf /usr/share/mu-wizard/overrides/protonmail.com $HOME/.config/mu4e/overrides/example.com
    163 #+END_SRC
    164 
    165 Keep in mind that you will need protonmail bridge in order to send mails.
    166 
    167 ** Google
    168 
    169 Google requires you to enable less-secure access in order to receive mail. See
    170 [[https://support.google.com/accounts/answer/6010255][here]] for more information.
    171 
    172 ** Forcing a password manager
    173 
    174 Using the =$MUW_PWM= environment variable, you can specify which password
    175 manager to use. If you don't specify a password manager, ~muw~ will use it with
    176 the following order:
    177 
    178 1. ~pass~
    179 2. ~pash~
    180 3. ~pm~