.. 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 make-uuid


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

You can always just add ``--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 ``--help`` to your command line but omit the
subcommand, e.g.::

   bin/rattail --help

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

   bin/rattail make-uuid --help


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 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