AERC(1)

📦
version 0.22.0 · 17 versions
, in arch rolling

aerc(1) 💖

okay bestie, welcome to the General Commands Manual for aerc — literally the email client whose whole official vibe is “a pretty good email client.” We are keeping every flag, path, command, caveat, and tiny little detail. no cap. 🫶

🌸 NAME 🌸

aerc - a pretty good email client.

✨ SYNOPSIS ✨

aerc [-h] [-v] [-a <name>] [-C <file>] [-A <file>] [-B <file>] [-I]
[mailto:<...> | mbox:<file> | :<command...>]

For a guided tutorial, use :help tutorial from aerc, or man aerc-tutorial from your terminal. 🎀

💅 OPTIONS 💅

  • -h, --help — Show aerc usage help and exit.
  • -v, --version — Print the installed version of aerc and exit.
  • -a <name>, --account <name> — Load only the named account, as opposed to all configured accounts. It can also be a comma separated list of names. This option may be specified multiple times. The account order will be preserved. 👑
  • -C </path/to/aerc.conf>, --aerc-conf </path/to/aerc.conf> — Instead of using $XDG_CONFIG_HOME/aerc/aerc.conf, use the file at the specified path for configuring aerc.
  • -A </path/to/accounts.conf>, --accounts-conf </path/to/accounts.conf> — Instead of using $XDG_CONFIG_HOME/aerc/accounts.conf, use the file at the specified path for configuring accounts.
  • -B </path/to/binds.conf>, --binds-conf </path/to/binds.conf> — Instead of using $XDG_CONFIG_HOME/aerc/binds.conf, use the file at the specified path for configuring binds.
  • -I, --no-ipc — Run commands (mailto:..., :<command...>, mbox:<file>) directly in this instance rather than over IPC in an existing aerc instance. Also disable creation of an IPC server for subsequent aerc instances to communicate with this one.
  • mailto:address[,address][?query[&query]] — Open the composer with the address(es) in the To field. These addresses must not be percent encoded.

If aerc is already running (and IPC is not disabled), the composer is started in that instance; otherwise a new instance is started with the composer.

The following (optional) query parameters are supported:

  • subject=<text> — Subject line will be completed with the <text>.
  • body=<text> — Message body will be completed with the <text>.
  • cc=<address>[,<address>] — Cc header will be completed with the list of addresses.
  • bcc=<address>[,<address>] — Bcc header will be completed with the list of addresses.
  • in-reply-to=<message-id> — In-reply-to header will be set to the message id.
  • account=<accountname> — Specify the account (must be in accounts.conf; default is the selected account).
  • template=<template-file> — Template sets the template file for creating the message.
Note that reserved characters in the queries must be percent encoded. 🧚
  • :<command...> — Run an aerc-internal command as you would in Ex-Mode. See RUNTIME COMMANDS below.

The command to be executed and its arguments can either be passed as separate arguments in the shell (e.g., aerc :cmd arg1 arg2) or as a single argument in the shell (e.g., aerc ":cmd arg1 arg2"). In the former case, aerc may add quotes to the command before it is parsed in an attempt to preserve arguments containing spaces and other special characters. In the latter case, aerc will parse the command verbatim, as if it had been typed directly on aerc's command line. This latter form can be helpful for commands that don't interpret quotes in their arguments.

If aerc is already running (and IPC is not disabled), the command is run in that instance; otherwise a new instance is started with the command.

  • mbox:<file> — Open the specified mbox file as a virtual temporary account.

If aerc is already running (and IPC is not disabled), the file is opened in that instance; otherwise a new instance is started with the file.

🦋 RUNTIME COMMANDS 🦋

To execute a command, press : to bring up the command interface. Commands may also be bound to keys, see aerc-binds(5) for details. In some contexts, such as the terminal emulator, <c-x> is used to bring up the command interface.

Different commands work in different contexts, depending on the kind of tab you have selected.

Dynamic arguments are expanded following aerc-templates(7) depending on the context. For example, if you have a message selected, the following command:

:filter -f "{{index (.From | emails) 0}}"

Will filter all messages sent by the same sender. 🔥

Aerc stores a history of commands, which can be cycled through in command mode. Pressing the up key cycles backwards in history, while pressing down cycles forwards.

🌍 GLOBAL COMMANDS 🌍

These commands work in any context.

  • :help <topic>, :man <topic> — Display one of aerc's man pages in the embedded terminal.
  • :help keys, :man keys — Display the active key bindings in the current context.
  • :new-account [-t] — Start the new account wizard.

