AERC-SEARCH(1)

📦
version 0.22.0 · 17 versions
, in arch rolling

🌸 aerc-search(1) — the search glow-up guide 🌸

okay bestie, welcome to aerc-search(1) — it's from the General Commands Manual section and it's literally the cheat sheet for finding stuff in aerc(1). Think of it as your group chat search bar but make it ✨powerful✨.

This page covers the filter/search patterns and options — the syntax works for every backend, no cap. 💅

✨ SYNTAX ✨

so this syntax is common to all backends, meaning you don't gotta relearn it per backend. iconic behavior fr fr.

:filter [-rubave] [-x <flag>] [-X <flag>] [-H <header>:[<value>]] [-f <from>] [-t <to>] [-c <cc>] [-d <start[..end]>] [<terms>...]
:search [-rubave] [-x <flag>] [-X <flag>] [-H <header>:[<value>]] [-f <from>] [-t <to>] [-c <cc>] [-d <start[..end]>] [<terms>...]

Both of these search the current folder for messages matching the set of conditions you give em. 🫶

  • :filter — this one restricts the displayed messages to only the search results. like, it actually hides everything else. main character filtering energy.
  • :search — the searching one, but it doesn't hide your other messages from view the way :filter does.

Each space separated term of <terms>, if you provided any, gets searched case-insensitively among subject lines — unless you threw in -b or -a. 💖

🎀 the options (yes, all of them)

  • -r — search for read messages
  • -u — search for unread messages
  • -x <flag>, -X <flag> — restrict search to messages with or without <flag>
    • use -x to search for messages with the flag set
    • use -X to search for messages without the flag set

possible values are:

  • seen — read messages
  • answered — replied messages
  • forwarded — forwarded messages
  • flagged — flagged messages
  • draft — draft messages
  • -H <header>:[<value>] — search in the headers of the messages for a specific <header> that matches <value>. <value> can be omitted to only search for a <header>. if either the <header> or the <value> contain a space then the whole argument needs to be escaped with quotes. ⚠️ note: spaces around <value> are trimmed.
  • -b — search in the body of the messages
  • -a — search in the entire text of the messages
  • -v — exclude messages which match this search (inverse queen 👑)
  • -e — instruct the backend to use a custom search extension (such as X-GM-EXT-1 if available). search terms are expected in <terms>; other flags will be ignored. 🫡
  • -f <from> — search for messages from <from>
  • -t <to> — search for messages to <to>
  • -c <cc> — search for messages cc'ed to <cc>
  • -d <since[..until]> — search for messages within a particular date range between since and until, excluding the latter (in mathematical notation: search for messages in the [since, until) interval). until can be omitted to only search for <since> to present.

🦋 date formats for -d (iykyk)

spaces and underscores are allowed in relative dates to improve readability. yes bestie, readability matters 💖

  • YYYY-MM-DD
  • today, yesterday
  • (this|last) (year|month|week)
  • Weekdays, Monthnames — can also be abbreviated, so Monday..Tuesday can be written as Mon..Tue and February..March as Feb..Mar.
  • <N> (y[ear]|m[onth]|w[eek]|d[ay]) — <N> is a positive integer that represents the number of time units in the past. multiple relative terms can be accumulated. the units can also be abbreviated by a single letter such that yesterday would correspond to 1d (equivalent to 1 day or 1_day) and 8 days ago would be either 1w1d or 8d. 🧚

🔥 CUSTOM IMAP EXTENSIONS 🔥

the Gmail IMAP extension (X-GM-EXT-1) can be used for searching and filtering. to use this custom extension, make sure it is activated (see aerc-imap(5)) and use the extension -e flag in your :filter or :search commands. slay 🎀

example:

:filter -e filename:pdf from:bob
:filter -e has:attachment newer_than:2d

:search -e is:read is:starred
:search -e list:~rjarry/aerc-devel@lists.sr.ht

💜 NOTMUCH 💜

for notmuch, it is possible to avoid using the above flags and only rely on notmuch search syntax. lowkey a vibe.

:filter query...
:search query...

you can use the full notmuch query language as described in notmuch-search-terms(7). 📚

the query will only apply on top of the active folder query — so it stacks, it doesn't replace. no cap.

example, jump to next unread:

:search tag:unread

⭐ SEE ALSO ⭐

🌈 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/. 👑

and that's the whole page bestie 💅 go forth and search, filter, and generally ate 💖

— with love, the general commands manual, dated 2026-09-07, AERC-SEARCH(1) out. 🫶✨

📦 where this page comes from