.. highlight:: sh

Commands
========

By "commands" here we really mean console commands, e.g. things you might enter
on a terminal, or run via shell script or cron job.


Typical Usage
-------------

Unless there is a specific reason not to, all commands should be ran from the
root of your virtual environment.  For example this command will generate and
display a new UUID::

   cd /srv/envs/poser
   bin/rattail -c app/quiet.conf make-uuid

Also note that in general, you should always specify a config file as part of
the command line (as shown above).


Getting Help
------------

You can always just add ``-h`` (or ``--help``) to the end of any command line.
This will render the command "inert" and the only thing it will do, is display
some help text.

Really there are 2 "layers" to the command framework: commands proper, and
subcommands.  In the example above, ``bin/rattail`` is the command proper,
and ``make-uuid`` is the subcommand.

To get help on the command proper, add ``-h`` to your command line but omit the
subcommand, e.g.::

   bin/rattail -c app/quiet.conf -h

To get help on a subcommand, you must include the subcommand name as though you
were running it, then also add ``-h`` to the command line::

   bin/rattail -c app/quiet.conf make-uuid -h


Usage with ``sudo``
-------------------

If your virtual environment is owned by someone other than yourself, then you
probably should run commands as that user also::

   cd /srv/envs/poser
   sudo -u rattail bin/rattail -c app/quiet.conf make-uuid

Among other things this may be necessary so that:

* user has permission to read from config files which may be restricted
* user has permission to write to log file(s) which may be restricted