Shell scripting in macOS – Part 10: Distribution

February 2, 2023 / Arun Patwardhan / 1 Comment

This is the last article in the series of scripts. We will take the script from Part 8 and continue with it. We will be taking our folderCreator script and using it in our distribution process.

Distribution is the process of placing the script along with any supporting resources on a destination computer making it easily available for use. There are many aspects to this process, but we are going to look at a few of them:

Where should our script be installed?
How will the end user be invoking the script?
Does the script have its own man page?

Creating our own commands from other shell scripts

You may have noticed that whenever we use commands like defaults, echo, ls, cd, … we do not have to specify the path to the command. There is a reason for that. When we run our script the shell interpreter ‘knows’ where to go and look for these commands. There are some predefined locations available. We can get these predefined locations from the environment.

printenv PATH

This gives us an output that looks like:

/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

The output you see will vary from computer to computer. As we can see it is a list of folders separated by a ‘:’. These are the folders the interpreter will go through to locate the commands we use.

While we do not specify the path to a command in our script it is actually considered good practice. In fact, we will be making the same change to our script.

So if we want our own commands to be located easily it should be placed in one of these folders.

Installing commands

While installing commands there is one feature of macOS that we need to keep in mind: SIP (System Integrity Protection). Introduced in OS X 10.11 El Capitan, SIP prevents the modification of certain system files or folders even if you have root privileges. So this means that we do not have a lot of choice when it comes to installing our command. We will place it in /usr/local/bin folder.

Here is the final version of the folderCreator script. I have added paths to some commands and have kept the file name as folderCreator. The version number has been removed from the file name.

#!/bin/zsh

#-------------------------------------------------------------------------------------------------
#NAME: Folder creator
#AUTHOR: Arun Patwardhan
#CONTACT: arun@amaranthine.co.in
#DATE: 15th September 2022
#WEBSITE: https://github.com/AmaranthineTech/ShellScripts
#-------------------------------------------------------------------------------------------------

#LEGAL DISCLAIMER --------------------------------------------------------------------------------
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
#SOFTWARE.
#-------------------------------------------------------------------------------------------------

#LICENSE/TERMS AND CONDITIONS --------------------------------------------------------------------
#MIT License

#Copyright (c) Amaranthine 2021.

#Permission is hereby granted, free of charge, to any person obtaining a copy
#of this software and associated documentation files (the "Software"), to deal
#in the Software without restriction, including without limitation the rights
#to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
#copies of the Software, and to permit persons to whom the Software is
#furnished to do so, subject to the following conditions:

#The above copyright notice and this permission notice shall be included in all
#copies or substantial portions of the Software.
#-------------------------------------------------------------------------------------------------

#ABOUT -------------------------------------------------------------------------------------------
# fileCreator.zsh
# 1.8
#-------------------------------------------------------------------------------------------------

#DESCRIPTION -------------------------------------------------------------------------------------
# - THis script is intended for creating the custom folders that are required on all corporate computers.
# - Run this script on a new computer or a computer being reassigned to another employee.
# - This script can run on all computers.
#-------------------------------------------------------------------------------------------------

#USAGE -------------------------------------------------------------------------------------------
# - To create folders with default names run the command: ./folderCreator.zsh
# - To define your own folder names: ./folderCreator.zsh <folder1> <folder2> <folder3>
# - Available options : Only the help option is available
# - Getting help : Use the -h or the -help options to get more information. Or you can use the man command to view the man page.
#-------------------------------------------------------------------------------------------------

#WARNING/CAUTION ---------------------------------------------------------------------------------
#******************************************************************************************************************
#******************************************************************************************************************
#******************************************************************************************************************
#******************************************************************************************************************
# This script doesn't perform any validation of the folder names being passed in by the user.
# If the script does not see the -h or the -help options then it will assume that the data being passed in is the name of the folder.
# The user of the script must ensure that the desired folder names are passed in.
#******************************************************************************************************************
#******************************************************************************************************************
#******************************************************************************************************************
#******************************************************************************************************************
#-------------------------------------------------------------------------------------------------

#INSTALLATION ------------------------------------------------------------------------------------
# Instructions for placing the script in the correct place are listed here.
# Location: /Library/Scripts/
# Permissions: rwx r-x r-x
#-------------------------------------------------------------------------------------------------

#REQUIREMENTS ------------------------------------------------------------------------------------
# Shell: /bin/zsh
# OS: macOS Big Sur 11.4 or later
# Dependencies: None
#-------------------------------------------------------------------------------------------------

#HELP/SUPPORT ------------------------------------------------------------------------------------
# You can get help by running the following commands.
# ./folderCreator.zsh -h
# ./folderCreator.zsh -help
# OR
# man folderCreator.zsh
# You can also view the log file for the same at: ~/Library/Logs/folderCreator_log_v1-8.log
#-------------------------------------------------------------------------------------------------

#HISTORY -----------------------------------------------------------------------------------------
# ------------------------------------------------------------------------------------------------
# Version 1.0: Basic script which creates the folders
# Version 1.1: Gives user the ability to specify the folder names at run time.
# Version 1.2: Adds safety checks to the scripts
# Version 1.3: Includes documentation as well as ability to get help.
# Version 1.4: Includes optimisation using for loop
# Version 1.5: Prompts the user in the GUI for names for the different folders.
# Version 1.6: Updated the log mechanism with the help of a function and here document.
# Version 1.7: Replaced the folder variables with an array
# Version 1.8: Added absolute path for commands. Final version ready for deployment.
#-------------------------------------------------------------------------------------------------

#-------------------------------------------------------------------------------------------------
# ------------------------------ SCRIPT STARTS HERE ----------------------------------------------
#-------------------------------------------------------------------------------------------------
#-------------------------------------------------------------------------------------------------
#-------------------------------------------------------------------------------------------------

#These are the default values used for the folder names incase the user doesn't provide any.
FOLDERS=("Tools" "Reports" "Help")

#Script version number
VERSION_NUMBER="1.8"

#Command name
COMMAND_NAME="folderCreator.zsh"

#1. Check to see if the user is asking for help. In which case we will have to provide information about the command.
if [[ $1 == "-h" ]] || [[ $1 == "-help" ]]; then
echo "ABOUT
-----
fileCreator.zsh
Version $VERSION_NUMBER

NAME
----
$COMMAND_NAME — Folder creation utility SYNOPSIS
$COMMAND_NAME folder names [ verbs ]

DESCRIPTION
-----------
$COMMAND_NAME creates 3 folders in the home folder. In case the folder names are not provided then the command will create folders with default names 'Tools', 'Reports', \"Help\".

There is also the option of getting help via the help verb.
- This script is intended for creating the custom folders that are required on all corporate computers.
- Run this script on a new computer or a computer being reassigned to another employee.
- This script can run on all computers.

VERBS
-----
[ −h −help] Both the options are used to invoke the help documentation.
[ −v −version] Both the options are used to get the version number of the folderCreator command.

REQUIREMENTS
------------
The following are the minimum requirements to get the script running.
Shell: zsh
OS: macOS Big Sur 11.4 or later
Dependencies: None

INSTALLATION
------------
$COMMAND_NAME can be installed anywhere you wish. However, there are certain locations that are recommended.
Location: /Library/Scripts/
Permissions: rwxr-xr-x

USAGE
-----
$COMMAND_NAME folder1 folder2 folder3
Will create folders with your own names.

$COMMAND_NAME -h OR $COMMAND_NAME -help
Will invoke the help utility.

