*******************************************************************************
Command-line interface
*******************************************************************************

:mod:`emblematic` is usually invoked as a command-line tool.

============
Installation
============

To install :mod:`emblematic` for command-line usage:

.. code-block:: console

    $ pipx install emblematic

:mod:`pipx` should automatically add ``emblematic`` to your :envvar:`PATH`, allowing you to call it like this:

.. code-block:: console

    $ emblematic --version

If that for some reason does not work, you should still be able to use emblematic by calling it via :mod:`pipx`:

.. code-block:: console

    $ pipx run emblematic --version

=====
Usage
=====

-----------------
Show help message
-----------------

To display a message explaining how to use a certain command, append the ``--help`` option to it:

.. code-block:: console

    $ emblematic --help
    Usage: emblematic [OPTIONS] COMMAND [ARGS]...

      Generate an emblem, an easily recognizable yet consistently styled icon.

    Options:
      --version  Show the version and exit.
      --help     Show this message and exit.

    Commands:
      basic    Create a simple emblem.
      duotone  Create an emblem with two separate colors as foreground.
      shadow   Create an emblem with a solid color foreground with a shadow.
      solid    Create an emblem with a solid color foreground.

.. code-block:: console

    $ emblematic basic --help
    Usage: emblematic basic [OPTIONS] [FOREGROUND_FILENAME]...

      Create a simple emblem.

    Options:
      -b, --background-file FILE      SVG file to use as background.  [required]
      -o, --output-dir DIRECTORY      Base directory where created emblems should be stored in. Must already exist.  [required]
      -s, --save-svg / -S, --ignore-svg
                                      Whether an emblem in SVG format should be generated or not.  [default: s]
      -p, --save-png / -P, --ignore-png
                                      Whether an emblem in PNG format should be generated or not.  [default: p]
      -w, --width-px FLOAT            Width in pixels of the output.  [default: 512.0]
      -h, --height-px FLOAT           Height in pixels of the output.  [default: 512.0]
      --help                          Show this message and exit.

-------------------
Show version number
-------------------

To find the version number of the version of emblematic you have installed, pass the ``--version`` option to the main command:

.. code-block:: console

    $ emblematic --version
    emblematic, version 4.0.0


.. todo:: Describe how to use the command-line interface from v4 onwards.