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

* NAME

mu-server - the mu backend for the mu4e e-mail client

* SYNOPSIS

mu [common-options] server

* DESCRIPTION

*mu server* starts a simple shell in which one can query and manipulate the mu
database. The output uses s-expressions. *mu server* is not meant for use by
humans, except for debugging purposes. Instead, it is designed specifically for
the *mu4e* e-mail client.

#+begin_example
   (<command-name> :param1 value1 :param2 value2)
#+end_example

For example, to view a certain message, the command would be:

#+begin_example
   (view :docid 12345)
#+end_example

Parameters can be sent in any order; they must be of the correct type though.
See *lib/utils/mu-sexp-parser.hh* and *lib/utils/mu-sexp-parser.cc* in source-tree
for the details.

* OUTPUT FORMAT

*mu server* accepts a number of commands, and delivers its results in the form:

#+begin_example
   \\376<length>\\377<s-expr>
#+end_example

\\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).

* SERVER OPTIONS

** --commands

List available commands (and try with ~--verbose~)

** --eval <expression>

Evaluate a mu4e server s-expression

** --allow-temp-file

If set, allow for the output of some commands to use temp-files rather than
directly through the emacs process input/output. This is noticeably faster for
commands with a lot of output, esp. when the the temp-file uses a in-memory
file-system.

* PERFORMANCE

As an indication for the relative performance, we can simulate something ~mu4e~
does; we take overall time of 50 such requests:

#+begin_src sh
time build/mu/mu server --allow-temp-file --eval '(find :query "\"\"" :include-related t :threads t :maxnum 50000)' >/dev/null
#+end_src
(and ~--allow-temp-file~ for 1.11)

#+ATTR_MAN: :disable-caption t
|       release | time (sec) |
|---------------+------------|
|           1.8 | 8.6s       |
|          1.10 | 5.7s       |
| 1.11 (master) | 2.8s       |


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

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

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

* SEE ALSO
*mu(1)*