Parse CLI Flags Correctly in POSIX Shell with getopts

1. Write the getopts loop with explicit validation per flag.

#!/usr/bin/env bash
set -euo pipefail

ENV=""; REGION=""; VERBOSE=0; DRY_RUN=0
usage() {
  cat <<EOF
usage: $(basename "$0") [-v] [-n] -e ENV [-r REGION] [target]
  -e ENV     environment: staging|prod (required)
  -r REGION  region (default: from ENV)
  -v         verbose
  -n         dry run
EOF
  exit 2
}

while getopts ":e:r:vn" opt; do
  case "$opt" in
    e) ENV=$OPTARG ;;
    r) REGION=$OPTARG ;;
    v) VERBOSE=1 ;;
    n) DRY_RUN=1 ;;
    :) echo "error: -$OPTARG requires a value" >&2; usage ;;
    \?) echo "error: unknown flag -$OPTARG" >&2; usage ;;
  esac
done
shift $((OPTIND - 1))

[ -n "$ENV" ] || { echo "error: -e ENV is required" >&2; usage; }
case "$ENV" in staging|prod) ;; *) echo "error: ENV must be staging|prod, got \"$ENV\"" >&2; usage ;; esac

Expected output: Missing values and unknown flags each fail with a message naming the flag, and the required-value check catches a silently empty ENV.

2. Test the three failure modes deliberately.

bash deploy.sh -e 2>&1 | head -2; bash deploy.sh -x 2>&1 | head -2; bash deploy.sh 2>&1 | head -2; echo "--- happy:"; bash deploy.sh -e staging -v target1 2>&1 | head -2

Expected output: Each misuse prints its specific error plus usage: requires a value, unknown flag -x, and -e ENV is required, while the happy path proceeds.

3. Support the -- escape hatch for positional args starting with a dash.

TARGET=${1:-}
shift $((OPTIND - 1))

# caller can now say:
#   deploy.sh -e prod -- -weird-name
# and TARGET receives "-weird-name" verbatim
if [ "${1:-}" = "--" ]; then shift; fi
TARGET=${1:-}
[ -n "$TARGET" ] || { echo "error: target required" >&2; usage; }

Expected output: A positional argument that begins with a dash survives intact instead of being parsed as a flag and swallowed.

4. Distinguish an empty value from a missing one explicitly.

e)  # -e "" (empty) is different from -e (missing)
   if [ -z "$OPTARG" ]; then
     echo "error: -e value is empty" >&2; usage
   fi
   ENV=$OPTARG ;;

Expected output: An explicitly empty flag value now fails loudly at parse time instead of flowing downstream as an empty environment name.

5. Prove the argument grammar with a table test.

# test-args.sh -- table-driven, one line per case
run() { # run <expect-code> <args...>
  local expect=$1; shift
  set -- "$@"
  out=$(bash deploy.sh "$@" 2>&1); code=$?
  if [ "$code" -ne "$expect" ]; then
    echo "FAIL args=[$*] want=$expect got=$code out=$out"; exit 1
  fi
  echo "ok [$*] -> $code"
}
run 2 -e
run 2 -z
run 2 ""
run 2 -e ""
run 0 -e staging
run 0 -e prod -v -- -odd-name

Expected output: Each grammar row prints ok with its exit code, and the table runs in CI to keep the parser from regressing silently.

Problem

Long options like --env are needed

Solution

getopts is short-flags-only; either normalize long flags to short before the loop (a pre-pass translating --env X to -e X), or accept the constraint and document short flags, since portable POSIX offers no long-option builtin.

Problem

OPTARG swallows the next flag when value is missing

Solution

That is the classic -e -v bug: use the leading colon in the optstring (":e:r:") so a missing value yields the : case instead of consuming the next token as the value.

Problem

Flags after positional arguments are ignored

Solution

getopts stops at the first non-option; either require flags-first (documented in usage) or loop getopts a second time after shifting positionals, which handles the interspersed style.