[get_PAT_owner] enhancements (#66)

* Improve get_PAT_owner script

- support passing PAT via environment variable
- add more docs

get_PAT_owner

@@ -1,9 +1,19 @@
 #!/usr/bin/env bash
 
-USAGE="usage: ${0##*/} PAT
+USAGE="usage: ${0##*/} [PAT]
 Return the owner & permissions associated with the PAT
+
+Passing the PAT via the environment variable PAT is prefered and takes
+precedence. The PAT should be passed as an argument as a CI variable reference,
+only where the CI system guarantees the value will not be displayed in any log.
+
+ENVIRONMENT:
+    PAT     The GitHub token to audit
 "
 
+# Defaults
+token="${PAT:-}"
+
 if [ -n "$DEBUG" ]; then
     PS4=':${LINENO}+'
     set -x
@@ -23,11 +33,19 @@ while [[ $# -gt 0 ]]; do
     shift
 done
 
-MIN_ARGS=1
+MIN_ARGS=0
 MAX_ARGS=1
-[[ $# -lt $MIN_ARGS || $# -lt $MAX_ARGS ]] && usage "Wrong number of args $#"
+[[ $# -lt $MIN_ARGS || $# -gt $MAX_ARGS ]] && usage "Wrong number of args $#"
 
-token="$1"
+if [[ -z $token ]]; then
+    if [[ $# -eq 1 ]]; then
+        token="$1"
+    else
+        usage "No PAT supplied"
+    fi
+elif [[ $# -eq 1 ]]; then
+        warn "WARNING: Ignoring command line arguement, using environment variable PAT"
+fi
 
 resp=$(curl --silent --show-error \
     --include \
@@ -41,6 +59,6 @@ oauth=$(echo "$resp" | grep -i ^X-OAuth-Scopes)
 login=$(echo "$resp" | grep -i -w login | cut -d: -f2)
 id_v4=$(echo "$resp" | grep -i -w node_id | cut -d: -f2)
 
-echo "The PAT is owned by $(echo $login $id_v4)
+echo "The PAT is owned by $login $id_v4
 and has the following permissions:
 $oauth"