xolo-admin 1.0.0 → 2.0.2

data/data/client/xolo

@@ -0,0 +1,1233 @@
+#!/bin/zsh
+
+
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# SHELL SETUP
+###############################
+###############################
+
+# Load the zsh/zutil module for several utility functions
+zmodload zsh/zutil
+
+# for perl-style regexps
+#
+# DISABLED FOR NOW - macOS before 15 Sequoia doesn't have the pcre module,
+# and we want to support 14 Sonoma for now.
+# The file required is /usr/lib/zsh/5.9/zsh/pcre.so
+#
+# Until then, all our regexps now use posix style
+#
+# setopt RE_MATCH_PCRE
+
+# ENVIRONMENT
+###############################
+###############################
+
+# Needed for the UTF-8 chars in the lsreg output
+export LANG="en_US.UTF-8"
+export LC_ALL="en_US.UTF-8"
+
+# CONSTANTS
+###############################
+###############################
+
+# The version of xolo
+# This should be updated automatically when this script is packaged
+XOLO_VERSION="0.0.0"
+
+# The usage message for xolo
+USAGE='xolo [options] <command> [ title1[=version1] [ title2[=version2] ... ]]'
+
+# The URL for more information about xolo
+XOLO_DOX_URL='https://pixaranimationstudios.github.io/xolo-home/'
+
+# The long path to the lsregister command
+LSREG='/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister'
+
+# The path to the jamf binary
+JAMF='/usr/local/bin/jamf'
+
+# The path to the client data json file
+CLIENT_DATA_JSON_FILE="/Library/Application Support/xolo/client-data.json"
+
+# The jamf policy trigger to update the client data
+UPDATE_CLIENT_DATA_TRIGGER='update-xolo-client-data'
+
+# In the CLI args, titles and versions are separated by the first
+# occurrence of the equals sign
+TITLE_VERSION_SEPARATOR='='
+
+
+# These commands must be run as root
+ROOT_COMMANDS=(
+  install
+  i
+  uninstall
+  u
+  update
+  U
+  refresh
+  r
+  expire
+  e
+)
+
+# GLOBAL VARIABLES
+###############################
+###############################
+
+# From the command line
+
+# options
+show_help=
+be_verbose=
+debugging_on=
+no_versions=
+show_xolo_version=
+
+# arguments
+command=
+targets=
+title=
+version=
+
+# An Associative Array to hold the installed apps
+# is populated by get_installed_apps()
+typeset -A installed_apps
+
+# FUNCTIONS
+###############################
+###############################
+
+# Print a message to stderr
+###############################
+function echoerr() { echo "$@" 1>&2; }
+
+# Die with an error message and status
+###############################
+function die() {
+  local msg="$1"
+  local mystat=1
+
+  [[ -n "$2" ]] && mystat=$2
+  echoerr "ERROR: $msg"
+  exit $mystat
+}
+
+# Die if not root and the command being run is in the list of root commands
+#################################
+function must_be_root() {
+  if (( $ROOT_COMMANDS[(Ie)$command] )); then
+    [[ $EUID -ne 0 ]] && die "You must be root to use the '$command' command."
+  fi
+  return 0
+}
+
+# Show the help message
+###############################
+function show_help() {
+  cat <<ENDHELP
+xolo: manage software titles on this computer
+
+Usage:
+  $USAGE
+
+Options:
+  -h, -H, --help:    Show this help message.
+  -v, --verbose:     Enable verbose mode, extra information will be printed.
+  -d, --debug:       Enable debug mode, extra debug information will be printed.
+                     Implies --verbose.
+  -r, --recon:       With 'install' or 'uninstall' run a 'jamf recon' after the
+                     operation completes successfully.
+  -n, --no-versions: With the 'list-titles' and 'list-installed' commands,
+                     do not show the versions available, or the version
+                     installed, respectively.
+  -V, --version:     Show the version of xolo.
+
+Commands:
+  install, i <title>[=<version>] [<title2>[=<version2>] ...]
+    Install a title, or specific version thereof (e.g. a version currently in pilot)
+    If no version is specified, the currently released version will be installed.
+
+  uninstall, u <title> [<title2> ...]
+    Uninstall a title, if possible. Not all titles are uninstallable via xolo.
+
+  update, U
+    Run any pending updates to currently installed titles, or install new titles
+    that are scoped to auto-install on this computer. The exact behavior depends on
+    what's installed and the title's configuration. This also happens automatically
+    every time this computer checks in with Jamf Pro.
+    Note: this just runs the 'jamf policy' command, which will execute any pending
+    Jamf policies triggered by "recurring check-in".
+
+  refresh, r
+    Update xolo's information about current titles and versions.
+    This also happens automatically at least daily, when this computer is online.
+
+  list-titles, lt
+    List all known titles and versions. Not all may be available for install,
+    e.g., if this computer is in an excluded computer-group
+
+  list-installed, li
+    List titles installed on this computer, that are known to xolo. This may take
+    a few moments, since all titles with version scripts will run those scripts
+    to see if they are installed.
+
+  details, d <title>[=<version>] [<title2>[=<version2>] ...]
+    Show detailed information about titles, or a specific versions thereof.
+    Note that titles and versions contain different sets of information, so the output
+    will differ depending on what you specify.
+
+  expire, e
+    Expire the given title if it has not been used in its defined expiration period.
+    Does nothing if the title is not expirable.
+    This also happens automatically at least daily, when this computer is online.
+
+  help, h
+    Show this help message. The same as -h or --help.
+
+Examples:
+  xolo install transmogrifier
+    Installs the currently released version of the title "transmogrifier".
+
+  xolo install laserbeam transmogrifier=2.0
+    Installs the currently released version of the title "laserbeam" and version 2.0 of
+    the title "transmogrifier", if it is in pilot or already released.
+
+  xolo uninstall transmogrifier laserbeam
+    Uninstalls the titles "transmogrifier" and "laserbeam, if they are uninstallable via
+    xolo and currently installed. Note that versions are ignored for uninstalling, since
+    only one version of a title can be installed at a time.
+
+  xolo list-titles
+    Lists all titles known to xolo, with their versions and statuses.
+
+  xolo details laserbeam transmogrifier=2.0
+    Shows detailed information about the title "laserbeam" and version 2.0 of the title
+    "transmogrifier".
+
+  For more information about xolo, see $XOLO_DOX_URL
+ENDHELP
+} # end show_help
+
+# Parse the command line arguments
+###############################
+function parse_cli() {
+  zparseopts -D -F -E -- \
+    {h,H,-help}=show_help \
+    {v,-verbose}=be_verbose \
+    {d,-debug}=debugging_on \
+    {n,-no-versions}=no_versions \
+    {r,-recon}=do_recon \
+    {V,-version}=show_xolo_version || \
+    die 'Unknonwn Options or Args.'
+
+  # they are in arrays, but we want regular vars
+  show_help=$show_help[-1]
+  be_verbose=$be_verbose[-1]
+  debugging_on=$debugging_on[-1]
+  no_versions=$no_versions[-1]
+  do_recon=$do_recon[-1]
+  show_xolo_version=$show_xolo_version[-1]
+
+  # if debugging is on, verbose is also on
+  [[ -n $debugging_on ]] && be_verbose=1
+
+  command=$1
+  [[ ${#@} -gt 0 ]] && shift
+
+  targets=("${(@)@}")
+
+  debug "Parsed command line:"
+  debug "..show_help is: $show_help"
+  debug "..be_verbose is: $be_verbose"
+  debug "..debugging_on is: $debugging_on"
+  debug "..no_versions is: $no_versions"
+  debug "..show_xolo_version is: $show_xolo_version"
+
+  debug "..command is: $command"
+  debug "..targets are: $targets"
+}
+
+# Parse a title and version from the command line, where they may be given in the form
+# title or title=version
+#################################
+function parse_title_and_version() {
+  local arg=$1
+  debug "Parsing title and version from arg: '$arg'"
+
+  if [[ "$arg" == *"$TITLE_VERSION_SEPARATOR"* ]] ; then
+    # everything before the first = is title
+    title=${arg%%$TITLE_VERSION_SEPARATOR*}
+    # everything after the first = is version
+    version=${arg#*$TITLE_VERSION_SEPARATOR}
+  else
+    title="$arg"
+    version=''
+  fi
+
+  debug "..title is: '$title'"
+  debug "..version is: '$version'"
+
+  return 0
+}
+
+# quick test for debugging_on
+###############################
+function debugging_on() {
+  [[ -n "$debugging_on" ]]
+}
+
+# quick test for be_verbose
+###############################
+function be_verbose() {
+  [[ -n "$be_verbose" ]]
+}
+
+# Print a message to stout
+###############################
+function say() {
+  echo "$*"
+}
+
+# Print a message to stdout if we're in verbose or debug mode
+###############################
+function verbose() {
+  be_verbose && echo "$*"
+}
+
+# Print a message to stderr if we're in debug mode
+###############################
+function debug() {
+  debugging_on && echo "DEBUG: $*" 1>&2
+}
+
+# Gather all installed bundle ids and installed versions from lsreg
+# store them in an associative array in $installed_apps.
+# keys are bundle ids, values are app name & installed version
+# separated by a semicolon
+# e.g. 'com.apple.Safari => Safari.app;14.0.3'
+###############################
+function get_installed_apps() {
+  debug "Getting all installed .apps on this Mac..."
+  local app_name
+  local app_bundle_id
+  local app_vers
+
+  # loop thru lsreg output
+  "$LSREG" -dump Bundle | while IFS= read -r line ; do
+    # a line if ------ starts a new record
+    if [[ "$line" =~ '^-+$' ]] ; then
+      unset app_name
+      unset app_bundle_id
+      unset app_vers
+      continue
+    fi
+
+    # $MATCH is the whole matched string, $match is the array of captures
+    # NOTE this only works if the path is listed before the CFBundleIdentifier
+    # which seems to be the case in the lsreg output
+    [[ "$line" =~ '^path:[[:space:]]+/.*/(.+\.app) \(' ]] && app_name=$match[1]
+    [[ "$line" =~ '^[[:space:]]+CFBundleIdentifier = \"(.+)\";' ]] && app_bundle_id=$match[1]
+    [[ "$line" =~ '^[[:space:]]+CFBundleShortVersionString = \"(.+)\";' ]] && app_vers=$match[1]
+
+    if [[ -n "$app_name" && -n "$app_bundle_id" && -n "$app_vers" ]] ; then
+      installed_apps[$app_bundle_id]="$app_name;$app_vers"
+      unset app_name
+      unset app_bundle_id
+      unset app_vers
+    fi
+  done
+  # installed_apps is now an associative array with bundle ids as keys and app names as values
+
+  # print the installed apps - this is a long list
+  if debugging_on ; then
+    debug "All installed .apps on this Mac:"
+    for bundle app in ${(kv)installed_apps}; do
+          debug "'$bundle' -> '$app'"
+    done
+  fi
+
+} # end installed_apps
+
+# Extract data from the client-data.json file
+#
+# TODO: Once we only support macOS 15 (Sequoia) and higher, we
+# can use /usr/bin/jq to parse the JSON file instead of using JXA.
+#
+# $1 = a string of javascript that extracts your desired info from
+# the client-data.json file, which has already been parsed into
+# the variable 'parsed_data'
+#
+# your code should process parsed_data however it needs, and then
+# put the desired output string  into the 'result' var, which has already
+# been declared.
+#
+# The result of your processing will be sent to stdout of this function
+#######################################
+function extract_json_data() {
+  debug "Extracting data from client-data.json..."
+  local processing_code="$1"
+  local CLIENT_DATA_PROCESSING_JS
+
+  read -r -d '' CLIENT_DATA_PROCESSING_JS <<ENDJAVASCRIPT
+// this gives us access to the local file system
+var app = Application.currentApplication();
+app.includeStandardAdditions = true;
+
+// run() is automatically executed when the program is called, and will print any output returned.
+function run() {
+    var parsed_data = JSON.parse(app.read("${CLIENT_DATA_JSON_FILE}"));
+    var result;
+
+    // the line below will sub-in whatever code we were passed
+    // to process the parsed data and store the result in 'result'
+
+    ${processing_code}
+
+    return result
+}
+ENDJAVASCRIPT
+
+  # in debug mode, show the javascript that will be run
+  debug '============= EXECUTING JAVASCRIPT ==========='
+  debug "${CLIENT_DATA_PROCESSING_JS}"
+  debug '========================'
+
+  # run the javascript to send the result to stdout, which is the default
+  # behavior of of the 'run' function in JXA
+  osascript -l "JavaScript" <<< "${CLIENT_DATA_PROCESSING_JS}"
+
+}
+
+# Outputs all known titles, one per line
+#######################################
+function all_xolo_titles() {
+  debug "Getting all known titles..."
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+    result = Object.keys(parsed_data.titles).join('\n');
+ENDJAVASCRIPT
+  extract_json_data "$jscode" | sort
+}
+
+# Outputs all known titles, one per line, with versions and statuses
+#######################################
+function all_xolo_titles_with_versions() {
+  debug "Getting all known titles with versions and statuses..."
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+
+    result = '';
+
+    Object.entries(parsed_data.titles).forEach(([title, title_data]) => {
+      result += \`\${title}: \`;
+
+      if (title_data.versions.length > 0) {
+        vers_array = title_data.versions.map(
+          function (version) {
+            return \`\${version.version} (\${version.status})\`;
+          } // end function
+        ); // end map
+
+        result += \`\${vers_array.join(', ')}\`;
+      } // end if
+
+      result += "\n";
+    }); // end forEach
+
+    // remove the last newline
+    result = result.slice(0, -1);
+
+ENDJAVASCRIPT
+  extract_json_data "$jscode"  | sort
+}
+
+
+# $1 = the name of a title
+# Outputs all the versions for the title, one per line
+#######################################
+function versions_for_title() {
+  debug "Getting versions for title $1..."
+  local desired_title=$1
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+   if (parsed_data.titles["${desired_title}"]) {
+     result = parsed_data.titles["${desired_title}"]["version_order"].join('\n');
+   } else {
+     result = \`Unknown title \${desired_title}\n\`;
+   }
+ENDJAVASCRIPT
+  extract_json_data "$jscode"
+}
+
+# $1 = the name of a title
+# Output the text to be displayed for the 'details' command for a title
+#######################################
+function details_for_title() {
+  debug "Getting details for title $1..."
+  local desired_title=$1
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+   if (parsed_data.titles["${desired_title}"]) {
+     var title_data = parsed_data.titles["${desired_title}"];
+
+     result = \`Details of title \${title_data.title}\n\`;
+     result += \`..Display Name: \${title_data.display_name}\n\`;
+     result += \`..Description: \${title_data.description}\n\`;
+     result += \`..Publisher: \${title_data.publisher}\n\`;
+     result += \`..Release Groups: \${title_data.release_groups}\n\`;
+     result += \`..Excluded Groups: \${title_data.excluded_groups}\n\`;
+
+     if (title_data.uninstall_script || title_data.uninstall_ids.length > 0) {
+       var uninstallable = 'true';
+     } else {
+       var uninstallable = 'false';
+     }
+     result += \`..Uninstallable: \${uninstallable}\n\`;
+
+     if ( uninstallable == 'true' && title_data.expiration && title_data.expire_paths.length > 0) {
+       result += \`..Expires after days of disuse: \${title_data.expiration}\n\`;
+       result += \`..Expire Paths: \${title_data.expire_paths}\n\`;
+     }
+
+     if ( title_data.self_service ) {
+      result += \`..In Self Service: true\n\`;
+      result += \`..Self Service Category: \${title_data.self_service_category}\n\`;
+     }
+
+     result += \`..Contact: \${title_data.contact_email}\n\`;
+     result += \`..Added to Xolo: \${title_data.creation_date} by \${title_data.created_by}\n\`;
+
+     result += \`..Versions:\n\`;
+     if (title_data.versions.length > 0) {
+       title_data.versions.forEach(
+         function (arrayItem) {
+            result += \`....\${arrayItem.version}: \${arrayItem.status}\n\`;
+          }
+        );
+      } else {
+        result += \`....No versions added yet\n\`;
+      }
+
+   } else {
+     result = \`Unknown title ${desired_title}\n\`;
+   }
+ENDJAVASCRIPT
+
+  extract_json_data "$jscode"
+}
+
+
+# $1 = the name of a title
+# $2 = the name of a version
+# Output the text to be displayed for the 'details' command for a version
+#######################################
+function details_for_version() {
+  debug "Getting details for version $2 of title $1 ..."
+  local desired_title=$1
+  local desired_version=$2
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+   if (parsed_data.titles["${desired_title}"]) {
+     var title_data = parsed_data.titles["${desired_title}"];
+     var version_data = title_data.versions.find(
+        function(value, index, array) {
+          return value.version == "${desired_version}";
+        }
+      );
+
+     if (version_data) {
+         result = \`Details of version '\${version_data.version}' of title \${title_data.title}\n\`;
+         result += \`..Publish Date: \${version_data.publish_date}\n\`;
+         result += \`..Added to Xolo: \${version_data.creation_date} by \${version_data.created_by}\n\`;
+         if (version_data.pilot_groups.length > 0) result += \`..Pilot Groups: \${version_data.pilot_groups}\n\`;
+
+         result += \`..Minimum OS Version: \${version_data.min_os}\n\`;
+         if (version_data.max_os) result += \`..Maximum OS Version: \${version_data.max_os}\n\`;
+         result += \`..Requires Reboot: \${version_data.reboot}\n\`;
+         result += \`..Standalone: \${version_data.standalone}\n\`;
+         if (version_data.killapps.length > 0) result += \`..KillApps: \${version_data.killapps}\n\`;
+
+         result += \`..Status: \${version_data.status}\n\`;
+         if (version_data.status == 'released') {
+           result += \`..Released: \${version_data.release_date} by \${version_data.released_by}\n\`;
+           if (title_data.release_groups.length > 0)  result += \`..Release Groups: \${title_data.release_groups}\n\`;
+         }
+
+         if (version_data.status == 'deprecated') {
+           result += \`..Deprecated: \${version_data.deprecation_date} by \${version_data.deprecated_by}\n\`;
+         }
+
+         if (version_data.status == 'skipped') {
+           result += \`..Skipped: \${version_data.skipped_date} by \${version_data.skipped_by}\n\`;
+         }
+
+
+
+      } else {
+        result = \`Unknown version '${desired_version}' for title ${desired_title}\`;
+     }
+
+   } else {
+     result = \`Unknown title ${desired_title}\`;
+   }
+ENDJAVASCRIPT
+
+  extract_json_data "$jscode"
+}
+
+# $1 = the name of a title
+# Outputs the version script for the title
+# or empty string if not set, or if no matching title
+#######################################
+function version_script_for_title() {
+  debug "Getting version script for title $1..."
+  local desired_title=$1
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+   if (parsed_data.titles["${desired_title}"]) {
+     var vscript = parsed_data.titles["${desired_title}"]["version_script"];
+     result = vscript ? vscript : ''
+   } else {
+     result = '';
+   }
+ENDJAVASCRIPT
+  extract_json_data "$jscode"
+}
+
+# $1 = the name of a title
+# Outputs the app_name and app_bundle_id for the title, semi-colon separated
+# or empty string if not set, or if no matching title
+#######################################
+function app_data_for_title() {
+  debug "Getting app data for title $1..."
+  local desired_title=$1
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+   if (parsed_data.titles["${desired_title}"]) {
+     var appname = parsed_data.titles["${desired_title}"]["app_name"];
+     var bundleid = parsed_data.titles["${desired_title}"]["app_bundle_id"];
+     if (appname && bundleid) {
+      result = \`\${appname};\${bundleid}\`;
+     } else {
+       result = '';
+     }
+        } else {
+     result = '';
+   }
+ENDJAVASCRIPT
+  extract_json_data "$jscode"
+}
+
+# $1 = the name of a title
+# Outputs the expiration period (integer of days) for the title
+# or empty string if not set, or if no matching title
+#######################################
+function expiration_for_title() {
+  debug "Getting expiration for title $1..."
+  local desired_title=$1
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+   if (parsed_data.titles["${desired_title}"]) {
+     var expiration = parsed_data.titles["${desired_title}"]["expiration"];
+     result = expiration ? expiration : ''
+   } else {
+     result = '';
+   }
+ENDJAVASCRIPT
+  extract_json_data "$jscode"
+}
+
+# $1 = the name of a title
+# Outputs the expire paths for the title, one per line
+# or empty string if not set, or if no matching title
+#######################################
+function expire_paths_for_title() {
+  debug "Getting expire paths for title $1..."
+  local desired_title=$1
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+   if (parsed_data.titles["${desired_title}"]) {
+     var expire_paths = parsed_data.titles["${desired_title}"]["expire_paths"];
+     result = expire_paths.length > 0 ? expire_paths.join("\n") : ''
+   } else {
+     result = '';
+   }
+ENDJAVASCRIPT
+  extract_json_data "$jscode"
+}
+
+# $1 = the name of a title
+# Outputs the currently released version for the title
+# or empty string if not set, or if no matching title
+#######################################
+function released_version_for_title() {
+  debug "Getting released version for title $1..."
+  local desired_title=$1
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+   if (parsed_data.titles["${desired_title}"]) {
+     var released_version = parsed_data.titles["${desired_title}"]["released_version"];
+     result = released_version ? released_version : ''
+   } else {
+     result = '';
+   }
+ENDJAVASCRIPT
+  extract_json_data "$jscode"
+}
+
+# $1 = the name of a title
+# $2 = the name of a version
+# Output status of a version
+#######################################
+function status_for_version() {
+  debug "Getting status for version $2 of title $1 ..."
+  local desired_title=$1
+  local desired_version=$2
+  local jscode
+
+  read -r -d '' jscode <<ENDJAVASCRIPT
+   if (parsed_data.titles["${desired_title}"]) {
+     var title_data = parsed_data.titles["${desired_title}"];
+     var version_data = title_data.versions.find(
+        function(value, index, array) {
+          return value.version == "${desired_version}";
+        }
+      );
+
+     if (version_data) {
+        result = version_data.status;
+      } else {
+        result = \`Unknown version '${desired_version}' for title ${desired_title}\`;
+     }
+
+   } else {
+     result = \`Unknown title ${desired_title}\`;
+   }
+ENDJAVASCRIPT
+
+  extract_json_data "$jscode"
+}
+
+# Run a Jamf policy trigger
+# $1 = the policy trigger to run
+# $2 = any extra options to pass to the jamf command
+# be_verbose() will automatically be honored
+#######################################
+function run_jamf_policy_trigger() {
+  local policy_trigger=$1
+  local jamf_options=$2
+  local jamf_verbose=''
+  local cmd
+
+  be_verbose && jamf_verbose='-verbose'
+
+  cmd="$JAMF policy -trigger $policy_trigger $jamf_options $jamf_verbose"
+  tempfile=$(mktemp /tmp/xolo-policy.XXXXXXXX)
+
+  debug "Running jamf policy command: $cmd"
+  eval "$cmd" | tee "$tempfile"
+
+  policy_output=$(<"$tempfile")
+  rm -f "$tempfile"
+
+  [[ $policy_output =~ 'Submitting log to https://' ]] && return 0
+
+  # callers can examine $policy_output if they want to see what happened
+  return 1
+}
+
+# Refresh the client data
+###############################
+function refresh_client_data() {
+
+  # if we've already refreshed during this run, we're done
+  [[ -n "$client_data_refreshed" ]] && return
+
+  [[ "$command" == 'refresh' ]] && say "Refreshing client data..." || debug "Refreshing client data..."
+
+  run_jamf_policy_trigger $UPDATE_CLIENT_DATA_TRIGGER
+
+  client_data_refreshed=1
+}
+
+# validate that the title exists
+###############################
+function validate_title() {
+  # if we've already validated the title, we're done
+  [[ -n "$title_is_valid" ]] && return
+
+  debug "Validating title: $title"
+
+  # die if no title given
+  [[ -z "$title" ]] && die "No title given.\nUsage: $USAGE\nUse --help for more information."
+
+  # make sure the JSON data file is up to date, if we are root
+
+  [[ $EUID -eq 0 ]] && refresh_client_data
+
+  # die if no such title
+  # all titles in an array
+  IFS=$'\n' all_titles=($(all_xolo_titles))
+
+  # index will be zero if the title is not in the array
+  [[ ${all_titles[(Ie)$title]} -eq 0 ]] && die "No such title: $title"
+  title_is_valid=1
+}
+
+# validate that the version exists
+###############################
+function validate_version() {
+  # if we've already validated the version, we're done
+  [[ -n "$version_is_valid" ]] && return
+
+  validate_title
+  debug "Validating version: $version"
+
+  # die if no version given
+  [[ -z "$version" ]] && die "No version given.\nUsage: $USAGE\nUse --help for more information."
+
+  # die if no such version
+  all_versions=$(versions_for_title $title)
+  debug "All versions for title $title:\n$all_versions"
+  # [[ $all_versions =~ (^|\n)$version($|\n) ]] || die "No such version: $version"
+  echo "$all_versions" | grep -q "^$version$" || die "No such version: $version"
+  version_is_valid=1
+}
+
+# Install all the items on the command line, which may be titles or specific versions of titles
+#################################
+function install_cli_args() {
+  debug "Installing Targets: $targets"
+  for item in $targets ; do
+    parse_title_and_version "$item"
+    install
+  done
+}
+
+
+# Install a title, or a specific version thereof
+###############################
+function install() {
+
+  validate_title
+
+  # if no version is given, we'll find the current release
+  if [[ -z "$version" ]] ; then
+    version=$(released_version_for_title $title)
+    [[ -z "$version" ]] && die "No current release for title: $title. Specify a version to install."
+
+    # This trigger always installs the current release via a single policy for the title
+    install_trigger="xolo-${title}-install"
+  else
+    # this is the trigger for a specific version of a title.
+    install_trigger="xolo-${title}-${version}-manual-install"
+  fi
+
+  validate_version
+
+  if [[ -n "$version" ]] ; then
+    thing_being_installed="version $version of title $title"
+  else
+    thing_being_installed="released version of title $title"
+  fi
+  say "Installing $thing_being_installed"
+
+  if run_jamf_policy_trigger "${install_trigger}" ; then
+    run_recon
+    say "Done, installed $thing_being_installed"
+  else
+    if [[ $policy_output =~ 'No policies were found for the' ]] ; then
+      die "Title $title is excluded for this computer or is not installable via xolo"
+    else
+      die "Install of title $title failed."
+    fi
+  fi
+}
+
+# uninstall CLI args, which are just titles since versions don't matter for uninstalling
+##############################
+function uninstall_cli_args() {
+  debug "Uninstalling Targets: $targets"
+  for item in $targets ; do
+    parse_title_and_version "$item"
+    uninstall
+  done
+}
+
+# Unnstall a title
+# This might not do anything if the title is not uninstallable,
+# or if the title is not installed
+###############################
+function uninstall() {
+  validate_title
+
+  details_for_title $title | grep -q 'Uninstallable: true' || die "Title $title is not uninstallable via xolo"
+
+  say "Uninstalling title $title..."
+
+  if run_jamf_policy_trigger "xolo-${title}-uninstall" ; then
+    run_recon
+    say "Done, title $title uninstalled"
+  else
+    if [[ $policy_output =~ 'No policies were found for the' ]] ; then
+      die "Title $title is not uninstallable via xolo"
+    else
+      die "Uninstall of title $title failed."
+    fi
+  fi
+}
+
+# run a jamf recon if requested
+#
+#############################
+function run_recon() {
+  [[ -n "$do_recon" ]] || return 0
+
+  say 'Running jamf recon...'
+  if be_verbose ; then
+    $JAMF recon -verbose
+  else
+    $JAMF recon
+  fi
+}
+
+# Update installed titles or install new ones
+# scoped to this computer.
+# This is just running 'jamf policy' with its default
+# trigger "recurring check-in".
+###############################
+function update() {
+  say "Updating installed titles, or installing newly scoped ones..."
+
+  debug "Running jamf policy..."
+    if be_verbose ; then
+    $JAMF policy -verbose
+  else
+    $JAMF policy
+  fi
+}
+
+# List all known titles and their versions and statuses
+###############################
+function list_all_titles() {
+  say "All Titles known to Xolo..."
+
+  if [[ -n "$no_versions" ]] ; then
+    all_xolo_titles
+    return 0
+  fi
+
+  all_xolo_titles_with_versions
+}
+
+# Show detailed information about all titles, or specific versions thereof, given on the command line
+########################
+function show_details_cli_args() {
+  debug "Showing details for targets: $targets"
+  for item in $targets; do
+    parse_title_and_version "$item"
+    show_details
+  done
+}
+
+# Show detailed information about a title or a version thereof
+###############################
+function show_details() {
+  debug "Showing details for title '$title' and version '$version'..."
+  validate_title
+
+  if [[ -z "$version" ]] ; then
+    details_for_title $title
+  else
+    validate_version
+    details_for_version $title $version
+  fi
+}
+
+# List all installed titles
+###############################
+function list_installed_titles() {
+  local ttl
+  local app_data
+
+
+  verbose "Locating installed titles..."
+
+  # populate the installed_apps associative array
+  get_installed_apps
+
+  while IFS= read -r ttl; do
+    app_data=$(app_data_for_title $ttl)
+
+    if [[ -n "$app_data" ]] ; then
+      debug "App Data: '$app_data'"
+      display_title_if_installed_by_app_data $ttl "$app_data"
+    else
+      display_title_if_installed_by_version_script $ttl
+    fi
+  done <<<"$(all_xolo_titles)"
+  return 0
+}
+
+# given a title and some app data (name, bundle id)
+# output a line if its installed, optionally with the version
+# $1 is the semicolon separated app data, name:bundle_id
+###############################
+function display_title_if_installed_by_app_data() {
+  local ttl=$1
+  local app_data=$2
+  local app_name
+  local app_bundle_id
+  local inst_app_name
+  local inst_app_vers
+  local data
+  local parts
+
+
+  parts=(${(s/;/)app_data})
+  app_name=$parts[1]
+  app_bundle_id=$parts[2]
+  debug "Split App Data: '$app_bundle_id' -> '$app_name'"
+
+  # This shouldn't happen but...
+  [[ -n "$app_name" && -n "$app_bundle_id" ]] || return
+
+  # is this bundle id installed?
+  [[ -n $installed_apps[$app_bundle_id] ]] || return
+
+  data=$installed_apps[$app_bundle_id]
+  parts=(${(s/;/)data})
+  inst_app_name=$parts[1]
+  inst_app_vers=$parts[2]
+  debug "Split Installed Data: '$inst_app_name' -> '$inst_app_vers'"
+
+  # no go if the app name doesn't match
+  [[ "$inst_app_name" == "$app_name" ]] || return
+
+  if [[ -n "$no_versions" ]] ; then
+    echo $ttl
+  else
+    echo "$ttl ($inst_app_vers)"
+  fi
+}
+
+
+# Given a title, use its version script to see if its installed,
+# and if so, output a line for it, optionally with the version
+# $1 is the title
+###############################
+function display_title_if_installed_by_version_script() {
+  local title=$1
+  local version_script=$(version_script_for_title $title)
+  local app_vers=
+
+  [[ -n "$version_script" ]] || return
+
+  # Save it to a file, make it executable, run it capturing the output, then delete the file
+  tmp_file=$(mktemp -t xolo.$title)
+  touch "$tmp_file"
+  chmod 700 "$tmp_file"
+  echo "$version_script" > "$tmp_file"
+
+  debug "Running version script for $title from $tmp_file"
+  vsout=$("$tmp_file" 2>/dev/null)
+  debug "Version Script Output: '$vsout'"
+
+  rm -f "$tmp_file"
+
+  [[ -n "$vsout" ]] || return
+
+  # the output should be something like
+  # <result>version</result> if installed, and
+  # <result></result> if not installed
+  [[ "$vsout" =~ '<result>(.*)</result>' ]] && app_vers=$match[1]
+  [[ -n "$app_vers" ]] || return
+
+  if [[ -n "$no_versions" ]] ; then
+    echo $ttl
+  else
+    echo "$ttl ($app_vers)"
+  fi
+}
+
+# Expire the title given on the command line, if
+# - it has an expiration period set
+# - it has defined expire paths
+# - none of the paths are running right now
+# - none of the paths have been used in the defined period
+###############################
+function expire() {
+  validate_title
+
+  local now=$(date '+%s')
+  local expiration=$(expiration_for_title $title)
+  local exp_secs=$(( $expiration * 24 * 3600 ))
+  local expire_paths
+  local victim_path
+  local must_have_been_used_since=$(( $now - $exp_secs ))
+  local last_use_epoch
+  local last_use
+
+  # return if no expiration period
+  if [[ -z "$expiration" ]] ;then
+    say "Title $title is not expirable: No expiration period."
+    return
+  fi
+  # this gives us an array of paths
+  IFS=$'\n' expire_paths=($(expire_paths_for_title $title))
+  # return if empty
+  if [[ ${#expire_paths} -eq 0 ]] ; then
+    say "Title $title is not expirable: no expire paths."
+    return
+  fi
+
+  # loop thru the paths and see if any have been used recently
+  for victim_path in $expire_paths ; do
+
+    # don't expire if any expire path doesn't exist
+    if ! [[ -e "$victim_path" ]] ; then
+      say "Expiration Path: '$victim_path' doesn't exist, not expiring $title."
+      return
+    fi
+
+    # if any of the paths are running, we're done
+    if [[ -n $(/usr/bin/pgrep -f "$victim_path") ]] ; then
+      say "Title $title is not expirable right now: $victim_path is running."
+      return
+    fi
+
+    # if any of the paths have been used in the defined period, we're done
+    # The Apple Developer Site says: kMDItemLastUsedDate is the date and time
+    # that the file was last used. This value is updated automatically by
+    # LaunchServices everytime a file is opened by double clicking, or by asking
+    # LaunchServices to open a file.
+    last_use=$(/usr/bin/mdls -name kMDItemLastUsedDate "$victim_path" -raw)
+    # +> 2024-11-25 23:10:00 +0000
+
+    # use install time if no last use time
+    if ! [[ "$last_use" =~ '^[[:digit:]]{4}-' ]] ; then
+      debug "No last use time for $victim_path, using install time."
+      last_use=$(/usr/bin/mdls -name kMDItemDateAdded "$victim_path" -raw)
+
+      # not installed if mdls fails or returns nothing
+      # so don't expire it
+      if [[ "$last_use" =~ '^[[:digit:]]{4}-' ]] || [[ -z "$last_use" ]] ; then
+        say "Title $title is not expirable: $victim_path has no last use or install time."
+        return
+      fi
+    fi
+
+    last_use_epoch=$(/bin/date -j -f "%Y-%m-%d %H:%M:%S %z" "$last_use" +"%s")
+
+    # if the last use time is more recent than the expiration period,
+    # for any path, we're done
+    if [[ "$last_use_epoch" -gt "$must_have_been_used_since" ]] ; then
+      say "Title $title is not expirable right now: $victim_path was used recently."
+      return
+    fi
+  done # for victim_path in $expire_paths
+
+  # if we're here, we can expire the title
+  say "Expiring title $title..."
+  uninstall
+}
+
+
+
+
+# MAIN
+###############################
+###############################
+
+function main() {
+  # Parse the command line
+  parse_cli "$@"
+
+  # If the user asked for help, show it and exit
+  if [[ -n "$show_help" ]] ; then
+    show_help
+    exit 0
+  fi
+
+  # If the user asked for the xolo version, show it and exit
+  if [[ -n "$show_xolo_version" ]] ; then
+    echo "$XOLO_VERSION"
+    exit 0
+  fi
+
+  if [[ "$command" != "refresh" ]] ; then
+    # If we're not refreshing, we need to have the client data file
+    # and it needs to be up to date
+    [[ -f "$CLIENT_DATA_JSON_FILE" ]] || die "No client data file found at $CLIENT_DATA_JSON_FILE.\nPlease run the 'refresh' command to update the client data."
+  fi
+
+  [[ -z "$command" ]] && die "No command given.\nUsage: $USAGE\nUse --help for more information."
+
+  # confirm we are root for those commands that need it
+  must_be_root
+
+  case "$command" in
+    install|i)
+      debug "processing command 'install'"
+      install_cli_args
+      ;;
+    uninstall|u)
+      debug "processing command 'uninstall'"
+      uninstall_cli_args
+      ;;
+    update|U)
+      debug "processing command 'update'"
+      update
+      ;;
+    refresh|r)
+      debug "processing command 'refresh'"
+      # if 'r' reset to 'refresh' so we can use it in the run_jamf_policy_trigger
+      command=refresh
+      refresh_client_data
+      ;;
+    list-titles|lt)
+      debug "processing command 'list_titles'"
+      list_all_titles
+      ;;
+    list-installed|li)
+      debug "processing command 'list_installed'"
+      list_installed_titles
+      ;;
+    details|d)
+      debug "processing command 'details'"
+      show_details_cli_args
+      ;;
+    expire|e)
+      debug "processing command 'expire'"
+      expire
+      ;;
+    help|h)
+      debug "processing command 'help'"
+      show_help
+      ;;
+    *)
+      die "Unknown command: $command\nUsage: $USAGE\nUse --help for more information."
+      ;;
+  esac
+
+}
+
+# RUN!
+###########################
+main "$@"