$COMMAND_NAME -v OR $COMMAND_NAME -version
will print the version number in stdout.

WARNING/CAUTION
---------------
$COMMAND_NAME does not perform any validation of names. The only options that folderCreator accepts are -h and -help verbs or the -v and
-version verbs. If the script does not see the -h , -help or the -v , -version options then it will assume that the data being passed in is
the name of the folder. The user of the folderCreator command must ensure that the desired folder names are passed in. The user will also be
prompted, via the graphical user interface, if he/she wishes to provide the names for the folders. If yes, then there will be subsequent
prompts asking for the folder names.

EXAMPLES
--------
$COMMAND_NAME Resources Results Assistant
This will create 3 folders Resources , Results , Assistant , in the user’s home folder.

$COMMAND_NAME
This will create 3 folders with the default names

$COMMAND_NAME Apps
This will use the Apps name for the first folder but the default names for the last 2 folders.

NOTE
----
The user will be asked if he/she wishes to provide custom names in all the examples mentioned above. The user's value will always override
whatever is being provided to the script or defaults.

DIAGNOSTICS
-----------
The script produces a log file called ~/Library/Logs/folderCreator_log_v1-x.log
This file is typically located in the user’s home folder log folder. The x represents the version number of $COMMAND_NAME
You can view the logs for each respective version.

EXIT STATUS
-----------
In most situations, $COMMAND_NAME exits 0 on success"
exit 0
fi

PATH_TO_LOG="$HOME/Library/Logs/folderCreator_log_v1-8.log"

# Function to log activity
function recordActivity() {
/bin/cat << EOF >> $PATH_TO_LOG
[$(date)] $1
EOF
}

echo "$(date) Running script $0 to create folders."
echo ""

TODAY=$(date)

recordActivity "Starting"

#2. Check to see if the version number is
if [[ $1 == "-version" ]] || [[ $1 == "-v" ]]; then
echo "Version: $VERSION_NUMBER"
exit 0
fi

#3. The following if statements check to see if the script is receiving any arguments. It then picks those arguments and assigns them to the respective variables for use in the script.
if [[ $1 != "" ]]; then
FOLDERS[0]=$1
fi

if [[ $2 != "" ]]; then
FOLDERS[1]=$2
fi

if [[ $3 != "" ]]; then
FOLDERS[2]=$3
fi

#4. We can prompt the user to see if they wish to provide folder names themselves. This will override any values provided as arguments.
userClicked=$(/usr/bin/osascript -e 'button returned of (display dialog "Would you like to provide names for the folders or use the defaults instead?" buttons {"Custom", "Default"} default button 2 with icon POSIX file "/System/Library/CoreServices/HelpViewer.app/Contents/Resources/AppIcon.icns")')

# if the user decides to provide custom names then go ahead and ask the user via GUI prompts. Otherwise use the values sent as arguments or defaults.
if [[ $userClicked == "Custom" ]]; then
recordActivity "The user decided to provide custom names."

FOLDERS[0]=$(/usr/bin/osascript -e 'text returned of (display dialog "Enter the name of folder 1" default answer "Utilities" buttons {"OK"} default button 1 with title "Folder that will hold the utilities" with icon POSIX file "/Users/Shared/Finder.icns")')

FOLDERS[1]=$(/usr/bin/osascript -e 'text returned of (display dialog "Enter the name of folder 2" default answer "Tools" buttons {"OK"} default button 1 with title "Folder that will hold the tools" with icon POSIX file "/Users/Shared/Finder.icns")')

FOLDERS[2]=$(/usr/bin/osascript -e 'text returned of (display dialog "Enter the name of folder 3" default answer "Help" buttons {"OK"} default button 1 with title "Folder that will hold the support documents" with icon POSIX file "/Users/Shared/Finder.icns")')

recordActivity "User provided: ${FOLDER[@]}"
else
recordActivity "User decided to use default values: ${FOLDER[@]}"
fi

#5. Go to the home folder.
cd $HOME

#6. Check to see if each of the folders exists. If it exists then do not create it. Else create the folder.
recordActivity "Creating folders: ${FOLDER[@]}"

for item in ${FOLDER[@]}; do
if [[ -d $item ]]; then
recordActivity "Not creating $item as it already exists."
else
recordActivity "Creating $item"
/bin/mkdir $item
fi

#7. Create the task completion file inside each folder.
recordActivity "Creating hidden file for $item folder."
cd $item
#8. Generate the file names based on the folder names.
/usr/bin/touch ".$item-FolderCreated"
cd ..
done

echo "$(date) Task completed. Have a nice day!"

#-------------------------------------------------------------------------------------------------
#-------------------------------------------------------------------------------------------------
#-------------------------------------------------------------------------------------------------
# ------------------------------ END OF SCRIPT ---------------------------------------------------

In order to run this command we will have to give it execute capabilities.

chmod 755 folderCreator

This should change the icon of the script to that of an executable. If it doesn’t then go ahead and remove the extension from the file.

Copy the file to the /usr/local/bin folder. You will need to authenticate as admin to do this. There may be other executables in this folder.

Using commands

Now let us test to see if this has worked. Run the command:

folderCreator -h

We can use the which command to confirm that the correct binary is being used.

which folderCreator

Adding path to the environment

Now, it is not necessary that the executables we create should be placed in one of the standard PATH folders. We could place it anywhere else. All we would have to do is to export this new folder path to the PATH environment variable. There are a few ways of doing this.

Use the export command
Source another script file into your script
Automatically configure bash/zsh to source the export command

Using the export command

The export command temporarily adds a value to the PATH environment variable. We could do this at the start of the script. Let us look at this as an example.

Create a script, message.bash and save it in the /Users/Shared/Scripts/.

#!/bin/bash

echo "$(date) This is a random script $RANDOM"

Create another script called test.bash and save it where ever you want.

#!/bin/bash

export DEVELOPER_PATH=/Users/Shared/Scripts/
export PATH=$DEVELOPER_PATH:$PATH

bash welcome.bash

which welcome.bash

Run the script with the command: bash test.bash. Don’t forget to put the path when using the script.

The 2 export commands are setting the value of the PATH environment variable to the new path. Note that while doing that we still keep the existing PATH value. So the environment will contain all the existing PATHS as well as the new path.

We can immediately see the benefit of adding another folder to our PATH component. The commands on line 6 and 8 do not require the path to the welcome.bash script to be explicitly mentioned. Even though they are not in the standard search paths. In fact, any script/executable that is placed in that folder will now be directly accessible without having to specify the absolute path. Having said that it is still a good idea to put the absolute path to a command.

An important thing to keep in mind is that this change only applies to the script that we are running. This will not impact other shells or other scripts running in the same shell. The next 2 options will show us how we could possibly do that.

Source the export commands from another script

If the export commands are needed in more than one script then it might be a good idea to source them instead of rewriting them over and over again.

Start off by creating a new file called newPath.bash. It should only have the 2 export commands in them.

#!/bin/bash

export DEVELOPER_PATH=/Users/Shared/Scripts/
export PATH=$DEVELOPER_PATH:$PATH

Now we will modify our test.bash script from the previous example as shown below.

#!/bin/bash
#Using source

source /Users/Shared/newPath.bash

bash welcome.bash

which welcome.bash

You can see that we simply source the original script in here. This is extremely useful if there are multiple paths that need to be added to multiple scripts. Any change in the path only has to be made in one place making this approach far more convenient and scalable. There is still the same catch. Any change to the path is only applicable to the scope of the script. Other scripts and the shell environment itself does not get affected.

