1AERC(1)                     General Commands Manual                    AERC(1)
2
3
4

NAME

6       aerc - a pretty good email client.
7

SYNOPSIS

9       aerc [-v] [-a <account>[,<account>]] [mailto:...]
10
11       For a guided tutorial, use :help tutorial from aerc, or man aerc-tuto‐
12       rial from your terminal.
13

OPTIONS

15       -v
16           Prints the installed version of aerc and exits.
17
18       -a <account>[,<account>]
19           Load only the named accounts, as opposed to all configured ac‐
20           counts. List must be comma separated, with no spaces. The account
21           order will be preserved.
22
23       mailto:address[,address][?query[&query]]
24           Opens the composer with the address(es) in the To field. These ad‐
25           dresses must not be percent encoded. If aerc is already running,
26           the composer is started in this instance, otherwise aerc will be
27           started. The following (optional) query parameters are supported:
28
29       ┌──────────────────────────┬────────────────────────────┐
30Query                     Description                
31       ├──────────────────────────┼────────────────────────────┤
32subject=<text>            │ Subject line will be com‐  │
33       │                          │ pleted with the <text>
34       ├──────────────────────────┼────────────────────────────┤
35body=<text>               │ Message body will be com‐  │
36       │                          │ pleted with the <text>
37       ├──────────────────────────┼────────────────────────────┤
38cc=<address>[,<address>]  │ Cc header will be com‐     │
39       │                          │ pleted with the list of    │
40       │                          │ addresses                  │
41       ├──────────────────────────┼────────────────────────────┤
42bcc=<address>[,<address>] │ Bcc header will be com‐    │
43       │                          │ pleted with the list of    │
44       │                          │ addresses                  │
45       ├──────────────────────────┼────────────────────────────┤
46in-reply-to=<message-id>  │ In-reply-to header will be │
47       │                          │ set to the message id      │
48       ├──────────────────────────┼────────────────────────────┤
49account=<accountname>     │ Specify the account (must  │
50       │                          │ be in accounts.conf; de‐   │
51       │                          │ fault is the selected ac‐  │
52       │                          │ count)                     │
53       ├──────────────────────────┼────────────────────────────┤
54template=<template-file>  │ Template sets the template │
55       │                          │ file for creating the mes‐ │
56       │                          │ sage                       │
57       └──────────────────────────┴────────────────────────────┘
58           Note that reserved characters in the queries must be percent en‐
59           coded.
60
61       :command [...]
62           Run an aerc-internal command as you would in Ex-Mode. See RUNTIME
63           COMMANDS below.
64

RUNTIME COMMANDS

