=====================================
Run shell commands from your instance
=====================================

Command line engines are custom engines that run commands in the shell of the
host. In this article you can learn how to create a command engine and how to
customize the result display.

The command
===========

When specifyng commands, you must make sure the commands are available on the
searx host. Searx will not install anything for you. Also, make sure that the
``searx`` user on your host is allowed to run the selected command and has
access to the required files.

Access control
==============

Be careful when creating command engines if you are running a public
instance. Do not expose any sensitive information. You can restrict access by
configuring a list of access tokens under tokens in your ``settings.yml``.

Available settings
==================

* ``command``: A comma separated list of the elements of the command. A special
  token ``{{QUERY}}`` tells searx where to put the search terms of the
  user. Example: ``['ls', '-l', '-h', '{{QUERY}}']``
* ``query_type``: The expected type of user search terms. Possible values:
  ``path`` and ``enum``. ``path`` checks if the uesr provided path is inside the
  working directory. If not the query is not executed. ``enum`` is a list of
  allowed search terms. If the user submits something which is not included in
  the list, the query returns an error.
* ``delimiter``: A dict containing a delimiter char and the "titles" of each
  element in keys.
* ``parse_regex``: A dict containing the regular expressions for each result
  key.
* ``query_enum``: A list containing allowed search terms if ``query_type`` is
  set to ``enum``.
* ``working_dir``: The directory where the command has to be executed. Default:
  ``.``
* ``result_separator``: The character that separates results. Default: ``\n``

Customize the result template
=============================

There is a default result template for displaying key-value pairs coming from
command engines. If you want something more tailored to your result types, you
can design your own template.

Searx relies on `Jinja2 <https://jinja.palletsprojects.com/>`_ for
templating. If you are familiar with Jinja, you will not have any issues
creating templates. You can access the result attributes with ``{{
result.attribute_name }}``.

In the example below the result has two attributes: ``header`` and ``content``.
To customize their diplay, you need the following template (you must define
these classes yourself):

.. code:: html

    <div class="result">
        <div class="result-header">
            {{ result.header }}
        </div>
        <div class="result-content">
            {{ result.content }}
        </div>
    </div>

Then put your template under ``searx/templates/{theme-name}/result_templates``
named ``your-template-name.html``. You can select your custom template with the
option ``result_template``.

.. code:: yaml

  - name: your engine name
    engine: command
    result_template: your-template-name.html

Examples
========

Find files by name
------------------

The first example is to find files on your searx host. It uses the command
`find` available on most Linux distributions. It expects a path type query. The
path in the search request must be inside the ``working_dir``.

The results are displayed with the default `key-value.html` template.  A result
is displayed in a single row table with the key "line".

.. code:: yaml

  - name : find
    engine : command
    command : ['find', '.', '-name', '{{QUERY}}']
    query_type : path
    shortcut : fnd
    tokens : []
    disabled : True
    delimiter :
        chars : ' '
        keys : ['line']


Find files by contents
-----------------------

In the second example, we define an engine that searches in the contents of the
files under the ``working_dir``. The search type is not defined, so the user can
input any string they want. To restrict the input, you can set the ``query_type``
to ``enum`` and only allow a set of search terms to protect
yourself. Alternatively, make the engine private, so no one malevolent accesses
the engine.

.. code:: yaml

  - name : regex search in files
    engine : command
    command : ['grep', '{{QUERY}}']
    shortcut : gr
    tokens : []
    disabled : True
    delimiter :
        chars : ' '
        keys : ['line']