.. _sardana-cli-reference:

==================
Command line tools
==================

This page lists the executables installed by the ``sardana`` package and the
subcommands of the ``sardanactl`` umbrella command.

.. contents::

Device servers
--------------

Each server takes the Tango device server instance name as its only
positional argument::

    Sardana <instance_name> [options]

.. list-table::
    :header-rows: 1
    :widths: 25 75

    * - Command
      - Description
    * - ``Sardana``
      - Runs a Pool and a MacroServer in a single Tango device server
        process.
    * - ``Pool``
      - Runs a Pool Tango device server.
    * - ``MacroServer``
      - Runs a MacroServer Tango device server.

If the instance name is omitted, the server asks for it interactively. If
the instance is not registered in the Tango database yet, the server offers
to create it and registers the corresponding devices: a Pool device for
``Pool``, a MacroServer and a Door device for ``MacroServer`` (also asking
which Pools to connect to) and all three for ``Sardana``.

Apart from the standard Tango device server options (``-nodb``, ``-dlist``,
``-v<level>``, ``-ORB*``...), the three servers accept:

``--log-level=LOG_LEVEL``
    Log output level, one of ``critical`` (or ``0``), ``error`` (``1``),
    ``warning`` (``2``), ``info`` (``3``), ``debug`` (``4``), ``trace``
    (``5``). Default: ``warning``.

``--log-file-level=LOG_FILE_LEVEL``
    Log file level, same choices as above. Default: ``debug``. Ignored if
    ``--without-log-file`` is set.

``--log-file-name=LOG_FILE_NAME``
    Absolute log file name. Default:
    ``/tmp/tango-<user name>/<DS name>/<DS instance name lower case>/log.txt``.
    Ignored if ``--without-log-file`` is set.

``--without-log-file=VALUE``
    Disables logging into a file. Default: ``False`` (the file log is
    enabled).

    .. warning::
        Despite its name and its ``--help`` text, this is **not** a boolean
        flag: it requires a value, and *any* non-empty value disables the
        file log -- including ``--without-log-file=False``. Pass it only
        when you actually want the file log off.

Command line client
-------------------

``spock``
    IPython-based command line interface for executing macros and general
    control. It accepts IPython options, notably ``--profile=<name>`` to
    select the profile (and thus the Door) to use. See
    :ref:`sardana-spock`. Requires the ``spock`` extra dependencies.

The ``sardanactl`` command
--------------------------

``sardanactl`` is the umbrella command of Sardana. It accepts:

``--log-level=[critical|error|warning|info|debug|trace]``
    Show only logs with priority LEVEL or above. Default: ``error``.

``--version``
    Print the Sardana version and exit.

Subcommands are not hardcoded: they are discovered at runtime from the
``sardana.cli.subcommands`` setuptools entry point group, so any installed
package may contribute one. A subcommand that fails to load is skipped with
a warning instead of aborting the command. Run ``sardanactl --help`` to
list the subcommands actually installed.

The subcommands registered by this package are:

.. list-table::
    :header-rows: 1
    :widths: 30 70

    * - Subcommand
      - Description
    * - ``sardanactl expconf [DOOR]``
      - GUI for configuring experiments: measurement groups, snapshot group
        and data storage. See :ref:`expconf_ui`.
    * - ``sardanactl expstatus [DOOR_NAME]``
      - GUI showing the elements reserved by a running macro, allowing to
        stop them if they are stuck. ``-a/--all`` shows all elements
        instead of only the ones currently being used. See
        :ref:`expstatus_ui`.
    * - ``sardanactl macroexecutor [DOOR]``
      - GUI for executing macros, with parameter editors, history and
        favourites. See :ref:`macroexecutor_ui`.
    * - ``sardanactl sequencer [DOOR]``
      - GUI for executing macro sequences. ``-f/--file`` loads a sequence
        from a file (XML or spock syntax). See :ref:`sequencer_ui`.
    * - ``sardanactl showscan DOOR``
      - GUI for online plotting of scan data. ``--group=single|x-axis``
        (default ``x-axis``) selects the plot organization and
        ``--taurus-log-level`` the Taurus log level (default ``error``).
        See :ref:`showscan-online`.
    * - ``sardanactl spock``
      - Same command line client as the ``spock`` executable above.

All of them except ``sardanactl spock`` require the ``qt`` extra
dependencies.

.. note::
    ``sardanactl config``, the YAML-based configuration tool, is
    contributed by the separately distributed ``sardana-config`` package
    and therefore does not appear in this repository's entry points. See
    :ref:`sardana-configuration` and :ref:`sardana-installing`.

Standalone Qt applications
--------------------------

These executables require the ``qt`` extra dependencies.

.. list-table::
    :header-rows: 1
    :widths: 45 55

    * - Command
      - Description
    * - ``diffractometeralignment <model> [door_name]``
      - Diffractometer alignment: h, k, l movements and scans, go to
        maximum... ``model`` is a diffractometer controller.
    * - ``hklscan <model> [door_name]``
      - Performs hkl scans. ``model`` is a diffractometer controller.
    * - ``ubmatrix <model>``
      - Sets diffractometer parameters: ub matrix, lattice, reflections...
        ``model`` is a diffractometer controller.
    * - ``macroexecutor [options]``
      - Deprecated since 3.4.0, use ``sardanactl macroexecutor``.
    * - ``sequencer [options]``
      - Deprecated since 3.4.0, use ``sardanactl sequencer``.
    * - ``showscan DOOR``
      - Deprecated since 3.4.0, use ``sardanactl showscan``.

Optional dependencies
---------------------

Some tools are only usable if the corresponding extra requirements are
installed:

.. list-table::
    :header-rows: 1
    :widths: 25 75

    * - Extra
      - Needed by
    * - ``spock``
      - ``spock`` and ``sardanactl spock``.
    * - ``qt``
      - all ``sardanactl`` subcommands except ``spock``, and all the
        standalone Qt applications.
    * - ``all``
      - both of the above.

Install them with e.g. ``pip install "sardana[all]"``, see
:ref:`sardana-installing`.