1MU CFIND(1) General Commands Manual MU CFIND(1)
2
6 mu cfind is the mu command to find contacts in the mu database and ex‐
7 port them for use in other programs.
8
11 mu [common-options] cfind [options] [<pattern>]
12
15 mu cfind is the mu command for finding contacts (name and e-mail ad‐
16 dress of people who were either an e-mail's sender or receiver). There
17 are different output formats available, for importing the contacts into
18 other programs.
19
22 When you index your messages (see mu index), mu creates a list of
23 unique e-mail addresses found and the accompanying name, and caches
24 this list. In case the same e-mail address is used with different
25 names, the most recent non-empty name is used.
26 mu cfind starts a search for contacts that match a regular expression.
29 For example:
30 $ mu cfind '@gmail.com'
32 would find all contacts with a gmail-address, while
36 $ mu cfind Mary
38 lists all contacts with Mary in either name or e-mail address.
42 If you do not specify a search expression, mu cfind returns the full
45 list of contacts. Note, mu cfind uses a cache with the e-mail informa‐
46 tion, which is populated during the indexing process.
47 The regular expressions are basic case-insensitive PCRE, see pcre(3).
50
53 --format=plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv
54 sets the output format to the given value. The following are available:
55 ┌────────────────────────────────────────────────┐
58 │--format= description │
59 ├────────────────────────────────────────────────┤
60 │plain default, simple list │
61 │mutt-alias mutt alias-format │
62 │mutt-ab mutt external address book format │
63 │wl wanderlust addressbook format │
64 │org-contact org-mode org-contact format │
65 │bbdb BBDB format │
66 │csv comma-separated values [1] │
67 │json JSON format │
68 └────────────────────────────────────────────────┘
69 [1] CSV is not fully standardized, but *mu cfind follows some common
72 practices: any double-quote is replaced by a double-double quote (thus,
73 "hello" become ""hello"", and fields with commas are put in double-
74 quotes. Normally, this should only apply to name fields.
75 --personal,-p only show addresses seen in messages where one of 'my' e-mail
78 addresses was seen in one of the address fields; this is to exclude ad‐
79 dresses only seen in mailing-list messages. See the --my-address param‐
80 eter to mu init.
81 --after=<timestamp> only show addresses last seen after
84 <timestamp>. <timestamp> is a UNIX timet value, the number of seconds
85 since 1970-01-01 (in UTC).
86 From the command line, you can use the date command to get this value.
89 For example, only consider addresses last seen after 2020-06-01, you
90 could specify
91 --after=`date +%s --date='2020-06-01'`
92 --muhome
96 use a non-default directory to store and read the database, write the
97 logs, etc. By default, mu uses the XDG Base Directory Specification
98 (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Ear‐
99 lier versions of mu defaulted to ~/.mu, which now requires
100 --muhome=~/.mu.
101 The environment variable MUHOME can be used as an alternative to
104 --muhome. The latter has precedence.
105
108 -d, --debug
109 makes mu generate extra debug information, useful for debugging the
110 program itself. By default, debug information goes to the log file,
111 ~/.cache/mu/mu.log. It can safely be deleted when mu is not running.
112 When running with --debug option, the log file can grow rather quickly.
113 See the note on logging below.
114 -q, --quiet
117 causes mu not to output informational messages and progress information
118 to standard output, but only to the log file. Error messages will still
119 be sent to standard error. Note that mu index is much faster with
120 --quiet, so it is recommended you use this option when using mu from
121 scripts etc.
122 --log-stderr
125 causes mu to not output log messages to standard error, in addition to
126 sending them to the log file.
127 --nocolor
130 do not use ANSI colors. The environment variable NO_COLOR can be used
131 as an alternative to --nocolor.
132 -V, --version
135 prints mu version and copyright information.
136 -h, --help
139 lists the various command line options.
140
143 With --format=json, the matching contacts come out as a JSON array,
144 e.g.,
145 [
146 {
147 "email" : "syb@example.com",
148 "name" : "Sybil Gerard",
149 "display" : "Sybil Gerard <syb@example.com>",
150 "last-seen" : 1075982687,
151 "last-seen-iso" : "2004-02-05T14:04:47Z",
152 "personal" : false,
153 "frequency" : 14
154 },
155 {
156 "email" : "ed@example.com",
157 "name" : "Mallory, Edward",
158 "display" : "
159 "last-seen" : 1425991805,
160 "last-seen-iso" : "2015-03-10T14:50:05Z",
161 "personal" : true,
162 "frequency" : 2
163 }
164 ]
165 Each contact has the following fields:
169┌─────────────────────────────────────────────────────────────────────────────────────────┐
172│property description │
173├─────────────────────────────────────────────────────────────────────────────────────────┤
174│email the email-address │
175│name the name (or none) │
176│display the combination name and e-mail address for display purposes │
177│last-seen date of most recent message with this contact (Unix time) │
178│last-seen-iso last-seen represented as an ISO-8601 timestamp │
179│personal whether the email was seen in a message together with a personal address │
180│frequency approximation of the number of times this contact was seen in messages │
181└─────────────────────────────────────────────────────────────────────────────────────────┘
182 The JSON format is useful for further processing, e.g. using the jq(1)
184 tool:
185 List display names, sorted by their last-seen date:
188 $ mu cfind --format=json --personal | jq -r '.[] | ."last-seen-iso" + " " + .display' | sort
189
193 You can use mu cfind as an external address book server for mutt. For
194 this to work, add the following to your muttrc:
195 set query_command = "mu cfind --format=mutt-ab '%s'"
197 Now, in mutt, you can search for e-mail addresses using the query-com‐
201 mand, which is (by default) accessible by pressing Q.
202
205 mu cfind output is encoded according to the current locale except for
206 --format=bbdb. This is hard-coded to UTF-8, and as such specified in
207 the output-file, so emacs/bbdb can handle things correctly, without
208 guessing.
209
212 This command returns 0 upon successful completion, or a non-zero exit
213 code otherwise. Typical values are 2 (no matches found), 11 (database
214 schema mismatch) and 12 (failed to acquire database lock).
215 no matches found (2)
218 Nothing matching found; try a different query
219 database schema mismatch (11)
222 You need to re-initialize mu, see mu-init(1)
223 failed to acquire lock (19)
226 Some other program has exclusive access to the mu (Xapian) database
227
230 Please report bugs at https://github.com/djcb/mu/issues.
231
234 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
235
238 This manpage is part of mu 1.10.5.
239 Copyright © 2022-2023 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL ver‐
242 sion 3 or later https://gnu.org/licenses/gpl.html. This is free soft‐
243 ware: you are free to change and redistribute it. There is NO WARRANTY,
244 to the extent permitted by law.
245
248 mu(1), mu-index(1), mu-find(1), pcre(3), jq(1)
249 MU CFIND(1)