feat: add support for enhanced help output

2017-09-11 01:25:41 -04:00
parent 782127781f
commit b493c6a2a5
28 changed files with 564 additions and 230 deletions
--- 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 "$@"