cmc/cleberg.net

  1#+date:        [2025-11-02 Sun 10:07:14]
  2#+title:       Using aerc on macOS
  3#+description: How I use aerc, a TUI email client, on macOS.
  4#+slug: aerc-macos
  5#+filetags:    :linux:
  6
  7#+caption: aerc-mail
  8#+attr_html: :alt An image of aerc with an email opened in the reader window.
  9https://img.cleberg.net/blog/20251102-aerc-macos/read.webp
 10
 11Shout-out to [[https://baty.net/posts/2025/10/using-aerc-for-email/][Jack Baty]] for inspiring me to write about my =aerc-mail= client
 12after chatting about it over email recently!
 13
 14* Overview
 15
 16[[https://aerc-mail.org/][aerc]] is a text user interface (TUI) email client with intuitive defaults, easy
 17setup, and hassle-free operations. This post will walk through my personal
 18configuration for aerc on macOS.
 19
 20* Installation
 21
 22Since I am on macOS, I opted to install aerc from Homebrew. There are build
 23options for additional modules if you build from source, but I am okay with the
 24default options.
 25
 26You can view the information about the package prior to installing it, if you
 27wish:
 28
 29#+begin_src sh
 30brew info aerc
 31#+end_src
 32
 33#+begin_src sh
 34==> aerc: stable 0.21.0 (bottled), HEAD
 35Email client that runs in your terminal
 36https://aerc-mail.org/
 37Installed
 38/opt/homebrew/Cellar/aerc/0.21.0 (48 files, 23MB) *
 39  Poured from bottle using the formulae.brew.sh API on 2025-10-05 at 19:51:31
 40From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/a/aerc.rb
 41License: MIT
 42==> Dependencies
 43Build: go ✘, scdoc ✘
 44Required: notmuch ✔
 45==> Options
 46--HEAD
 47	Install HEAD version
 48==> Downloading https://formulae.brew.sh/api/formula/aerc.json
 49==> Analytics
 50install: 136 (30 days), 560 (90 days), 1,772 (365 days)
 51install-on-request: 136 (30 days), 560 (90 days), 1,772 (365 days)
 52build-error: 3 (30 days)
 53#+end_src
 54
 55Once you confirm you want to install this package, run the following:
 56
 57#+begin_src sh
 58brew install aerc
 59#+end_src
 60
 61* First-Time Wizard
 62
 63When you run aerc for the first time, an IMAP & SMTP wizard will walk you
 64through a basic setup for your email account(s).
 65
 66On macOS, aerc will save your configuration files in the following location:
 67=~/Library/Preferences/aerc=.
 68
 69I tried to create a =~/.config/aerc= directory, but the Library directory above
 70took precedence. If you truly need to keep your files in =~/.config=, you could
 71probably symlink that to the Library location. However, I accepted my fate and
 72will just edit the files within the Library directory.
 73
 74* Configuration
 75
 76Once you have installed and setup aerc for the first time, you can configure the
 77client and account settings.
 78
 79As noted above, I will be working within the Library directory that aerc
 80defaults to when installed via brew.
 81
 82#+begin_src sh
 83cd ~/Library/Preferences/aerc
 84#+end_src
 85
 86This directory should contain the following files. You can open the
 87=accounts.conf= file to confirm it contains the information you input during the
 88wizard process.
 89
 90| File            | Purpose                                                     |
 91|-----------------+-------------------------------------------------------------|
 92| =accounts.conf= | Contains account-specific settings for IMAP & SMTP accounts |
 93| =aerc.conf=     | Contains program-wide settings                              |
 94| =binds.conf=    | Contains key bindings for aerc                              |
 95
 96I'll share my personal configuration, which is close to the defaults that
 97existed at the time of writing this post.
 98
 99=accounts.conf=
100
101This is the information from the wizard. The only further customization I
102provided is the default signature file to be appended to each message I compose.
103
104#+begin_src conf
105[Personal]
106source         = imaps://hello%40cleberg.net:PASSWORD@imap.migadu.com
107outgoing       = smtps://hello%40cleberg.net:PASSWORD@smtp.migadu.com
108default        = INBOX
109from           = Christian Cleberg <hello@cleberg.net>
110copy-to        = Sent
111cache-headers  = true
112signature-file = /Users/cmc/Library/Preferences/aerc/sigs/default
113#+end_src
114
115=sigs/default=
116
117Any content within this file will be appended to my messages, as noted above.
118
119#+begin_src text
120Christian Cleberg <hello@cleberg.net>
121GPG: 3917 973F B159 BBB8 6194 5385 69451A51 7AC0 CB37
122#+end_src
123
124=aerc.conf=
125
126This contains quite a few customizations for my preferences related to
127downloads, encryption, mouse controls, editor, and message composition.
128
129#+begin_src conf
130[general]
131# Prefer downloads to be saved to the Downloads folder
132default-save-path=~/Downloads
133# Use GPG for PGP encryption
134pgp-provider=gpg
135
136[ui]
137# Enable mouse controls for scrolling, paging, etc.
138mouse-enabled=true
139
140[statusline]
141[viewer]
142# Use emacs instead of vi
143pager=/usr/local/bin/emacs_viewer
144
145[compose]
146# Use emacs instead of vi
147editor=emacs
148# Add Cc as a default field to view each time I compose a message
149header-layout=To|From,Cc,Subject
150# Allow me to edit headers when composing (so I can customize From address)
151edit-headers=true
152# Warn me if I mentioned these words but don't attach a file
153empty-subject-warning=true
154no-attachment-warning=^[^>]*attach(ed|ment)
155
156[multipart-converters]
157
158[filters]
159text/plain=colorize
160text/calendar=calendar
161message/delivery-status=colorize
162message/rfc822=colorize
163text/html=! html
164.headers=colorize
165
166[openers]
167[hooks]
168[templates]
169#+end_src
170
171#+begin_quote
172*IMPORTANT*: If you use the =pager= option above that I'm using, you will need
173 to create the =emacs_viewer= file as well.
174#+end_quote
175
176You can create the file following my process below, which will create an
177executable in the location specified in my =aerc.conf= file. I put it in
178=/usr/local/bin=, but you can put it anywhere as long as it exists in the file
179path specific within your configuration file.
180
181#+begin_src sh
182sudo nano /usr/local/bin/emacs_viewer
183#+end_src
184
185Paste this inside the file:
186
187#+begin_src sh
188#!/bin/bash
189emacs -nw - < "$1"
190#+end_src
191
192#+begin_src sh
193sudo chmod +x /usr/local/bin/emacs_viewer
194#+end_src
195
196=binds.conf=
197
198Finally, here are the key bindings. I did not change these, but I'm showing them
199here in case you have an issue and want to see the defaults.
200
201#+begin_src conf
202# Binds are of the form <key sequence> = <command to run>
203# To use '=' in a key sequence, substitute it with "Eq": "<Ctrl+Eq>"
204# If you wish to bind #, you can wrap the key sequence in quotes: "#" = quit
205<C-p> = :prev-tab<Enter>
206<C-PgUp> = :prev-tab<Enter>
207<C-n> = :next-tab<Enter>
208<C-PgDn> = :next-tab<Enter>
209\[t = :prev-tab<Enter>
210\]t = :next-tab<Enter>
211<C-t> = :term<Enter>
212? = :help keys<Enter>
213<C-c> = :prompt 'Quit?' quit<Enter>
214<C-q> = :prompt 'Quit?' quit<Enter>
215<C-z> = :suspend<Enter>
216
217[messages]
218q = :prompt 'Quit?' quit<Enter>
219
220j = :next<Enter>
221<Down> = :next<Enter>
222<C-d> = :next 50%<Enter>
223<C-f> = :next 100%<Enter>
224<PgDn> = :next 100%<Enter>
225
226k = :prev<Enter>
227<Up> = :prev<Enter>
228<C-u> = :prev 50%<Enter>
229<C-b> = :prev 100%<Enter>
230<PgUp> = :prev 100%<Enter>
231g = :select 0<Enter>
232G = :select -1<Enter>
233
234J = :next-folder<Enter>
235<C-Down> = :next-folder<Enter>
236K = :prev-folder<Enter>
237<C-Up> = :prev-folder<Enter>
238H = :collapse-folder<Enter>
239<C-Left> = :collapse-folder<Enter>
240L = :expand-folder<Enter>
241<C-Right> = :expand-folder<Enter>
242
243v = :mark -t<Enter>
244<Space> = :mark -t<Enter>:next<Enter>
245V = :mark -v<Enter>
246
247T = :toggle-threads<Enter>
248zc = :fold<Enter>
249zo = :unfold<Enter>
250za = :fold -t<Enter>
251zM = :fold -a<Enter>
252zR = :unfold -a<Enter>
253<tab> = :fold -t<Enter>
254
255zz = :align center<Enter>
256zt = :align top<Enter>
257zb = :align bottom<Enter>
258
259<Enter> = :view<Enter>
260d = :choose -o y 'Really delete this message' delete-message<Enter>
261D = :delete<Enter>
262a = :archive flat<Enter>
263A = :unmark -a<Enter>:mark -T<Enter>:archive flat<Enter>
264
265C = :compose<Enter>
266m = :compose<Enter>
267
268b = :bounce<space>
269
270rr = :reply -a<Enter>
271rq = :reply -aq<Enter>
272Rr = :reply<Enter>
273Rq = :reply -q<Enter>
274
275c = :cf<space>
276$ = :term<space>
277! = :term<space>
278| = :pipe<space>
279
280/ = :search<space>
281\ = :filter<space>
282n = :next-result<Enter>
283N = :prev-result<Enter>
284<Esc> = :clear<Enter>
285
286s = :split<Enter>
287S = :vsplit<Enter>
288
289pl = :patch list<Enter>
290pa = :patch apply <Tab>
291pd = :patch drop <Tab>
292pb = :patch rebase<Enter>
293pt = :patch term<Enter>
294ps = :patch switch <Tab>
295
296[messages:folder=Drafts]
297<Enter> = :recall<Enter>
298
299[view]
300/ = :toggle-key-passthrough<Enter>/
301q = :close<Enter>
302O = :open<Enter>
303o = :open<Enter>
304S = :save<space>
305| = :pipe<space>
306D = :delete<Enter>
307A = :archive flat<Enter>
308
309<C-y> = :copy-link <space>
310<C-l> = :open-link <space>
311
312f = :forward<Enter>
313rr = :reply -a<Enter>
314rq = :reply -aq<Enter>
315Rr = :reply<Enter>
316Rq = :reply -q<Enter>
317
318H = :toggle-headers<Enter>
319<C-k> = :prev-part<Enter>
320<C-Up> = :prev-part<Enter>
321<C-j> = :next-part<Enter>
322<C-Down> = :next-part<Enter>
323J = :next<Enter>
324<C-Right> = :next<Enter>
325K = :prev<Enter>
326<C-Left> = :prev<Enter>
327
328[view::passthrough]
329$noinherit = true
330$ex = <C-x>
331<Esc> = :toggle-key-passthrough<Enter>
332
333[compose]
334# Keybindings used when the embedded terminal is not selected in the compose
335# view
336$noinherit = true
337$ex = <C-x>
338$complete = <C-o>
339<C-k> = :prev-field<Enter>
340<C-Up> = :prev-field<Enter>
341<C-j> = :next-field<Enter>
342<C-Down> = :next-field<Enter>
343<A-p> = :switch-account -p<Enter>
344<C-Left> = :switch-account -p<Enter>
345<A-n> = :switch-account -n<Enter>
346<C-Right> = :switch-account -n<Enter>
347<tab> = :next-field<Enter>
348<backtab> = :prev-field<Enter>
349<C-p> = :prev-tab<Enter>
350<C-PgUp> = :prev-tab<Enter>
351<C-n> = :next-tab<Enter>
352<C-PgDn> = :next-tab<Enter>
353
354[compose::editor]
355# Keybindings used when the embedded terminal is selected in the compose view
356$noinherit = true
357$ex = <C-x>
358<C-k> = :prev-field<Enter>
359<C-Up> = :prev-field<Enter>
360<C-j> = :next-field<Enter>
361<C-Down> = :next-field<Enter>
362<C-p> = :prev-tab<Enter>
363<C-PgUp> = :prev-tab<Enter>
364<C-n> = :next-tab<Enter>
365<C-PgDn> = :next-tab<Enter>
366
367[compose::review]
368# Keybindings used when reviewing a message to be sent
369# Inline comments are used as descriptions on the review screen
370y = :send<Enter> # Send
371n = :abort<Enter> # Abort (discard message, no confirmation)
372s = :sign<Enter> # Toggle signing
373x = :encrypt<Enter> # Toggle encryption to all recipients
374v = :preview<Enter> # Preview message
375p = :postpone<Enter> # Postpone
376q = :choose -o d discard abort -o p postpone postpone<Enter> # Abort or postpone
377e = :edit<Enter> # Edit (body and headers)
378a = :attach<space> # Add attachment
379d = :detach<space> # Remove attachment
380
381[terminal]
382$noinherit = true
383$ex = <C-x>
384
385<C-p> = :prev-tab<Enter>
386<C-n> = :next-tab<Enter>
387<C-PgUp> = :prev-tab<Enter>
388<C-PgDn> = :next-tab<Enter>
389#+end_src
390
391* Operation
392
393Now that I have configured the program to my liking, I can run =aerc= in my
394terminal and see my changes reflected!
395
396Personally, I keep aerc running in a terminal at all times, since it has the
397operation to ring a bell when a new message arrives.
398
399#+caption: Notification
400#+attr_html: :alt An image of the bell notification on macOS from aerc.
401[[https://img.cleberg.net/blog/20251102-aerc-macos/notification.webp]]
402
403The mailbox views and composition screens are fairly standard, but it does a
404great job at displaying information effectively.
405
406#+caption: Inbox
407#+attr_html: :alt An image of the aerc inbox view.
408[[https://img.cleberg.net/blog/20251102-aerc-macos/inbox.webp]]
409
410#+caption: Compose Message
411#+attr_html: :alt An image of Emacs being used as the composition window for aerc.
412[[https://img.cleberg.net/blog/20251102-aerc-macos/compose.webp]]
413
414#+caption: Send Message
415#+attr_html: :alt An image of the aerc commands to send an email.
416[[https://img.cleberg.net/blog/20251102-aerc-macos/send.webp]]
417
418#+caption: Read Message
419#+attr_html: :alt An image of an email opened in aerc's reading window.
420[[https://img.cleberg.net/blog/20251102-aerc-macos/read.webp]]
421
422All in all, I love aerc and far prefer it to my previous client (neomutt). In
423certain cases, Thunderbird is more convenient, but I don't find myself opening
424it at all lately. I will definitely update this post in the future if I find
425anything extraordinary to add about aerc.