MU-CFIND(1)

📦
version 1.14.2 · 10 versions
, in ubuntu stonking

💖 MU CFIND(1) — the contact-finder era 💖

okay bestie, pull up a chair, we're doing mu-cfind today ✨ this one's from the General Commands Manual section, and it's genuinely one of the most underrated little tools in the mu fam. let's get into it 🫶

🌸 NAME 🌸

mu-cfind — find contacts in the mu database and export them so other programs can have them too. it's giving "sharing is caring" but for your address book 💅

🦋 SYNOPSIS 🦋

mu [COMMON-OPTIONS] cfind [OPTIONS] [PATTERN]

✨ DESCRIPTION ✨

mu cfind is the mu command for finding contacts — and when we say contacts we mean the name and e-mail address of every person who was either an e-mail's sender or receiver 👑 not me casually building a whole social graph out of your inbox.

and the best part? different output formats are available, so you can import those contacts straight into other programs. slay 🌈

🔍 SEARCHING CONTACTS 🔍

so when you index your messages (see mu index), mu creates a list of unique e-mail addresses it found, plus the accompanying name, and caches that list 💾

if the same e-mail address shows up with different names, the most recent non-empty name is the one that wins. if that's not the name you wanted… see CORRECTING below, bestie, we got you 🙈

mu cfind starts a search for contacts that match a regular expression. for example:

$ mu cfind '@gmail\.com'

finds all contacts with a gmail-address, while

$ mu cfind Mary

lists all contacts with Mary in either the name or the e-mail address. literally so easy 💅

if you do not specify a search expression, mu cfind returns the full list of contacts. mu cfind uses a cache with the e-mail information, which is populated during the indexing process.

the regular expressions are basic case-insensitive PCRE, see pcre(3).

🎀 CFIND OPTIONS 🎀

💌 --format plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv

sets the output format to the given value. here's everything that's on the menu:

  • plain — default, simple list
  • mutt-alias — mutt alias-format
  • mutt-ab — mutt external address book format
  • wl — wanderlust address book format
  • org-contact — org-mode org-contact format
  • bbdb — BBDB format
  • csv — comma-separated values [1]
  • json — JSON format
[1] CSV is not fully standardized, but mu cfind follows some common practices: any double-quote is replaced by a double-double quote (thus, "hello" become ""hello""), and fields with commas are put in double-quotes. Normally, this should only apply to name fields.

💗 -p, --personal

only show addresses seen in messages where at least one of your personal e-mail addresses was seen in any of the address fields 🫶 this is to exclude addresses only seen in mailing-list messages. see the --personal-address parameter to mu init for specifying your personal e-mail addresses.

⏰ --after timestamp

only show addresses last seen after timestamp. timestamp is a UNIX time_t value — the number of seconds since 1970-01-01 (in UTC).

from the command line, you can use the date command to get this value. for example, to only consider addresses last seen after 2020-06-01, you could specify

--after=$(date +%s --date='2020-06-01')

🏠 --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).

🤫 -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. 🔥

📜 --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.

💜 -V, --version

prints mu version and copyright information.

🙋 -h, --help

lists the various command line options.

🌸 JSON FORMAT 🌸

with --format=json, the matching contacts come out as a JSON array, e.g.

[
  {
    "email"         : "syb@example.com",
    "name"          : "Sybil Gerard",
    "display"       : "Sybil Gerard <syb@example.com>",
    "last-seen"     : 1075982687,
    "last-seen-iso" : "2004-02-05T14:04:47Z",
    "personal"      : false,
    "frequency"     : 14
  },
  {
    "email"         : "ed@example.com",
    "name"          : "Mallory, Edward",
    "display"       : "\"Mallory, Edward\" <ed@example.com>",
    "last-seen"     : 1425991805,
    "last-seen-iso" : "2015-03-10T14:50:05Z",
    "personal"      : true,
    "frequency"     : 2
  }
]

each contact has the following fields:

  • email — the email-address
  • name — the name (or none)
  • display — the combination name and e-mail address for display purposes
  • last-seen — date of most recent message with this contact (Unix time)
  • last-seen-iso — last-seen represented as an ISO-8601 timestamp
  • personal — whether the email was seen in a message together with a personal address
  • frequency — approximation of the number of times this contact was seen in messages

the JSON format is useful for further processing, e.g. using the jq(1) tool 🫶

list display names, sorted by their last-seen date:

$ mu cfind --format=json --personal | jq -r '.[] | ."last-seen-iso" + " " + .display' | sort

🧚 INTEGRATION WITH MUTT 🧚

you can use mu cfind as an external address book server for mutt. for this to work, add the following to your muttrc:

set query_command = "mu cfind --format=mutt-ab '%s'"

now, in mutt, you can search for e-mail addresses using the query-command, which is (by default) accessible by pressing Q. go off 👑

🌈 ENCODING 🌈

mu cfind output is encoded according to the current locale — except for --format=bbdb. that one is hard-coded to UTF-8, and as such specified in the output-file, so emacs/bbdb can handle things correctly, without guessing ✨

💅 CORRECTING 💅

if you want to correct the name for a given contact, one trick is to manual create an e-mail message with some future date that has all the correct name / e-mail address combinations, and put this in the Maildir you use. lowkey genius, highkey chaotic 🍓

💀 EXIT CODE 💀

this command returns 0 upon successful completion, or a non-zero exit code otherwise.

  1. 0 — success
  2. 2 — no matches found. Try a different query
  3. 11 — database schema mismatch. You need to re-initialize mu, see mu-init(1)
  4. 19 — failed to acquire lock. Some other program has exclusive access to the mu database
  5. 99 — caught an exception
not the schema mismatch and the lock drama 😭 if you see 11 or 19, that's a whole situation, bestie.

🐞 REPORTING BUGS 🐞

please report bugs at https://github.com/djcb/mu/issues.

👑 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-find(1), pcre(3), jq(1)

k that's the whole thing, bestie 💖 this is mu-cfind(1) from the General Commands Manual, part of mu 1.14.2 — now go find some contacts and slay ✨🎀🦋

📦 where this page comes from