Show Bash script usage

Is it best practice to include usage in every Bash script that you create. This gives the user an idea of what options the script is expecting, so they can use it as intended. It also gives the script some error checking ability to make sure that the user has supplied arguments in the expected way.

In this tutorial, you will learn a couple of different methods to show Bash script usage, check which user is executing the script, and check the current number of arguments on Linux.

In this tutorial you will learn:

• How to show Bash script usage with if and $@
• How to show Bash script usage with getopts
• How to show Bash script usage when an unrecognized option is entered
• How to check correct number of options are passed to Bash script
• How to verify if root user is executing a Bash script

Software Requirements and Linux Command Line Conventions

Category	Requirements, Conventions or Software Version Used
System	Any Linux distro
Software	Bash (installed by default)
Other	Privileged access to your Linux system as root or via the sudo command.
Conventions	# – requires given linux commands to be executed with root privileges either directly as a root user or by use of sudo command $ – requires given linux commands to be executed as a regular non-privileged user

Show Bash script usage

---

---

There are multiple ways to show script usage inside of your Bash script. One way is to check if the user has supplied the -h or --help options as arguments as seen below.

#!/bin/bash 
 
# check whether user had supplied -h or --help . If yes display usage
if [[ ( $@ == "--help") ||  $@ == "-h" ]]
then 
	echo "Usage: $0 [arguments]"
	exit 0
fi 
 
echo "All good !!!"

Now our if statement containing the Bash usage is only triggered when --help OR -h is supplied.

$ ./test.sh
All good !!!

$ ./test.sh --help
Usage: ./test.sh [arguments]

The next way you can provide this functionality is with getopts. The following example will do the same thing as our previous script, but has the added advantage of showing usage whenever the user supplies an invalid option.

#!/bin/bash

while getopts 'lh' OPTION; do
  case "$OPTION" in
    l)
      echo "linuxconfig"
      ;;
    h)
      echo "script usage: $(basename \$0) [-l] [-h]" >&2
	  exit 0
      ;;
    ?)
      echo "script usage: $(basename \$0) [-l] [-h]" >&2
      exit 1
      ;;
  esac
done

The script above can accept the -l option. If the -h option is supplied instead, then the Bash script usage is shown. If some other option is passed to the script, and the script does not recognize it, the Bash usage will be shown in that circumstance as well.

$ ./test.sh -l
linuxconfig

$ ./test.sh -h
script usage: $0 [-l] [-h]

$ ./test.sh -s
./test.sh: illegal option -- s
script usage: $0 [-l] [-h]

---

---

We have more information about this method in our tutorial on: Bash Script: Flags usage with arguments examples.

Sometimes it is needed to check what user is executing the Bash script and whether the user supplied all required arguments. In that case, a more beefed up script like this one would come in handy, which checks for multiple things:

#!/bin/bash 
 
display_usage() { 
	echo "This script must be run with super-user privileges." 
	echo -e "\nUsage: $0 [arguments] \n" 
	} 
# if less than two arguments supplied, display usage 
	if [  $# -le 1 ] 
	then 
		display_usage
		exit 1
	fi 
 
# check whether user had supplied -h or --help . If yes display usage 
	if [[ ( $@ == "--help") ||  $@ == "-h" ]] 
	then 
		display_usage
		exit 0
	fi 
 
# display usage if the script is not run as root user 
	if [[ "$EUID" -ne 0 ]]; then 
		echo "This script must be run as root!" 
		exit 1
	fi 
 
echo "All good !!!"

You may also be interested in viewing our tutorials on Bash Scripting: Command line arguments and Bash script: Number of arguments passed to the script.

Closing Thoughts

---

---

In this tutorial, you saw how to show Bash script usage when a user executes the script on a Linux system. We showed multiple methods for this, and the best one will depend on your situation and how complex you want to make your script. It is also always a good idea to verify the number of arguments passed and check which user is executing the script.