Merge pull request #87 from dokku/expanded-help

feat: add support for enhanced help output
2017-09-11 03:12:48 -04:00
parent 782127781f b493c6a2a5
commit 792f1b318d
28 changed files with 564 additions and 230 deletions
--- a/169
+++ b/169
@@ -3,174 +3,11 @@ source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/config"
 [[ " help $PLUGIN_COMMAND_PREFIX:help " == *" $1 "* ]] || [[ "$1" == "$PLUGIN_COMMAND_PREFIX:"* ]] || exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x

-source "$PLUGIN_BASE_PATH/common/functions"
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/functions"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/help-functions"

 if [[ ! -d $PLUGIN_DATA_ROOT ]]; then
+  source "$PLUGIN_BASE_PATH/common/functions"
  dokku_log_fail "$PLUGIN_SERVICE: Please run: sudo dokku plugin:install"
 fi

-case "$1" in
-  $PLUGIN_COMMAND_PREFIX:backup)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/backup" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:backup-auth)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/backup-auth" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:backup-deauth)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/backup-deauth" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:backup-schedule)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/backup-schedule" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:backup-set-encryption)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/backup-set-encryption" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:backup-unschedule)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/backup-unschedule" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:backup-unset-encryption)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/backup-unset-encryption" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:clone)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/clone" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:connect)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/connect" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:create)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/create" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:destroy)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/destroy" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:export)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/export" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:expose)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/expose" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:import)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/import" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:info)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/info" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:link)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/link" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:list)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/list" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:logs)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/logs" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:promote)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/promote" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:restart)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/restart" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:start)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/start" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:stop)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/stop" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:unexpose)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/unexpose" "$@"
-    ;;
-
-  $PLUGIN_COMMAND_PREFIX:unlink)
-    "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands/unlink" "$@"
-    ;;
-
-  help | $PLUGIN_COMMAND_PREFIX:help)
-    help_content_func() {
-      # shellcheck disable=SC2034
-      declare desc="return $PLUGIN_COMMAND_PREFIX plugin help content"
-      cat<<help_content
-    $PLUGIN_COMMAND_PREFIX:backup <name> <bucket> (--use-iam), Create a backup of the $PLUGIN_COMMAND_PREFIX service to an existing s3 bucket
-    $PLUGIN_COMMAND_PREFIX:backup-auth <name> <aws_access_key_id> <aws_secret_access_key> (<aws_default_region>) (<aws_signature_version>) (<endpoint_url>), Sets up authentication for backups on the $PLUGIN_COMMAND_PREFIX service
-    $PLUGIN_COMMAND_PREFIX:backup-deauth <name>, Removes backup authentication for the $PLUGIN_COMMAND_PREFIX service
-    $PLUGIN_COMMAND_PREFIX:backup-schedule <name> <schedule> <bucket>, Schedules a backup of the $PLUGIN_COMMAND_PREFIX service
-    $PLUGIN_COMMAND_PREFIX:backup-set-encryption <name> <encryption_key>, Sets up GPG encryption for future backups of the $PLUGIN_COMMAND_PREFIX service
-    $PLUGIN_COMMAND_PREFIX:backup-unschedule <name>, Unschedules the backup of the $PLUGIN_COMMAND_PREFIX service
-    $PLUGIN_COMMAND_PREFIX:backup-unset-encryption <name>, Removes backup encryption for future backups of the $PLUGIN_COMMAND_PREFIX service
-    $PLUGIN_COMMAND_PREFIX:clone <name> <new-name>, Create container <new-name> then copy data from <name> into <new-name>
-    $PLUGIN_COMMAND_PREFIX:connect <name>, Connect via redis-cli to a $PLUGIN_SERVICE service
-    $PLUGIN_COMMAND_PREFIX:create <name>, Create a $PLUGIN_SERVICE service
-    $PLUGIN_COMMAND_PREFIX:destroy <name>, Delete the $PLUGIN_SERVICE service, delete the data and stop its container if there are no links left
-    $PLUGIN_COMMAND_PREFIX:export <name>, Export a dump of the $PLUGIN_SERVICE service database
-    $PLUGIN_COMMAND_PREFIX:expose <name> [port], Expose a $PLUGIN_SERVICE service on custom port if provided (random port otherwise)
-    $PLUGIN_COMMAND_PREFIX:import <name> < <file>, Import a dump into the $PLUGIN_SERVICE service database
-    $PLUGIN_COMMAND_PREFIX:info <name>, Print the connection information
-    $PLUGIN_COMMAND_PREFIX:link <name> <app>, Link the $PLUGIN_SERVICE service to the app
-    $PLUGIN_COMMAND_PREFIX:list, List all $PLUGIN_SERVICE services
-    $PLUGIN_COMMAND_PREFIX:logs <name> [-t], Print the most recent log(s) for this service
-    $PLUGIN_COMMAND_PREFIX:promote <name> <app>, Promote service <name> as ${PLUGIN_DEFAULT_ALIAS}_URL in <app>
-    $PLUGIN_COMMAND_PREFIX:restart <name>, Graceful shutdown and restart of the $PLUGIN_SERVICE service container
-    $PLUGIN_COMMAND_PREFIX:start <name>, Start a previously stopped $PLUGIN_SERVICE service
-    $PLUGIN_COMMAND_PREFIX:stop <name>, Stop a running $PLUGIN_SERVICE service
-    $PLUGIN_COMMAND_PREFIX:unexpose <name>, Unexpose a previously exposed $PLUGIN_SERVICE service
-    $PLUGIN_COMMAND_PREFIX:unlink <name> <app>, Unlink the $PLUGIN_SERVICE service from the app
-help_content
-    }
-
-    help_list_func() {
-      # shellcheck disable=SC2034
-      declare desc="return $PLUGIN_COMMAND_PREFIX plugin help content"
-      cat<<help_list
-      NAME, VERSION, STATUS, EXPOSED PORTS, LINKS
-      service-name, $PLUGIN_COMMAND_PREFIX:$PLUGIN_IMAGE_VERSION, running, -, app-name
-help_list
-    }
-
-    if [[ $1 = "$PLUGIN_COMMAND_PREFIX:help" ]] ; then
-      echo -e "Usage: dokku $PLUGIN_COMMAND_PREFIX[:COMMAND]"
-      echo ''
-      echo "List your $PLUGIN_COMMAND_PREFIX services."
-      echo ''
-      echo 'Example:'
-      echo ''
-      echo "\$ dokku $PLUGIN_COMMAND_PREFIX:list"
-      help_list_func | column -c5 -t -s,
-      echo ''
-      echo 'Additional commands:'
-      help_content_func | sort | column -c2 -t -s,
-    elif [[ $(ps -o command= $PPID) == *"--all"* ]]; then
-      help_content_func
-    else
-      cat<<help_desc
-    $PLUGIN_COMMAND_PREFIX, Plugin for managing $PLUGIN_SERVICE services
-help_desc
-    fi
-    ;;
-
-  *)
-    exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
-    ;;
-
-esac
+fn-help "$@"
--- a/12
+++ b/12
@@ -2,6 +2,7 @@
 source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/config"
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/common-functions"
+source "$PLUGIN_BASE_PATH/common/functions"
 source "$PLUGIN_AVAILABLE_PATH/config/functions"
 if [[ -f "$PLUGIN_AVAILABLE_PATH/docker-options/functions" ]]; then
  source "$PLUGIN_AVAILABLE_PATH/docker-options/functions"