Configure bash/zsh to source our export commands.

While the pervious 2 approaches are good, they have the limitation that the changes are only applicable to the script where the sourcing is done. All the other scripts and the shell itself are not affected by it. Now this maybe a desired outcome. There are situations where you would want this to be applicable globally to all the scripts and the shell itself without having to change the PATH value manually by ourselves. This can be done by changing the scripts that are invoked when the shell is loaded.

The file that is to be invoked is located in the /etc folder. It is called zshrc. If you want to make a change to bash shell then you need to modify bashrc. Copy this file to your desktop. Change it as shown below.

# System-wide profile for interactive zsh(1) shells.

# Setup user specific overrides for this in ~/.zshrc. See zshbuiltins(1)
# and zshoptions(1) for more details.

# Correctly display UTF-8 with combining characters.
if [[ "$(locale LC_CTYPE)" == "UTF-8" ]]; then
    setopt COMBINING_CHARS
fi

# Disable the log builtin, so we don't conflict with /usr/bin/log
disable log

# Save command history
HISTFILE=${ZDOTDIR:-$HOME}/.zsh_history
HISTSIZE=2000
SAVEHIST=1000

# Beep on error
setopt BEEP

# Use keycodes (generated via zkbd) if present, otherwise fallback on
# values from terminfo
if [[ -r ${ZDOTDIR:-$HOME}/.zkbd/${TERM}-${VENDOR} ]] ; then
    source ${ZDOTDIR:-$HOME}/.zkbd/${TERM}-${VENDOR}
else
    typeset -g -A key

    [[ -n "$terminfo[kf1]" ]] && key[F1]=$terminfo[kf1]
    [[ -n "$terminfo[kf2]" ]] && key[F2]=$terminfo[kf2]
    [[ -n "$terminfo[kf3]" ]] && key[F3]=$terminfo[kf3]
    [[ -n "$terminfo[kf4]" ]] && key[F4]=$terminfo[kf4]
    [[ -n "$terminfo[kf5]" ]] && key[F5]=$terminfo[kf5]
    [[ -n "$terminfo[kf6]" ]] && key[F6]=$terminfo[kf6]
    [[ -n "$terminfo[kf7]" ]] && key[F7]=$terminfo[kf7]
    [[ -n "$terminfo[kf8]" ]] && key[F8]=$terminfo[kf8]
    [[ -n "$terminfo[kf9]" ]] && key[F9]=$terminfo[kf9]
    [[ -n "$terminfo[kf10]" ]] && key[F10]=$terminfo[kf10]
    [[ -n "$terminfo[kf11]" ]] && key[F11]=$terminfo[kf11]
    [[ -n "$terminfo[kf12]" ]] && key[F12]=$terminfo[kf12]
    [[ -n "$terminfo[kf13]" ]] && key[F13]=$terminfo[kf13]
    [[ -n "$terminfo[kf14]" ]] && key[F14]=$terminfo[kf14]
    [[ -n "$terminfo[kf15]" ]] && key[F15]=$terminfo[kf15]
    [[ -n "$terminfo[kf16]" ]] && key[F16]=$terminfo[kf16]
    [[ -n "$terminfo[kf17]" ]] && key[F17]=$terminfo[kf17]
    [[ -n "$terminfo[kf18]" ]] && key[F18]=$terminfo[kf18]
    [[ -n "$terminfo[kf19]" ]] && key[F19]=$terminfo[kf19]
    [[ -n "$terminfo[kf20]" ]] && key[F20]=$terminfo[kf20]
    [[ -n "$terminfo[kbs]" ]] && key[Backspace]=$terminfo[kbs]
    [[ -n "$terminfo[kich1]" ]] && key[Insert]=$terminfo[kich1]
    [[ -n "$terminfo[kdch1]" ]] && key[Delete]=$terminfo[kdch1]
    [[ -n "$terminfo[khome]" ]] && key[Home]=$terminfo[khome]
    [[ -n "$terminfo[kend]" ]] && key[End]=$terminfo[kend]
    [[ -n "$terminfo[kpp]" ]] && key[PageUp]=$terminfo[kpp]
    [[ -n "$terminfo[knp]" ]] && key[PageDown]=$terminfo[knp]
    [[ -n "$terminfo[kcuu1]" ]] && key[Up]=$terminfo[kcuu1]
    [[ -n "$terminfo[kcub1]" ]] && key[Left]=$terminfo[kcub1]
    [[ -n "$terminfo[kcud1]" ]] && key[Down]=$terminfo[kcud1]
    [[ -n "$terminfo[kcuf1]" ]] && key[Right]=$terminfo[kcuf1]
fi

# Default key bindings
[[ -n ${key[Delete]} ]] && bindkey "${key[Delete]}" delete-char
[[ -n ${key[Home]} ]] && bindkey "${key[Home]}" beginning-of-line
[[ -n ${key[End]} ]] && bindkey "${key[End]}" end-of-line
[[ -n ${key[Up]} ]] && bindkey "${key[Up]}" up-line-or-search
[[ -n ${key[Down]} ]] && bindkey "${key[Down]}" down-line-or-search

# Default prompt
PS1="%n@%m %1~ %# "

# Useful support for interacting with Terminal.app or other terminal programs
[ -r "/etc/zshrc_$TERM_PROGRAM" ] && . "/etc/zshrc_$TERM_PROGRAM"

if [[ -f /Users/Shared/newPath.bash ]]; then
    source /Users/Shared/newPath.bash
fi

Save this file back to the etc folder. It might be a good idea to take a backup of the original file in case we need to restore it back to undo any errors we might introduce.

Open the terminal app. Run the welcome.bash script without providing the path. See if it works.

Run the command to print the path variable:

printenv PATH

As we can see, there is no need to run the export command repeatedly. There is no need to source the file that contains those commands either.

Standard location or custom path

This approach does give us a lot of flexibility. However, we can see that there are several things we need to do before we can get everything working well. It might be better for us to place our commands in the standard /usr/local folder. That would make the deployment a lot easier.

Man pages

What are man pages?

If you have used the command line interface on macOS/Unix/Linux then you would be familiar with the man command. In case you aren’t then the man command is the command that loads the manual for the binary specified. It is a quick easy way to access the documentation and help for the command. However, man pages aren’t restricted to only binaries. They could be applied on normal files too.

There is one thing to keep in mind. It is not necessary that a man page exists for a given command. Try running the command man folderCreator. What do you get?

No manual entry for folderCreator

We get a message saying that there is no manual entry for our binary. So we need to go ahead and create one.

Before I talk about how to create them I will first address the question of whether we need to create one in the first place. Especially since we are already providing help view the -h -help options. Actually we don’t have to. However, keep in mind that most users are already familiar with the man command and their instinctive reaction is to look for the man page of your command. It would be very nice to offer them that ability.

How do we create them?

In order to create our man page we need to use certain macros that render the document for us. More information can be available via the mandoc, groff, mdoc, and man commands. I would highly recommend going through the man pages of these commands.

man pages are simple files that contain information which is formatted with the help of different macros. A typical man page contains the following sections in the specified sequence:

NAME
SYNOPSIS
DESCRIPTION
VERBS
REQUIREMENTS
INSTALLATION
USAGE
WARNINGS
EXIT STATUS
EXAMPLES
DIAGNOSTICS
COPYRIGHT
CONTACT DETAILS

