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

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

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

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

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