66       To execute a command, press : to bring up the command interface. Com‐
67       mands may also be bound to keys, see aerc-binds(5) for details. In some
68       contexts, such as the terminal emulator, <c-x> is used to bring up the
69       command interface.
70
71       Different commands work in different contexts, depending on the kind of
72       tab you have selected.
73
74       Dynamic arguments are expanded following aerc-templates(7) depending on
75       the context. For example, if you have a message selected, the following
76       command:
77
78           :filter -f "{{index (.From | emails) 0}}"
79
80       Will filter all messages sent by the same sender.
81
82       Aerc stores a history of commands, which can be cycled through in com‐
83       mand mode. Pressing the up key cycles backwards in history, while
84       pressing down cycles forwards.
85
86   GLOBAL COMMANDS
87       These commands work in any context.
88
89       :cd <directory>
90           Changes aerc's current working directory.
91
92       :z <directory or zoxide query>
93           Changes aerc's current working directory using zoxide. If zoxide is
94           not on $PATH., the command will not be registered.
95
96       :change-tab [+|-]<tab name or index>
97       :ct [+|-]<tab name or index>
98           Changes the focus to the tab with the given name. If a number is
99           given, it's treated as an index. If the number is prepended with +
100           or -, the number is interpreted as a delta from the selected tab.
101           If only a - is given, changes the focus to the previously selected
102           tab.
103
104       :exec <command>
105           Executes an arbitrary command in the background. Aerc will set the
106           environment variables $account and $folder when the command is exe‐
107           cuted from an Account tab or an opened message.
108
109           Note: commands executed in this way are not executed with the
110           shell.
111
112       :eml [<path>]
113       :preview
114           Opens an eml file and displays the message in the message viewer.
115
116           Can also be used in the message viewer to open an rfc822 attachment
117           or in the composer to preview the message.
118
119       :pwd
120           Displays aerc's current working directory in the status bar.
121
122       :term [<command>...]
123       :terminal
124           Opens a new terminal tab with a shell running in the current work‐
125           ing directory, or the specified command.
126
127       :move-tab [+|-]<index>
128           Moves the selected tab to the given index. If + or - is specified,
129           the number is interpreted as a delta from the selected tab.
130
131       :prev-tab [<n>]
132       :next-tab [<n>]
133           Cycles to the previous or next tab in the list, repeating <n> times
134           (default: 1).
135
136       :pin-tab
137           Moves the current tab to the left of all non-pinned tabs and dis‐
138           plays the pinned-tab-marker (default: `) to the left of the tab ti‐
139           tle.
140
141       :unpin-tab
142           Removes the pinned-tab-marker from the current tab and returns the
143           tab to its previous location.
144
145       :prompt <prompt> <command>...
146           Displays the prompt on the status bar, waits for user input, then
147           appends that input as the last argument to the command and executes
148           it. The input is passed as one argument to the command, unless it
149           is empty, in which case no extra argument is added.
150
151       :choose -o <key> <text> <command> [-o <key> <text> <command>]...
152           Prompts the user to choose from various options.
153
154       :quit [-f]
155       :exit [-f]
156           Exits aerc. If a task is being performed that should not be inter‐
157           rupted (like sending a message), a normal quit call might fail. In
158           this case, closing aerc can be forced with the -f option.
159
160   MESSAGE COMMANDS
161       These commands are valid in any context that has a selected message
162       (e.g. the message list, the message in the message viewer, etc).
163
164       :archive <scheme>
165           Moves the selected message to the archive. The available schemes
166           are:
167
168           flat: No special structure, all messages in the archive directory
169
170           year: Messages are stored in folders per year
171
172           month: Messages are stored in folders per year and subfolders per
173           month
174
175       :accept
176           Accepts an iCalendar meeting invitation.
177
178       :accept-tentative
179           Accepts an iCalendar meeting invitation tentatively.
180
181       :copy <target>
182       :cp <target>
183           Copies the selected message to the target folder.
184
185       :decline
186           Declines an iCalendar meeting invitation.
187
188       :delete
189       :delete-message
190           Deletes the selected message.
191
192       :envelope [-h] [-s <format-specifier>]
193           Opens the message envelope in a dialog popup.
194
195           -h: Show all header fields
196
197           -s <format-specifier>
198               User-defined format specifier requiring two %s for the key and
199               value strings. Default format: %-20.20s: %s
200
201       :recall [-f]
202           Opens the selected message for re-editing. Messages can only be re‐
203           called from the postpone directory. The original message is
204           deleted.
205
206           -f: Open the message for re-editing even if it is not in the post‐
207           pone directory. The original message will be deleted only if it is
208           in the postpone directory.
209
210       :forward [-A|-F] [-T <template-file>] [<address>...]
211           Opens the composer to forward the selected message to another re‐
212           cipient.
213
214           -A: Forward the message and all attachments.
215
216           -F: Forward the full message as an RFC 2822 attachment.
217
218           -T <template-file>
219               Use the specified template file for creating the initial mes‐
220               sage body. Unless -F is specified, this defaults to what is set
221               as forwards in the [templates] section of aerc.conf.
222
223       :move <target>
224       :mv <target>
225           Moves the selected message to the target folder.
226
227       :pipe [-bmp] <cmd>
228           Downloads and pipes the selected message into the given shell com‐
229           mand, and opens a new terminal tab to show the result. By default,
230           the selected message part is used in the message viewer and the
231           full message is used in the message list.
232
233           Operates on multiple messages when they are marked. When piping
234           multiple messages, aerc will write them with mbox format separa‐
235           tors.
236
237           -b: Run the command in the background instead of opening a terminal
238           tab
239
240           -m: Pipe the full message
241
242           -p: Pipe just the selected message part, if applicable
243
244           This can be used to apply patch series with git:
245
246               :pipe -m git am -3
247
248           When at least one marked message subject matches a patch series
249           (e.g. [PATCH X/Y]), all marked messages will be sorted by subject
250           to ensure that the patches are applied in order.
251
252       :reply [-acq] [-T <template-file>]
253           Opens the composer to reply to the selected message.
254
255           -a: Reply all
256
257           -c: Close the view tab when replying. If the reply is not sent, re‐
258           open the view tab.
259
260           -q: Insert a quoted version of the selected message into the reply
261           editor
262
263           -T <template-file>
264               Use the specified template file for creating the initial mes‐
265               sage body. If -q is specified, defaults to what is set as
266               quoted-reply in the [templates] section of aerc.conf.
267
268       :read [-t]
269           Marks the marked or selected messages as read.
270
271           -t: Toggle the messages between read and unread.
272
273       :unread [-t]
274           Marks the marked or selected messages as unread.
275
276           -t: Toggle the messages between read and unread.
277
278       :flag [-t] [-a | -x <flag>]
279           Sets (enables) a certain flag on the marked or selected messages.
280
281           -t: Toggle the flag instead of setting (enabling) it.
282
283           -a: Mark message as answered/unanswered.
284
285           -x <flag>: Mark message with specific flag.
286               The available flags are (adapted from RFC 3501, section 2.3.2):
287
288               Seen
289                   Message has been read
290               Answered
291                   Message has been answered
292               Flagged
293                   Message is flagged for urgent/special attention
294
295       :unflag [-t] <flag>
296           Operates exactly like :flag, defaulting to unsetting (disabling)
297           flags.
298
299       :modify-labels [+|-]<label>...
300       :tag [+|-]<label>...
301           Modify message labels (e.g. notmuch tags). Labels prefixed with a +
302           are added, those prefixed with a - removed. As a convenience, la‐
303           bels without either operand add the specified label.
304
305           Example: add inbox and unread labels, remove spam label.
306
307               :modify-labels +inbox -spam unread
308
309       :unsubscribe
310           Attempt to automatically unsubscribe the user from the mailing list
311           through use of the List-Unsubscribe header. If supported, aerc may
312           open a compose window pre-filled with the unsubscribe information
313           or open the unsubscribe URL in a web browser.
314
315   MESSAGE LIST COMMANDS
316       :clear [-s]
317           Clears the current search or filter criteria.
318
319           By default, the selected message will be kept. To clear the se‐
320           lected message and move cursor to the top of the message list, use
321           the -s flag.
322
323           -s: Selects the message at the top of the message list after clear‐
324           ing.
325
326       :cf <folder>
327           Change the folder shown in the message list.
328
329       :check-mail
330           Check for new mail on the selected account. Non-imap backends re‐
331           quire check-mail-cmd to be set in order for aerc to initiate a
332           check for new mail. Issuing a manual :check-mail command will reset
333           the timer for automatic checking.
334
335       :compose [-H "<header>: <value>"] [-T <template-file>] [<body>]
336           Open the compose window to send a new email. The new email will be
337           sent with the current account's outgoing transport configuration.
338           For details on configuring outgoing mail delivery consult aerc-ac‐
339           counts(5).
340
341           -H "<header>: <value>"
342               Add the specified header to the message, e.g:
343
344                   :compose -H "X-Custom: custom value"
345
346           -T <template-file>
347               Use the specified template file for creating the initial mes‐
348               sage body.
349
350           <body>: The initial message body.
351
352       :filter [<options>] <terms>...
353           Similar to :search, but filters the displayed messages to only the
354           search results. The search syntax is dependent on the underlying
355           backend. Refer to aerc-search(1) for details
356
357       :mkdir <name>
358           Creates a new folder for this account and changes to that folder.
359
360       :rmdir [-f]
361           Removes the current folder.
362
363           By default, it will fail if the directory is non-empty (see -f).
364
365           -f
366               Remove the directory even if it contains messages.
367
368           Some programs that sync maildirs may recover deleted directories
369           (e.g. offlineimap). These can either be specially configured to
370           properly handle directory deletion, or special commands need to be
371           run to delete directories (e.g. offlineimap --delete-folder).
372
373           It is possible, with a slow connection and the imap backend, that
374           new messages arrive in the directory before they show up - using
375           :rmdir at this moment would delete the directory and such new mes‐
376           sages before the user sees them.
377
378       :next <n>[%]
379       :next-message <n>[%]
380       :prev <n>[%]
381       :prev-message <n>[%]
382           Selects the next (or previous) message in the message list. If
383           specified as a percentage, the percentage is applied to the number
384           of messages shown on screen and the cursor advances that far.
385
386       :next-folder <n>
387       :prev-folder <n>
388           Cycles to the next (or previous) folder shown in the sidebar, re‐
389           peated <n> times (default: 1).
390
391       :expand-folder
392       :collapse-folder
393           Expands or collapses the current folder when the directory tree is
394           enabled.
395
396       :export-mbox <file>
397           Exports all messages in the current folder to an mbox file.
398
399       :import-mbox <file>
400           Imports all messages from an mbox file to the current folder.
401
402       :next-result
403       :prev-result
404           Selects the next or previous search result.
405
406       :select <n>
407       :select-message <n>
408           Selects the <n>th message in the message list (and scrolls it into
409           view if necessary).
410
411       :split [[+|-]<n>]
412           Creates a horizontal split, showing <n> messages and a message view
413           below the message list. If a + or - is prepended, the message list
414           size will grow or shrink accordingly. The split can be cleared by
415           calling :split 0, or just :split. The split can be toggled by call‐
416           ing split with the same (absolute) size repeatedly. For example,
417           :split 10 will create a split. Calling :split 10 again will remove
418           the split. If not specified, <n> is set to an estimation based on
419           the user's terminal. Also see :vsplit.
420
421       :sort [[-r] <criterion>]...
422           Sorts the message list by the given criteria. -r sorts the immedi‐
423           ately following criterion in reverse order.
424
425           Available criteria:
426
427       ┌──────────┬───────────────────────────┐
428Criterion Description        
429       ├──────────┼───────────────────────────┤
430arrival   │ Date and time of the mes‐ │
431       │          │ sages arrival             │
432       ├──────────┼───────────────────────────┤
433cc        │ Addresses in the Cc field │
434       ├──────────┼───────────────────────────┤
435date      │ Date and time of the mes‐ │
436       │          │ sage                      │
437       ├──────────┼───────────────────────────┤
438from      │   Addresses in the From   │
439       │          │   field                   │
440       ├──────────┼───────────────────────────┤
441read      │ Presence of the read flag │
442       ├──────────┼───────────────────────────┤
443size      │    Size of the message    │
444       ├──────────┼───────────────────────────┤
445subject   │  Subject of the message   │
446       ├──────────┼───────────────────────────┤
447to        │ Addresses in the To field │
448       └──────────┴───────────────────────────┘
449       :toggle-threads
450           Toggles between message threading and the normal message list.
451
452       :view [-p]
453       :view-message [-p]
454           Opens the message viewer to display the selected message. If the
455           peek flag -p is set, the message will not be marked as seen and ig‐
456           nores the auto-mark-read config.
457
458       :vsplit [[+|-]<n>]
459           Creates a vertical split of the message list. The message list will
460           be <n> columns wide, and a vertical message view will be shown to
461           the right of the message list. If a + or - is prepended, the mes‐
462           sage list size will grow or shrink accordingly. The split can be
463           cleared by calling :vsplit 0, or just :vsplit. The split can be
464           toggled by calling split with the same (absolute) size repeatedly.
465           For example, :vsplit 10 will create a split. Calling :vsplit 10
466           again will remove the split. If not specified, <n> is set to an es‐
467           timation based on the user's terminal. Also see :split.
468
469   MESSAGE VIEW COMMANDS
470       :close
471           Closes the message viewer.
472
473       :next <n>[%]
474       :prev <n>[%]
475           Selects the next (or previous) message in the message list. If
476           specified as a percentage, the percentage is applied to the number
477           of messages shown on screen and the cursor advances that far.
478
479       :next-part
480       :prev-part
481           Cycles between message parts being shown. The list of message parts
482           is shown at the bottom of the message viewer.
483
484       :open [<args...>]
485           Saves the current message part to a temporary file, then opens it.
486           If no arguments are provided, it will open the current MIME part
487           with the matching command in the [openers] section of aerc.conf.
488           When no match is found in [openers], it falls back to the default
489           system handler.
490
491           When arguments are provided:
492
493           •   The first argument must be the program to open the message part
494               with. Subsequent args are passed to that program.
495{} will be expanded as the temporary filename to be opened. If
496               it is not encountered in the arguments, the temporary filename
497               will be appened to the end of the command.
498
499
500       :open-link <url> [<args...>]
501           Open the specified URL with an external program. The opening logic
502           is the same than for :open but the opener program will be looked up
503           according to the URL scheme MIME type: x-scheme-handler/<scheme>.
504
505       :save [-fpa] <path>
506           Saves the current message part to the given path. If the path is
507           not an absolute path, [general].default-save-path from aerc.conf
508           will be prepended to the path given. If path ends in a trailing
509           slash or if a folder exists on disc or if -a is specified, aerc as‐
510           sumes it to be a directory. When passed a directory :save infers
511           the filename from the mail part if possible, or if that fails, uses
512           aerc_$DATE.
513
514           -f: Overwrite the destination whether or not it exists
515
516           -p: Create any directories in the path that do not exist
517
518           -a: Save all attachments. Individual filenames cannot be specified.
519
520       :mark [-atvT]
521           Marks messages. Commands will execute on all marked messages in‐
522           stead of the highlighted one if applicable. The flags below can be
523           combined as needed.
524
525           -a: Apply to all messages in the current folder
526
527           -t: toggle the mark state instead of marking a message
528
529           -v: Enter / leave visual mark mode
530
531           -V: Same as -v but does not clear existing selection
532
533           -T: Marks the displayed message thread of the selected message.
534
535       :unmark [-at]
536           Unmarks messages. The flags below can be combined as needed.
537
538           -a: Apply to all messages in the current folder
539
540           -t: toggle the mark state instead of unmarking a message
541
542       :remark
543           Re-select the last set of marked messages. Can be used to chain
544           commands after a selection has been acted upon
545
546   MESSAGE COMPOSE COMMANDS
547       :abort
548           Close the composer without sending, discarding the message in
549           progress.
550
551       :attach <path>
552       :attach -m [<arg>]
553           Attaches the file at the given path to the email. The path can con‐
554           tain globbing syntax described at
555           https://godocs.io/path/filepath#Match.
556
557           -m [<arg>]
558               Runs the file-picker-cmd to select files to be attached. Re‐
559               quires an argument when file-picker-cmd contains the %s verb.
560
561       :attach-key
562           Attaches the public key for the configured account to the email.
563
564       :detach [<path>]
565           Detaches the file with the given path from the composed email. If
566           no path is specified, detaches the first attachment instead.
567
568       :cc <addresses>
569       :bcc <addresses>
570           Sets the Cc or Bcc header to the given addresses. If an editor for
571           the header is not currently visible in the compose window, a new
572           one will be added.
573
574       :edit
575           (Re-)opens your text editor to edit the message in progress.
576
577       :multipart [-d] <mime/type>
578           Makes the message to multipart/alternative and add the specified
579           <mime/type> part. Only the MIME types that are configured in the
580           [multipart-converters] section of aerc.conf are supported and their
581           related commands will be used to generate the alternate part.
582
583           -d:
584               Remove the specified alternative <mime/type> instead of adding
585               it. If no alternative parts are left, make the message
586               text/plain (i.e. not multipart/alternative).
587
588       :next-field
589       :prev-field
590           Cycles between input fields in the compose window.
591
592       :postpone
593           Saves the current state of the message to the postpone folder (from
594           accounts.conf) for the current account.
595
596       :save [-p] <path>
597           Saves the selected message part to the specified path. If -p is se‐
598           lected, aerc will create any missing directories in the specified
599           path. If the path specified is a directory or ends in /, aerc will
600           use the attachment filename if available or a generated name if
601           not.
602
603       :send [-a <scheme>]
604           Sends the message using this accounts default outgoing transport
605           configuration. For details on configuring outgoing mail delivery
606           consult aerc-accounts(5).
607
608           -a: Archive the message being replied to. See :archive for schemes.
609
610       :switch-account <account-name>
611       :switch-account -n
612       :switch-account -p
613           Switches the account. Can be used to switch to a specific account
614           from its name or to cycle through accounts using the -p and -n
615           flags.
616
617           -p: switch to previous account
618
619           -n: switch to next account
620
621       :header [-f] <name> [<value>]
622           Add a new email header. If the header already exists, -f must be
623           specified to replace the given value.
624
625       :toggle-headers
626           Toggles the visibility of the message headers.
627
628       :encrypt
629           Encrypt the message to all recipients. If a key for a recipient
630           cannot be found the message will not be encrypted.
631
632       :sign
633           Sign the message using the account's default key. If pgp-key-id is
634           set in accounts.conf (see aerc-accounts(5)), it will be used in
635           priority. Otherwise, the From header address will be used to look
636           for a matching private key in the pgp keyring.
637
638   TERMINAL COMMANDS
639       :close
640           Closes the terminal.
641

LOGGING

643       Aerc does not log by default, but collecting log output can be useful
644       for troubleshooting and reporting issues. Redirecting stdout when in‐
645       voking aerc will write log messages to that file:
646
647           $ aerc > aerc.log
648
649       Persistent logging can be configured via the log-file and log-level
650       settings in aerc.conf.
651

SEE ALSO

653       aerc-config(5) aerc-imap(5) aerc-notmuch(5) aerc-smtp(5) aerc-
654       maildir(5) aerc-sendmail(5) aerc-search(1) aerc-stylesets(7) aerc-tem‐
655       plates(7) aerc-accounts(5) aerc-binds(5) aerc-tutorial(7)
656

AUTHORS

658       Originally created by Drew DeVault <sir@cmpwn.com> and maintained by
659       Robin Jarry <robin@jarry.cc> who is assisted by other open source con‐
660       tributors. For more information about aerc development, see
661       https://sr.ht/~rjarry/aerc/.
662
663
664
665                                  2023-07-19                           AERC(1)
Impressum