Repository files navigation

Available includes two CLI tools designed to ease writing scripts for administration tasks on macOS. These CLI tools are wrapped within an application shell in order to provide a reliable installation path.

• available-cli evaluates whether the console user is 'available' for interaction.
• output-cli aids in displaying script output and logging script results.

In most cases, the included tools would be used in scripts run via an MDM such as Jamf Pro.

While I feel confident thatavailable-cli works well in most cases, please be aware that many of the tests depend on 3rd party applications and OS tools, which break suddenly if the vendor makes changes to their app, or Apple makes changes to the OS.

In particular, the detection of various online meetings is fragile, relying on specific file locations and states.

The detection of focus modes may not detect all focus modes set via smart triggers, especially those set on a different iCloud device.

Please test and determine the best way to use the tool in your environment.

Some of the methodology used within these tools may not match the 'Swifty' way of obtaining the information, for two primary reasons:

• While some of the functionality may be possible in Swift, some of those APIs are not available to CLI applications or are only possible for the user running the application.
• Swift is not, by any means, my primary programming language.

As such, I am open to suggestions for improving the tests and reducing the number of bash callouts within the code. Open an issue or a PR!

Many of the ideas and portions of code in this tool came from a variety of sources on the web and within the MacAdmins community. I have attempted to provide full credit throughout the code base where applicable, even in cases where the original code had to be rewritten to work in Swift.

Of particular note are the individuals below. Without their contributions to Open Source and the MacAdmins community this tool would not be possible, and many users would still be voicing their ire to me:

• Erik Gomez
• Armin Briegel
• Bart Reardon
• Drew Kerr
• brunerd
• Steven J. Selcuk

Often one may need to interact with a user when running a management script. As many management tasks are critical for the security and stability of macOS, these dialogs can be pretty important. Of course, it'salso possible that the user is already doing something equally important. Or slightly less important, but still not worth interrupting such as that pesky sales presentation on stage in front of 50,000 convention attendees.

That's whereavailable-cli comes in. This tool can check several different items to determine if it is a wise time to interrupt the user. Best of all, you can decide what level of deference you want to give to the user based on the flags used.

Additionally, theWork focus can be excluded from the--focus check with the additional flag--no-work.

Depending on whether you would like some feedback, or simply a boolean result, usage may vary. Output can take three forms:

Here is an example of Bash usage, with a standard installation:

binAvailable="/Applications/Available.app/Contents/Resources/available-cli"if state=$($binAvailable --camera --metered --presenting); then  echo "User Unavaiable: '${state}'.  Exiting..."  exit 1fi

Note that the script must be run via sudo or root for the best results. This is because many of the checks are checking the contents of files within the current console user's directory.

While many management scripts can have fairly plain output, it can be useful for troubleshooting purposes to standardize output. The addition of color and context can also be helpful when testing scripts or running them directly from the CLI.

Usingoutput-cli, script output can be easily colorized and standardized across all your management scripts. When used with a terminal that supports ANSI color,output-cli uses contextual colors based on the given flags. When run via a method that has no color support, only plain text is used.

This tool can also provide consistent indentation, allowing for sectioned output.

By setting the environment variableOUTPUT_QUIET=1 orOUTPUT_VERBOSE=1 prior to usingoutput-cli, you can emit messages for different verbosity levels.

The most frequent use case is in combination with some sort of test. The example below gives an example using--notify and--badge to provide feedback on the result of a test.

binOutput="/Applications/Available.app/Contents/Resources/output-cli"$binOutput --notify "Checking Firefox Install"if [ -d "/Applications/Firefox.app ]; then   $binOutput --success --badge "FOUND"else  $binOutput --error --badge "NOT FOUND"  exit 1fi

Which would show the following output:

Checking Firefox Install................................................. [FOUND]

An example of providing different levels of messages is below:

binOutput="/Applications/Available.app/Contents/Resources/output-cli"$binOutput --notify "Checking Something"out=$(/usr/bin/somebinary 2>&1);if echo "$out"; grep -q "error"; then  $binOutput --error --badge "ERROR"  echo ""  # Show the error only if OUTPUT_VERBOSE=2  $binOutput --error --verbose "$out"  exit 1else  $binOutput --success --badge "SUCCESS"fi

If used withOUTPUT_VERBOSE=2 before the snippet above, and assumingsomebinary fails, the output would be:

Checking Something....................................................... [ERROR]

ERROR MESSAGE FROM somebinary DISPLAYED HERE

If used without settingOUTPUT_VERBOSE only the notify and badge would be shown.