#+TITLE: MU CFIND
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"

* 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:

#+begin_example
$ mu cfind '@gmail\.com'
#+end_example

would find all contacts with a gmail-address, while

#+begin_example
$ mu cfind Mary
#+end_example

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:

#+ATTR_MAN: :disable-caption t
| --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 *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
#+begin_example
  --after=`date +%s --date='2020-06-01'`
#+end_example

#+include: "muhome.inc" :minlevel 2

#+include: "common-options.inc" :minlevel 1

* JSON FORMAT

With ~--format=json~, the matching contacts come out as a JSON array, e.g.,
#+begin_example
[
  {
    "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
  }
]
#+end_example

Each contact has the following fields:

#+ATTR_MAN: :disable-caption t
| 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:
#+begin_example
$ mu cfind --format=json --personal | jq -r '.[] | ."last-seen-iso" + " " + .display' | sort
#+end_example

* 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=:

#+begin_example
set query_command = "mu cfind --format=mutt-ab '%s'"
#+end_example

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.

#+include: "exit-code.inc" :minlevel 1

#+include: "bugs.inc" :minlevel 1

#+include: "author.inc" :minlevel 1

#+include: "copyright.inc" :minlevel 1

* SEE ALSO
*mu(1)*, *mu-index(1)*, *mu-find(1)*, *pcre(3)*, *jq(1)*