There are other sections available too: the man page for groff command contains excellent information about that. Armed with the information about which sections are there within the man page we need to start gathering all our details together.

One piece that we need is the manual section.If we run the man command on man:

man man

It gives us some information about the manual sections. The sections describe the kinds of commands and potentially the actions they perform. Our command would fall under the user commands section or section 1.

Where are they located?

These files are located in the /usr/local/share/man/man1 folder. Where man1 represents the section number.

Let us try to create the file. Before that we will look at some macros that we would need.

Macro	Description
`.Dd`	This is used to specify the date when the man page was created/published.
`.Dt`	This is used to specify the title for the man page. Its value should always be in all caps.
`.Os`	The name of the operating system.
`.Sh`	Section header name,
`.Nm`	The name of the command. This is the name that will be used throughout the document.
`.Nd`	The description of the command.
`.Ar`	Arguments being passed to a command
`.Op`	Options being passed to a command
`.Pp`	New paragraph
`.Bl`	Start a list
`.El`	End the list
`.Ev`	For environment variables
`.It`	Italics
`.Ss`	Subsection
`.An`	Name of the author
`.Sy`	Symbolic font mode
`.\"`	Comment

Macros used to create the man page file

You can get more details and information about these macros by running the following command:

man mdoc

We will now use these macros to render our man page. The easiest way to do this would be to use an existing man page file as a template. The idea is to use the macros to do the rendering for us. Copy paste the contents of any existing man page into your file and start replacing the content with your own content. You can always test your page by using the man command directly on your file.

man /path/to/your/manpage/file.1

A good thing to do would be to add 1 item at a time and run the above command repeatedly till you get comfortable with how everything fits together.

If you need help correcting the formatting of the file run the following command:

mandoc -T lint folderCreator.1

This is how the man page file looks. Name it folderCreator.1 where the ‘1’ indicates the section number.

	.\"Copyright (c) 2015-2022 Amaranthine. All Rights Reserved.
	.\"
	.\"
	.Dd August 10, 2021
	.Dt FOLDERCREATOR 1
	.Os macOS 11
	.Sh NAME
	.Nm folderCreator
	.Nd Folder creation utility
	.\"
	.\" ============================================================================
	.\" ========================== BEGIN SYNOPSIS SECTION ==========================
	.Sh SYNOPSIS
	.Nm
	.Ar "folder names"
	.Op verbs
	.\" =========================== END SYNOPSIS SECTION ===========================
	.\" ============================================================================
	.\"
	.\" ============================================================================
	.\" ======================== BEGIN DESCRIPTION SECTION =========================
	.Sh DESCRIPTION
	.Nm
	creates 3 folders in the home folder.
	In case the folder names are not provided then the command
	will create folders with default names "Tools", "Reports", "Help".
	.Pp
	The user is also prompted via the graphical user interface for names that should be used for the folders.
	This is optional and the user can cancel it.
	.Pp
	There is also the option of getting help via the help verb.
	.Pp
	- This script is intended for creating the custom folders that are required on all corporate computers.
	.Pp
	- Run this script on a new computer or a computer being reassigned to another employee.
	.Pp
	- This script can run on all computers.
	.\" ----------------------------------------------------------------------------
	.\" ------------------------- BEGIN TERMINOLOGY LIST ---------------------------
	.Sh VERBS
	.Bl -hang
	.It Op Fl h help
	Both the options are used to invoke the help documentation.
	.It Op Fl v version
	Both the options are used to get the version number of the
	.Nm
	command.
	.El
	.\" --------------------------- END TERMINOLOGY LIST ---------------------------
	.\" ----------------------------------------------------------------------------
	.\" ============================================================================
	.\" ======================== BEGIN REQUIREMENTS SECTION ========================
	.Sh REQUIREMENTS
	The following are the minimum requirements to get the script running.
	.Bl -hang -offset 4n -width "xxxxxxxxxxxx" -compact
	.It Shell:
	zsh
	.It OS:
	macOS Big Sur 11.4 or later
	.It Dependencies:
	None
	.El
	.Ev HOME
	.\" ============================================================================
	.\" ======================== BEGIN INSTALLATION SECTION ========================
	.Sh INSTALLATION
	.Nm
	can be installed anywhere you wish.
	However, there are certain locations that are recommended.
	.Bl -hang -offset 4n -width "xxxxxxxxxxxx" -compact
	.It Location:
	/Library/Scripts/
	.It Permissions:
	rwx r-x r-x
	.El
	.\" ============================================================================
	.\" ======================== BEGIN USAGE SECTION ========================
	.Sh USAGE
	.Nm
	.Ar folder1
	.Ar folder2
	.Ar folder3
	.Pp
	Will create folders with your own names.
	.Pp
	.Nm
	.Ar -h
	OR
	.Nm
	.Ar -help
	.Pp
	Will invoke the help utility.
	.Pp
	.Nm
	.Ar -v
	OR
	.Nm
	.Ar -version
	.Pp
	Will print the version number in stdout.
	.Ss GUI Interaction
	In all cases the user is always prompted for entering folder names via the graphical user interface.
	Therefore this script triggers a gui popup.
	In case this is not the desired behavior then the appropriate lines of code will need to be commented out.
	.\" ============================================================================
	.\" ======================== BEGIN WARNING/CAUTION SECTION ========================
	.Sh WARNING/CAUTION
	.Nm
	does not perform any validation of names.
	The only options that
	.Nm
	accepts are
	.Ar -h
	and
	.Ar -help
	verbs or the
	.Ar -v
	and
	.Ar -version
	verbs.
	If the script does not see the
	.Ar -h
	,
	.Ar -help
	or the
	.Ar -v
	,
	.Ar -version
	options then it will assume that the data being passed in is the name of the folder.
	The user of the
	.Nm
	command must ensure that the desired folder names are passed in.
	The user will also be prompted, via the graphical user interface, if he/she wishes to provide the names for the folders.
	If yes, then there will be subsequent
	prompts asking for the folder names.
	.\" ============================================================================
	.\" ======================== BEGIN EXIT STATUS SECTION =========================
	.Sh EXIT STATUS
	In most situations,
	.Nm
	exits 0 on success
	.\" ============================================================================
	.\" ======================== BEGIN EXAMPLES SECTION ========================
	.Sh EXAMPLES
	.Nm
	.Ar Resources
	.Ar Results
	.Ar Assistant
	.Pp
	This will create 3 folders
	.Sy Resources
	,
	.Sy Results
	,
	.Sy Assistant
	,
	in the user's home folder.
	.Pp
	.Nm
	.Pp
	This will create 3 folders with the default names
	.Pp
	.Nm
	.Ar Apps
	.Pp
	This will use the
	.Sy Apps
	name for the first folder but the default names for the last 2 folders.
	.\" ============================================================================
	.\" ======================== BEGIN DIAGNOSTICS SECTION ========================
	.Sh DIAGNOSTICS
	The script produces a log file called
	.Sy ~/Library/Logs/folderCreator_log_v1-x.log
	.Pp
	This file is typically located in the user's home folder log folder.
	The x represents the version number of
	.Nm
	.Pp
	You can view the logs for each respective version.
	.\" ============================================================================
	.\" ======================== BEGIN COPYRIGHT SECTION ========================
	.Sh COPYRIGHT
	Copyright (c) Amaranthine 2015-2021.
	All rights reserved.
	https://amaranthine.in
	.\" ============================================================================
	.\" ======================== BEGIN CONTACT SECTION ========================
	.Sh CONTACT DETAILS
	.An Author: Arun Patwardhan
	.Pp
	Website: https://amaranthine.in
	.Pp
	Email: arun@amaranthine.co.in

