Skip to content
This repository
Newer
Older
100644 269 lines (198 sloc) 7.224 kb
e621fadf »
2012-07-19 * update manpage, add mu-help manpage
1 .TH MU-SERVER 1 "July 2012" "User Manuals"
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
2
3 .SH NAME
4
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
5 mu server \- the mu backend for the mu4e e-mail client
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
6
e621fadf »
2012-07-19 * update manpage, add mu-help manpage
7 .SH SYNOPSIS
8
9 .B mu server [options]
10
97d2e0e2 » djcb
2011-12-07 * beginnings of mu-server documentations (WIP)
11 .SH DESCRIPTION
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
12
e621fadf »
2012-07-19 * update manpage, add mu-help manpage
13 \fBmu server\fR starts a simple shell in which one can query and manipulate
14 the mu database. The output of the commands is terms of Lisp symbolic
15 expressions (s-exps). \fBmu server\fR is not meant for use by humans; instead,
16 it is designed specifically for the \fBmu4e\fR e-mail client.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
17
18 In this man-page, we document the commands \fBmu server\fR accepts, as well as
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
19 their responses. In general, the commands sent to the server are of the form
20
21 .nf
22 <command> [<parameters>]*
23 .fi
24
25 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
28 .nf
29 view docid:12345
30 .fi
31
32 Parameters can be sent in any order, and parameters not used by a certain
33 command are simply ignored.
34
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
35
97d2e0e2 » djcb
2011-12-07 * beginnings of mu-server documentations (WIP)
36 .SH OUTPUT FORMAT
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
37
97d2e0e2 » djcb
2011-12-07 * beginnings of mu-server documentations (WIP)
38 \fBmu server\fR accepts a number of commands, and delivers its results in
39 the form:
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
40
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
41 .nf
422516a7 »
2012-04-29 * mu-server.1: update manpage for the mu client/server protocol changes
42 \\376<length>\\377<s-expr>
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
43 .fi
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
44
422516a7 »
2012-04-29 * mu-server.1: update manpage for the mu client/server protocol changes
45 \\376 (one byte 0xfe), followed by the length of the s-expression expressed as
46 an hexadecimal number, followed by another \\377 (one byte 0xff), followed by
47 the actual s-expression.
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
48
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
49 By prefixing the expression with its length, it can be processed more
422516a7 »
2012-04-29 * mu-server.1: update manpage for the mu client/server protocol changes
50 efficiently. The \\376 and \\377 were chosen since they never occur in valid
51 UTF-8 (in which the s-expressions are encoded).
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
52
97d2e0e2 » djcb
2011-12-07 * beginnings of mu-server documentations (WIP)
53 .SH COMMAND AND RESPONSE
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
54
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
55 .TP
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
56 .B add
57
58 Using the \fBadd\fR command, we can add a message to the database.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
59
60 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
61 -> add path:<path> maildir:<maildir>
62 <- (:info add :path <path> :docid <docid>)
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
63 .fi
64
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
65
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
66 .TP
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
67 .B compose
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
68
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
69 Using the \fBcompose\fR command, we get the (original) message, and tell what
70 to do with it. The user-interface is then expected to pre-process the message,
71 e.g. set the subject, sender and recipient for a reply message.
72
73 Messages of type 'new' don't use the docid: parameter, the other ones do.
67261b61 »
2012-03-25 * implement the :erase message from the backend to properly clean up the
74
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
75 .nf
635e049f »
2012-06-18 * mu-cmd-server: add the 'contacts' command, which gives us the conta…
76 -> compose type:<reply|forward|edit|new> [docid:<docid>]
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
77 <- (:compose <reply|forward|edit|new> :original <s-exp> :include (<list-of-attachments))
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
78 .fi
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
79
80 The <list-of-attachments> is an s-expression describing the attachments to
81 include in the message; this currently only applies to message we are
82 forwarding. This s-exprssion looks like:
83
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
84 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
85 (:file-name <filename> :mime-type <mime-type> :disposition <disposition>)
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
86 .fi
87
88
89 .TP
635e049f »
2012-06-18 * mu-cmd-server: add the 'contacts' command, which gives us the conta…
90 .B contacts
91
92 Using the \fBcompose\fR command, we can retrieve an s-expression with all known
93 contacts (name + e-mail address). For the details, see \fBmu-cfind(1)\fR.
94
95 .nf
63687e87 »
2012-06-20 * documentation updates
96 -> contacts [personal:true|false] [after:<time_t>]
97 <- (:contacts ((:name abc :mail foo@example.com ...) ...)
635e049f »
2012-06-18 * mu-cmd-server: add the 'contacts' command, which gives us the conta…
98 .fi
99
100
101 .TP
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
102 .B extract
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
103
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
104 Using the \fBextract\fR command we can save and open attachments.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
105 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
106 -> extract action:<save|open|temp> index:<index> [path:<path>] [what:<what> [param:<param>]]
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
107 .fi
108
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
109 If the action is 'save', the path argument is required; the attachment will
110 be saved, and a message
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
111 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
112 <- (:info save :message "... has been saved")
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
113 .fi
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
114 is sent.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
115
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
116 If the action is 'open', the attachment will saved to a temporary file, after
117 which it will be opened with the default handler for this kind of file (see
118 \fBmu-extract(1)\fR), and a message
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
119 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
120 <- (:info open :message "... has been opened")
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
121 .fi
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
122 is sent.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
123
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
124 If the action is 'temp', the arguments 'what' is required. The attachment will
125 saved to a temporary file, and the following message is sent:
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
126 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
127 <- (:temp :what <what> :param <param)
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
128 .fi
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
129 The front-end can then take action on the temp file, based on what :what and
130 :param contain. \fBmu4e\fR uses this mechanism e.g. for piping an attachment
131 to a shell command.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
132
133 .TP
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
134 .B find
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
135
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
136 Using the \fBfind\fR command we can search for messages.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
137 .nf
20d858e4 »
2012-06-10 * implement / document changing sort order and threading
138 -> find query:"<query>" [threads:true|false] [sortfield:<sortfield>]
139 [reverse:true|false] [maxnum:<maxnum>]
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
140 .fi
20d858e4 »
2012-06-10 * implement / document changing sort order and threading
141 The \fBquery\fR-parameter provides the search query; the
142 \fBthreads\fR-parameter determines whether the results will be returned in
143 threaded fashion or not; the \fBsortfield\fR-parameter (a string, "to",
144 "from", "subject", "date", "size", "prio") sets the search field, the
145 \fBreverse\fR-parameter, if true, set the sorting order Z->A and, finally, the
146 \fBmaxnum\fR-parameter limits the number of results to return (<= 0
147 means 'unlimited').
148
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
149 First, this will return an 'erase'-sexp, to clear the buffer from possible
150 results from a previous query.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
151 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
152 <- (:erase t)
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
153 .fi
154
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
155 This will return a series of 0 up to <maxnum> s-expression corresponding to
156 each message found (if there's no maxnum, all results will be returned). The
157 information message s-exps this function returns do not contain the message
158 body; the \fBview\fR command is for that.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
159 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
160 <- (...)
6e3e425c » djcb
2012-01-14 * when forwarding, include attachments from original
161 .fi
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
162 and finally, we receive:
6e3e425c » djcb
2012-01-14 * when forwarding, include attachments from original
163 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
164 <- (:found <number-of-matches>)
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
165 .fi
166
167
168 .TP
4e5b60d4 »
2012-07-20 * mu-server.1: update
169 .B guile
170 The \fBguile\fR command is reserved for future use.
171
172
173 .TP
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
174 .B index
175
176 Using the \fBindex\fR command, we can (re)index the database, similar to what
b150f450 »
2012-06-19 * mu4e: support setting my-addresses when indexing
177 \fBmu find\fR does. The \fBmy-addresses\fR parameter (optionally)
178 registers 'my' email addresses; see the documentation for
179 \fBmu_store_set_my_addresses\fR.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
180
181 .nf
b150f450 »
2012-06-19 * mu4e: support setting my-addresses when indexing
182 -> index path:<path> [my-addresses:<comma-separated-list-of-email-addresses>]
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
183 .fi
184 As a response, it will send (for each 500 messages):
185 .nf
186 (:info index :status running :processed <processed> :updated <updated>)
187 .fi
188 and finally:
189 .nf
190 (:info index :status complete :processed <processed :updated <updated>
191 :cleaned-up <cleaned-up>)
192 .fi
193
194 .TP
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
195 .B mkdir
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
196
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
197 Using the \fBmkdir\fR command, we can create a new maildir.
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
198
199 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
200 -> mkdir path:<path>
201 <- (:info mkdir :message "<maildir> has been created")
858552af » djcb
2011-12-27 * mu-server.1: document the mu server command / control language
202 .fi
203
c2e3eac1 »
2012-03-27 * don't save drafts immediately, and do the post-sending stuff not in…
204 .TP
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
205 .B move
c2e3eac1 »
2012-03-27 * don't save drafts immediately, and do the post-sending stuff not in…
206
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
207 Using the \fBmove\fR command, we can move messages to another maildir or
208 change its flags (which ultimately means it is being move to a different
209 filename), and update the database correspondingly. The function returns an
210 s-exp describing the updated message, so that it can be updated in the user
211 interface.
c2e3eac1 »
2012-03-27 * don't save drafts immediately, and do the post-sending stuff not in…
212
213 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
214 -> move docid:<docid>|msgid:<msgid> [maildir:<maildir>] [flags:<flags>]
215 <- (:update <s-exp> :move t)
c2e3eac1 »
2012-03-27 * don't save drafts immediately, and do the post-sending stuff not in…
216 .fi
217
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
218 One of docid and msgid must be specified to identify the message. At least one
219 of maildir and flags must be specified.
c2e3eac1 »
2012-03-27 * don't save drafts immediately, and do the post-sending stuff not in…
220
221
a2aed887 » djcb
2011-12-28 * mu-cmd-server/mu-server.1: cleanup 'mkdir', add documentation
222 .TP
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
223 .B ping
a2aed887 » djcb
2011-12-28 * mu-cmd-server/mu-server.1: cleanup 'mkdir', add documentation
224
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
225 The \fBping\fR command provokes a \fBpong\fR response. It is used for the initial
226 handshake between \fBmu4e\fR and \fBmu server\fR.
227 .nf
228 -> ping
229 <- (:pong "mu" :version <version> :doccount <doccount>)
230 .fi
231
232 .TP
233 .B remove
234
235 Using the \fBremove\fR command, we can remove the message from disk, and
236 update the database accordingly.
a2aed887 » djcb
2011-12-28 * mu-cmd-server/mu-server.1: cleanup 'mkdir', add documentation
237
238 .nf
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
239 -> remove docid:<docid>
240 <- (:remove <docid>)
a2aed887 » djcb
2011-12-28 * mu-cmd-server/mu-server.1: cleanup 'mkdir', add documentation
241 .fi
242
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
243
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
244 .TP
245 .B view
246
247 Using the \fBview\fR command, we can all information (including the body) of a
248 particular e-mail message.
249
47e77204 »
2012-05-16 * support getting all image attachments as temp files (change in mu-m…
250 If the optional parameter \fBextract-images\fR is \fBtrue\fR, extract images
251 to temp files, and include links to them in the returned s-exp.
252
4e5b60d4 »
2012-07-20 * mu-server.1: update
253 If the optional parameter \fBuse-agent\fR is \fBtrue\fR, try to use
254 \fBgpg-agent\fR when verifying PGP/GPG message parts.
255
256 If the optional parameter \fBauto-retrieve-key\fR is \fBtrue\fR, attempt to
257 retrieve public keys online automatically.
258
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
259 .nf
4e5b60d4 »
2012-07-20 * mu-server.1: update
260 -> view docid:<docid>|msgid:<msgid> [extract-images:true] [use-agent:false] [auto-retrieve-key:false]
7a04f149 »
2012-04-15 * update mu4e-server manpage for the protocol updates
261 <- (:view <s-exp>)
262 .fi
263
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
264
97d2e0e2 » djcb
2011-12-07 * beginnings of mu-server documentations (WIP)
265 .SH AUTHOR
4ce44f69 »
2011-09-03 * add 'mu server', which starts a process that accepts some commands
266 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
267
268 .SH "SEE ALSO"
269 .BR mu(1)
Something went wrong with that request. Please try again.