-t: Create a temporary account. Do not modify accounts.conf.

  • :cd <directory> — Changes aerc's current working directory.
  • :z <directory or zoxide query> — Changes aerc's current working directory using zoxide. If zoxide is not on $PATH, the command will not be registered.
  • :change-tab [+|-]<tab name or index>, :ct [+|-]<tab name or index> — Changes the focus to the tab with the given name. If a number is given, it's treated as an index. If the number is prepended with + or -, the number is interpreted as a delta from the selected tab. If only a - is given, changes the focus to the previously selected tab.
  • :exec <command> — Executes an arbitrary command in the background. Aerc will set the environment variables $account and $folder when the command is executed from an Account tab or an opened message.
Note: commands executed in this way are not executed with the shell.
  • :echo <string> — Resolve templates in <string> and print it.
  • :eml [<path>], :preview [<path>] — Opens an eml file and displays the message in the message viewer.

Can also be used in the message viewer to open an rfc822 attachment or in the composer to preview the message.

  • :pwd — Displays aerc's current working directory in the status bar.
  • :version — Displays the version of the running aerc instance.
  • :send-keys <keystrokes> — Send keystrokes to the currently visible terminal, if any. Can be used to control embedded editors to save drafts or quit in a safe manner.

Here's an example of quitting a Vim-like editor:

:send-keys <Esc>:wq!<Enter>
Note: when used in binds.conf (see aerc-binds(5)), angle brackets need to be escaped in order to make their way to the command:
<C-q> = :send-keys \<Esc\>:wq!\<Enter\><Enter>