view raw folderCreator.1 hosted with ❤ by GitHub

Place the man page in the following folder.

/usr/local/share/man/man1/folderCreator.1

This is how it would look if we run the man command on our folderCreator script.

This is how it would look like if we opened it in the Preview application.

FolderCreator-ManPage

Video

Download

You can download the final script from here.

You can download the man page file from here.

Summary

Our script has evolved quite a bit from the first blog. We started off with a very simple script and have ended with a larger script. It still does the same thing it did originally but is now a lot better. Here are some of the key points:

Writing event updates to log files
User interaction
Flexibility in terms of folder names via user interaction from the GUI as well as the command line arguments
Easy to maintain thanks to functions
Arrays make it scalable
Loops help make the script compact
Variables enhance scalability
Periodic checks ensure the script is safe and stable
User can get help using
- the -h or the -help options
- From the comments in the script
- by viewing the man page for the script

Of course, there is room for improvement. Some of you might come up with ways of achieving this solution differently. Which is perfectly fine. There is no such thing as a universally perfect script. The point behind the script above was to illustrate how the different features could work together.

Final thoughts

Scripting is a continuous learning process. There are so many things in it. Over time you will find that you are faced with similar challenges. One thing that a lot of script writers and programmers do is to refer to perviously written scripts to get a head start. Every time you write a script it would be a good idea to archive it and keep a copy elsewhere. This will come in handy.

Happy scripting!

Shell scripting in macOS – Part 9: Automating scripts

January 25, 2023January 27, 2023 / Arun Patwardhan / 1 Comment

This article is NOT a continuation of the previous article. The topics covered in this article won’t be used in our folder creation script as the features covered are not required or can’t be appropriately used. We will use a different script instead. This article is a continuation of the Shell scripting series though.

Why automate?

Most of the times we or someone else will be running the desired script. However there is one major drawback with this. It assumes that there is ‘someone’ who can run the script and they have access to the computer that the script is supposed to run on. This is not always a given.

The above approach also has the problem of efficiency. If the script is to be run periodically or at regular intervals it can get very inefficient and is likely to affect the workflows of the organisation.

Automation solves these problems for us by allowing scripts to run by themselves.

How to automate?

There are 2 options that we will look at in this article:

Expect utility
Launch Daemons/Launch Agents

Expect utility

The expect utility isn’t strictly an automation solution. It’s a tool that can answer stdout prompts from another script/program/application. Let us see how it works with an example.

The script below is asking a series of questions from the user and is expecting a response. The response is stored in a variable which is echo’d out. To make it interesting the last question is a choice based questions. Based on some random value the script will ask question ‘a’ or question ‘b’.

#!/bin/zsh

# Questions
# --------------------------------------------------
echo "1) What is your name?"
read -s NAME
echo $NAME 

echo "2) What is your email address?"
read -s EMAIL
echo $EMAIL 

echo "3) Could you tell me your company's website address?"
read -s WEBSITE
echo $WEBSITE 

echo "4) Please provide your mobile number?"
read -s MOBILE
echo $MOBILE 

# Choice
# --------------------------------------------------
if [[ $RANDOM -gt 90000 ]]; then
	echo "Do you like option A?"
else 
	echo "Would you prefer option B?"
fi

read -s OPTION
echo $OPTION

Now if we just run the above script we would see prompts on stdout for the different questions and simply answer them. But what if this script is going to be called by another script? That is where the expect utility comes in. Let us have a look at out script and then analyse it

#!/bin/zsh
#!/usr/bin/expect 

#Variables
ANS1="Arun"
ANS2="arun@amaranthine.co.in"
ARG1=$1

export ANS1
export ANS2
export ARG1 

/usr/bin/expect << "EOF"
set myValue1 $env(ANS1);
set myValue2 $env(ANS2);
set arg1 $env(ARG1);

spawn /Users/arunpatwardhan/Developer/questions.zsh
expect "1) What is your name?\r" 
send -- "$myValue1\r"

expect "2) What is your email address?"
send -- "$myValue2\r"

expect "3) Could you tell me your company website address?"
send -- "www.amaranthine.in\r"

expect "4) Please provide your mobile number?"
send -- "$arg1\r"

expect {
	"Do you like option A?" { send -- "Of course!\r" }
	"Would you prefer option B?" { send -- "Definitely!\r" }
}

expect eof
EOF

Let us analyse this file line by line.

The first line is our interpreter declaration. The second line is where we specify which expect we will be using.

#!/bin/zsh
#!/usr/bin/expect

Next we declare some variables. We will use them in our expect utility soon.

#Variables
ANS1="Arun"
ANS2="arun@amaranthine.co.in"
ARG1=$1

In order to use them in our utility we need to export these variables. We will then access them via the environment.

export ANS1
export ANS2
export ARG1

This is where we start writing our expect command. Notice that we are using the ‘here’ document that we learnt in the previous script. This allows use to send multiple expect commands to the expect utility.

/usr/bin/expect << "EOF"

The first thing that we do is create variables for the expect utility from the variables that we already have.

set myValue1 $env(ANS1);
set myValue2 $env(ANS2);
set arg1 $env(ARG1);

Then we use the spawn command to start the script whose questions we wish to answer.

spawn /Users/arunpatwardhan/Developer/questions.zsh

Next we tell the expect utility to ‘expect’ a question. We specify the question to expect in the string after the expect command.

expect "1) What is your name?\r"

Once the expectation has been met, we send out our response to the question using the send command.

send -- "$myValue1\r"

We can answer the rest of the questions the same way. We can use variables to pass in data or directly write our answers in there.

In case of a choice we write an expect block command with the help of braces.

expect {
	"Do you like option A?" { send -- "Of course!\r" }
	"Would you prefer option B?" { send -- "Definitely!\r" }
}

Finally we end with an eof being passed to expect.

expect eof

The last EOF is for the ‘here’ document.

EOF

That’s it! It’s that simple to write expect scripts. Note that there are more commands available for the expect utility. I would strongly recommend going through the man page for details about expect.

man expect

There is also a utility called autoexpect that builds the expect script for you. As of this article (tested on macOS 12.6) it is not installed by default.

One last thing I would like to mention. The expect utility should ideally be used in a larger script which is invoking other scripts. It is not meant to replace human interaction. Use caution when invoking scripts/binaries/tools that you cannot read as you are not fully aware of everything that is done by these scripts.

Launch Daemons/Launch Agents

The other and option is to use launch daemons/launch agents. I will be referring to them as daemons through the rest of this article unless something specific has to be mentioned.

Daemons solve a different problem as compared to the expect utility.

The expect utility allows for a script/binary/tool/program to complete execution by answering questions expected from a human.

Daemons on the other hand allow us to schedule and automatically run scripts and custom intervals. These are background processes that are started on specific events. Daemons and agents are exactly the same, but they have some key differences:

Launch Daemons	Launch Agents
These are owned by the system	These are owned by the currently logged in user
Start as soon as the system boots up	Starts only after the user logs in. Stops as soon as the user logs out
Is system wide	Can apply to all user accounts or to a specific user account

These are some of the points that you have to keep in mind while deciding whether to create a daemon or an agent. The process for creating them is exactly the same. It is plist file that provides all the information that is necessary for the system to schedule and run the processes.

