MU-FIND(1)

📦
version 1.14.2 · 11 versions
, in ubuntu stonking

💌 MU-FIND(1) — the find-y one, bestie

okay so this is mu-find, from the General Commands Manual section of your local manual (that's section 1, for the people keeping score 👑). It's the page all about finding e-mail messages in the mu database. Let's get into it 🦋

✨ NAME ✨

mu-find — find e-mail messages in the mu database. that's it, that's the whole vibe 💅

🌸 SYNOPSIS 🌸

mu [COMMON-OPTIONS] find [OPTIONS] SEARCH_EXPRESSION

literally just mu find plus your options plus a query. so simple. so iconic.

🎀 DESCRIPTION 🎀

mu find is the mu command for searching e-mail messages that got stored earlier when you ran mu index(1). So like — index first, find later. No index, no finds, no cap 🙈

🔍 SEARCHING MAIL 🔍

mu find kicks off a search for messages in the database that match some search pattern. And the search patterns? They're described in juicy detail in mu-query(7). Go read it, iykyk.

For example:

$ mu find subject:snow and date:2009..

that would find all messages in 2009 with snow in the subject field, e.g:

2009-03-05 17:57:33 EET Lucia  <lucia@example.com> running in the snow
2009-03-05 18:38:24 EET Marius <marius@foobar.com> Re: running in the snow

This uses the default, plain output (implicitly, --format=plain). And if you want other output formats — like symlinks, XML, s-expressions or JSON — go peek at the whole discussion of --format down in the OPTIONS section below 👇

The search pattern is taken as a command-line parameter. And heads up: if the search parameter consists of multiple parts (like in that example up there), they get treated as if there were a logical and between them. Sneaky but helpful fr.

For all the deets on the possible queries, see mu-query(7). 📚

🎯 FIND OPTIONS 🎯

Quick note bestie: some of the important options are described over in the mu(1) manual page, not here, because they apply to multiple mu commands. Not me gatekeeping, it's just where they live 💀

The find-command has various options that influence the way mu displays the results. And if you don't specify anything at all, the defaults are --fields="d f s", --sortfield=date and --reverse. Slay, sensible defaults ✨

🧾 -f, --fields fields

Specifies a string that determines which fields are shown in the output. This string consists of a number of characters (such as s for subject or f for from), which will replace with the actual field in the output. Fields that are not known will be output as-is, allowing for some simple formatting. cute right?

For example:

$ mu find subject:snow --fields "d f s"

lists the date, subject and sender of all messages with snow in the their subject.

The table of replacement characters is super-set of the list mentioned for search parameters, such as:

t       *t*o: recipient
d       Sent *d*ate of the message
f       Message sender (*f*rom:)
g       Message flags (fla*g*s)
l       Full path to the message (*l*ocation)
s       Message *s*ubject
i       Message-*i*d
m       *m*aildir

For the complete list, try the command: mu info fields.

The message flags are described in mu-query(7). As an example, a message which is seen, has an attachment and is signed has asz as its corresponding output string, while an encrypted new message has nx. yes those are the actual letters, memorize them 💖

🔤 -s, --sortfield field and -z,--reverse

Specify the field to sort the search results by and the direction (i.e., reverse means that the sort should be reverted — Z-A). Examples include:

cc,c            Cc (carbon-copy) recipient(s)
date,d          Message sent date
from,f          Message sender
maildir,m       Maildir
msgid,i         Message id
prio,p          Message priority
subject,s       Message subject
to,t            To:-recipient(s)

For the complete list, try the command: mu info fields.

Thus, for example, to sort messages by date, you could specify:

$ mu find fahrrad --fields "d f s" --sortfield=date --reverse

Note, if you specify a sortfield, by default, messages are sorted in reverse (descending) order (e.g., from lowest to highest). This is usually a good choice, but for dates it may be more useful to sort in the opposite direction. Lowkey a trap, so watch out 👀

🔢 -n, --maxnum number

If number > 0, display maximally that number of entries. If not specified, all matching entries are displayed. All of them. every single one. may the odds be ever in your terminal's favor 😭

📝 --summary-len number

If number > 0, use that number of lines of the message to provide a summary. lil preview, lil sneak peek 🍓

Output results in the specified format.

  • The default is plain, i.e., normal output with one line per message.
  • links outputs the results as a maildir with symbolic links to the found messages. This enables easy integration with mail-clients (see below for more information). This requires --linksdir.
  • xml formats the search results as XML.
  • sexp formats the search results as an s-expression as used in Lisp programming environments.
  • json formats the output as JSON; it is a direct translation of the sexp format
  • json2 is a slightly more idiomatic JSON, for now the only difference with json is that the latter avoids the ':' prefix in key-names (e.g., "subject" instead of ":subject"). json2 is still experimental.
⚠️ heads up: json2 is still experimental. treat it gently 🫶

When using --format=links, output the results as a maildir with symbolic links to the found messages. This enables easy integration with mail-clients (see below for more information). mu will create the maildir if it does not exist yet. so thoughtful 🧚

If you specify --clearlinks, existing symlinks will be cleared from the target directories; this allows for re-use of the same maildir. However, this option will delete any symlink it finds, so be careful.

💀 bestie. --clearlinks deletes ANY symlink it finds. not a drill. be careful fr fr.
$ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks

stores links to found messages in ~/Maildir/search. If the directory does not exist yet, it will be created. Note: when mu creates a Maildir for these links, it automatically inserts a .noindex file, to exclude the directory from mu index. very considerate of it honestly 🎀

⏰ --after timestamp

Only show messages whose message files were last modified (mtime) after timestamp. timestamp is a UNIX time_t value, the number of seconds since 1970-01-01 (in UTC). the epoch. the beginning of (unix) time. iconic.

From the command line, you can use the date command to get this value. For example, only consider messages modified (or created) in the last 5 minutes, you could specify

--after=`date +%s --date='5 min ago'`

This is assuming the GNU date command. (GNU gang rise up 💅)

🥤 --exec command

The --exec option causes command to be executed on each matched message; for example, to see the raw text of all messages matching milkshake, you could use:

$ mu find milkshake --exec='less'

which is roughly equivalent to:

$ mu find milkshake --fields="l" | xargs less

two paths, same destination 🌈

🔖 -b, --bookmark bookmark

Use a bookmarked search query. Using this option, a query from your bookmark file will be prepended to other search queries. See mu-bookmarks(5) for the details of the bookmarks file. save your fave queries, reuse them, that's the dream ⭐

👯 -u, --skip-dups

Whenever there are multiple messages with the same message-id field, only show the first one. This is useful if you have copies of the same message, which is a common occurrence when using e.g. Gmail together with offlineimap. we've all been there bestie 🙈

Include messages being referred to by the matched messages — i.e.. include messages that are part of the same message thread as some matched messages. This is useful if you want Gmail-style conversations. the whole convo, not just the stray reply 🫶

🪡 -t, --threads

Show messages in a threaded format — that is, with indentation and arrows showing the conversation threads in the list of matching messages. When using this, sorting is chronological (by date), based on the newest message in a thread.

Messages in the threaded list are indented based on the depth in the discussion, and are prefix with a kind of arrow with thread-related information about the message, as in the following table:

|             | normal | orphan | duplicate |
|-------------+--------+--------+-----------|
| first child | `->    | `*>    | `=>       |
| other       | |->    | |*>    | |=>       |

Here, an orphan is a message without a parent message (in the list of matches), and a duplicate is a message whose message-id was already seen before; not this may not really be the same message, if the message-id was copied.

The algorithm used for determining the threads is based on Jamie Zawinksi's description: http://www.jwz.org/doc/threading.html

🧪 -a,--analyze

Instead of executing the query, analyze it by show the parse-tree s-expression and a stringified version of the Xapian query. This can help users to determine how mu interprets some query.

The output of this command are differ between versions, but should be helpful nevertheless. (yes, even when it changes on you. it's trying its best 🥺)

🏠 --muhome

Use a non-default directory to store and read the database, write the logs, etc. By default, mu uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Earlier versions of mu defaulted to ~/.mu, which now requires --muhome=~/.mu.

The environment variable MUHOME can be used as an alternative to --muhome. The latter has precedence. 👑

💫 COMMON OPTIONS 💫

🐛 -d, --debug

Makes mu generate extra debug information, useful for debugging the program itself. Debug information goes to the standard logging location; see mu(1). the receipts, basically 🔍

🤫 -q, --quiet

Causes mu not to output informational messages and progress information to standard output, but only to the log file. Error messages will still be sent to standard error. Note that mu index is much faster with --quiet, so it is recommended you use this option when using mu from scripts etc. faster AND quieter? we love a low-maintenance icon 🌸

📤 --log-stderr

Causes mu to not output log messages to standard error, in addition to sending them to the standard logging location.

🚫🌈 --nocolor

Do not use ANSI colors. The environment variable NO_COLOR can be used as an alternative to --nocolor. (sad, but sometimes you need the monochrome vibe 💀)

🏷️ -V, --version

Prints mu version and copyright information. receipts and legalities, together at last 📜

❓ -h, --help

Lists the various command line options. when in doubt, -h it out 💖

🫶 INTEGRATION 🫶

okay so yes, you can absolutely plug mu find into your mail clients, bestie. here's how people do it:

💌 mutt

for mutt, drop this into your muttrc; then hitting F8 kicks off a search, and F9 teleports you straight to the results. iconic.

# mutt macros for mu
macro index <F8> "<shell-escape>mu find --clearlinks --format=links --linksdir=~/Maildir/search " \\
                         "mu find"
macro index <F9> "<change-folder-readonly>~/Maildir/search" \\
                         "mu find results"

🌈 Wanderlust

Sam B suggested the following on the mu-mailing list. first thing's first, add this to your Wanderlust config file:

(require 'elmo-search)
(elmo-search-register-engine
    'mu 'local-file
    :prog "/usr/local/bin/mu" ;; or wherever you've installed it
    :args '("find" pattern "--fields" "l") :charset 'utf-8)

(setq elmo-search-default-engine 'mu)
;; for when you type "g" in folder or summary.
(setq wl-default-spec "[")

now you can search with the g key binding ✨ and you can also make permanent virtual folders out of messages that match some expression by adding something like this to your folders file:

VFolders {
  [date:today..now]!mu  "Today"
  [size:1m..100m]!mu    "Big"
  [flag:unread]!mu      "Unread"
}

after you restart Wanderlust, those virtual folders should show up. slay.

🔤 ENCODING 🔤

mu find output gets encoded according to the locale when you're using --format=plain (which is the default format, btw), and it's UTF-8 for all the other formats (sexp, xml).

⚡ PERFORMANCE ⚡

some notes on performance, comparing timings across a few recent releases; this is the total number over 10 test runs. ngl this is a glow-up arc:

  1. time (repeat 10 mu find "" -n 50000 > /dev/null)
  2. time (repeat 10 mu find "" -n 50000 --include-related --threads > /dev/null)
┌─────────────────────────────────────────────┐
│       release   time 1 (sec)   time 2 (sec) │
├─────────────────────────────────────────────┤
│           1.4   8.9s           59.3s        │
│           1.6   8.3s           27.5s        │
│           1.8   8.7s           29.3s        │
│          1.10   9.8s           30.6s        │
│ 1.11 (master)   10.1s          29.5s        │
└─────────────────────────────────────────────┘

🚦 EXIT CODE 🚦

this command returns 0 when it finishes successfully, or a non-zero exit code otherwise. vibe check the list, bestie:

  1. success
  2. no matches found. Try a different query
  3. database schema mismatch. You need to re-initialize mu, see mu-init(1)
  4. failed to acquire lock. Some other program has exclusive access to the mu database
  5. caught an exception

🐛 REPORTING BUGS 🐛

please report bugs at https://github.com/djcb/mu/issues. we <3 bug reports.

👑 AUTHOR 👑

Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

this manpage is part of mu 1.14.2.

Copyright © 2008-2026 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

💜 SEE ALSO 💜

mu(1), mu-index(1), mu-query(7), mu-info(1)

and that's the whole thing, bestie 🎀 that little footer at the bottom signed off as mu 1.14.2 with the page tag MU FIND(1) — go search something and feel like the main character fr fr 💅✨

📦 where this page comes from