1aerc-config(5) File Formats Manual aerc-config(5)
2
6 aerc-config - configuration file formats for aerc(1)
7
9 There are three aerc config files: aerc.conf, binds.conf, and ac‐
10 counts.conf. The last one must be kept secret, as it may include your
11 account credentials. We look for these files in your XDG config home
12 plus "aerc", which defaults to ~/.config/aerc.
13 Examples of these config files are typically included with your instal‐
15 lation of aerc and are usually installed in /usr/share/aerc.
16 Each file uses the ini format, and consists of sections with keys and
18 values. A line beginning with # is considered a comment and ignored, as
19 are empty lines. New sections begin with [section-name] on a single
20 line, and keys and values are separated with "=".
21
23 This file is used for configuring the general appearance and behavior
24 of aerc.
25 GENERAL OPTIONS
27 These options are configured in the [general] section of aerc.conf.
28 default-save-path
30 Used as a default path for save operations if no other path is
31 specified.
32 UI OPTIONS
34 These options are configured in the [ui] section of aerc.conf.
35 index-format
37 Describes the format for each row in a mailbox view. This field is
38 compatible with mutt's printf-like syntax.
39 Default: %D %-17.17n %s
41 ┌─────────────────┬────────────────────────────┐
43 │Format specifier │ Description │
44 ├─────────────────┼────────────────────────────┤
45 │ %% │ literal % │
46 ├─────────────────┼────────────────────────────┤
47 │ %a │ sender address │
48 ├─────────────────┼────────────────────────────┤
49 │ %A │ reply-to address, or │
50 │ │ sender address if none │
51 ├─────────────────┼────────────────────────────┤
52 │ %C │ message number │
53 ├─────────────────┼────────────────────────────┤
54 │ %d │ formatted message time‐ │
55 │ │ stamp │
56 ├─────────────────┼────────────────────────────┤
57 │ %D │ formatted message time‐ │
58 │ │ stamp converted to local │
59 │ │ timezone │
60 ├─────────────────┼────────────────────────────┤
61 │ %f │ sender name and address │
62 ├─────────────────┼────────────────────────────┤
63 │ %F │ author name, or recipient │
64 │ │ name if the message is │
65 │ │ from you. The address is │
66 │ │ shown if no name part. │
67 ├─────────────────┼────────────────────────────┤
68 │ %g │ message labels (for exam‐ │
69 │ │ ple notmuch tags) │
70 ├─────────────────┼────────────────────────────┤
71 │ %i │ message id │
72 ├─────────────────┼────────────────────────────┤
73 │ %n │ sender name, or sender ad‐ │
74 │ │ dress if none │
75 ├─────────────────┼────────────────────────────┤
76 │ %r │ comma-separated list of │
77 │ │ formatted recipient names │
78 │ │ and addresses │
79 ├─────────────────┼────────────────────────────┤
80 │ %R │ comma-separated list of │
81 │ │ formatted CC names and ad‐ │
82 │ │ dresses │
83 ├─────────────────┼────────────────────────────┤
84 │ %s │ subject │
85 ├─────────────────┼────────────────────────────┤
86 │ %t │ the (first) address the │
87 │ │ new email was sent to │
88 ├─────────────────┼────────────────────────────┤
89 │ %T │ the account name which re‐ │
90 │ │ ceived the email │
91 ├─────────────────┼────────────────────────────┤
92 │ %u │ sender mailbox name (e.g. │
93 │ │ "smith" in "smith@exam‐ │
94 │ │ ple.net") │
95 ├─────────────────┼────────────────────────────┤
96 │ %v │ sender first name (e.g. │
97 │ │ "Alex" in "Alex Smith │
98 │ │ <smith@example.net>") │
99 ├─────────────────┼────────────────────────────┤
100 │ %Z │ flags (O=old, N=new, r=an‐ │
101 │ │ swered, D=deleted, │
102 │ │ !=flagged, *=marked) │
103 └─────────────────┴────────────────────────────┘
104 timestamp-format
105 See time.Time#Format at https://godoc.org/time#Time.Format
106 Default: 2006-01-02 03:04 PM (ISO 8601 + 12 hour time)
108 sidebar-width
110 Width of the sidebar, including the border. Set to zero to disable
111 the sidebar.
112 Default: 20
114 empty-message
116 Message to display when viewing an empty folder.
117 Default: (no messages)
119 empty-dirlist
121 Message to display when no folders exists or are all filtered.
122 Default: (no folders)
124 mouse-enabled
126 Enable mouse events in the ui, e.g. clicking and scrolling with the
127 mousewheel
128 Default: false
130 new-message-bell
132 Ring the bell when a new message is received.
133 Default: true
135 pinned-tab-marker
137 Marker to show before a pinned tab's name.
138 Default: `
140 spinner
142 Animation shown while loading, split by spinner-delimiter (below)
143 Examples:
145 • spinner = "-_-,_-_"
146 • spinner = '. , .'
147 • spinner = ",|,/,-"
148 Default: "[..] , [..] , [..] , [..] , [..], [..] ,
151 [..] , [..] "
152 spinner-delimiter
154 Spinner delimiter to split string into an animation
155 Default: ","
157 sort
159 List of space-separated criteria to sort the messages by, see sort
160 command in aerc(1) for reference. Prefixing a criterion with "-r "
161 reverses that criterion.
162 Example: "from -r date"
164 Default: ""
166 dirlist-format
168 Describes the format string to use for the directory list
169 Default: %n %>r
171 ┌─────────────────┬───────────────────────────┐
173 │Format specifier │ Description │
174 ├─────────────────┼───────────────────────────┤
175 │ %% │ literal % │
176 ├─────────────────┼───────────────────────────┤
177 │ %n │ directory name │
178 ├─────────────────┼───────────────────────────┤
179 │ %r │ recent/unseen/total mes‐ │
180 │ │ sage count │
181 ├─────────────────┼───────────────────────────┤
182 │ %>X │ make format specifier 'X' │
183 │ │ be right justified │
184 └─────────────────┴───────────────────────────┘
185 next-message-on-delete
186 Moves to next message when the current message is deleted
187 Default: true
189 completion-popovers
191 Shows potential auto-completions for text inputs in popovers.
192 Default: true
194 completion-delay
196 How long to wait after the last input before auto-completion is
197 triggered.
198 Default: 250ms
200 stylesets-dirs
202 The directories where the stylesets are stored. The config takes a
203 colon-seperated list of dirs.
204 Default: "/usr/share/aerc/stylesets"
206 styleset-name
208 The name of the styleset to be used to style the ui elements. The
209 stylesets are stored in the 'stylesets' directory in the config di‐
210 rectory.
211 Default: default
213 Have a look at aerc-stylesets(7) as to how a styleset looks like.
215 Contextual UI Configuration
217 The UI configuration can be specialized for accounts, specific mail di‐
218 rectories and message subjects. The specializations are added using
219 contextual config sections based on the context.
220 The contextual UI configuration is merged to the base UiConfig in the
222 following order: Base UIConfig > Account Context > Folder Context >
223 Subject Context.
224 [ui:account=<AccountName>]
226 Adds account specific configuration with the account name.
227 [ui:folder=<FolderName>]
229 Add folder specific configuration with the folder name.
230 [ui:folder~<Regex>]
232 Add folder specific configuration for folders whose names match the
233 regular expression.
234 [ui:subject~<Regex>]
236 Add specialized ui configuration for messages that match a given
237 regular expression.
238 Example:
240 [ui:account=Work]
241 sidebar-width=...
242 [ui:folder=Sent]
244 index-format=...
245 [ui:folder~Archive/d+/.*]
247 index-format=...
248 [ui:subject~^[PATCH]
250 index-format=...
251 VIEWER
253 These options are configured in the [viewer] section of aerc.conf.
254 pager
256 Specifies the pager to use when displaying emails. Note that some
257 filters may add ANSI escape sequences to add color to rendered
258 emails, so you may want to use a pager which supports ANSI.
259 Default: less -R
261 alternatives
263 If an email offers several versions (multipart), you can configure
264 which mimetype to prefer. For example, this can be used to prefer
265 plaintext over HTML emails.
266 Default: text/plain,text/html
268 header-layout
270 Defines the default headers to display when viewing a message. To
271 display multiple headers in the same row, separate them with a
272 pipe, e.g. "From|To". Rows will be hidden if none of their speci‐
273 fied headers are present in the message.
274 Default: From|To,Cc|Bcc,Date,Subject
276 show-headers
278 Default setting to determine whether to show full headers or only
279 parsed ones in message viewer.
280 Default: false
282 always-show-mime
284 Whether to always show the mimetype of an email, even when it is
285 just a single part.
286 Default: false
288 COMPOSE
290 These options are configured in the [compose] section of aerc.conf.
291 editor
293 Specifies the command to run the editor with. It will be shown in
294 an embedded terminal, though it may also launch a graphical window
295 if the environment supports it. Defaults to $EDITOR, or vi(1).
296 header-layout
298 Defines the default headers to display when composing a message. To
299 display multiple headers in the same row, separate them with a
300 pipe, e.g. "To|From".
301 Default: To|From,Subject
303 address-book-cmd
305 Specifies the command to be used to tab-complete email addresses.
306 Any occurrence of "%s" in the address-book-cmd will be replaced
307 with what the user has typed so far.
308 The command must output the completions to standard output, one
310 completion per line. Each line must be tab-delimited, with an email
311 address occurring as the first field. Only the email address field
312 is required. The second field, if present, will be treated as the
313 contact name. Additional fields are ignored.
314 Example:
316 khard email --remove-first-line --parsable '%s'
317 Default: none
319 FILTERS
321 Filters allow you to pipe an email body through a shell command to ren‐
322 der certain emails differently, e.g. highlighting them with ANSI escape
323 codes. They are configured in the [filters] section of aerc.conf.
324 The first filter which matches the email's mimetype will be used, so
326 order them from most to least specific.
327 You can also match on non-mimetypes, by prefixing with the header to
329 match against (non-case-sensitive) and a comma, e.g. subject,text will
330 match a subject which contains "text". Use header,~regex to match
331 against a regex.
332 aerc ships with some default filters installed in the share directory
334 (usually /usr/share/aerc/filters). Note that these may have additional
335 dependencies that aerc does not have alone.
336 TRIGGERS
338 Triggers specify commands to execute when certain events occur.
339 They are configured in the [triggers] section of aerc.conf.
341 new-email
343 Executed when a new email arrives in the selected folder.
344 e.g. new-email=exec notify-send "New email from %n" "%s"
346 Default: ""
348 Format specifiers from index-format are expanded with respect to
350 the new message.
351 TEMPLATES
353 Templates are used to populate the body of an email. The compose, reply
354 and forward commands can be called with the -T flag with the name of
355 the template name.
356 aerc ships with some default templates installed in the share directory
358 (usually /usr/share/aerc/templates).
359 These options are configured in the [templates] section of aerc.conf.
361 template-dirs
363 The directory where the templates are stored. The config takes a
364 colon-separated list of dirs.
365 Default: "/usr/share/aerc/templates"
367 quoted-reply
369 The template to be used for quoted replies.
370 Default: "quoted_reply"
372 forwards
374 The template to be used for forward as body.
375 Default: "forward_as_body"
377
379 This file is used for configuring each mail account used for aerc. Each
380 section is the name of an account you want to configure, and the keys &
381 values in that section specify details of that account's configuration.
382 In addition to the options documented here, specific transports for in‐
383 coming and outgoing emails may have additional configuration parame‐
384 ters, documented on their respective man pages.
385 Note that many of these configuration options are written for you, such
387 as source and outgoing, when you run the account configuration wizard
388 (:new-account).
389 archive
391 Specifies a folder to use as the destination of the :archive com‐
392 mand.
393 Default: Archive
395 copy-to
397 Specifies a folder to copy sent mails to, usually "Sent".
398 Default: none
400 default
402 Specifies the default folder to open in the message list when aerc
403 configures this account.
404 Default: INBOX
406 folders
408 Specifies the comma separated list of folders to display in the
409 sidebar. Names prefixed with ~ are interpreted as regular expres‐
410 sions.
411 Default: all folders
413 folders-exclude
415 Specifies the comma separated list of folders to exclude from the
416 sidebar. Names prefixed with ~ are interpreted as regular expres‐
417 sions. Note that this overrides anything from folders.
418 Default: no folders
420 folders-sort
422 Specifies a comma separated list of folders to be shown at the top
423 of the list in the provided order. Remaining folders will be sorted
424 alphabetically.
425 Default: none
427 from
429 The default value to use for the From header in new emails. This
430 should be an RFC 5322-compatible string, such as "Your Name
431 <you@example.org>".
432 Default: none
434 aliases
436 All aliases of the current account. These will be used to fill in
437 the From: field. Make sure that your email server accepts this
438 value, or for example use aerc-sendmail(5) in combination with
439 msmtp and --read-envelope-from.
440 Default: none
442 outgoing
444 Specifies the transport for sending outgoing emails on this ac‐
445 count. It should be a connection string, and the specific meaning
446 of each component varies depending on the protocol in use. See
447 each protocol's man page for more details:
448 • aerc-smtp(5)
450 outgoing-cred-cmd
453 Specifies an optional command that is run to get the outgoing ac‐
454 count's password. See each protocol's man page for more details.
455 Default: none
457 postpone
459 Specifies the folder to save postponed messages to.
460 Default: Drafts
462 source
464 Specifies the source for reading incoming emails on this account.
465 This key is required for all accounts. It should be a connection
466 string, and the specific meaning of each component varies depending
467 on the protocol in use. See each protocol's man page for more de‐
468 tails:
469 • aerc-imap(5)
471 • aerc-maildir(5)
472 • aerc-notmuch(5)
473 Default: none
476 source-cred-cmd
478 Specifies an optional command that is run to get the source ac‐
479 count's password. See each protocol's man page for more details.
480 signature-file
482 Specifies the file to read in order to obtain the signature to be
483 added to emails sent from this account.
484 signature-cmd
486 Specifies the command to execute in sh in order to obtain the sig‐
487 nature to be added to emails sent from this account. If the command
488 fails then signature-file is used instead.
489
491 This file is used for configuring keybindings used in the aerc interac‐
492 tive client. You may configure different keybindings for different con‐
493 texts by writing them into different [sections] of the ini file. The
494 available contexts are:
495 [messages]
497 keybindings for the message list
498 [view]
500 keybindings for the message viewer
501 [compose]
503 keybindings for the message composer
504 [compose::editor]
506 keybindings for the composer, when the editor is focused
507 [compose::review]
509 keybindings for the composer, when reviewing the email before it's
510 sent
511 [terminal]
513 keybindings for terminal tabs
514 You may also configure global keybindings by placing them at the begin‐
516 ning of the file, before specifying any context-specific sections. For
517 each key=value option specified, the key is the keystrokes pressed (in
518 order) to invoke this keybinding, and value specifies keystrokes that
519 aerc will simulate when the keybinding is invoked. Generally this is
520 used to execute commands, for example:
521 rq = :reply -q<Enter>
523 Pressing r, then q, will simulate typing in ":reply -q<Enter>", and ex‐
525 ecute :reply -q accordingly. It is also possible to invoke keybindings
526 recursively in a similar fashion. Additionally, the following special
527 options are available in each binding context:
528 $noinherit
530 If set to "true", global keybindings will not be effective in this
531 context.
532 Default: false
534 $ex
536 This can be set to a keystroke which will bring up the command in‐
537 put in this context.
538 Default: <semicolon>
540 In addition to letters, special keys may be specified in <angle brack‐
542 ets>. The following special keys are supported:
543 ┌──────────┬─────────────┐
545 │Name │ Description │
546 ├──────────┼─────────────┤
547 │space │ " " │
548 ├──────────┼─────────────┤
549 │semicolon │ ; │
550 ├──────────┼─────────────┤
551 │tab │ │
552 ├──────────┼─────────────┤
553 │enter │ │
554 ├──────────┼─────────────┤
555 │up │ │
556 ├──────────┼─────────────┤
557 │down │ │
558 ├──────────┼─────────────┤
559 │right │ │
560 ├──────────┼─────────────┤
561 │left │ │
562 ├──────────┼─────────────┤
563 │pgup │ │
564 ├──────────┼─────────────┤
565 │pgdn │ │
566 ├──────────┼─────────────┤
567 │home │ │
568 ├──────────┼─────────────┤
569 │end │ │
570 ├──────────┼─────────────┤
571 │insert │ │
572 ├──────────┼─────────────┤
573 │delete │ │
574 ├──────────┼─────────────┤
575 │exit │ │
576 ├──────────┼─────────────┤
577 │cancel │ │
578 ├──────────┼─────────────┤
579 │print │ │
580 ├──────────┼─────────────┤
581 │pause │ │
582 ├──────────┼─────────────┤
583 │backtab │ │
584 ├──────────┼─────────────┤
585 │c-space │ Ctrl+Space │
586 ├──────────┼─────────────┤
587 │c-a │ Ctrl+a │
588 ├──────────┼─────────────┤
589 │c-b │ Ctrl+b │
590 ├──────────┼─────────────┤
591 │c-c │ Ctrl+c │
592 ├──────────┼─────────────┤
593 │c-d │ Ctrl+d │
594 ├──────────┼─────────────┤
595 │c-e │ Ctrl+e │
596 ├──────────┼─────────────┤
597 │c-f │ Ctrl+f │
598 ├──────────┼─────────────┤
599 │c-g │ Ctrl+g │
600 ├──────────┼─────────────┤
601 │c-h │ Ctrl+h │
602 ├──────────┼─────────────┤
603 │c-i │ Ctrl+i │
604 ├──────────┼─────────────┤
605 │c-j │ Ctrl+j │
606 ├──────────┼─────────────┤
607 │c-k │ Ctrl+k │
608 ├──────────┼─────────────┤
609 │c-l │ Ctrl+l │
610 ├──────────┼─────────────┤
611 │c-m │ Ctrl+m │
612 ├──────────┼─────────────┤
613 │c-n │ Ctrl+n │
614 ├──────────┼─────────────┤
615 │c-o │ Ctrl+o │
616 ├──────────┼─────────────┤
617 │c-p │ Ctrl+p │
618 ├──────────┼─────────────┤
619 │c-q │ Ctrl+q │
620 ├──────────┼─────────────┤
621 │c-r │ Ctrl+r │
622 ├──────────┼─────────────┤
623 │c-s │ Ctrl+s │
624 ├──────────┼─────────────┤
625 │c-t │ Ctrl+t │
626 ├──────────┼─────────────┤
627 │c-u │ Ctrl+u │
628 ├──────────┼─────────────┤
629 │c-v │ Ctrl+v │
630 ├──────────┼─────────────┤
631 │c-w │ Ctrl+w │
632 ├──────────┼─────────────┤
633 │c-x │ Ctrl+x │
634 ├──────────┼─────────────┤
635 │c-y │ Ctrl+y │
636 ├──────────┼─────────────┤
637 │c-z │ Ctrl+z │
638 ├──────────┼─────────────┤
639 │c-] │ Ctrl+] │
640 ├──────────┼─────────────┤
641 │c-[ │ Ctrl+[ │
642 ├──────────┼─────────────┤
643 │c-^ │ Ctrl+^ │
644 ├──────────┼─────────────┤
645 │c-_ │ Ctrl+_ │
646 └──────────┴─────────────┘
647
649 aerc(1) aerc-imap(5) aerc-smtp(5) aerc-maildir(5) aerc-sendmail(5)
650 aerc-notmuch(5) aerc-stylesets(7)
651
653 Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other
654 open source contributors. For more information about aerc development,
655 see https://git.sr.ht/~sircmpwn/aerc.
656 2021-07-21 aerc-config(5)