@@ -9,6 +10,17 @@ fi

 # non-generic functions

+service_connect() {
+  local SERVICE="$1"
+  local SERVICE_ROOT="$PLUGIN_DATA_ROOT/$SERVICE"
+  local SERVICE_NAME="$(get_service_name "$SERVICE")"
+  local PASSWORD="$(service_password "$SERVICE")"
+  local SERVICE_TTY_OPTS
+  has_tty && SERVICE_TTY_OPTS="-t"
+
+  docker exec -i $SERVICE_TTY_OPTS "$SERVICE_NAME" redis-cli -a "$PASSWORD"
+}
+
 service_create() {
  local SERVICE="$1"
  [[ -z "$SERVICE" ]] && dokku_log_fail "Please specify a name for the service"
--- a/307
+++ b/307
@@ -0,0 +1,307 @@
+#!/usr/bin/env bash
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+export SUBCOMMAND_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/subcommands"
+
+fn-help() {
+  declare CMD="$1"
+  local cmd EXIT_CODE
+
+  if [[ "$CMD" == "help" ]] || [[ "$CMD" == "$PLUGIN_COMMAND_PREFIX" ]] || [[ "$CMD" == "$PLUGIN_COMMAND_PREFIX:help" ]]; then
+    fn-help-all "$@"
+    exit 0
+  fi
+
+  pushd "$SUBCOMMAND_ROOT" > /dev/null 2>&1
+  for cmd in *; do
+    if [[ "$CMD" == "${PLUGIN_COMMAND_PREFIX}:$cmd" ]]; then
+      "$SUBCOMMAND_ROOT/$cmd" "$@"
+      EXIT_CODE="$?"
+      exit "$EXIT_CODE"
+    fi
+  done
+  popd > /dev/null 2>&1
+
+  exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
+}
+
+fn-help-all() {
+  declare CMD="$1" SUBCOMMAND="$2"
+  local CMD_OUTPUT BLUE BOLD FULL_OUTPUT NORMAL 
+  FULL_OUTPUT=true
+
+  if [[ "$CMD" = "$PLUGIN_COMMAND_PREFIX:help" ]] ; then
+    BOLD="$(tput bold)"
+    NORMAL="\033[m"
+    BLUE="\033[0;34m"
+    CYAN="\033[1;36m"
+    if [[ -n "$SUBCOMMAND" ]] && [[ "$SUBCOMMAND" != "--all" ]]; then
+      fn-help-contents-subcommand "$SUBCOMMAND" "$FULL_OUTPUT"
+      return "$?"
+    fi
+
+    echo -e "${BOLD}usage${NORMAL}: dokku $PLUGIN_COMMAND_PREFIX[:COMMAND]"
+    echo ''
+    echo -e "${BOLD}List your $PLUGIN_COMMAND_PREFIX services.${NORMAL}"
+    echo ''
+    echo -e "${BLUE}Example:${NORMAL}"
+    echo ''
+    echo "    \$ dokku $PLUGIN_COMMAND_PREFIX:list"
+    echo ''
+    fn-help-list-example | column -c5 -t -s,
+    echo ''
+    echo -e "dokku ${BOLD}${PLUGIN_COMMAND_PREFIX}${NORMAL} commands: (get help with ${CYAN}dokku ${PLUGIN_COMMAND_PREFIX}:help SUBCOMMAND${NORMAL})"
+    echo ''
+    fn-help-contents | sort | column -c2 -t -s,
+    echo ''
+  elif [[ $(ps -o command= $PPID) == *"--all"* ]]; then
+    fn-help-contents
+  else
+    cat<<help_desc
+  $PLUGIN_COMMAND_PREFIX, Plugin for managing $PLUGIN_SERVICE services
+help_desc
+  fi
+
+  return 0
+}
+
+fn-help-contents() {
+  local TMPDIR
+
+  TMPDIR=$(mktemp -d)
+  trap 'rm -rf "$TMPDIR" > /dev/null' RETURN INT TERM EXIT
+  pushd "$SUBCOMMAND_ROOT" > /dev/null 2>&1
+  for cmd in *; do
+    fn-help-contents-subcommand "$cmd" || true
+  done
+}
+
+fn-help-contents-subcommand() {
+  declare SUBCOMMAND="$1" FULL_OUTPUT="$2"
+  local UNCLEAN_FILE="${TMPDIR}cmd-unclean" CLEAN_FILE="${TMPDIR}cmd-clean"
+  local BOLD CMD_OUTPUT CYAN EXAMPLE LIGHT_GRAY NORMAL
+
+  rm -rf "$UNCLEAN_FILE" "$CLEAN_FILE"
+  cat "$SUBCOMMAND_ROOT/$SUBCOMMAND" > "$UNCLEAN_FILE"
+
+  fn-help-subcommand-sanitize "$UNCLEAN_FILE" "$CLEAN_FILE"
+  if [[ "$(fn-help-is-subcommand-unimplemented "$CLEAN_FILE")" == true ]]; then
+    return 1
+  fi
+
+  args="$(fn-help-subcommand-args "$CLEAN_FILE" "$FULL_OUTPUT")"
+  cmd_line="$(echo -e "${SUBCOMMAND} ${args}" | sed -e 's/[[:space:]]*$//')"
+  desc="$(grep desc "$CLEAN_FILE" | head -1)"
+  eval "$desc"
+
+  BLUE="\033[0;34m"
+  BOLD="$(tput bold)"
+  CYAN="\033[1;36m"
+  NORMAL="\033[m"
+  LIGHT_GRAY="\033[2;37m"
+  LIGHT_RED="\033[1;31m"
+  CMD_OUTPUT="$(echo -e "    ${PLUGIN_COMMAND_PREFIX}:${cmd_line}, ${LIGHT_GRAY}${desc}${NORMAL}")"
+  if [[ "$FULL_OUTPUT" != "true" ]]; then
+    echo "$CMD_OUTPUT"
+    return 0
+  fi
+
+  echo -e "${BOLD}usage:${NORMAL} dokku ${PLUGIN_COMMAND_PREFIX}:${cmd_line}"
+  echo ''
+  echo -e "${BOLD}${desc}${NORMAL}"
+  echo ''
+
+  ARGS="$(fn-help-subcommand-list-args "$CLEAN_FILE")"
+  if [[ -n "$ARGS" ]]; then
+    echo -e "${CYAN}arguments:${NORMAL}"
+    echo ''
+    echo "$ARGS" | column -c2 -t -s,
+    echo ''
+  fi
+
+  FLAGS="$(fn-help-subcommand-list-flags "$CLEAN_FILE")"
+  if [[ -n "$FLAGS" ]]; then
+    echo -e "${BLUE}flags:${NORMAL}"
+    echo ''
+    echo "$FLAGS" | column -c2 -t -s,
+    echo ''
+  fi
+
+  EXAMPLE="$(fn-help-subcommand-example "$CLEAN_FILE")"
+  if [[ -n "$EXAMPLE" ]]; then
+    echo -e "${LIGHT_RED}examples:${NORMAL}"
+    echo ''
+    echo "$EXAMPLE"
+    echo ''
+  fi
+
+  return 0
+}
+
+fn-help-is-subcommand-unimplemented() {
+  declare FUNC_FILE="$1"
+  local UNIMPLEMENTED
+
+  UNIMPLEMENTED="$(grep "Not yet implemented" "$FUNC_FILE" | head -1 || true)"
+  if [[ -n "$UNIMPLEMENTED" ]]; then
+    echo true
+  else
+    echo false
+  fi
+}
+
+fn-help-list-example() {
+  # shellcheck disable=SC2034
+  declare desc="return $PLUGIN_COMMAND_PREFIX plugin help content"
+  cat<<help_list
+      NAME, VERSION, STATUS, EXPOSED PORTS, LINKS
+      service-name, $PLUGIN_COMMAND_PREFIX:$PLUGIN_IMAGE_VERSION, running, -, app-name
+help_list
+}
+
+fn-help-subcommand-args() {
+  declare FUNC_FILE="$1" FULL_OUTPUT="$2"
+  local argline arglist args argpos BLUE NORMAL
+
+  if [[ "$FULL_OUTPUT" == "true" ]]; then
+    BLUE="\033[0;34m"
+    NORMAL="\033[m"
+  fi
+  argline=$(grep declare "$FUNC_FILE" | grep -v "declare desc" | head -1 || true)
+  arglist=($(echo -e "${argline// /"\n"}" | awk -F= '/=/{print ""$1""}'))
+  args=""
+  argpos=0
+  for arg in "${arglist[@]}"; do
+    argpos=$((argpos + 1))
+    if [[ "$FULL_OUTPUT" != "true" ]] && [[ "$argpos" == 4 ]]; then
+      args+="..."
+      break
+    fi
+
+    if [[ "$arg" == *_FLAG ]]; then
+      arg="${arg/_FLAG/}"
+      if [[ $arg == "INFO" ]]; then
+        arg="SINGLE_INFO_FLAG..."
+        args+=" ${BLUE}[--${arg//_/-}]${NORMAL}"
+      else
+        args+=" ${BLUE}[-${arg:0:1}|--${arg//_/-}]${NORMAL}"
+      fi
+    elif [[ "$arg" == *_FLAGS_LIST ]]; then
+      arg=${arg%_*}
+      args+=" [--${arg//_/-}...]"
+    elif [[ "$arg" == *_LIST ]]; then
+      arg=${arg%_*}
+      args+=" <${arg//_/-}...>"
+    else
+      args+=" <${arg//_/-}>"
+    fi
+  done
+  args=$(echo "$args" | tr "\n" " ")
+  # shellcheck disable=SC2001
+  echo "${args,,}" | sed -e 's/^[[:space:]]*//'
+}
+
+fn-help-subcommand-example() {
+  declare FUNC_FILE="$1"
+  local EXAMPLE
+
+  EXAMPLE=$(grep "#E" "$FUNC_FILE" | cut -d' ' -f2- || true)
+  if [[ -z "$EXAMPLE" ]]; then
+    return 0
+  fi
+
+  BOLD="$(tput bold)"
+  LAST_LINE=""
+  LIGHT_GRAY="\033[2;37m"
+  OTHER_GRAY="\033[7;37m"
+  NEWLINE=""
+  NORMAL="\033[m"
+  _fn-help-apply-shell-expansion "$EXAMPLE" | while read -r line; do
+    line="$(echo "$line" | cut -c 4-)"
+    if [[ "$line" == export* ]] || [[ "$line" == dokku* ]]; then
+      [[ "$LAST_LINE" == "command" ]] && NEWLINE=""
+      [[ "$LAST_LINE" == "sentence" ]] && NEWLINE="\n"
+      echo -e "${NEWLINE}    ${LIGHT_GRAY}${line}${NORMAL}"
+      LAST_LINE="command"
+    else
+      [[ "$LAST_LINE" == "command" ]] && NEWLINE="\n"
+      [[ "$LAST_LINE" == "sentence" ]] && NEWLINE=""
+      [[ "$line" == \>* ]] && line="\n    ${BOLD}${line}${NORMAL}"
+      # shellcheck disable=SC2001
+      [[ "$line" == "    "* ]] && line="    ${OTHER_GRAY}$(echo "$line" | sed -e 's/^[[:space:]]*//')${NORMAL}"
+      echo -e "${NEWLINE}${line}"
+      LAST_LINE="sentence"
+      NEWLINE="\n"
+    fi
+  done
+}
+
+fn-help-subcommand-list-args() {
+  declare FUNC_FILE="$1"
+  local EXAMPLE LIGHT_GRAY NORMAL
+
+  FLAGS=$(grep "#A" "$FUNC_FILE" | cut -d'A' -f2- | sed -e 's/^[[:space:]]*//' || true)
+  if [[ -z "$FLAGS" ]]; then
+    return 0
+  fi
+
+  NORMAL="\033[m"
+  LIGHT_GRAY="\033[2;37m"
+
+  _fn-help-apply-shell-expansion "$FLAGS" | while read -r line; do 
+    echo -e "$(echo "$line" | cut -d',' -f1),${LIGHT_GRAY}$(echo "$line" | cut -d',' -f2-)${NORMAL}"
+  done
+}
+
+fn-help-subcommand-list-flags() {
+  declare FUNC_FILE="$1"
+  local EXAMPLE LIGHT_GRAY NORMAL
+
+  FLAGS=$(grep "#F" "$FUNC_FILE" | cut -d'F' -f2- | sed -e 's/^[[:space:]]*//' || true)
+  if [[ -z "$FLAGS" ]]; then
+    return 0
+  fi
+
+  NORMAL="\033[m"
+  LIGHT_GRAY="\033[2;37m"
+
+  _fn-help-apply-shell-expansion "$FLAGS" | while read -r line; do 
+    echo -e "$(echo "$line" | cut -d',' -f1),${LIGHT_GRAY}$(echo "$line" | cut -d',' -f2-)${NORMAL}"
+  done
+}
+
+fn-help-subcommand-sanitize() {
+  declare FUNC_FILE="$1" OUTGOING_FUNC_FILE="$2"
+  local FUNCTION_FOUND=false
+  local IFS OIFS
+
+  touch "$OUTGOING_FUNC_FILE"
+
+  OIFS="$IFS"
+  IFS=,
+  while read -r p; do
+    IFS="$OIFS"
+    if [[ "$p" == *"-cmd \"\$@\""* ]] || [[ "$p" == "" ]]; then
+      continue
+    fi
+
+    if [[ "$FUNCTION_FOUND" == true ]]; then
+      echo "$p" >> "$OUTGOING_FUNC_FILE"
+      continue
+    fi
+
+    if [[ "$p" == *"()"* ]]; then
+      FUNCTION_FOUND=true
+      echo "$p" >> "$OUTGOING_FUNC_FILE"
+      continue
+    fi
+  done < "$FUNC_FILE"
+}
+
+_fn-help-apply-shell-expansion() {
+  declare desc="Expand environment variables for a shell command"
+  declare data="$1"
+  declare delimiter="__apply_shell_expansion_delimiter__"
+  declare command="cat <<$delimiter"$'\n'"$data"$'\n'"$delimiter"
+  eval "$command"
+}
--- a/subcommands/backup
+++ b/subcommands/backup
@@ -4,7 +4,12 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-backup-cmd() {
+service-backup-cmd() {
+  #E backup the 'lolipop' service to the 'my-s3-bucket' bucket on AWS
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup lolipop my-s3-bucket --use-iam
+  #F -i|--use-iam, use the IAM profile associated with the current server
+  #A service, service to run command against
+  #A bucket-name, name of the s3 bucket to upload backups to
  declare desc="creates a backup of the $PLUGIN_SERVICE service to an existing s3 bucket"
  local cmd="$PLUGIN_COMMAND_PREFIX:backup" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" BUCKET_NAME="$2" USE_IAM_OPTIONAL_FLAG="$3"
@@ -15,4 +20,4 @@ redis-backup-cmd() {
  service_backup "$SERVICE" "$BUCKET_NAME" "$USE_IAM_OPTIONAL_FLAG"
 }

-redis-backup-cmd "$@"
+service-backup-cmd "$@"
--- a/subcommands/backup-auth
+++ b/subcommands/backup-auth
@@ -4,7 +4,21 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-backup-auth-cmd() {
+service-backup-auth-cmd() {
+  #E setup s3 backup authentication
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup-auth lolipop AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY
+  #E setup s3 backup authentication with different region
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup-auth lolipop AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_REGION
+  #E setup s3 backup authentication with different signature version and endpoint
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup-auth lolipop AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_REGION AWS_SIGNATURE_VERSION ENDPOINT_URL
+  #E more specific example for minio auth
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup-auth lolipop MINIO_ACCESS_KEY_ID MINIO_SECRET_ACCESS_KEY us-east-1 s3v4 https://YOURMINIOSERVICE
+  #A service, service to run command against
+  #A access-key-id, an amazon AWS_ACCESS_KEY_ID
+  #A aws-secret-access-key, an amazon AWS_SECRET_ACCESS_KEY
+  #A aws-default-region, (optional) a valid amazon S3 region
+  #A aws-signature-version, (optional) the AWS signature version to use when signing S3 requests
+  #A endpoint-url, (optional) an aws endpoint to upload to
  declare desc="sets up authentication for backups on the $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:backup-auth" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" AWS_ACCESS_KEY_ID="$2" AWS_SECRET_ACCESS_KEY="$3" AWS_DEFAULT_REGION="$4" AWS_SIGNATURE_VERSION="$5" ENDPOINT_URL="$6"
@@ -13,8 +27,7 @@ redis-backup-auth-cmd() {
  [[ -z "$AWS_ACCESS_KEY_ID" ]] && dokku_log_fail "Please specify an aws access key id"
  [[ -z "$AWS_SECRET_ACCESS_KEY" ]] && dokku_log_fail "Please specify an aws secret access key"
  verify_service_name "$SERVICE"
-
  service_backup_auth "$SERVICE" "$AWS_ACCESS_KEY_ID" "$AWS_SECRET_ACCESS_KEY" "$AWS_DEFAULT_REGION" "$AWS_SIGNATURE_VERSION" "$ENDPOINT_URL"
 }

-redis-backup-auth-cmd "$@"
+service-backup-auth-cmd "$@"
--- a/subcommands/backup-deauth
+++ b/subcommands/backup-deauth
@@ -4,7 +4,10 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-backup-deauth-cmd() {
+service-backup-deauth-cmd() {
+  #E remove s3 authentication
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup-deauth lolipop
+  #A service, service to run command against
  declare desc="removes backup authentication for the $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:backup-deauth" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"
@@ -14,4 +17,4 @@ redis-backup-deauth-cmd() {
  service_backup_deauth "$SERVICE"
 }

-redis-backup-deauth-cmd "$@"
+service-backup-deauth-cmd "$@"
--- a/subcommands/backup-schedule
+++ b/subcommands/backup-schedule
@@ -4,7 +4,13 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-backup-schedule-cmd() {
+service-backup-schedule-cmd() {
+  #E schedule a backup
+  #E > 'schedule' is a crontab expression, eg. "0 3 * * *" for each day at 3am
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup-deauth lolipop "0 3 * * *" my-s3-bucket
+  #A service, service to run command against
+  #A schedule, a cron schedule to run backups on
+  #A bucket-name, name of the s3 bucket to upload backups to
  declare desc="schedules a backup of the $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:backup-schedule" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" SCHEDULE="$2" BUCKET_NAME="$3"
@@ -16,4 +22,4 @@ redis-backup-schedule-cmd() {
  service_backup_schedule "$SERVICE" "$SCHEDULE" "$BUCKET_NAME"
 }

-redis-backup-schedule-cmd "$@"
+service-backup-schedule-cmd "$@"
--- a/subcommands/backup-set-encryption
+++ b/subcommands/backup-set-encryption
@@ -4,7 +4,11 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-backup-set-encryption-cmd() {
+service-backup-set-encryption-cmd() {
+  #E set a GPG encryption key for backups
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup-set-encryption lolipop
+  #A service, service to run command against
+  #A encryption-key, a GPG encryption key
  declare desc="sets encryption for all future backups of $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:backup-set-encryption" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" ENCRYPTION_KEY="$2"
@@ -15,4 +19,4 @@ redis-backup-set-encryption-cmd() {
  service_backup_set_encryption "$SERVICE" "$ENCRYPTION_KEY"
 }

-redis-backup-set-encryption-cmd "$@"
+service-backup-set-encryption-cmd "$@"
--- a/subcommands/backup-unschedule
+++ b/subcommands/backup-unschedule
@@ -4,7 +4,10 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-backup-unschedule-cmd() {
+service-backup-unschedule-cmd() {
+  #E remove the scheduled backup from cron
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup-unschedule lolipop
+  #A service, service to run command against
  declare desc="unschedules the backup of the $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:backup-unschedule" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"
@@ -14,4 +17,4 @@ redis-backup-unschedule-cmd() {
  service_backup_unschedule "$SERVICE"
 }

-redis-backup-unschedule-cmd "$@"
+service-backup-unschedule-cmd "$@"
--- a/subcommands/backup-unset-encryption
+++ b/subcommands/backup-unset-encryption
@@ -4,7 +4,10 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-backup-unset-encryption-cmd() {
+service-backup-unset-encryption-cmd() {
+  #E unset a GPG encryption key for backups
+  #E dokku $PLUGIN_COMMAND_PREFIX:backup-unset-encryption lolipop
+  #A service, service to run command against
  declare desc="unsets encryption for future backups of the $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:backup-unset-encryption" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"
@@ -14,4 +17,4 @@ redis-backup-unset-encryption-cmd() {
  service_backup_unset_encryption "$SERVICE"
 }

-redis-backup-unset-encryption-cmd "$@"
+service-backup-unset-encryption-cmd "$@"
--- a/subcommands/clone
+++ b/subcommands/clone
@@ -4,14 +4,17 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-clone-cmd() {
+service-clone-cmd() {
+  #E you can clone an existing service to a new one
+  #E dokku $PLUGIN_COMMAND_PREFIX:clone lolipop lolipop-2
+  #A service, service to run command against
+  #A new-service, name of new service
  declare desc="create container <new-name> then copy data from <name> into <new-name>"
  local cmd="$PLUGIN_COMMAND_PREFIX:clone" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
-  declare SERVICE="$1" NEW_SERVICE="$2"
+  declare SERVICE="$1" NEW_SERVICE="$2" CLONE_FLAGS_LIST="${@:3}"

  [[ -z "$SERVICE" ]] && dokku_log_fail "Please specify a name for the service"
  [[ -z "$NEW_SERVICE" ]] && dokku_log_fail "Please specify a name for the new service"
-
  verify_service_name "$SERVICE"

  PLUGIN_IMAGE=$(service_version "$SERVICE" |  grep -o "^.*:" | sed -r "s/://g")
@@ -23,4 +26,4 @@ redis-clone-cmd() {
  dokku_log_info1 "Done"
 }

-redis-clone-cmd "$@"
+service-clone-cmd "$@"
--- a/subcommands/connect
+++ b/subcommands/connect
@@ -4,19 +4,17 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-connect-cmd() {
+service-connect-cmd() {
+  #E connect to the service via the $PLUGIN_COMMAND_PREFIX connection tool
+  #E dokku $PLUGIN_COMMAND_PREFIX:connect lolipop
+  #A service, service to run command against
  declare desc="connect via redis-cli to a $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:connect" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"

  [[ -z "$SERVICE" ]] && dokku_log_fail "Please specify a name for the service"
  verify_service_name "$SERVICE"
-  SERVICE_ROOT="$PLUGIN_DATA_ROOT/$SERVICE"
-  SERVICE_NAME="$(get_service_name "$SERVICE")"
-  PASSWORD="$(service_password "$SERVICE")"
-  has_tty && SERVICE_TTY_OPTS="-t"
-
-  docker exec -i $SERVICE_TTY_OPTS "$SERVICE_NAME" redis-cli -a "$PASSWORD"
+  service_connect "$SERVICE"
 }

-redis-connect-cmd "$@"
+service-connect-cmd "$@"
--- a/subcommands/create
+++ b/subcommands/create
@@ -4,12 +4,29 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-create-cmd() {
+service-create-cmd() {
+  #E create a $PLUGIN_COMMAND_PREFIX service named lolipop
+  #E dokku $PLUGIN_COMMAND_PREFIX:create lolipop
+  #E you can also specify the image and image version to use for the service.
+  #E it *must* be compatible with the ${PLUGIN_IMAGE} image.
+  #E export ${PLUGIN_DEFAULT_ALIAS}_IMAGE="${PLUGIN_IMAGE}"
+  #E export ${PLUGIN_DEFAULT_ALIAS}_IMAGE_VERSION="${PLUGIN_IMAGE_VERSION}"
+  #E dokku $PLUGIN_COMMAND_PREFIX:create lolipop
+  #E you can also specify custom environment variables to start 
+  #E the ${PLUGIN_COMMAND_PREFIX} service in semi-colon separated form.
+  #E export ${PLUGIN_DEFAULT_ALIAS}_CUSTOM_ENV="USER=alpha;HOST=beta"
+  #E dokku $PLUGIN_COMMAND_PREFIX:create lolipop
+  #A service, service to run command against
+  #F -c|--custom-env "USER=alpha;HOST=beta", semi-colon delimited environment variables to start the service with
+  #F -i|--image IMAGE, the image name to start the service with
+  #F -i|--image-version IMAGE_VERSION, the image version to start the service with
+  #F -p|--password PASSWORD, override the user-level service password
+  #F -r|--root-password PASSWORD, override the root-level service password
  declare desc="create a $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:create" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
-  declare SERVICE="$1"
+  declare SERVICE="$1" CREATE_FLAGS_LIST="${@:2}"

  service_create "$SERVICE" "${@:2}"
 }

-redis-create-cmd "$@"
+service-create-cmd "$@"
--- a/subcommands/destroy
+++ b/subcommands/destroy
@@ -4,7 +4,11 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-destroy-cmd() {
+service-destroy-cmd() {
+  #E destroy the service, it's data, and the running container
+  #E dokku $PLUGIN_COMMAND_PREFIX:destroy lolipop
+  #A service, service to run command against
+  #F -f|--force, force destroy without asking for confirmation
  declare desc="delete the $PLUGIN_SERVICE service/data/container if there are no links left"
  local cmd="$PLUGIN_COMMAND_PREFIX:destroy" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" FORCE_FLAG="$2"
@@ -52,4 +56,4 @@ redis-destroy-cmd() {
  dokku_log_info2 "$PLUGIN_SERVICE container deleted: $SERVICE"
 }

-redis-destroy-cmd "$@"
+service-destroy-cmd "$@"
--- a/subcommands/enter
+++ b/subcommands/enter
@@ -4,13 +4,20 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-enter-cmd() {
+service-enter-cmd() {
+  #E a bash prompt can be opened against a running service.
+  #E filesystem changes will not be saved to disk.
+  #E dokku $PLUGIN_COMMAND_PREFIX:enter lolipop
+  #E you may also run a command directly against the service.
+  #E filesystem changes will not be saved to disk.
+  #E dokku $PLUGIN_COMMAND_PREFIX:enter lolipop touch /tmp/test
+  #A service, service to run command against
  declare desc="enter or run a command in a running $PLUGIN_SERVICE service container"
  local cmd="$PLUGIN_COMMAND_PREFIX:enter" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
-  declare SERVICE="$1" && shift 1
+  declare SERVICE="$1"

  dokku_log_info1_quiet "Filesystem changes may not persist after container restarts"
-  service_enter "$SERVICE" "$@"
+  service_enter "$SERVICE" "${@:2}"
 }

-redis-enter-cmd "$@"
+service-enter-cmd "$@"
--- a/subcommands/export
+++ b/subcommands/export
@@ -4,7 +4,12 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-export-cmd() {
+service-export-cmd() {
+  #E by default, datastore output is exported to stdout
+  #E dokku $PLUGIN_COMMAND_PREFIX:export lolipop
+  #E you can redirect this output to a file
+  #E dokku $PLUGIN_COMMAND_PREFIX:export lolipop > lolipop.dump
+  #A service, service to run command against
  declare desc="export a dump of the $PLUGIN_SERVICE service database"
  local cmd="$PLUGIN_COMMAND_PREFIX:export" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"
@@ -14,4 +19,4 @@ redis-export-cmd() {
  service_export "$SERVICE"
 }

-redis-export-cmd "$@"
+service-export-cmd "$@"
--- a/subcommands/expose
+++ b/subcommands/expose
@@ -4,14 +4,18 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-expose-cmd() {
+service-expose-cmd() {
+  #E expose the service on the service's normal ports, allowing access to it from the public interface (0.0.0.0)
+  #E dokku $PLUGIN_COMMAND_PREFIX:expose lolipop ${PLUGIN_DATASTORE_PORTS[@]}
+  #A service, service to run command against
+  #A ports, a list of ports to run against
  declare desc="expose a $PLUGIN_SERVICE service on custom port if provided (random port otherwise)"
  local cmd="$PLUGIN_COMMAND_PREFIX:expose" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
-  declare SERVICE="$1" PORTS="${@:2}"
+  declare SERVICE="$1" PORTS_LIST="${@:2}"

  [[ -z "$SERVICE" ]] && dokku_log_fail "Please specify a name for the service"
  verify_service_name "$SERVICE"
  service_port_expose "$SERVICE" "${@:2}"
 }

-redis-expose-cmd "$@"
+service-expose-cmd "$@"
--- a/subcommands/import
+++ b/subcommands/import
@@ -4,7 +4,10 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-import-cmd() {
+service-import-cmd() {
+  #E import a datastore dump
+  #E dokku $PLUGIN_COMMAND_PREFIX:import lolipop < database.dump
+  #A service, service to run command against
  declare desc="import a dump into the $PLUGIN_SERVICE service database"
  local cmd="$PLUGIN_COMMAND_PREFIX:import" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"
@@ -14,4 +17,4 @@ redis-import-cmd() {
  service_import "$SERVICE"
 }

-redis-import-cmd "$@"
+service-import-cmd "$@"
--- a/subcommands/info
+++ b/subcommands/info
@@ -4,7 +4,31 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-info-cmd() {
+service-info-cmd() {
+  #E get connection information as follows:
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop
+  #E you can also retrieve a specific piece of service info via flags:
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --config-dir
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --data-dir
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --dsn
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --exposed-ports
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --id
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --internal-ip
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --links
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --service-root
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --status
+  #E dokku $PLUGIN_COMMAND_PREFIX:info lolipop --version
+  #A service, service to run command against
+  #F --config-dir, show the service configuration directory
+  #F --data-dir, show the service data directory
+  #F --dsn, show the service DSN
+  #F --exposed-ports, show service exposed ports
+  #F --id, show the service container id
+  #F --internal-ip, show the service internal ip
+  #F --links, show the service app links
+  #F --service-root, show the service root directory
+  #F --status, show the service running status
+  #F --version, show the service image version
  declare desc="print the connection information"
  local cmd="$PLUGIN_COMMAND_PREFIX:info" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" INFO_FLAG="$2"
@@ -14,4 +38,4 @@ redis-info-cmd() {
  service_info "$SERVICE" "$INFO_FLAG"
 }

-redis-info-cmd "$@"
+service-info-cmd "$@"
--- a/subcommands/link
+++ b/subcommands/link
@@ -4,7 +4,41 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-link-cmd() {
+service-link-cmd() {
+  #E a $PLUGIN_COMMAND_PREFIX service can be linked to a container.
+  #E this will use native docker links via the docker-options plugin.
+  #E here we link it to our 'playground' app.
+  #E > NOTE: this will restart your app
+  #E dokku $PLUGIN_COMMAND_PREFIX:link lolipop playground
+  #E the following environment variables will be set automatically by docker
+  #E (not on the app itself, so they won’t be listed when calling dokku config):
+  #E
+  #E     DOKKU_${PLUGIN_DEFAULT_ALIAS}_LOLIPOP_NAME=/lolipop/DATABASE
+  #E     DOKKU_${PLUGIN_DEFAULT_ALIAS}_LOLIPOP_PORT=tcp://172.17.0.1:${PLUGIN_DATASTORE_PORTS[0]}
+  #E     DOKKU_${PLUGIN_DEFAULT_ALIAS}_LOLIPOP_PORT_${PLUGIN_DATASTORE_PORTS[0]}_TCP=tcp://172.17.0.1:${PLUGIN_DATASTORE_PORTS[0]}
+  #E     DOKKU_${PLUGIN_DEFAULT_ALIAS}_LOLIPOP_PORT_${PLUGIN_DATASTORE_PORTS[0]}_TCP_PROTO=tcp
+  #E     DOKKU_${PLUGIN_DEFAULT_ALIAS}_LOLIPOP_PORT_${PLUGIN_DATASTORE_PORTS[0]}_TCP_PORT=${PLUGIN_DATASTORE_PORTS[0]}
+  #E     DOKKU_${PLUGIN_DEFAULT_ALIAS}_LOLIPOP_PORT_${PLUGIN_DATASTORE_PORTS[0]}_TCP_ADDR=172.17.0.1
+  #E
+  #E the following will be set on the linked application by default:
+  #E
+  #E     ${PLUGIN_DEFAULT_ALIAS}_URL=${PLUGIN_SCHEME}://lolipop:SOME_PASSWORD@dokku-${PLUGIN_COMMAND_PREFIX}-lolipop:${PLUGIN_DATASTORE_PORTS[0]}/lolipop
+  #E
+  #E the host exposed here only works internally in docker containers.
+  #E if you want your container to be reachable from outside, you should
+  #E use the 'expose' subcommand. another service can be linked to your app:
+  #E dokku $PLUGIN_COMMAND_PREFIX:link other_service playground
+  #E it is possible to change the protocol for ${PLUGIN_DEFAULT_ALIAS}_URL by setting the
+  #E environment variable ${PLUGIN_DEFAULT_ALIAS}_DATABASE_SCHEME on the app. doing so will
+  #E after linking will cause the plugin to think the service is not
+  #E linked, and we advise you to unlink before proceeding.
+  #E dokku config:set playground ${PLUGIN_DEFAULT_ALIAS}_DATABASE_SCHEME=${PLUGIN_SCHEME}2
+  #E dokku $PLUGIN_COMMAND_PREFIX:link lolipop playground
+  #E this will cause ${PLUGIN_DEFAULT_ALIAS}_URL to be set as:
+  #E
+  #E     ${PLUGIN_SCHEME}2://lolipop:SOME_PASSWORD@dokku-${PLUGIN_COMMAND_PREFIX}-lolipop:${PLUGIN_DATASTORE_PORTS[0]}/lolipop
+  #A service, service to run command against
+  #A app, app to run command against
  declare desc="link the $PLUGIN_SERVICE service to the app"
  local cmd="$PLUGIN_COMMAND_PREFIX:link" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" APP="$2"
@@ -17,4 +51,4 @@ redis-link-cmd() {
  service_link "$SERVICE" "$APP"
 }

-redis-link-cmd "$@"
+service-link-cmd "$@"
--- a/subcommands/list
+++ b/subcommands/list
@@ -4,11 +4,13 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-list-cmd() {
+service-list-cmd() {
+  #E list all services
+  #E dokku $PLUGIN_COMMAND_PREFIX:list
  declare desc="list all $PLUGIN_SERVICE services"
  local cmd="$PLUGIN_COMMAND_PREFIX:list" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1

  service_list
 }

-redis-list-cmd "$@"
+service-list-cmd "$@"
--- a/subcommands/logs
+++ b/subcommands/logs
@@ -4,7 +4,13 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-logs-cmd() {
+service-logs-cmd() {
+  #E you can tail logs for a particular service:
+  #E dokku $PLUGIN_COMMAND_PREFIX:logs lolipop
+  #E by default, logs will not be tailed, but you can do this with the --tail flag:
+  #E dokku $PLUGIN_COMMAND_PREFIX:logs lolipop --tail
+  #A service, service to run command against
+  #F -t|--tail, do not stop when end of the logs are reached and wait for additional output
  declare desc="print the most recent log(s) for this service"
  local cmd="$PLUGIN_COMMAND_PREFIX:logs" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" TAIL_FLAG="$2"
@@ -14,4 +20,4 @@ redis-logs-cmd() {
  service_logs "$SERVICE" "$TAIL_FLAG"
 }

-redis-logs-cmd "$@"
+service-logs-cmd "$@"
--- a/subcommands/promote
+++ b/subcommands/promote
@@ -4,7 +4,24 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-promote-cmd() {
+service-promote-cmd() {
+  #E if you have a $PLUGIN_COMMAND_PREFIX service linked to an app and try to link another $PLUGIN_COMMAND_PREFIX service
+  #E another link environment variable will be generated automatically:
+  #E
+  #E     DOKKU_${PLUGIN_DEFAULT_ALIAS}_BLUE_URL=${PLUGIN_SCHEME}://other_service:ANOTHER_PASSWORD@dokku-${PLUGIN_COMMAND_PREFIX}-other-service:${PLUGIN_DATASTORE_PORTS[0]}/other_service
+  #E
+  #E you can promote the new service to be the primary one
+  #E > NOTE: this will restart your app
+  #E dokku $PLUGIN_COMMAND_PREFIX:promote other_service playground
+  #E this will replace ${PLUGIN_DEFAULT_ALIAS}_URL with the url from other_service and generate
+  #E another environment variable to hold the previous value if necessary.
+  #E you could end up with the following for example:
+  #E
+  #E     ${PLUGIN_DEFAULT_ALIAS}_URL=${PLUGIN_SCHEME}://other_service:ANOTHER_PASSWORD@dokku-${PLUGIN_COMMAND_PREFIX}-other-service:${PLUGIN_DATASTORE_PORTS[0]}/other_service
+  #E     DOKKU_${PLUGIN_DEFAULT_ALIAS}_BLUE_URL=${PLUGIN_SCHEME}://other_service:ANOTHER_PASSWORD@dokku-${PLUGIN_COMMAND_PREFIX}-other-service:${PLUGIN_DATASTORE_PORTS[0]}/other_service
+  #E     DOKKU_${PLUGIN_DEFAULT_ALIAS}_SILVER_URL=${PLUGIN_SCHEME}://lolipop:SOME_PASSWORD@dokku-${PLUGIN_COMMAND_PREFIX}-lolipop:${PLUGIN_DATASTORE_PORTS[0]}/lolipop
+  #A service, service to run command against
+  #A app, app to run command against
  declare desc="promote service <service> as ${PLUGIN_DEFAULT_ALIAS}_URL in <app>"
  local cmd="$PLUGIN_COMMAND_PREFIX:promote" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" APP="$2"
@@ -17,4 +34,4 @@ redis-promote-cmd() {
  service_promote "$SERVICE" "$APP"
 }

-redis-promote-cmd "$@"
+service-promote-cmd "$@"
--- a/subcommands/restart
+++ b/subcommands/restart
@@ -4,7 +4,10 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-restart-cmd() {
+service-restart-cmd() {
+  #E restart the service
+  #E dokku $PLUGIN_COMMAND_PREFIX:restart lolipop
+  #A service, service to run command against
  declare desc="graceful shutdown and restart of the $PLUGIN_SERVICE service container"
  local cmd="$PLUGIN_COMMAND_PREFIX:restart" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"
@@ -16,4 +19,4 @@ redis-restart-cmd() {
  dokku_log_info1 "Please call dokku ps:restart on all linked apps"
 }

-redis-restart-cmd "$@"
+service-restart-cmd "$@"
--- a/subcommands/start
+++ b/subcommands/start
@@ -4,7 +4,10 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-start-cmd() {
+service-start-cmd() {
+  #E start the service
+  #E dokku $PLUGIN_COMMAND_PREFIX:start lolipop
+  #A service, service to run command against
  declare desc="start a previously stopped $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:start" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"
@@ -14,4 +17,4 @@ redis-start-cmd() {
  service_start "$SERVICE"
 }

-redis-start-cmd "$@"
+service-start-cmd "$@"
--- a/subcommands/stop
+++ b/subcommands/stop
@@ -4,7 +4,10 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-stop-cmd() {
+service-stop-cmd() {
+  #E stop the service and the running container
+  #E dokku $PLUGIN_COMMAND_PREFIX:stop lolipop
+  #A service, service to run command against
  declare desc="stop a running $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:stop" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"
@@ -14,4 +17,4 @@ redis-stop-cmd() {
  service_stop "$SERVICE"
 }

-redis-stop-cmd "$@"
+service-stop-cmd "$@"
--- a/subcommands/unexpose
+++ b/subcommands/unexpose
@@ -4,7 +4,10 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-unexpose-cmd() {
+service-unexpose-cmd() {
+  #E unexpose the service, removing access to it from the public interface (0.0.0.0)
+  #E dokku $PLUGIN_COMMAND_PREFIX:unexpose lolipop
+  #A service, service to run command against
  declare desc="unexpose a previously exposed $PLUGIN_SERVICE service"
  local cmd="$PLUGIN_COMMAND_PREFIX:unexpose" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1"
@@ -14,4 +17,4 @@ redis-unexpose-cmd() {
  service_port_unexpose "$SERVICE"
 }

-redis-unexpose-cmd "$@"
+service-unexpose-cmd "$@"
--- a/subcommands/unlink
+++ b/subcommands/unlink
@@ -4,7 +4,12 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 source "$PLUGIN_BASE_PATH/common/functions"
 source "$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")/functions"

-redis-unlink-cmd() {
+service-unlink-cmd() {
+  #E you can unlink a $PLUGIN_COMMAND_PREFIX service
+  #E > NOTE: this will restart your app and unset related environment variables
+  #E dokku $PLUGIN_COMMAND_PREFIX:unlink lolipop playground
+  #A service, service to run command against
+  #A app, app to run command against
  declare desc="unlink the $PLUGIN_SERVICE service from the app"
  local cmd="$PLUGIN_COMMAND_PREFIX:unlink" argv=("$@"); [[ ${argv[0]} == "$cmd" ]] && shift 1
  declare SERVICE="$1" APP="$2"
@@ -12,9 +17,9 @@ redis-unlink-cmd() {

  [[ -z "$SERVICE" ]] && dokku_log_fail "Please specify a name for the service"
  [[ -z "$APP" ]] && dokku_log_fail "Please specify an app to run the command on"
-  verify_app_name "$APP"
  verify_service_name "$SERVICE"
+  verify_app_name "$APP"
  service_unlink "$SERVICE" "$APP"
 }

-redis-unlink-cmd "$@"
+service-unlink-cmd "$@"