This way the <Esc> and the first <Enter> keystrokes are passed to :send-keys, while the last <Enter> keystroke is executed directly, committing the :send-keys command's execution. 💅

  • :term [<command>...], :terminal [<command>...] — Opens a new terminal tab with a shell running in the current working directory, or the specified command.
  • :move-tab [+|-]<index> — Moves the selected tab to the given index. If + or - is specified, the number is interpreted as a delta from the selected tab.
  • :prev-tab [<n>], :next-tab [<n>] — Cycles to the previous or next tab in the list, repeating <n> times (default: 1).
  • :pin-tab — Moves the current tab to the left of all non-pinned tabs and displays the pinned-tab-marker (default: `) to the left of the tab title.
  • :unpin-tab — Removes the pinned-tab-marker from the current tab and returns the tab to its previous location.
  • :prompt <prompt> <command>... — Displays the prompt on the status bar, waits for user input, then appends that input as the last argument to the command and executes it. The input is passed as one argument to the command, unless it is empty, in which case no extra argument is added.
  • :menu [-c "<shell-cmd>"] [-e] [-b] [-a] [-d] [-l] [-t "<title>"] <aerc-cmd ...> — Opens a popover dialog running sh -c "<shell-cmd>" (if not specified [general].default-menu-cmd will be used). When the command exits, all lines printed on its standard output will be appended to <aerc-cmd ...> and executed as a standard aerc command like xargs(1) would do when used in a shell. A colon (:) prefix is supported for <aerc-cmd ...> but is not required.

:menu can be used without an external program by setting <shell-cmd> to -. This also acts as a fallback in case where no <shell-cmd> was specified at all or the executable in the <shell-cmd> was not found.

  • -c "<shell-cmd>" — overrides [general].default-menu-cmd. The deets live in aerc-config(5), bestie. 💅
  • -e — the second a command throws an error, stop running the rest. Like, no cap, cut it off immediately.
  • -b — do NOT spawn the popover dialog. The commands just start up in the background (NOT in a virtual terminal — different vibes entirely). Use this one when <shell-cmd> is a graphical app that genuinely doesn't need a terminal. 🖼️
  • -t — override the dialog title (otherwise aerc just derives it from <shell-cmd>).

<shell-cmd> can get fed input text using these flags, and honestly they're the moment:

  • -a — all the account names, one per line. E.g. '<account>' LF
  • -d — all the current account directory names, one per line. E.g. '<directory>' LF
  • -ad — all the directories of all the accounts, one per line. E.g. '<account>' '<directory>' LF
  • -l — all the links extracted from the current message. 🔗

aerc may slip in quotes when either of the tokens contains special characters. Those quotes are doing important work — preserve them for <aerc-cmd ...>.

Examples, because they eat every single time:

:menu -adc fzf :cf -a
:menu -c 'fzf --multi' :attach
:menu -dc 'fzf --multi' :cp
:menu -bc 'dmenu -l 20' :cf
:menu -c 'ranger --choosefiles=%f' :attach
:menu -lc fzf :open-link

This absolutely works in key bindings too (peek aerc-binds(5)):

<C-p> = :menu -adc fzf :cf -a<Enter>

💌 MORE RUNTIME COMMANDS 💌

  • :choose -o <key> <text> <command> [-o <key> <text> <command>]... — prompts the user to choose between a bunch of options. Super simple, super cute.
  • :reload [-B] [-C] [-s <styleset-name>] — hot-reloads your config files for the key binds and the general aerc config. Okay but for real, reloading the account config file is not supported — don't come for me, that's just how it is. 🙈

If you pass no flags at all, binds.conf, aerc.conf, and the current styleset all get reloaded together. Slay.

  • -B — reload binds.conf.
  • -C — reload aerc.conf.
  • -s <styleset-name> — load up the specified styleset. 🎀
Heads up! Sending the SIGHUP signal to the aerc process makes :reload happen (with no flags). Free real estate.
  • :repeat — re-runs aerc's previously executed command, i.e. whatever you last hit : for. 🔁
  • :suspend — suspends the aerc process. Ngl, some ongoing connections may get terminated. 😭
  • :quit [-f], :exit [-f], :q [-f] — exits aerc. If a task is mid-roll that really shouldn't be interrupted (like sending a message), a normal quit call might just fail on you. In that case you force it shut with the -f option. Use responsibly, bestie. 💀
  • :redraw — forces a full redraw of the screen. Visual reset, main character energy. ✨

💌 MESSAGE COMMANDS 💌

These ones are valid in any context that has a selected message (like the message list, the message in the message viewer, etc).

  • :archive [-m <strategy>] <scheme> — moves the selected message to the archive. Available schemes, curated for you:
    • flat: no special structure, all messages just go in the archive directory.
    • year: messages get stored in folders per year.
    • month: messages get stored in folders per year and subfolders per month.

The -m option sets the multi-file strategy. aerc-notmuch(5) has more. 👀

  • :accept [-e|-E] [-s] — accepts an iCalendar meeting invitation. This opens a compose window with a specially crafted attachment, and sending the email lets the inviter know you accepted — it'll likely update their calendar too. But bestie, listen: this will NOT add the meeting to your own calendar. That's a separate manual step you gotta do yourself (e.g. by piping the text/calendar part to an appropriate script). 💅
    • -e — forces [compose].edit-headers = true for this message only.
    • -E — forces [compose].edit-headers = false for this message only.
    • -s — skips the editor entirely and goes straight to the review screen.
  • :accept-tentative [-e|-E] [-s] — accepts an iCalendar meeting invitation... tentatively. We love a maybe. 🦋
    • -e — forces [compose].edit-headers = true for this message only.
    • -E — forces [compose].edit-headers = false for this message only.
    • -s — skips the editor and goes directly to the review screen.
  • :copy [-dp] [-a <account>] [-m <strategy>] <folder>, :cp [-dp] [-a <account>] [-m <strategy>] <folder> — copies the selected message(s) to <folder>.
    • -d — decrypt the message before copying.
    • -p — create <folder> if it doesn't exist.
    • -a — copy to <folder> of <account>. If <folder> doesn't exist, it gets created whether or not you used -p. Iconic behaviour honestly.
    • -m — set the multi-file strategy. aerc-notmuch(5) for the details.
  • :decline [-e|-E] [-s] — declines an iCalendar meeting invitation. Respectfully, no. 🚫
    • -e — forces [compose].edit-headers = true for this message only.
    • -E — forces [compose].edit-headers = false for this message only.
    • -s — skips the editor and goes directly to the review screen.
  • :delete [-m <strategy>], :delete-message [-m <strategy>] — deletes the selected message. Gone, reduced to atoms. 💀
  • :envelope [-h] [-s <format-specifier>] — opens the message envelope in a dialog popup. 💌
    • -h — show all the header fields.
    • -s <format-specifier> — a user-defined format specifier that needs two %s, one for the key and one for the value strings. Default format: %-20.20s: %s
  • :recall [-f] [-e|-E] [-s] — opens the selected message for re-editing. Messages can only be recalled from the postpone directory, lowkey rules are rules.
    • -f — open the message for re-editing even if it is not in the postpone directory. aerc remembers the folder, so the further :postpone call saves the message right back there. Big memory energy. 🧠
    • -e — forces [compose].edit-headers = true for this message only.
    • -E — forces [compose].edit-headers = false for this message only.
    • -s — skips the editor and goes directly to the review screen.

Okay so here's the lore: original recalled messages get deleted if they're sent or postponed again — because in both those cases you've got another copy of the message somewhere. Otherwise the recalled message is left intact, which is what happens if you discard it after editing. If you don't need it, you can delete it with :rm.

  • :forward [-A|-F] [-T <template-file>] [-x <account>] [-e|-E] [-s] [<address>...] — opens the composer so you can forward the selected message to another recipient.
    • -A — forward the message and all the attachments. 🎁
    • -F — forward the full message as an RFC 2822 attachment.
    • -T <template-file> — use the specified template file when creating the initial message body. Unless -F is specified, this defaults to whatever is set as forwards in the [templates] section of aerc.conf.
    • -x <account> — forward using the specified account instead of the current one.
    • -e — forces [compose].edit-headers = true for this message only.
    • -E — forces [compose].edit-headers = false for this message only.
    • -s — skips the editor and goes directly to the review screen.
  • :move [-p] [-a <account>] [-m <strategy>] <folder>, :mv [-p] [-a <account>] [-m <strategy>] <folder> — moves the selected message(s) to <folder>.
    • -p — create <folder> if it doesn't exist.
    • -a — move to <folder> of <account>. If <folder> doesn't exist, it will be created whether or not -p is used.
    • -m — set the multi-file strategy. You already know where to look: aerc-notmuch(5).
  • :patch <args ...> — the patch management sub-commands. aerc-patch(7) has the whole saga. 🧵
  • :pipe [-bdmps] <cmd> — downloads the selected message and pipes it into the given shell command (executed with sh -c "<cmd>"), then opens a new terminal tab to show you the result. By default, the selected message part is used in the message viewer, and the full message is used in the message list. In the compose review mode, it pipes the composed message that's about to be sent. 📤

It operates on multiple messages when they're marked — and when piping multiple messages, aerc writes them with mbox format separators.

  • -b — run the command in the background instead of opening a terminal tab.
  • -d — pipe the (full) message but decrypt it first.
  • -m — pipe the full message.
  • -p — pipe just the selected message part, if applicable.
  • -s — silently close the terminal tab after the command is done.

You can absolutely use this to apply patch series with git:

:pipe -m git am -3

And when at least one marked message subject matches a patch series (like [PATCH X/Y]), all the marked messages get sorted by subject so the patches are applied in order. It's giving organized. 🌈

  • :reply [-acflqs] [-T <template-file>] [-A <account>] [-e|-E] — opens the composer so you can reply to the selected message.
    • -a — reply all.
    • -c — close the view tab when replying. If the reply doesn't get sent, the view tab reopens. It said "not today". 🫶
    • -f — reply to all the addresses in the From and Reply-To headers.
    • -l — reply to the mailing list in the List-Post header.
    • -q — insert a quoted version of the selected message into the reply editor. This defaults to whatever is set as quoted-reply in the [templates] section of aerc.conf.
    • -s — skip opening the text editor and go directly to the review screen.
    • -T <template-file> — use the specified template file for creating the initial message body.
    • -A <account> — reply with the specified account instead of the current one.
    • -e — forces [compose].edit-headers = true for this message only.
    • -E — forces [compose].edit-headers = false for this message only.
  • :read [-t] — marks the marked or selected messages as read. ✅
    • -t — toggle the messages between read and unread.
  • :unread [-t] — marks the marked or selected messages as unread.
    • -t — toggle the messages between read and unread.
  • :flag [-t] [-a] [-f] [-x <flag>] — sets (enables) a certain flag on the marked or selected messages. 🚩
    • -t — toggle the flag instead of setting (enabling) it.
    • -a — mark message as answered/unanswered.
    • -f — mark message as forwarded/not-forwarded.
    • -x <flag> — mark the message with a specific flag. The available flags are (adapted from RFC 3501, section 2.3.2):
      • seen — message has been read.
      • answered — message has been answered.
      • forwarded — message has been forwarded.
      • flagged — message is flagged for urgent/special attention.
      • draft — message is a draft.
Arbitrary IMAP keyword flags are managed using :modify-labels / :tag.
  • :unflag [-t] [-a] [-f] [-x <flag>] — operates exactly like :flag, except it defaults to unsetting (disabling) flags. Same energy, opposite direction. 💅
  • :modify-labels [+|-|!]<label>...
  • :tag [+|-|!]<label>... — ok so these two are your besties for messing with message labels (think IMAP and notmuch tags, GMail or Proton labels 💖). Slap a + in front and the label gets added, a - means it gets removed, and a ! means it gets toggled — heads up tho, toggling is not supported for IMAP, GMail nor Proton 🙈. And as a lil convenience, labels with no operand at all just add the label you named.

Example: add the inbox and unread labels, remove the spam label. slay ✨

:modify-labels +inbox -spam unread
  • :unsubscribe [-e|-E] [-s] — tries to auto-unsubscribe you from the mailing list using the List-Unsubscribe header 🎀. If the backend supports it, aerc may pop open a compose window pre-filled with the unsubscribe info, or yeet the unsubscribe URL into a web browser.
    • -e — forces [compose].edit-headers = true for this message only.
    • -E — forces [compose].edit-headers = false for this message only.
    • -s — skips the editor entirely and goes straight to the review screen. main character speed 💅

📬 MESSAGE LIST COMMANDS 📬

  • :align top|center|bottom — aligns the selected message, that's it, that's the vibe. The positions you can pick:
    • top — top of the message list.
    • center — center of the message list.
    • bottom — bottom of the message list.
  • :disconnect
  • :connect — disconnect or reconnect the current account 🔌. Just so you know, this only applies to certain email sources.
  • :clear [-s] — wipes the current search or filter criteria 🧼.

By default the selected message is kept. But if you want to clear the selection too and yeet the cursor to the top of the list, use the -s flag.

  • -s — selects the message at the top of the message list after clearing.
  • :cf [-a <account>] <folder> — changes the folder shown in the message list to <folder> 🗂️.
    • -a <account> — change to <folder> of <account> and focus its corresponding tab.
  • :check-mail — checks for new mail on the selected account 📥. Non-IMAP backends require check-mail-cmd to be set for aerc to initiate a check for new mail. Also: issuing a manual :check-mail command will reset the timer for automatic checking ⏰.
  • :compose [-H "<header>: <value>"] [-T <template-file>] [-e|-E] [-s] [<body>] — opens the compose window to send a new email ✍️. The new email goes out with the current account's outgoing transport configuration. For details on configuring outgoing mail delivery, consult aerc-accounts(5).
    • -H "<header>: <value>" — add the specified header to the message, e.g:
:compose -H "X-Custom: custom value"
  • -T <template-file> — use the specified template file for creating the initial message body.
  • -e — forces [compose].edit-headers = true for this message only.
  • -E — forces [compose].edit-headers = false for this message only.
  • -s — skips the editor and goes directly to the review screen.
  • <body> — the initial message body.
  • :bounce [-A <account>] <address> [<address>...]
  • :resend [-A <account>] <address> [<address>...] — bounces the selected message — or all the marked messages — to the specified addresses, optionally using the specified account 🏀. This forwards the message while preserving all the existing headers. The new sender (From), date (Date), Message-ID and recipients (To) are prepended to the headers with the Resent- prefix. For more info please refer to section 3.6.6 of RFC 2822. Also note that the bounced message is not copied over to the sent folder 👀.
Also please note that some providers (notably for instance Microsoft's O365) do not allow sending messages with the From header not matching any of the account's identities (even if Resent-From matches some). 💀
  • :recover [-f] [-e|-E] <file> — resumes composing a message that was neither sent nor postponed 🫶. The file may not contain header data unless [compose].edit-headers was enabled when the aborted message was originally composed.
    • -f — delete the <file> after opening the composer.
    • -e — forces [compose].edit-headers = true for this message only.
    • -E — forces [compose].edit-headers = false for this message only.
  • :filter [<options>] <terms>... — similar to :search, but it filters the displayed messages down to only the search results 🔍. The search syntax depends on the underlying backend. Refer to aerc-search(1) for details.
  • :mkdir <name> — creates a new folder for this account and changes to that folder 📁✨.
  • :rmdir [-f] [<folder>] — removes the folder <folder>, or the current folder if you don't specify one 🗑️.

By default it will fail if the directory is non-empty (see -f).

  • -f — remove the directory even if it contains messages.

Some programs that sync maildirs may recover deleted directories (e.g. offlineimap). These can either be specially configured to properly handle directory deletion, or special commands need to be run to delete directories (e.g. offlineimap --delete-folder).

It is possible, with a slow connection and the IMAP backend, that new messages arrive in the directory before they show up — using :rmdir at this moment would delete the directory and such new messages before the user sees them 😭.
  • :next <n>[%]
  • :next-message <n>[%]
  • :prev <n>[%]
  • :prev-message <n>[%] — selects the next (or previous) message in the message list ⏭️. If you give it as a percentage, the percentage is applied to the number of messages shown on screen and the cursor advances that far.
  • :next-folder [-u] <n>
  • :prev-folder [-u] <n> — cycles to the next (or previous) folder shown in the sidebar, repeated <n> times (default: 1) 🔁.
    • -u — cycles to the next (or previous) folder shown in the sidebar with unseen emails.
  • :expand-folder [<folder>]
  • :collapse-folder [<folder>]
  • :toggle-folder [<folder>] — expands, collapses, or toggles a folder when the directory tree is enabled 🌳. If no <folder> argument is specified, the currently selected folder is acted upon.
  • :export-mbox <file> — exports messages in the current folder to an mbox file 📦. If there are marked messages in the folder, only the marked ones are exported. Otherwise the whole folder gets exported.
  • :import-mbox <path> — imports all messages from a (gzipped) mbox file into the current folder 📥. <path> can either be a path to a file or an URL.

Examples:

:import-mbox ~/messages.mbox
:import-mbox https://lists.sr.ht/~rjarry/aerc-devel/patches/55634/mbox
:import-mbox https://lore.kernel.org/all/20190807155524.5112-1-steve.capper@arm.com/t.mbox.gz
  • :next-result
  • :prev-result — selects the next or previous search result 🔎.
  • :query [-a <account>] [-n name] [-f] <notmuch query> — creates a virtual folder using the specified top-level notmuch query 🪄. This command is exclusive to the notmuch backend.
    • -a <account> — change to <folder> of <account> and focus its corresponding tab.
    • -n <name> — specify the display name for the virtual folder. If not provided, <notmuch query> is used as the display name.
    • -f — load the query results into an already existing folder (messages in the original folder are not deleted).
  • :search [<options>] <terms>... — searches the current folder for messages matching the given set of conditions 🔍💫. The search syntax depends on the underlying backend. Refer to aerc-search(1) for details.
  • :select <n>
  • :select-message <n> — selects the *<n>*th message in the message list (and scrolls it into view if necessary) 👆.
  • :hsplit [[+|-]<n>]
  • :split [[+|-]<n>] — creates a horizontal split, showing <n> messages and a message view below the message list 🖥️. If a + or - is prepended, the message list size will grow or shrink accordingly. The split can be cleared by calling :[h]split 0, or just :[h]split. The split can be toggled by calling split with the same (absolute) size repeatedly — for example, :[h]split 10 will create a split, and calling :[h]split 10 again will remove it 😌. If not specified, <n> is set to an estimation based on the user's terminal. Also see :vsplit.
  • :sort [[-r] <criterion>]... — sorts the message list by the given criteria 🧹. -r sorts the immediately following criterion in reverse order.

Available criteria:

  • arrival — date and time of the messages arrival
  • cc — addresses in the Cc field
  • date — date and time of the message
  • from — addresses in the From field
  • read — presence of the read flag
  • flagged — presence of the flagged flag
  • size — size of the message
  • subject — subject of the message
  • to — addresses in the To field
  • :toggle-threads — toggles between message threading and the normal message list 🧵.
  • :toggle-sidebar — toggles the sidebar on or off 📚.
  • :fold [-at] / :unfold [-at] — collapses / un-collapses the thread children of whatever message you've got selected 🫶 If the toggle flag -t is set, the folded status gets flipped instead. If -a is set, literally every thread in the current view gets hit. You can spot folded threads because of the {{.Thread*}} template attributes in [ui].index-columns 👀 more deets in aerc-config(5) and aerc-templates(7).
  • :toggle-thread-context — flips between showing the entire thread and only showing messages that match your current query / mailbox. Ngl, thread context is currently only supported by the notmuch backend 🫠
  • :view [-pb] / :view-message [-pb] — opens the message viewer to display the selected message. Set the peek flag -p and the message will not be marked as seen (and it straight-up ignores the auto-mark-read config 😌). Set the background flag -b and it opens in a background tab.
  • :vsplit [[+|-]<n>] — makes a vertical split of the message list ✨ The message list gets <n> columns wide, and a vertical message view shows up to the right of it. Prepend a + or - and the message list size grows or shrinks accordingly. Clear the split by calling :vsplit 0, or just :vsplit. You can also toggle it by calling split with the same (absolute) size over and over — so :vsplit 10 creates a split, and calling :vsplit 10 again removes it 🔁 If you don't specify <n>, it's set to an estimation based on your terminal. Also peep :split 👑

💌 MESSAGE VIEW COMMANDS 💌

  • :close — closes the message viewer. bye bestie 👋
  • :next <n>[%] / :prev <n>[%] — selects the next (or previous) message in the message list. If you give it as a percentage, that percentage gets applied to the number of messages shown on screen and the cursor advances that far 📏
  • :next-part / :prev-part — cycles between the message parts being shown. The list of message parts lives at the bottom of the message viewer, iykyk 🧩
  • :open [-d] [<args...>] — saves the current message part to a temporary file, then opens it. With no arguments, it opens the current MIME part with the matching command in the [openers] section of aerc.conf. When there's no match in [openers], it falls back to the default system handler 🖥️
    • -d: delete the temporary file after the opener exits 🗑️

When you do pass arguments:

  • The first argument must be the program to open the message part with. Subsequent args get passed to that program.
  • {} expands to the temporary filename to be opened. If it's not found in the arguments, the temporary filename gets appended to the end of the command.
  • :copy-link <url> — copies the specified URL to the system clipboard. This uses the OSC52 escape sequence, which your terminal has to support (no cap, check first) 📋
  • :open-link <url> [<args...>] — opens the specified URL with an external program. The opening logic is the same as :open, except the opener program is looked up according to the URL scheme MIME type: x-scheme-handler/<scheme> 🔗
  • :save [-fpaA] <path> — saves the current message part to the given path. If the path isn't absolute, [general].default-save-path from aerc.conf gets prepended to whatever you gave. If the path ends in a trailing slash, or a folder exists on disc, or -a is specified, aerc assumes it's a directory. When you hand it a directory, :save infers the filename from the mail part if it can, and if that fails it uses aerc_$DATE 💾
    • -f: overwrite the destination whether or not it exists
    • -p: create any directories in the path that don't exist
    • -a: save all attachments. Individual filenames cannot be specified.
    • -A: same as -a but saves all the named parts, not just attachments.
  • :mark [-atuUvVTsr] <filter> — marks messages. Commands will execute on all marked messages instead of the highlighted one if applicable. Flags can be combined as needed. Heads up: the existence of a filter implies -a unless -T has been specified ⚠️
    • -a: apply to all messages in the current folder
    • -t: toggle the mark state instead of marking a message
    • -v: enter / leave visual mark mode
    • -V: same as -v but does not clear existing selection
    • -T: marks the displayed message thread of the selected message
    • -s: apply the filter to the From: header (does not work with -v or -V)
    • -r: apply the filter to the To:, Cc:, Bcc: headers (does not work with -v or -V)
    • -u: mark unread messages. Can be combined with other filters.
    • -U: mark read messages. Can be combined with other filters.
  • :unmark [-atTsr] <filter> — unmarks messages. Flags combine as needed. Same deal: a filter implies -a unless -T is specified 🚫
    • -a: apply to all messages in the current folder
    • -t: toggle the mark state instead of unmarking a message
    • -T: marks the displayed message thread of the selected message
    • -s: apply the filter to the From: header (does not work with -v or -V)
    • -r: apply the filter to the To:, Cc:, Bcc: headers (does not work with -v or -V)
  • :remark — re-selects the last set of marked messages 🎀 perfect for chaining commands after a selection has been acted upon.
  • :toggle-headers — toggles the visibility of the message headers 👀
  • :toggle-key-passthrough — enter or exit the [view::passthrough] key bindings context. See aerc-binds(5) for more details ⌨️

✍️ MESSAGE COMPOSE COMMANDS ✍️

  • :abort — closes the composer without sending, discarding the message in progress 🙈

If the text editor exits with an error (e.g. :cq in vim(1)), the message is immediately discarded. gone. poof. 💀

  • :attach <path> / :attach -m [<arg>] / :attach -r <name> <cmd> — attaches the file at the given path to the email. The path can contain globbing syntax described at https://godocs.io/path/filepath#Match 📎
    • -m [<arg>] — runs the file-picker-cmd to select files to be attached. Requires an argument when file-picker-cmd contains the %s verb.
    • -r <name> <cmd> — runs the <cmd>, reads its output and attaches it as <name>. The attachment MIME type is derived from the <name>'s extension.
  • :attach-key — attaches the public key for the configured account to the email 🔑 iconic behaviour tbh.
  • :detach [<path>] — detaches the file with the given path from the composed email. If no path is specified, it detaches the first attachment instead. The path can contain globbing syntax described at https://godocs.io/path/filepath#Match ✂️
  • :cc <addresses> / :bcc <addresses> — sets the Cc or Bcc header to the given addresses. If an editor for that header isn't currently visible in the compose window, a new one gets added 💌
  • :edit [-e|-E] — (re-)opens your text editor to edit the message in progress. This also lets you edit the message headers. Only available from the review screen 📝
    • -e: forces [compose].edit-headers = true for this message only.
    • -E: forces [compose].edit-headers = false for this message only.
  • :multipart [-d] <mime/type> — converts the message to multipart/alternative and adds the specified <mime/type> part. Only the MIME types configured in the [multipart-converters] section of aerc.conf are supported, and their related commands get used to generate the alternate part 🧬
    • -d: remove the specified alternative <mime/type> instead of adding it. If no alternative parts are left, make the message text/plain (i.e. not multipart/alternative).
  • :next-field / :prev-field — cycles between input fields in the compose window. Only available when the text editor is visible and [compose].edit-headers = false 🔄
  • :postpone [-t <folder>] — saves the current state of the message to the postpone folder (from accounts.conf) for the current account, by default. Only available from the review screen ⏳
    • -t: overrides the target folder for saving the message

If the message was force-recalled with :recall -f from a different folder, :postpone will save it back to that folder instead of the default postpone folder configured in settings. Use -t to override that, or use :mv to move the saved message to a different folder 🗂️

  • :send [-a <scheme>] [-t <folder>] [-r|-R] [--dsn] — sends the message using this account's default outgoing transport configuration. For details on configuring outgoing mail delivery, consult aerc-accounts(5). Only available from the review screen 🚀
    • -a: archive the message being replied to. See :archive for schemes.
    • -t: overrides the Copy-To folder for saving the message.
    • -r: also save the sent message to the folder of the message being replied to.
    • -R: do not save the sent message to the folder of the message being replied to (overrides the copy-to-replied account setting).
    • --dsn: request delivery status notification from the server. This will request notification on successful delivery, delayed delivery, and delivery failure 📬
  • :switch-account <account-name> / :switch-account -n / :switch-account -p — switches the account. Use it to jump to a specific account by name, or cycle through accounts with the -p and -n flags 🔀
    • -p: switch to previous account
    • -n: switch to next account
  • :header [-f] <name> [<value>] / :header [-d] <name> — adds a new email header to the compose window. If the header is already set and isn't empty, you must use -f to overwrite its value 🏷️
    • -f: overwrite any existing header.
    • -d: remove the header instead of adding it.
  • :encrypt — encrypts the message to all recipients 🔐 If a key for a recipient can't be found, the message will not be encrypted. (no silent half-encryption here, bestie)
  • :sign — signs the message using the account's default key ✍️ If pgp-key-id is set in accounts.conf (see aerc-accounts(5)), it'll be used in priority. Otherwise, the From header address is used to look for a matching private key in the pgp keyring 🔑

🖥️ TERMINAL COMMANDS 🖥️

  • :close — closes the terminal. that's it, that's the whole command 💅

📝 LOGGING 📝

Aerc does not log by default, but collecting log output is genuinely useful for troubleshooting and reporting issues 🐛 Redirecting stdout when invoking aerc will write log messages to that file:

$ aerc > aerc.log

Persistent logging can be configured via the log-file and log-level settings in aerc.conf ⚙️

🌈 SEE ALSO ✨

okay bestie, here's the whole friend group — every one of these is a real page you can pull up, no cap:

like, that's the entire extended universe 💖 go read them, they're giving main character energy, iykyk.

👑 AUTHORS 🫶

Originally created by Drew DeVault and maintained by Robin Jarry who is assisted by other open source contributors. For more information about aerc development, see https://sr.ht/~rjarry/aerc/.

no fr, shoutout to the whole crew — Drew DeVault started this thing and Robin Jarry keeps it thriving with help from a bunch of other open source contributors, and honestly? iconic. 🌸 The link above is the spot for all the aerc development tea.

and that's a wrap on the whole page, bestie!! 🎀 this one's from the AERC(1) manual — dated 2026-09-07 — so if you're reading it way after that, go check if anything changed, mwah 💅✨💜

📦 where this page comes from