'\" t .ftr C B .TH "MU CFIND" "1" .SH "NAME" .PP mu-cfind - find contacts in the \fBmu\fP database and export them for use in other programs. .SH "SYNOPSIS" .PP \fBmu [common-options] cfind [options] []\fP .SH "DESCRIPTION" .PP \fBmu cfind\fP is the \fBmu\fP command for finding \fIcontacts\fP (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. .SH "SEARCHING CONTACTS" .PP When you index your messages (see \fBmu index\fP), \fBmu\fP 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. .PP \fBmu cfind\fP starts a search for contacts that match a \fIregular expression\fP. For example: .RS .nf $ mu cfind '@gmail\.com' .fi .RE .PP would find all contacts with a gmail-address, while .RS .nf $ mu cfind Mary .fi .RE .PP lists all contacts with Mary in either name or e-mail address. .PP If you do not specify a search expression, \fBmu cfind\fP returns the full list of contacts. Note, \fBmu cfind\fP uses a cache with the e-mail information, which is populated during the indexing process. .PP The regular expressions are basic case-insensitive PCRE, see \fBpcre(3)\fP. .SH "CFIND OPTIONS" .SS "--format=plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv" .PP sets the output format to the given value. The following are available: .TS center,box; l l . --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 .TE .PP [1] \fBCSV\fP is not fully standardized, but \fBmu cfind\fP 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. .SS "--personal,-p only show addresses seen in messages where one of `my' e-mail" .PP addresses was seen in one of the address fields; this is to exclude addresses only seen in mailing-list messages. See the \fC\-\-my\-address\fP parameter to \fBmu init\fP. .SS "--after= only show addresses last seen after" .PP \fI\fP. \fI\fP is a UNIX \fBtime_t\fP value, the number of seconds since 1970-01-01 (in UTC). .PP From the command line, you can use the \fBdate\fP command to get this value. For example, only consider addresses last seen after 2020-06-01, you could specify .RS .nf --after=`date +%s --date='2020-06-01'` .fi .RE .SS "--muhome" .PP use a non-default directory to store and read the database, write the logs, etc. By default, \fCmu\fP uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to \fI~/.cache/mu\fP and \fI~/.config/mu\fP). Earlier versions of \fCmu\fP defaulted to \fI~/.mu\fP, which now requires \fI\-\-muhome=~/.mu\fP. .PP The environment variable \fCMUHOME\fP can be used as an alternative to \fC\-\-muhome\fP. The latter has precedence. .SH "COMMON OPTIONS" .SS "-d, --debug" .PP 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. .SS "-q, --quiet" .PP 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. .SS "--log-stderr" .PP causes mu to not output log messages to standard error, in addition to sending them to the log file. .SS "--nocolor" .PP do not use ANSI colors. The environment variable \fCNO_COLOR\fP can be used as an alternative to \fC\-\-nocolor\fP. .SS "-V, --version" .PP prints mu version and copyright information. .SS "-h, --help" .PP lists the various command line options. .SH "JSON FORMAT" .PP With \fC\-\-format=json\fP, the matching contacts come out as a JSON array, e.g., .RS .nf [ { "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 } ] .fi .RE .PP Each contact has the following fields: .TS center,box; l l . property description _ \fCemail\fP the email-address \fCname\fP the name (or \fCnone\fP) \fCdisplay\fP the combination name and e-mail address for display purposes \fClast\-seen\fP date of most recent message with this contact (Unix time) \fClast\-seen\-iso\fP \fClast\-seen\fP represented as an ISO-8601 timestamp \fCpersonal\fP whether the email was seen in a message together with a personal address \fCfrequency\fP approximation of the number of times this contact was seen in messages .TE .PP The JSON format is useful for further processing, e.g. using the \fBjq(1)\fP tool: .PP List display names, sorted by their last-seen date: .RS .nf $ mu cfind --format=json --personal | jq -r '.[] | ."last-seen-iso" + " " + .display' | sort .fi .RE .SH "INTEGRATION WITH MUTT" .PP You can use \fBmu cfind\fP as an external address book server for \fBmutt\fP. For this to work, add the following to your \fImuttrc\fP: .RS .nf set query_command = "mu cfind --format=mutt-ab '%s'" .fi .RE .PP Now, in mutt, you can search for e-mail addresses using the \fBquery\fP-command, which is (by default) accessible by pressing \fBQ\fP. .SH "ENCODING" .PP \fBmu cfind\fP output is encoded according to the current locale except for \fI\-\-format=bbdb\fP. This is hard-coded to UTF-8, and as such specified in the output-file, so emacs/bbdb can handle things correctly, without guessing. .SH "EXIT CODE" .PP This command returns 0 upon successful completion, or a non-zero exit code otherwise. .IP 0. 4 success .IP 2. 4 no matches found. Try a different query .IP 11. 4 database schema mismatch. You need to re-initialize \fCmu\fP, see \fBmu-init(1)\fP .IP 19. 4 failed to acquire lock. Some other program has exclusive access to the mu database .IP 99. 4 caught an exception .SH "REPORTING BUGS" .PP Please report bugs at \fIhttps://github.com/djcb/mu/issues\fP. .SH "AUTHOR" .PP Dirk-Jan C. Binnema .SH "COPYRIGHT" .PP This manpage is part of \fCmu\fP 1.12.3. .PP Copyright © 2008-2024 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later \fIhttps://gnu.org/licenses/gpl.html\fP. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. .SH "SEE ALSO" .PP \fBmu(1)\fP, \fBmu-index(1)\fP, \fBmu-find(1)\fP, \fBpcre(3)\fP, \fBjq(1)\fP