Introduction
------------

The following outlines how to interact with the monkeyfarm.hub using the
monkeyfarm.client utility.  It is intended to provide basic understanding, but
will not cover every possible combination of options available.

In general, each 'resource' is broken out into a separate namespace.  You can
see all available 'namespaces' from '--help':

.. code-block:: text

	$ mf --help
	Usage:   mf <COMMAND> [ARGS] --(OPTIONS)

	Commands:  
	    status, get-config, list-plugins, workon, whoami, clear-cache

	Namespaces (Nested SubCommands):
	    tag*, group*, system*, build*, distro*, release*, user*, arch*, 
	    target*, task*, package*, project*

	Help?  try '[COMMAND]-help' OR '[NAMESPACE] --help'

	Options:
	    --version               show program's version number and exit
	    -h, --help              show this help message and exit
	    --json                  render output as json (Cement CLI-API)
	    --debug                 toggle debug output
	    --quiet                 disable console logging
	    -y, --noprompt          don't prompt, always answer yes
	    --api-key=STR           api key [user_name:key]
	    -H URL, --hub=URL       base url of the MonkeyFarm Hub
	    -f TEXT, --filter=TEXT  resource filter regex
	    -l STR, --label=STR     resource label identifier
	    --all                   display all output (where applicable)
	    --mine                  display only items i own (where applicable)
	    -u STR, --user=STR      user name/label
	    -P STR, --project=STR   project label
	    --display-name=TEXT     resource display name
	    --rdikwid               really delete I know what I'm doing
	    -L LEVEL                log level [debug, info, warn, error, fatal]
	    --no-cache              do not cache any data


The above is the 'root' namespace, or the base of the application.  The 
options and commands change within each namespace.  For example, see the
project namespace:

.. code-block:: text

	$ mf project --help
	Usage:   mf project <SUBCOMMAND> [ARGS] --(OPTIONS)

	Sub-Commands:  
	    create, delete, update, listall, show

	Help?  try '[SUBCOMMAND]-help'

	Options:
	    --version                   show program's version number and exit
	    -h, --help                  show this help message and exit
	    --admin-group=ADMIN_GROUP_LABEL
	                                projects admin group.
	    --dev-group=DEV_GROUP_LABEL
	                                projects developer group.
	    --tag-path=TAG_PATH         project tag path
	    --public-gpg-key=PATH       path to public gpg key file
	    --url=STR                   resource url
	    --about=TEXT                resource about information
	    --vcs-handler=STR           vcs handler label
	    --bug-handler=STR           bug handler label
	    --json                      render output as json (Cement CLI-API)
	    --debug                     toggle debug output
	    --quiet                     disable console logging
	    -y, --noprompt              don't prompt, always answer yes
	    --api-key=STR               api key [user_name:key]
	    -H URL, --hub=URL           base url of the MonkeyFarm Hub
	    -f TEXT, --filter=TEXT      resource filter regex
	    -l STR, --label=STR         resource label identifier
	    --all                       display all output (where applicable)
	    --mine                      display only items i own (where applicable)
	    -u STR, --user=STR          user name/label
	    -P STR, --project=STR       project label
	    --display-name=TEXT         resource display name
	    --rdikwid                   really delete I know what I'm doing
	    -L LEVEL                    log level [debug, info, warn, error, fatal]
	    --no-cache                  do not cache any data


This doc outlines some common tasks for each resource/namespace.  Note
that some resources require administrative privileges.


Common Navigation
^^^^^^^^^^^^^^^^^

All namespaces/resources have some common commands you can expect to see.  
These generally relate to the REST-like API calls available.  They look like:

.. code-block:: text

    $ mf <resource> listall
    
    $ mf <resource> show <resource_label>
    
    $ mf <resource> create ...
    
    $ mf <resource> update <resource_label> ...
    
    $ mf <resource> delete <resource_label>
    

The 'listall' command for all resources also has an accompanying -f/--filter
option that filters the results on the server side (optimal performance).  
This option takes a regular expression that is passed directly to the python
're' module for matching.  For example:

.. code-block:: text

    $ mf user listall -f john
    
    $ mf group listall -f admin
    
    $ mf project listall -f "^some_string(.*)to_match$"
    
    
The filter is done by searching through certain members of the resource that
would likely be relevant.  For example, the 'label' or 'display_name'.
It is not an exact match, but rather if any part matches the string it is 
returned in the data set.


Return Data
^^^^^^^^^^^

It should be noted that most user related data will be listed by the most 
relevant.  For example, from the command line if you issue 
'mf listall projects' you will get back a list of projects that you are 
associated with.  To see all, you would add the '--all' flag.