=====
Usage
=====

*luci*'s command-line syntax is based on sub-commands:

.. code-block:: shell

   ❯ luci [luci-opts] LUCIFIER [lucifier-opts] DICTLET [dictlet-opts]

Currently, ``[luci-opts]`` only include the ``--vars``/``-v`` option. It is used to specify additional variables to overwrite dictlet defaults (but which can be overwritten by user-provided input).


*lucifiers*
-----------

*Lucifiers* are Python classes that describe tasks. Those tasks are configured by the metadata *luci* parses and assembles. One of the design goals of *luci* is to make it easy to write and add additional *Lucifiers*, to find out more about that please follow :doc:`this link <lucifiers>`.


*lucifier* options
++++++++++++++++++

*lucifiers* can be configured with their own set of options. Those are generally very high level, and independent of the *dictlet* (see below) they use. Usually they would be things like whether you want to use a pager for output, or which format it's output should be. A *lucifiers* options can be queried like so:

.. code-block:: console

   ❯ luci LUCIFIER --help


Default *lucifiers*
+++++++++++++++++++

That being said, *luci* comes with a couple of generic *lucifiers* which should cover a few main use-cases. If you think there's an obvious one that's missing, let me know! Here's a list of currently available ones:

.. toctree::
   :glob:
   :maxdepth: 1

   lucifiers/*


Custom lucifiers
++++++++++++++++

*luci* supports custom build, specialized *lucifiers*. For those to be picked up, the Python packages they come with need to be installed in the current ``PYTHONPATH`` (for example, the same virtualenv) and be registered with a name in the 'luci.lucifiers' namespace (using the `stevedore <https://docs.openstack.org/stevedore/latest/>`_ plugin system). For more details on how this works, please check out :doc:`the lucifier module documentation <lucifiers>`.


*dictlets*
----------

*Dictlet* is the name I chose to describe a file that contains metadata *luci* can parse. *Dictlets* are text files of any sort (bash scripts, yaml files, etc.) that, usually as comments, contain one or several dictionaries in a format *luci* has a :doc:`dictlet reader <dictlet_readers>` for. In most cases, you can think of a *dictlet* as a script within a script, that can be 'activated' by *luci*. A *template* can have it's own set of command-line arguments which can be either inherited by the *lucifier* that is used to run it, or which are contained within the metadata of the *dictlet*. More information on the format of this metadata can be found `here <XXX>`_, but as a quick example, here's how it looks to create an option that uses the ``--name`` flag, which accepts a string as input, and which stores the user input in the ``name`` key, which is a child of the ``person`` (root) key:

.. code-block:: yaml

   vars:
     person.name:
       meta:
         alias: 'name'
         type: str

Those command-line options can be described in more detail, if necessary. To query the options of a *dictlet*, you issue:

.. code-block:: console

   ❯ luci LUCIFIER DICTLET --help