diff --git a/commands/dorothy b/commands/dorothy
index e87e858c4..ad7870e5e 100755
--- a/commands/dorothy
+++ b/commands/dorothy
@@ -1940,18 +1940,18 @@ function dorothy_() (
 			filename="$(basename "$filepath")"
 
 			# check if we want to skip this test
-			if is-needle "$filename" -- "${skips[@]}"; then
+			if is-needle --needle="$filename" -- "${skips[@]}"; then
 				continue
 			fi
 
 			# check if we want to run only specific tests
-			if test "${#only[@]}" -ne 0 && ! is-needle "$filename" -- "${only[@]}"; then
+			if test "${#only[@]}" -ne 0 && ! is-needle --needle="$filename" -- "${only[@]}"; then
 				continue
 			fi
 
 			# run the test on the current bash version
 			{
-				if is-needle "$filename" -- "${flakey[@]}"; then
+				if is-needle --needle="$filename" -- "${flakey[@]}"; then
 					echo-style --invert="FIRST ATTEMPT: $filename"
 					eval-helper --no-quiet --wrap -- "$bash" "$filepath" --test || {
 						echo-style --invert="SECOND ATTEMPT: $filename"
@@ -1970,12 +1970,12 @@ function dorothy_() (
 			# check if we can test on bash v3
 			if test "$has_macos_bash_v3" = 'yes'; then
 				# we can test, but do we want to test this one on bash v3?
-				if is-needle "$filename" -- "${no_bash_v3[@]}"; then
+				if is-needle --needle="$filename" -- "${no_bash_v3[@]}"; then
 					continue
 				fi
 				# run the test on bash v3
 				{
-					if is-needle "$filename" -- "${flakey[@]}"; then
+					if is-needle --needle="$filename" -- "${flakey[@]}"; then
 						echo-style --invert="FIRST ATTEMPT: $filename"
 						env EVAL_TESTER_BASH=/bin/bash PATH="/bin:$PATH" eval-helper --no-quiet --wrap -- /bin/bash "$filepath" --test || {
 							echo-style --invert="SECOND ATTEMPT: $filename"
diff --git a/commands/down b/commands/down
index 1de441d08..c174c7802 100755
--- a/commands/down
+++ b/commands/down
@@ -136,13 +136,13 @@ function down_() (
 	# ensure tool
 	if test -z "$tool"; then
 		tool="${available_tools[0]}"
-	elif ! is-needle "$tool" -- "${available_tools[@]}"; then
+	elif ! is-needle --needle="$tool" -- "${available_tools[@]}"; then
 		help "The specified tool is not available: $tool"
 	fi
 
 	# some tools need shapeshifter
 	local shapeshifter='no'
-	if is-needle "$tool" -- "${shapeshifter_tools[@]}"; then
+	if is-needle --needle="$tool" -- "${shapeshifter_tools[@]}"; then
 		shapeshifter='yes'
 	fi
 
diff --git a/commands/edit b/commands/edit
index 4860c32eb..019d9d838 100755
--- a/commands/edit
+++ b/commands/edit
@@ -194,7 +194,7 @@ function edit_() (
 
 				# we have a suitable editor, leave the search
 				break
-			elif test "$gui" = 'yes' && is-needle "$needle" -- "${GUI_EDITORS[@]}" && get-app --quiet -- "$command"; then
+			elif test "$gui" = 'yes' && is-needle --needle="$needle" -- "${GUI_EDITORS[@]}" && get-app --quiet -- "$command"; then
 				# ignore gui editors that don't support sudo
 				if test "$sudo" = 'yes' && [[ $command =~ ^(TextEdit)$ ]]; then
 					continue
diff --git a/commands/get-profile b/commands/get-profile
index aa650e97b..e1e9b6c5f 100755
--- a/commands/get-profile
+++ b/commands/get-profile
@@ -144,7 +144,7 @@ function get_profile() (
 			;;
 		*)
 			if test -z "$selected_property"; then
-				if is-needle "$item" -- "${property_options[@]}"; then
+				if is-needle --needle="$item" -- "${property_options[@]}"; then
 					selected_property="$item"
 				else
 					help "An invalid property option was provided: $item"
diff --git a/commands/get-url-upgrade b/commands/get-url-upgrade
index 7ee90cf94..9e7ea8053 100755
--- a/commands/get-url-upgrade
+++ b/commands/get-url-upgrade
@@ -132,10 +132,10 @@ function get_url_upgrade() (
 		result=''
 
 		# check if it is a replaced domain
-		if is-needle "$url" -- 'https://login.live.com' 'https://account.live.com' 'https://account.microsoft.com'; then
+		if is-needle --needle="$url" -- 'https://login.live.com' 'https://account.live.com' 'https://account.microsoft.com'; then
 			__print_lines 'https://account.microsoft.com' # curl fails for this, even though it exists, user agent change does nothing
 			return 0
-		elif is-needle "$url" -- 'https://signin.ebay.com.au'; then
+		elif is-needle --needle="$url" -- 'https://signin.ebay.com.au'; then
 			__print_lines 'https://www.ebay.com.au/signin/'
 			return 0
 		fi
diff --git a/commands/is-needle b/commands/is-needle
index f17535545..0eaf589ac 100755
--- a/commands/is-needle
+++ b/commands/is-needle
@@ -57,9 +57,9 @@ function is_needle() (
 			is-needle  [...options] <needle> [--] ...<element>
 
 			OPTIONS:
-			<needle> | --needle=<needle>
+			--needle=<needle> | <needle>
 			    Verify this <needle> exists within the <element>s
-			    Use [--needle=<needle>] to provide multiple needles.
+			    Note that you should always use [--needle=<needle>] as just doing <needle> will fail if the <needle> looks like a flag.
 
 			RETURNS:
 			[0] if all <needle>s were found within the <element>s
diff --git a/commands/setup-git b/commands/setup-git
index 32b346408..ed7774727 100755
--- a/commands/setup-git
+++ b/commands/setup-git
@@ -149,10 +149,10 @@ function setup_git() (
 	if test -z "$GIT_NAME" -o -z "$GIT_EMAIL" -o -z "$GIT_DEFAULT_BRANCH"; then
 		option_configure='yes'
 	fi
-	if ! is-needle "$GIT_PROTOCOL" -- "${protocol_options[@]}"; then
+	if ! is-needle --needle="$GIT_PROTOCOL" -- "${protocol_options[@]}"; then
 		option_configure='yes'
 	fi
-	if ! is-needle "$MERGE_TOOL" -- "${merge_tools[@]}"; then
+	if ! is-needle --needle="$MERGE_TOOL" -- "${merge_tools[@]}"; then
 		option_configure='yes'
 	fi
 
diff --git a/commands/setup-mac-appstore b/commands/setup-mac-appstore
index 472a1d4f2..1013ad443 100755
--- a/commands/setup-mac-appstore
+++ b/commands/setup-mac-appstore
@@ -106,7 +106,7 @@ function setup_mac_appstore() (
 		# update MAS_INSTALL with all that are installed
 		local id name
 		while read -r id name; do
-			if ! is-needle "$id" -- "${MAS_INSTALL[@]}"; then
+			if ! is-needle --needle="$id" -- "${MAS_INSTALL[@]}"; then
 				MAS_INSTALL+=("$id" "$name")
 			fi
 		done <<<"$(mas list | cut -w -f1,2 | sort --ignore-case -k 2)"
diff --git a/commands/setup-mac-brew b/commands/setup-mac-brew
index 34ace9371..916251131 100755
--- a/commands/setup-mac-brew
+++ b/commands/setup-mac-brew
@@ -591,10 +591,10 @@ function setup_mac_brew() (
 				fi
 				continue
 			fi
-			if is-needle "$item" -- "${HOMEBREW_SLOW_FORMULAS[@]}"; then
+			if is-needle --needle="$item" -- "${HOMEBREW_SLOW_FORMULAS[@]}"; then
 				continue
 			fi
-			if is-needle "$item" -- "${HOMEBREW_ENCODING_FORMULAS[@]}"; then
+			if is-needle --needle="$item" -- "${HOMEBREW_ENCODING_FORMULAS[@]}"; then
 				continue
 			fi
 			if [[ $item == *'ffmpeg'* ]]; then
diff --git a/commands/setup-util b/commands/setup-util
index cfa380a9b..3606534ec 100755
--- a/commands/setup-util
+++ b/commands/setup-util
@@ -579,7 +579,7 @@ function setup_util() (
 		for installer in "${option_order[@]}"; do
 			if test "$installer" = '...'; then
 				for inject_installer in "${installers[@]}"; do
-					if is-needle "$inject_installer" -- "${option_order[@]}"; then
+					if is-needle --needle="$inject_installer" -- "${option_order[@]}"; then
 						continue
 					else
 						temp_order+=("$inject_installer")