I will be talking about launch daemons and agents as well as plist files in separate articles at a later point in time.

Example

Let us look at how to create a daemon with the help of an example.

We would like to show an informational popup that appears as soon as the user logs in and at 5 minutes interval. We would also like to show a notification of the same.

Now this could also be achieved using other approaches but it gives us an opportunity to explore how to create agents. Also the scheduling is chosen so that we can see how it is done. It is not strictly required for this situation.

So why have we decided to create it as an agent?

The main reason is because it is to run only after the user logs in. Something that a Launch Agent is perfectly suited for.

We also want this to run for every user account on the computer. So this will need to be installed in the /Library folder. Specifically:

/Library/LaunchAgents/

Now that we have decided how and where let us focus first on the script that we plan to run.

#!/bin/zsh

/usr/bin/osascript << EOF 
display notification "By using this computer you agree to terms and conditions of use set down by the company." \
					  with title "Terms & Conditions" \
					  subtitle "Acknowledge" \
					  sound name "Alert"

set theAlertText to "Terms and conditions of use"
set theAlertMessage to "By using this computer you agree to terms and conditions of use set down by the company."
display alert theAlertText \
	    message theAlertMessage \
		as informational \
		buttons {"Accept"} default button "Accept"
EOF

The script simply uses the osascript command to run a few AppleScript commands. These commands show a notification as well as an alert message to the user. Let us place this script in the /Library/Scripts/ folder. This will make it easily accessible.

Next we will focus on creating the launch agent plist. Let us first list out the items we will need to put in the plist.

Key	Description
Label	This is the name of our Launch Agent
ProgramArguments	This is the action to be performed. In our case the action is to invoke the script.
StartInterval	This is the time interval after which the program arguments must be executed.
RunAtLoad	This is a flag that indicates that the agent must be run as soon as it is loaded.

Armed with this information we will go ahead and create our plist. There are several tools available for this:

Xcode
TextEdit
defaults command
Third party tools like CodeRunner

We will use the defaults command for this. It is a built in command that allows us to work with plist files. Here is a little script that creates our plist.

#!/bin/zsh

defaults write ~/Desktop/in.amaranthine.welcomeMessage.plist Label -string "in.amaranthine.welcomeMessage"
defaults write ~/Desktop/in.amaranthine.welcomeMessage.plist ProgramArguments -array-add "/bin/zsh" "/Library/Scripts/welcome.zsh"
defaults write ~/Desktop/in.amaranthine.welcomeMessage.plist RunAtLoad -boolean true
defaults write ~/Desktop/in.amaranthine.welcomeMessage.plist StartInterval -integer 300

In the script, the defaults command is writing several key value pairs into a plist file at the specified path. Notice the key names: Label, ProgramArguments, RunAtLoad, StartInterval. These are the values we need to specify. The above commands need not be written in a specific sequence as they are being written to an XML file.

The resulting plist file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>in.amaranthine.welcomeMessage</string>
	<key>ProgramArguments</key>
	<array>
		<string>/bin/zsh</string>
		<string>/Library/Scripts/welcome.zsh</string>
	</array>
	<key>RunAtLoad</key>
	<true/>
	<key>StartInterval</key>
	<integer>300</integer>
</dict>
</plist>

Lets explore the different parts of this plist file. It contains a dictionary with several key value pairs.

<key>Label</key>
<string>in.amaranthine.welcomeMessage</string>

The first key value pair we encounter is ‘Label’. This is the name of our agent.

<key>ProgramArguments</key>
<array>
	<string>/bin/zsh</string>
	<string>/Library/Scripts/welcome.zsh</string>
</array>

The next key value pair is extremely important. It is telling our agent the task that needs to be performed. In this case use the zsh shell to run the welcome.zsh script. This is the same as running the following command in terminal:

/bin/zsh /Library/Scripts/welcome.zsh

<key>RunAtLoad</key>
<true/>

The second key value pair indicates that the agent must run as soon as it is loaded and not only when the user logs in. This is not strictly required but is very handy when we try to test our agent.

<key>StartInterval</key>
<integer>300</integer>

The last key value pair will schedule the agent to run at an interval of 5 minutes or 300 seconds.

You can check if the plist if properly formatted using the command:

plutil -lint /path/to/plist

Also, if you try to open the plist file in an editor it is likely that the formatting may not appear correctly. Run the following command to make it readable:

plutil -convert xml1 /path/to/plist

This does not affect the plist file in any way. So it is safe to perform.

The next bit is to place the file in correct location. Copy the plist file to the path:

/Library/LaunchAgents/

Next we will look at loading the agent

While the agent will be loaded automatically every time the user logs in. However, we would like to test the results immediately. We will use the launchctl command to load the agent.

launchctl bootstrap gui/501 /Library/LaunchAgents/in.amaranthine.welcomeMessage.plist

Let us explore the launchctl command.

The bootstrap option informs the system that an agent is being loaded.

The next bit tells launchctl that its for gui user 501. We can get the user number using the command id -u.

This is followed by the path to the plist file.

Run this command.

To find out if the launch agent has loaded correctly we will use the list option on launchctl to list out all the current agents.

launchctl list

To get more specific results:

launchctl list | grep "in.ama"

This will show a list of agents whose name starts with “in.ama”.

And that’s it. We have now scheduled the agent. If you have run the command to bootstrap the agent then you should see the popup appearing on the screen.

You should also see the notification:

If you wish to stop the agent run:

launchctl bootout gui/501 /Library/LaunchAgents/in.amaranthine.welcomeMessage.plist

It’s the same command as before. Except with the bootout option instead of the bootstrap.

NOTE: The agent will start running again the next time the user logs in.

Summary

As you can see there are several options available when it comes to automating scripts. This opens up more possibilities when it comes to performing management tasks on the device.

Video

Download

You can download the scripts from here:

Shell scripting in macOS – Part 8: Arrays & Dictionaries

January 25, 2023January 27, 2023 / Arun Patwardhan / 2 Comments

This article is a continuation of the previous article. We will be taking the previous script and using it to build on the concepts we will learning in this article.

So far we have been working with a single piece of data. This was stored in a single variable. For each new piece of information we created a new variable. However, we often come across situations where there is more than one value for a given item. This is where collections like arrays and dictionaries come in.

Arrays

An array is a sequential collection of data. It allows us to store more than one value in a variable. This is good for situations like the contents of a folder, list of users, list of applications. Creating, reading, modifying, and iterating over an array is very easy. Let us have a look.

Creating

To create an array simply declare a variable followed by the '=' operator followed by values within round brackets.

# Declaring an array of items 
items=("ABC" "DEF" "GHI" "JKL" "MNO" "PQR")

Note that if you assign another set of values to the items variable it will replace the original values. We will see how to add values to an existing array a little later in the article.

Reading

We need to use the ${ } to read an array. This expands the array and allows us to read different values. There are different operations possible. I have listed some of those in the code snipper below.

# Getting a specific element from the array
echo "\${items[0]} 		= ${items[0]}"

# Getting all the elements of the array
echo "\${items[@]} 		= ${items[@]}"

# Getting the count of the elements in the array
echo "\${#items[@]} 	= ${#items[@]}"

# Getting a range of values
echo "\${items[@]:3:2} 	= ${items[@]:3:2}"

Modifying

To modify we simply need to use the '+' operator before the equals. This will add the value to the existing array without disturbing the other values.

# Pushing a value into the array
items+=("STU")

# Remove a specific item
unset items[2]

