mirror of
https://github.com/djcb/mu.git
synced 2024-07-02 08:21:06 +02:00
d276b393af
This 500 number was correct in v0.9.7-pre-302-g858552a, but since v0.9.8.2-41-gc2e3eac it's been hardcoded to 1000 in the server code. See also issue #715 and issue #716.
276 lines
7.3 KiB
Groff
276 lines
7.3 KiB
Groff
.TH MU-SERVER 1 "September 2012" "User Manuals"
|
|
|
|
.SH NAME
|
|
|
|
mu server \- the mu backend for the mu4e e-mail client
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B mu server [options]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
\fBmu server\fR starts a simple shell in which one can query and manipulate
|
|
the mu database. The output of the commands is terms of Lisp symbolic
|
|
expressions (s-exps). \fBmu server\fR is not meant for use by humans; instead,
|
|
it is designed specifically for the \fBmu4e\fR e-mail client.
|
|
|
|
In this man-page, we document the commands \fBmu server\fR accepts, as well as
|
|
their responses. In general, the commands sent to the server are of the form
|
|
|
|
.nf
|
|
cmd:<command> [<parameters>]*
|
|
.fi
|
|
|
|
where each of the parameters is prefixed by their name and a colon. For
|
|
example, to view a certain message, the command would be:
|
|
|
|
.nf
|
|
cmd:view docid:12345
|
|
.fi
|
|
|
|
Parameters can be sent in any order, and parameters not used by a certain
|
|
command are simply ignored.
|
|
|
|
|
|
.SH OUTPUT FORMAT
|
|
|
|
\fBmu server\fR accepts a number of commands, and delivers its results in
|
|
the form:
|
|
|
|
.nf
|
|
\\376<length>\\377<s-expr>
|
|
.fi
|
|
|
|
\\376 (one byte 0xfe), followed by the length of the s-expression expressed as
|
|
an hexadecimal number, followed by another \\377 (one byte 0xff), followed by
|
|
the actual s-expression.
|
|
|
|
By prefixing the expression with its length, it can be processed more
|
|
efficiently. The \\376 and \\377 were chosen since they never occur in valid
|
|
UTF-8 (in which the s-expressions are encoded).
|
|
|
|
.SH COMMAND AND RESPONSE
|
|
|
|
.TP
|
|
.B add
|
|
|
|
Using the \fBadd\fR command, we can add a message to the database.
|
|
|
|
.nf
|
|
-> cmd:add path:<path> maildir:<maildir>
|
|
<- (:info add :path <path> :docid <docid>)
|
|
.fi
|
|
|
|
|
|
.TP
|
|
.B compose
|
|
|
|
Using the \fBcompose\fR command, we get the (original) message, and tell what
|
|
to do with it. The user-interface is then expected to pre-process the message,
|
|
e.g. set the subject, sender and recipient for a reply message.
|
|
|
|
Messages of type 'new' don't use the docid: parameter, the other ones do.
|
|
|
|
.nf
|
|
-> cmd:compose type:<reply|forward|edit|new> [docid:<docid>]
|
|
<- (:compose <reply|forward|edit|new> :original <s-exp> :include (<list-of-attachments))
|
|
.fi
|
|
|
|
The <list-of-attachments> is an s-expression describing the attachments to
|
|
include in the message; this currently only applies to message we are
|
|
forwarding. This s-expression looks like:
|
|
|
|
.nf
|
|
(:file-name <filename> :mime-type <mime-type> :disposition <disposition>)
|
|
.fi
|
|
|
|
|
|
.TP
|
|
.B contacts
|
|
|
|
Using the \fBcompose\fR command, we can retrieve an s-expression with all known
|
|
contacts (name + e-mail address). For the details, see \fBmu-cfind(1)\fR.
|
|
|
|
.nf
|
|
-> cmd:contacts [personal:true|false] [after:<time_t>]
|
|
<- (:contacts ((:name abc :mail foo@example.com ...) ...)
|
|
.fi
|
|
|
|
|
|
.TP
|
|
.B extract
|
|
|
|
Using the \fBextract\fR command we can save and open attachments.
|
|
.nf
|
|
-> cmd:extract action:<save|open|temp> index:<index> [path:<path>] [what:<what> [param:<param>]]
|
|
.fi
|
|
|
|
If the action is 'save', the path argument is required; the attachment will
|
|
be saved, and a message
|
|
.nf
|
|
<- (:info save :message "... has been saved")
|
|
.fi
|
|
is sent.
|
|
|
|
If the action is 'open', the attachment will saved to a temporary file, after
|
|
which it will be opened with the default handler for this kind of file (see
|
|
\fBmu-extract(1)\fR), and a message
|
|
.nf
|
|
<- (:info open :message "... has been opened")
|
|
.fi
|
|
is sent.
|
|
|
|
If the action is 'temp', the arguments 'what' is required. The attachment will
|
|
saved to a temporary file, and the following message is sent:
|
|
.nf
|
|
<- (:temp :what <what> :param <param :docid 12345)
|
|
.fi
|
|
The front-end can then take action on the temp file, based on what :what and
|
|
:param contain. \fBmu4e\fR uses this mechanism e.g. for piping an attachment
|
|
to a shell command.
|
|
|
|
.TP
|
|
.B find
|
|
|
|
Using the \fBfind\fR command we can search for messages.
|
|
.nf
|
|
-> cmd:find query:"<query>" [threads:true|false] [sortfield:<sortfield>]
|
|
[reverse:true|false] [maxnum:<maxnum>]
|
|
.fi
|
|
The \fBquery\fR-parameter provides the search query; the
|
|
\fBthreads\fR-parameter determines whether the results will be returned in
|
|
threaded fashion or not; the \fBsortfield\fR-parameter (a string, "to",
|
|
"from", "subject", "date", "size", "prio") sets the search field, the
|
|
\fBreverse\fR-parameter, if true, set the sorting order Z->A and, finally, the
|
|
\fBmaxnum\fR-parameter limits the number of results to return (<= 0
|
|
means 'unlimited').
|
|
|
|
First, this will return an 'erase'-sexp, to clear the buffer from possible
|
|
results from a previous query.
|
|
.nf
|
|
<- (:erase t)
|
|
.fi
|
|
|
|
This will return a series of 0 up to <maxnum> s-expression corresponding to
|
|
each message found (if there's no maxnum, all results will be returned). The
|
|
information message s-exps this function returns do not contain the message
|
|
body; the \fBview\fR command is for that.
|
|
.nf
|
|
<- (...)
|
|
.fi
|
|
and finally, we receive:
|
|
.nf
|
|
<- (:found <number-of-matches>)
|
|
.fi
|
|
|
|
|
|
.TP
|
|
.B guile
|
|
The \fBguile\fR command is reserved for future use.
|
|
|
|
|
|
.TP
|
|
.B index
|
|
|
|
Using the \fBindex\fR command, we can (re)index the database, similar to what
|
|
\fBmu find\fR does. The \fBmy-addresses\fR parameter (optionally)
|
|
registers 'my' email addresses; see the documentation for
|
|
\fBmu_store_set_my_addresses\fR.
|
|
|
|
.nf
|
|
-> cmd:index path:<path> [my-addresses:<comma-separated-list-of-email-addresses>]
|
|
.fi
|
|
As a response, it will send (for each 1000 messages):
|
|
.nf
|
|
(:info index :status running :processed <processed> :updated <updated>)
|
|
.fi
|
|
and finally:
|
|
.nf
|
|
(:info index :status complete :processed <processed :updated <updated>
|
|
:cleaned-up <cleaned-up>)
|
|
.fi
|
|
|
|
.TP
|
|
.B mkdir
|
|
|
|
Using the \fBmkdir\fR command, we can create a new maildir.
|
|
|
|
.nf
|
|
-> cmd:mkdir path:<path>
|
|
<- (:info mkdir :message "<maildir> has been created")
|
|
.fi
|
|
|
|
.TP
|
|
.B move
|
|
|
|
Using the \fBmove\fR command, we can move messages to another maildir or
|
|
change its flags (which ultimately means it is being move to a different
|
|
filename), and update the database correspondingly. The function returns an
|
|
s-exp describing the updated message, so that it can be updated in the user
|
|
interface.
|
|
|
|
.nf
|
|
-> cmd:move docid:<docid>|msgid:<msgid> [maildir:<maildir>] [flags:<flags>]
|
|
<- (:update <s-exp> :move t)
|
|
.fi
|
|
|
|
One of docid and msgid must be specified to identify the message. At least one
|
|
of maildir and flags must be specified.
|
|
|
|
|
|
.TP
|
|
.B ping
|
|
|
|
The \fBping\fR command provokes a \fBpong\fR response. It is used for the initial
|
|
handshake between \fBmu4e\fR and \fBmu server\fR.
|
|
.nf
|
|
-> cmd:ping
|
|
<- (:pong "mu" :version <version> :doccount <doccount>)
|
|
.fi
|
|
|
|
.TP
|
|
.B remove
|
|
|
|
Using the \fBremove\fR command, we can remove the message from disk, and
|
|
update the database accordingly.
|
|
|
|
.nf
|
|
-> cmd:remove docid:<docid>
|
|
<- (:remove <docid>)
|
|
.fi
|
|
|
|
|
|
.TP
|
|
.B view
|
|
|
|
Using the \fBview\fR command, we can retrieve all information (including the
|
|
body) of a particular e-mail message.
|
|
|
|
If the optional parameter \fBextract-images\fR is \fBtrue\fR, extract images
|
|
to temp files, and include links to them in the returned s-exp.
|
|
|
|
If the optional parameter \fBuse-agent\fR is \fBtrue\fR, try to use
|
|
\fBgpg-agent\fR when verifying PGP/GPG message parts.
|
|
|
|
If the optional parameter \fBauto-retrieve-key\fR is \fBtrue\fR, attempt to
|
|
retrieve public keys online automatically.
|
|
|
|
.nf
|
|
-> cmd:view docid:<docid>|msgid:<msgid> [extract-images:true] [use-agent:false] [auto-retrieve-key:false]
|
|
<- (:view <s-exp>)
|
|
.fi
|
|
|
|
or, alternatively:
|
|
|
|
.nf
|
|
-> cmd:view path:<path-to-msg> [extract-images:true] [use-agent:false] [auto-retrieve-key:false]
|
|
<- (:view <s-exp>)
|
|
.fi
|
|
|
|
.SH AUTHOR
|
|
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
|
|
|
|
.SH "SEE ALSO"
|
|
.BR mu(1)
|