Provided by: maildir-utils_1.10.8-2build3_amd64 
NAME
mucfind - 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).
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.
--personal,-p 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 timet 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. By
default, debug information goes to the log file, ~/.cache/mu/mu.log. It can safely be
deleted when mu is not running. When running with --debug option, the log file can grow
rather quickly. See the note on logging below.
-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
log file.
--nocolor
do not use ANSI colors. The environment variable NOCOLOR 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" : "
"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) 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.
Typical values are 2 (no matches found), 11 (database schema mismatch) and 12 (failed to
acquire database lock).
no matches found (2)
Nothing matching found; try a different query
database schema mismatch (11)
You need to re-initialize mu, see mu-init(1)
failed to acquire lock (19)
Some other program has exclusive access to the mu (Xapian) database
REPORTING BUGS
Please report bugs at https://github.com/djcb/mu/issues.
AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
COPYRIGHT
This manpage is part of mu 1.10.8.
Copyright © 2022-2023 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)
MU CFIND(1)