A small point to note. The unset is available with /bin/sh interpreter.

Iterating

for entry in "${items[@]}"
do 
	echo "-> $entry"
done

Here is a nice example of the user of arrays. The output of the list command is stored as an array in the variable named ‘directories’. Then using the for loop we can step through each folder and in turn printing its contents out.

directories=($(ls $HOME))

for folder in "${directories[@]}"
do 
	echo $folder
	eval "ls -l $HOME/$folder"
done

Dictionaries

Dictionaries are also collections just like arrays. However, there is one major difference. While arrays are indexed using integers, dictionaries are indexed using strings.

There is one small thing to note about dictionaries. They only work with bash version 4.0 or later. So if you face issues, make sure you are running bash 4.0 or later. In my example I am using zsh version 5.8.1. To find out which version you are running simply run the following command in terminal:

bash --version

zsh --version

Let us look at how to create and use dictionaries.

Creating

Creating a dictionary is very easy. We simply declare an associative array and give the dictionary variable a name.

declare -A contactDetails

Modifying

Editing or adding values to a dictionary is easy too. We use the variable name followed by the '[]' index brackets with the key value inside the brackets. This is followed by the '=' operator and the value to be assigned for that key after that.

contactDetails[name]="Arun"
contactDetails[email]="arun@amaranthine.co.in"
contactDetails[website]="www.amaranthine.in"
contactDetails[blog]="www.arunpatwardhan.com"
contactDetails[phone]="+91-9821000000"
contactDetails[dob]="$(date)"

Reading

We use the ‘@{ }’ operator to expand and read values from the dictionary, just as we did with an array. The only additional detail here is that we are using the key in order to get the specific value.

# Getting the value for a specific key
echo ${contactDetails[name]}

# Getting all the values
echo ${contactDetails[@]}

# Getting all the keys
echo ${(k)contactDetails[@]}

# Getting all the values
echo ${(v)contactDetails[@]}

# Getting all the keys and values
echo ${(kv)contactDetails[@]}

