#+date: [2025-11-02 Sun 10:07:14] #+title: Using aerc on macOS #+description: How I use aerc, a TUI email client, on macOS. #+slug: aerc-macos #+filetags: :linux: #+caption: aerc-mail #+attr_html: :alt An image of aerc with an email opened in the reader window. https://img.cleberg.net/blog/20251102-aerc-macos/read.webp Shout-out to [[https://baty.net/posts/2025/10/using-aerc-for-email/][Jack Baty]] for inspiring me to write about my =aerc-mail= client after chatting about it over email recently! * Overview [[https://aerc-mail.org/][aerc]] is a text user interface (TUI) email client with intuitive defaults, easy setup, and hassle-free operations. This post will walk through my personal configuration for aerc on macOS. * Installation Since I am on macOS, I opted to install aerc from Homebrew. There are build options for additional modules if you build from source, but I am okay with the default options. You can view the information about the package prior to installing it, if you wish: #+begin_src sh brew info aerc #+end_src #+begin_src sh ==> aerc: stable 0.21.0 (bottled), HEAD Email client that runs in your terminal https://aerc-mail.org/ Installed /opt/homebrew/Cellar/aerc/0.21.0 (48 files, 23MB) * Poured from bottle using the formulae.brew.sh API on 2025-10-05 at 19:51:31 From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/a/aerc.rb License: MIT ==> Dependencies Build: go ✘, scdoc ✘ Required: notmuch ✔ ==> Options --HEAD Install HEAD version ==> Downloading https://formulae.brew.sh/api/formula/aerc.json ==> Analytics install: 136 (30 days), 560 (90 days), 1,772 (365 days) install-on-request: 136 (30 days), 560 (90 days), 1,772 (365 days) build-error: 3 (30 days) #+end_src Once you confirm you want to install this package, run the following: #+begin_src sh brew install aerc #+end_src * First-Time Wizard When you run aerc for the first time, an IMAP & SMTP wizard will walk you through a basic setup for your email account(s). On macOS, aerc will save your configuration files in the following location: =~/Library/Preferences/aerc=. I tried to create a =~/.config/aerc= directory, but the Library directory above took precedence. If you truly need to keep your files in =~/.config=, you could probably symlink that to the Library location. However, I accepted my fate and will just edit the files within the Library directory. * Configuration Once you have installed and setup aerc for the first time, you can configure the client and account settings. As noted above, I will be working within the Library directory that aerc defaults to when installed via brew. #+begin_src sh cd ~/Library/Preferences/aerc #+end_src This directory should contain the following files. You can open the =accounts.conf= file to confirm it contains the information you input during the wizard process. | File | Purpose | |-----------------+-------------------------------------------------------------| | =accounts.conf= | Contains account-specific settings for IMAP & SMTP accounts | | =aerc.conf= | Contains program-wide settings | | =binds.conf= | Contains key bindings for aerc | I'll share my personal configuration, which is close to the defaults that existed at the time of writing this post. =accounts.conf= This is the information from the wizard. The only further customization I provided is the default signature file to be appended to each message I compose. #+begin_src conf [Personal] source = imaps://hello%40cleberg.net:PASSWORD@imap.migadu.com outgoing = smtps://hello%40cleberg.net:PASSWORD@smtp.migadu.com default = INBOX from = Christian Cleberg copy-to = Sent cache-headers = true signature-file = /Users/cmc/Library/Preferences/aerc/sigs/default #+end_src =sigs/default= Any content within this file will be appended to my messages, as noted above. #+begin_src text Christian Cleberg GPG: 3917 973F B159 BBB8 6194 5385 69451A51 7AC0 CB37 #+end_src =aerc.conf= This contains quite a few customizations for my preferences related to downloads, encryption, mouse controls, editor, and message composition. #+begin_src conf [general] # Prefer downloads to be saved to the Downloads folder default-save-path=~/Downloads # Use GPG for PGP encryption pgp-provider=gpg [ui] # Enable mouse controls for scrolling, paging, etc. mouse-enabled=true [statusline] [viewer] # Use emacs instead of vi pager=/usr/local/bin/emacs_viewer [compose] # Use emacs instead of vi editor=emacs # Add Cc as a default field to view each time I compose a message header-layout=To|From,Cc,Subject # Allow me to edit headers when composing (so I can customize From address) edit-headers=true # Warn me if I mentioned these words but don't attach a file empty-subject-warning=true no-attachment-warning=^[^>]*attach(ed|ment) [multipart-converters] [filters] text/plain=colorize text/calendar=calendar message/delivery-status=colorize message/rfc822=colorize text/html=! html .headers=colorize [openers] [hooks] [templates] #+end_src #+begin_quote *IMPORTANT*: If you use the =pager= option above that I'm using, you will need to create the =emacs_viewer= file as well. #+end_quote You can create the file following my process below, which will create an executable in the location specified in my =aerc.conf= file. I put it in =/usr/local/bin=, but you can put it anywhere as long as it exists in the file path specific within your configuration file. #+begin_src sh sudo nano /usr/local/bin/emacs_viewer #+end_src Paste this inside the file: #+begin_src sh #!/bin/bash emacs -nw - < "$1" #+end_src #+begin_src sh sudo chmod +x /usr/local/bin/emacs_viewer #+end_src =binds.conf= Finally, here are the key bindings. I did not change these, but I'm showing them here in case you have an issue and want to see the defaults. #+begin_src conf # Binds are of the form = # To use '=' in a key sequence, substitute it with "Eq": "" # If you wish to bind #, you can wrap the key sequence in quotes: "#" = quit = :prev-tab = :prev-tab = :next-tab = :next-tab \[t = :prev-tab \]t = :next-tab = :term ? = :help keys = :prompt 'Quit?' quit = :prompt 'Quit?' quit = :suspend [messages] q = :prompt 'Quit?' quit j = :next = :next = :next 50% = :next 100% = :next 100% k = :prev = :prev = :prev 50% = :prev 100% = :prev 100% g = :select 0 G = :select -1 J = :next-folder = :next-folder K = :prev-folder = :prev-folder H = :collapse-folder = :collapse-folder L = :expand-folder = :expand-folder v = :mark -t = :mark -t:next V = :mark -v T = :toggle-threads zc = :fold zo = :unfold za = :fold -t zM = :fold -a zR = :unfold -a = :fold -t zz = :align center zt = :align top zb = :align bottom = :view d = :choose -o y 'Really delete this message' delete-message D = :delete a = :archive flat A = :unmark -a:mark -T:archive flat C = :compose m = :compose b = :bounce rr = :reply -a rq = :reply -aq Rr = :reply Rq = :reply -q c = :cf $ = :term ! = :term | = :pipe / = :search \ = :filter n = :next-result N = :prev-result = :clear s = :split S = :vsplit pl = :patch list pa = :patch apply pd = :patch drop pb = :patch rebase pt = :patch term ps = :patch switch [messages:folder=Drafts] = :recall [view] / = :toggle-key-passthrough/ q = :close O = :open o = :open S = :save | = :pipe D = :delete A = :archive flat = :copy-link = :open-link f = :forward rr = :reply -a rq = :reply -aq Rr = :reply Rq = :reply -q H = :toggle-headers = :prev-part = :prev-part = :next-part = :next-part J = :next = :next K = :prev = :prev [view::passthrough] $noinherit = true $ex = = :toggle-key-passthrough [compose] # Keybindings used when the embedded terminal is not selected in the compose # view $noinherit = true $ex = $complete = = :prev-field = :prev-field = :next-field = :next-field = :switch-account -p = :switch-account -p = :switch-account -n = :switch-account -n = :next-field = :prev-field = :prev-tab = :prev-tab = :next-tab = :next-tab [compose::editor] # Keybindings used when the embedded terminal is selected in the compose view $noinherit = true $ex = = :prev-field = :prev-field = :next-field = :next-field = :prev-tab = :prev-tab = :next-tab = :next-tab [compose::review] # Keybindings used when reviewing a message to be sent # Inline comments are used as descriptions on the review screen y = :send # Send n = :abort # Abort (discard message, no confirmation) s = :sign # Toggle signing x = :encrypt # Toggle encryption to all recipients v = :preview # Preview message p = :postpone # Postpone q = :choose -o d discard abort -o p postpone postpone # Abort or postpone e = :edit # Edit (body and headers) a = :attach # Add attachment d = :detach # Remove attachment [terminal] $noinherit = true $ex = = :prev-tab = :next-tab = :prev-tab = :next-tab #+end_src * Operation Now that I have configured the program to my liking, I can run =aerc= in my terminal and see my changes reflected! Personally, I keep aerc running in a terminal at all times, since it has the operation to ring a bell when a new message arrives. #+caption: Notification #+attr_html: :alt An image of the bell notification on macOS from aerc. [[https://img.cleberg.net/blog/20251102-aerc-macos/notification.webp]] The mailbox views and composition screens are fairly standard, but it does a great job at displaying information effectively. #+caption: Inbox #+attr_html: :alt An image of the aerc inbox view. [[https://img.cleberg.net/blog/20251102-aerc-macos/inbox.webp]] #+caption: Compose Message #+attr_html: :alt An image of Emacs being used as the composition window for aerc. [[https://img.cleberg.net/blog/20251102-aerc-macos/compose.webp]] #+caption: Send Message #+attr_html: :alt An image of the aerc commands to send an email. [[https://img.cleberg.net/blog/20251102-aerc-macos/send.webp]] #+caption: Read Message #+attr_html: :alt An image of an email opened in aerc's reading window. [[https://img.cleberg.net/blog/20251102-aerc-macos/read.webp]] All in all, I love aerc and far prefer it to my previous client (neomutt). In certain cases, Thunderbird is more convenient, but I don't find myself opening it at all lately. I will definitely update this post in the future if I find anything extraordinary to add about aerc.