1MU-SERVER(1) General Commands Manual MU-SERVER(1)
2
6 mu server - the mu backend for the mu4e e-mail client
7
10 mu server [options]
11
14 mu server starts a simple shell in which one can query and manipulate
15 the mu database. The output of the commands is terms of Lisp symbolic
16 expressions (s-exps). mu server is not meant for use by humans;
17 instead, it is designed specifically for the mu4e e-mail client.
18 In this man-page, we document the commands mu server accepts, as well
20 as their responses. In general, the commands sent to the server are of
21 the form
22 cmd:<command> [<parameters>]*
24 where each of the parameters is prefixed by their name and a colon. For
26 example, to view a certain message, the command would be:
27 cmd:view docid:12345
29 Parameters can be sent in any order, and parameters not used by a cer‐
31 tain command are simply ignored.
32
36 mu server accepts a number of commands, and delivers its results in the
37 form:
38 \376<length>\377<s-expr>
40 \376 (one byte 0xfe), followed by the length of the s-expression
42 expressed as an hexadecimal number, followed by another \377 (one byte
43 0xff), followed by the actual s-expression.
44 By prefixing the expression with its length, it can be processed more
46 efficiently. The \376 and \377 were chosen since they never occur in
47 valid UTF-8 (in which the s-expressions are encoded).
48
51 add
52 Using the add command, we can add a message to the database.
54 -> cmd:add path:<path> maildir:<maildir>
56 <- (:info add :path <path> :docid <docid>)
57 compose
61 Using the compose command, we get the (original) message, and
63 tell what to do with it. The user-interface is then expected to
64 pre-process the message, e.g. set the subject, sender and recip‐
65 ient for a reply message.
66 Messages of type 'new' don't use the docid: parameter, the other
68 ones do.
69 -> cmd:compose type:<reply|forward|edit|new> [docid:<docid>]
71 <- (:compose <reply|forward|edit|new> :original <s-exp> :include (<list-of-attachments))
72 The <list-of-attachments> is an s-expression describing the
74 attachments to include in the message; this currently only
75 applies to message we are forwarding. This s-expression looks
76 like:
77 (:file-name <filename> :mime-type <mime-type> :disposition <disposition>)
79 contacts
83 Using the compose command, we can retrieve an s-expression with
85 all known contacts (name + e-mail address). For the details, see
86 mu-cfind(1).
87 -> cmd:contacts [personal:true|false] [after:<time_t>]
89 <- (:contacts ((:name abc :mail foo@example.com ...) ...)
90 extract
94 Using the extract command we can save and open attachments.
96 -> cmd:extract action:<save|open|temp> index:<index> [path:<path>] [what:<what> [param:<param>]]
97 If the action is 'save', the path argument is required; the
99 attachment will be saved, and a message
100 <- (:info save :message "... has been saved")
101 is sent.
102 If the action is 'open', the attachment will saved to a tempo‐
104 rary file, after which it will be opened with the default han‐
105 dler for this kind of file (see mu-extract(1)), and a message
106 <- (:info open :message "... has been opened")
107 is sent.
108 If the action is 'temp', the arguments 'what' is required. The
110 attachment will saved to a temporary file, and the following
111 message is sent:
112 <- (:temp :what <what> :param <param :docid 12345)
113 The front-end can then take action on the temp file, based on
114 what :what and :param contain. mu4e uses this mechanism e.g. for
115 piping an attachment to a shell command.
116 find
119 Using the find command we can search for messages.
121 -> cmd:find query:"<query>" [threads:true|false] [sortfield:<sortfield>]
122 [reverse:true|false] [maxnum:<maxnum>]
123 The query-parameter provides the search query; the threads-
124 parameter determines whether the results will be returned in
125 threaded fashion or not; the sortfield-parameter (a string,
126 "to", "from", "subject", "date", "size", "prio") sets the search
127 field, the reverse-parameter, if true, set the sorting order
128 Z->A and, finally, the maxnum-parameter limits the number of
129 results to return (<= 0 means 'unlimited').
130 First, this will return an 'erase'-sexp, to clear the buffer
132 from possible results from a previous query.
133 <- (:erase t)
134 This will return a series of 0 up to <maxnum> s-expression cor‐
136 responding to each message found (if there's no maxnum, all
137 results will be returned). The information message s-exps this
138 function returns do not contain the message body; the view com‐
139 mand is for that.
140 <- (...)
141 and finally, we receive:
142 <- (:found <number-of-matches>)
143 guile The guile command is reserved for future use.
147 index
151 Using the index command, we can (re)index the database, similar
153 to what mu find does. The my-addresses parameter (optionally)
154 registers 'my' email addresses; see the documentation for
155 mu_store_set_my_addresses.
156 -> cmd:index path:<path> [my-addresses:<comma-separated-list-of-email-addresses>]
158 As a response, it will send (for each 1000 messages):
159 (:info index :status running :processed <processed> :updated <updated>)
160 and finally:
161 (:info index :status complete :processed <processed :updated <updated>
162 :cleaned-up <cleaned-up>)
163 mkdir
166 Using the mkdir command, we can create a new maildir.
168 -> cmd:mkdir path:<path>
170 <- (:info mkdir :message "<maildir> has been created")
171 move
174 Using the move command, we can move messages to another maildir
176 or change its flags (which ultimately means it is being move to
177 a different filename), and update the database correspondingly.
178 The function returns an s-exp describing the updated message, so
179 that it can be updated in the user interface.
180 -> cmd:move docid:<docid>|msgid:<msgid> [maildir:<maildir>] [flags:<flags>]
182 <- (:update <s-exp> :move t)
183 One of docid and msgid must be specified to identify the mes‐
185 sage. At least one of maildir and flags must be specified.
186 ping
190 The ping command provokes a pong response. It is used for the
192 initial handshake between mu4e and mu server.
193 -> cmd:ping
194 <- (:pong "mu" :version <version> :doccount <doccount>)
195 remove
198 Using the remove command, we can remove the message from disk,
200 and update the database accordingly.
201 -> cmd:remove docid:<docid>
203 <- (:remove <docid>)
204 view
208 Using the view command, we can retrieve all information (includ‐
210 ing the body) of a particular e-mail message.
211 If the optional parameter extract-images is true, extract images
213 to temp files, and include links to them in the returned s-exp.
214 If the optional parameter use-agent is true, try to use gpg-
216 agent when verifying PGP/GPG message parts.
217 If the optional parameter auto-retrieve-key is true, attempt to
219 retrieve public keys online automatically.
220 -> cmd:view docid:<docid>|msgid:<msgid> [extract-images:true] [use-agent:false] [auto-retrieve-key:false]
222 <- (:view <s-exp>)
223 or, alternatively:
225 -> cmd:view path:<path-to-msg> [extract-images:true] [use-agent:false] [auto-retrieve-key:false]
227 <- (:view <s-exp>)
228
231 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
232
235 mu(1)
236User Manuals September 2012 MU-SERVER(1)