# Getting number of entries
echo ${#contactDetails[@]}

Iterating

There are several different ways of iterating over a dictionary. In the example below, the for loop is iterating over all the keys from the dictionary. Inside the loop we are using each key to extract the corresponding value.

for item in "${(k)contactDetails[@]}"
do 
	printf "%-10s \t%-40s" $item ${contactDetails[$item]}
	echo " "
done

Script

Let us update out script to use arrays.

#!/bin/zsh

#LICENSE/TERMS AND CONDITIONS --------------------------------------------------------------------
#MIT License

#ABOUT -------------------------------------------------------------------------------------------
# fileCreator.zsh
# 1.7
#-------------------------------------------------------------------------------------------------

#HELP/SUPPORT ------------------------------------------------------------------------------------
# You can get help by running the following commands.
# ./folderCreator.zsh -h
# ./folderCreator.zsh -help
# OR
# man folderCreator.zsh
# You can also view the log file for the same at: ~/Library/Logs/folderCreator_log_v1-7.log
#-------------------------------------------------------------------------------------------------

#HISTORY -----------------------------------------------------------------------------------------
# ------------------------------------------------------------------------------------------------
# Version 1.0: Basic script which creates the folders
# Version 1.1: Gives user the ability to specify the folder names at run time.
# Version 1.2: Adds safety checks to the scripts
# Version 1.3: Includes documentation as well as ability to get help.
# Version 1.4: Includes optimisation using for loop
# Version 1.5: Prompts the user in the GUI for names for the different folders.
# Version 1.6: Updated the log mechanism with the help of a function and here document.
# Version 1.7: Replaced the folder variables with an array
#-------------------------------------------------------------------------------------------------

#These are the default values used for the folder names incase the user doesn't provide any.
FOLDERS=("Tools" "Reports" "Help")

#Script version number
VERSION_NUMBER="1.7"

#Command name
COMMAND_NAME="folderCreator.zsh"

NAME
----
$COMMAND_NAME — Folder creation utility SYNOPSIS
$COMMAND_NAME folder names [ verbs ]

VERBS
-----
[ −h −help] Both the options are used to invoke the help documentation.
[ −v −version] Both the options are used to get the version number of the folderCreator command.

REQUIREMENTS
------------
The following are the minimum requirements to get the script running.
Shell:\t\t zsh
OS:\t\t macOS Big Sur 11.4 or later
Dependencies:\t None

INSTALLATION
------------
$COMMAND_NAME can be installed anywhere you wish. However, there are certain locations that are recommended.
Location:\t /Library/Scripts/
Permissions: \t rwxr-xr-x

USAGE
-----
$COMMAND_NAME folder1 folder2 folder3
Will create folders with your own names.

$COMMAND_NAME -h OR $COMMAND_NAME -help
Will invoke the help utility.

$COMMAND_NAME -v OR $COMMAND_NAME -version
will print the version number in stdout.

EXAMPLES
--------
$COMMAND_NAME Resources Results Assistant
This will create 3 folders Resources , Results , Assistant , in the user’s home folder.

$COMMAND_NAME
This will create 3 folders with the default names

$COMMAND_NAME Apps
This will use the Apps name for the first folder but the default names for the last 2 folders.

EXIT STATUS
-----------
In most situations, $COMMAND_NAME exits 0 on success"
exit 0
fi

PATH_TO_LOG="$HOME/Library/Logs/folderCreator_log_v1-7.log"

# Function to log activity
function recordActivity() {
cat << EOF >> $PATH_TO_LOG
[$(date)] $1
EOF
}

echo "$(date) Running script $0 to create folders."
echo ""

TODAY=$(date)

recordActivity "Starting"

#2. Check to see if the version number is
if [[ $1 == "-version" ]] || [[ $1 == "-v" ]]; then
echo "Version: $VERSION_NUMBER"
exit 0
fi

if [[ $2 != "" ]]; then
FOLDERS[1]=$2
fi

if [[ $3 != "" ]]; then
FOLDERS[2]=$3
fi

recordActivity "User provided: ${FOLDER[@]}"
else
recordActivity "User decided to use default values: ${FOLDER[@]}"
fi

#5. Go to the home folder.
cd $HOME

#6. Check to see if each of the folders exists. If it exists then do not create it. Else create the folder.
recordActivity "Creating folders: ${FOLDER[@]}"

for item in ${FOLDER[@]}; do
if [[ -d $item ]]; then
recordActivity "Not creating $item as it already exists."
else
recordActivity "Creating $item"
mkdir $item
fi

#7. Create the task completion file inside each folder.
recordActivity "Creating hidden file for $item folder."
cd $item
#8. Generate the file names based on the folder names.
touch ".$item-FolderCreated"
cd ..
done

echo "$(date) Task completed. Have a nice day!"

Summary

Both arrays and dictionaries now allow us to store collections of data in a single variable. This enables us to write compact scripts and deal with complex data.

Download

You can download the completed script from here.

List of macOS Terminal commands

July 29, 2020 / Arun Patwardhan / Leave a comment

This article lists out different macOS terminal commands you might encounter. You can use this list as a starting point in your search for a command to perform a specific task. This list is by no means exhaustive.

Basic terminal commands are not listed here. Some of them are listed in the following Terminal command articles.
Terminal Commands – Basic
Terminal Commands – Part 2
Terminal Commands – Part 3

Many of the commands have also been used in the article I wrote some time back. You can have a look at the scripts to see some of the commands being used.

To get more information about the commands simply run the following command from within Terminal Application. For example, to view the manual page for tmutil simply type:

man tmutil

For fdesetup

man fdesetup

Here is a nice command to quickly open the man page in the Preview App.

man -t tmutil | open -f -a /System/Applications/Preview.app

Note

This is not a complete list of commands
Some commands are available through the macOS Recovery Volume only
Some commands required other resources such as the OS installer
Some commands are available with certain versions of the OS only

Please read the documentation for more details. Use the commands with care. Improper use of commands may result in loss of data or damage to the computer.

Commands

Installation

Command	Description
startosinstall	Used to start the installation of macOS from the command line.
createinstallmedia	Used to create an external install disk.

Security

Command	Description
fdesetup	Manage FileVault configuration.
security	Manage keychain and security settings
spctl	Manage security assessment policy
csrutil	Configure System Integrity Protection (SIP) settings
resetpassword	Password reset utility located in the Recovery Partition

File System

Command	Description
hdiutil	Used to manipulate and manage disk images.
diskutil	Used to modify, verify, & repair local disks.

Data Management

Command	Description
tmutil	Used to configure Time Machine settings in macOS
screencapture	Takes screenshot of the specified screen and saves the image at the specified location.
mdls	Used to get metadata attributes for a given file
mdutil	Used to manage metadata stores that are used by Spotlight

Settings

Command	Description
defaults	Used to modify plist files. Typically used to update preference files.
ioreg	Used to view the I/O kit registry
system_profiler	Used to generate system hardware & software reports.
plutil	Used to check syntax of property lists or covert property lists from one format to another
AssetCacheManagerUtil	Used to configure content caching settings.
open	Used to open documents from within the command line.
networksetup	Perform network configuration.
systemsetup	Used to configure machine settings in System Preferences.
launchctl	Used to manage and inspect daemons, agents, & XPC Services

Applications

Command	Description
codesign	Used to create, check, display code signatures.
pkgbuild	Used to build installer packages
productbuild	Builds a product archive
installer	System software and package installer tool

User Account Management

Command	Description
dscl	This is a command line Directory service utility that allows us to create, read, and manage Directory Service data.
sysadminctl	User account management
passwd	Change user password
login	Used to login to another user account.

Server & Device Management

Command	Description
profiles	Used to install, remove, list, or manage Configuration profiles.
serveradmin	Used to manage the services in macOS
mdmclient	Located in /usr/libexec/mdmclient it is used to manage interactions with the MDM.
asr	Apple Software restore: Used to copy volumes.

Scripting

Command	Description
osascript	Used to execute the given AppleScript

Share any commands you may know of in the comments window.

Disclaimer

The information Is Provided “As Is”, Without Warranty Of Any Kind, Express Or Implied, Including But Not Limited To The Warranties Of Merchantability, Fitness For A Particular Purpose And Noninfringement. In No Event Shall The Authors Or Copyright Holders Be Liable For Any Claim, Damages Or Other Liability, Whether In An Action Of Contract, Tort Or Otherwise, Arising From, Out Of Or In Connection With The information provided Or The Use Or Other Dealings In The information.

Useful scripts for macOS

March 27, 2020March 27, 2020 / Arun Patwardhan / 2 Comments

Getting Started

You might find these articles useful

One of the advantages with scripts is the fact that you can easily automate many tasks. Here is an article that walks you through that process.

If you come across a situation where you want to perform a set of tasks on multiple computers then scripts come in very handy.

I will be providing the Shell Script version of the task. Feel free to make changes to the scripts as required. I will try to provide an AppleScript version of the tasks a little later.

This is not the only way to implement the scripts. There may be multiple approaches towards achieving the same result. You will have to explore and examine the correct approach.

This is not a comprehensive list. The scripts should give you some ideas and act as a useful reference when you are creating your own scripts.

I have tested these scripts on macOS Catalina 10.15

Download

You can download all the scripts from here.

Script Category	Page Number
Settings and Accounts	1
Security	2
Data	3
Information Collection	4
File System	5

Disclaimer

The Software Is Provided “As Is”, Without Warranty Of Any Kind, Express Or Implied, Including But Not Limited To The Warranties Of Merchantability, Fitness For A Particular Purpose And Noninfringement. In No Event Shall The Authors Or Copyright Holders Be Liable For Any Claim, Damages Or Other Liability, Whether In An Action Of Contract, Tort Or Otherwise, Arising From, Out Of Or In Connection With The Software Or The Use Or Other Dealings In The Software.

WARNING

Please try these scripts on a test computer. Some of the scripts do make changes to the system. Always test before using these scripts.

Pages: 1 2 3 4 5 6

Creating your own Drag and Drop DMG

January 4, 2019 / Arun Patwardhan / 1 Comment

What are Disk Images?

Disk images are a means of archiving data. They are created using a tool called Disk Utility which is a File System Management Utility of macOS. Disk Images follow the extension ‘.dmg‘ and are only compatible with macOS.

Disk Images are a popular way of distributing applications for macOS. They provide the capability of compressing large files and make delivery over the internet very easy.

In this article we are going to look at how we can create disk images for application distribution.

Creating the DMG Folder for distribution

Create a Background image. This can have any design. It’s a good idea to have arrows or other visual aids to assist others during installation.
Create a new Disk Image. Open Disk Utility.
Click on File > New Image > Blank Image
Leave the default settings as is. Choose the size that you desire.
Mount the Disk Image.
Create a folder called background in the mounted volume.
Save the background image in the folder we just created.
Now we will hide the background folder. Switch to terminal and run the following command.
```
 
cd /Volume/InstallDMG/
mv background .background
```
Here we are simply renaming the background folder with a ‘.’ before it. This hides the folder from the GUI.

Now we will prepare the payload. This can be any file or folder we wish to install. For the sake of this demo I will be choosing Mozilla FireFox. In reality you would be distributing your own application.
Copy the FireFox app into the mounted volume.
Open “Show View Options“.
Restrict the mounted volume to icon view only. Feel free to customise the other settings as you wish. This includes icon size.
Drag and arrange the icons in your mounted window to match the background.
Eject the disk image.
Make a duplicate copy of the image file. This can act as a reference for future images you wish to create.
Now we will convert the disk image into a read only compressed disk image. This will be the one that we will use for distribution. Open Disk Utility.
Click on Images > Convert
Select the InstallerDMG.dmg from Desktop or wherever you had saved it.
Give it a new name and convert it to compressed format.

That’s it. You now have your own drag drop window ready for distribution.

Creating our own commands from other shell scripts

Installing commands

Using commands

Adding path to the environment

Using the export command

Source the export commands from another script

Configure bash/zsh to source our export commands.

Standard location or custom path

Man pages

What are man pages?

How do we create them?

Where are they located?

Video

Download

Summary

Final thoughts

Share this:

Like this:

Why automate?

How to automate?

Expect utility

Launch Daemons/Launch Agents

Example

Summary

Video

Download

Share this:

Like this:

Arrays

Creating

Reading

Modifying

Iterating

Dictionaries

Creating

Modifying

Reading

Iterating

Script

Summary

Download

Share this:

Like this:

Here is a nice command to quickly open the man page in the Preview App.

Note

Commands

Installation

Security

File System

Data Management

Settings

Applications

User Account Management

Server & Device Management

Scripting

Disclaimer

Share this:

Like this:

Getting Started

Download

Disclaimer

WARNING

Share this:

Like this:

What are Disk Images?

Creating the DMG Folder for distribution

Share this:

Like this: