--- name: "mu-cfind" section: "1" platform: "linux" package: "maildir-utils" version: "1.12.9-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/mu-cfind" --- # mu-cfind(1) find contacts in the mu database and export them for use in other programs. ## NAME mu-cfind - find contacts in the **mu** database and export them for use in other programs. ## SYNOPSIS **mu** \[*COMMON-OPTIONS*\] **cfind** \[*OPTIONS*\] \[*PATTERN*\] ## DESCRIPTION **mu cfind** is the **mu** command for finding *contacts* (name and e-mail address of people who were either an e-mail's sender or receiver). There are different output formats available, for importing the contacts into other programs. ## SEARCHING CONTACTS When you index your messages (see **mu index**), **mu** creates a list of unique e-mail addresses found and the accompanying name, and caches this list. In case the same e-mail address is used with different names, the most recent non-empty name is used. **mu cfind** starts a search for contacts that match a *regular expression*. For example: ``` $ mu cfind '@gmail\.com' ``` would find all contacts with a gmail-address, while ``` $ mu cfind Mary ``` lists all contacts with Mary in either name or e-mail address. If you do not specify a search expression, **mu cfind** returns the full list of contacts. Note, **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)](/pcre/3.md). ## CFIND OPTIONS ### --format plain\|mutt-alias\|mutt-ab\|wl\|org-contact\|bbdb\|csv Sets the output format to the given value. The following are available: | | | | --- | --- | | --format= | description | | plain | default, simple list | | mutt-alias | mutt alias-format | | mutt-ab | mutt external address book format | | wl | wanderlust addressbook 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 one of \`my' e-mail addresses was seen in one of the address fields; this is to exclude addresses only seen in mailing-list messages. See the **--my-address** parameter to **mu init**. ### --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, 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)](/mu/1.md). ### -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 ", "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\" ", "last-seen" : 1425991805, "last-seen-iso" : "2015-03-10T14:50:05Z", "personal" : true, "frequency" : 2 } ] ``` Each contact has the following fields: | | | | --- | --- | | property | description | | `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)](/jq/1.md) 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**. ## ENCODING **mu cfind** output is encoded according to the current locale except for **--format=bbdb**. This is hard-coded to UTF-8, and as such specified in the output-file, so emacs/bbdb can handle things correctly, without guessing. ## EXIT CODE This command returns 0 upon successful completion, or a non-zero exit code otherwise. - 0\. success - 2\. no matches found. Try a different query - 11\. database schema mismatch. You need to re-initialize **mu**, see [**mu-init**(1)](/mu-init/1.md) - 19\. failed to acquire lock. Some other program has exclusive access to the **mu** database - 99\. caught an exception ## REPORTING BUGS Please report bugs at *https://github.com/djcb/mu/issues*. ## AUTHOR Dirk-Jan C. Binnema \ ## COPYRIGHT This manpage is part of **mu** 1.12.9. Copyright © 2008-2025 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/1.md), [**mu-index**(1)](/mu-index/1.md), [**mu-find**(1)](/mu-find/1.md), [**pcre**(3)](/pcre/3.md), [**jq**(1)](/jq/1.md)