Add support for captuing --help when using catch_all

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
  assert_string "#{key}.label", value['label']
  assert_optional_string "#{key}.help", value['help']
  assert_boolean "#{key}.required", value['required']
+ assert_boolean "#{key}.catch_help", value['catch_help']
  end
 
  def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
  class CatchAll
  class << self
  def option_keys
- @option_keys ||= %i[label help required]
+ @option_keys ||= %i[label help required catch_help]
  end
 
  def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
  when String
  { label: config }
  when Hash
-{ label: config['label'], help: config['help'], required: config['required'] }
+ config.transform_keys(&:to_sym).slice(*option_keys)
  else
  {}
  end
@@ -22,11 +22,12 @@ def from_config(config)
  end
  end
 
- def initialize(label: nil, help: nil, required: false, enabled: true)
+ def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
  @label = label
  @help = help
  @required = required
  @enabled = enabled
+ @catch_help = catch_help
  end
 
  def enabled?
@@ -45,6 +46,10 @@ def required?
  @required
  end
 
+ def catch_help?
+ @catch_help
+ end
+
  def usage_string
  return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
  end
  end
 
+ # Returns true if there is at least one fixed flag (--version / --help)
+ # Root command always has --version and subcommands always have --help
+ # except when it is consumed by catch_all
+ def fixed_flags?
+ root_command? || !catch_all.catch_help?
+ end
+
  # Returns true if this command's flags should be considered as gloal
  # flags, and cascade to subcommands
  def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
  > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
-> long_usage=yes
-> <%= function_name %>_usage
-> exit
-> ;;
-> 
+unless catch_all.catch_help?
+ = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+ > long_usage=yes
+ > <%= function_name %>_usage
+ > exit
+ > ;;
+ > 
+end
 
 if global_flags?
  flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
- options_caption = strings[:global_options]
-end
-
-> printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
- > printf " %s\n" "{{ '--help'.color(:flag) }}"
-else
- > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+ if short_flag_exist?("-h")
+ > printf " %s\n" "{{ '--help'.color(:flag) }}"
+ else
+ > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
+ end
 
-> printf " {{ strings[:help_flag_text] }}\n"
-> echo
+ > printf " {{ strings[:help_flag_text] }}\n"
+ > echo
+end
 
 if root_command?
  if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+ options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
  "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
  "type": "boolean",
  "default": false
+ },
+ "catch_help": {
+ "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+ "type": "boolean",
+ "default": false
  }
  },
  "additionalProperties": false

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [OPTIONS] [--] [PARAMS...]
+ cli docker --help | -h
+
+Options:
+ --show-help-anyway
+ Show this help message
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/fixtures/catch-all-no-fixed-flags

@@ -0,0 +1,22 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker show-hidden-usage
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [--] [PARAMS...]
+ cli docker --help | -h
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/validations/command_catch_all_catch_help

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.catch_all.catch_help must be a boolean>

spec/fixtures/script/validations.yml

@@ -94,6 +94,13 @@
  help: catch_all must be boolean, string, or hash
  catch_all: [1,2]
 
+:command_catch_all_catch_help:
+ name: invalid
+ help: catch_all.catch_help must be boolean
+ catch_all:
+ label: params
+ catch_help: "this is not a help string"
+
 :command_catch_all_valid:
  name: invalid
  catch_all:

spec/fixtures/workspaces/catch-all-including-help/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-including-help/README.md

@@ -0,0 +1 @@
+This fixture tests that catch all with catch_help is catching the --help flag

spec/fixtures/workspaces/catch-all-including-help/src/bashly.yml

@@ -0,0 +1,18 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true
+
+ # We want to see that the internal usage command still prints normally
+ flags:
+ - long: --show-help-anyway
+ help: Show this help message

spec/fixtures/workspaces/catch-all-including-help/src/docker_command.sh

@@ -0,0 +1,8 @@
+show_help=${args["--show-help-anyway"]-}
+
+if [[ $show_help ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-including-help/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker --show-help-anyway

spec/fixtures/workspaces/catch-all-no-fixed-flags/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-no-fixed-flags/README.md

@@ -0,0 +1,3 @@
+This fixture tests that when catch all is set with catch_help and no other
+flags, the usage text - if called by the developer - is not showing the 
+"Options" caption (since there are now zero options to show)

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/bashly.yml

@@ -0,0 +1,13 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/docker_command.sh

@@ -0,0 +1,6 @@
+if [[ "${other_args[0]}" == "show-hidden-usage" ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-no-fixed-flags/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker show-hidden-usage

spec/fixtures/workspaces/lib-upgrade/src/lib/send_completions.sh

@@ -11,24 +11,46 @@ send_completions() {
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
  echo $' local result=()'
  echo $''
+ echo $' # words the user already typed (excluding the command itself)'
+ echo $' local used=()'
+ echo $' if ((COMP_CWORD > 1)); then'
+ echo $' used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
+ echo $''
  echo $' if [[ "${cur:0:1}" == "-" ]]; then'
+ echo $' # Completing an option: offer everything (including options)'
  echo $' echo "$words"'
  echo $''
  echo $' else'
+ echo $' # Completing a non-option: offer only non-options,'
+ echo $' # and don\'t re-offer ones already used earlier in the line.'
  echo $' for word in $words; do'
- echo $' [[ "${word:0:1}" != "-" ]] && result+=("$word")'
+ echo $' [[ "${word:0:1}" == "-" ]] && continue'
+ echo $''
+ echo $' local seen=0'
+ echo $' for u in "${used[@]}"; do'
+ echo $' if [[ "$u" == "$word" ]]; then'
+ echo $' seen=1'
+ echo $' break'
+ echo $' fi'
+ echo $' done'
+ echo $' ((!seen)) && result+=("$word")'
  echo $' done'
  echo $''
  echo $' echo "${result[*]}"'
- echo $''
  echo $' fi'
  echo $'}'
  echo $''
  echo $'_cli_completions() {'
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
- echo $' local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")'
+ echo $' local compwords=()'
+ echo $' if ((COMP_CWORD > 0)); then'
+ echo $' compwords=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
  echo $' local compline="${compwords[*]}"'
  echo $''
+ echo $' COMPREPLY=()'
+ echo $''
  echo $' case "$compline" in'
  echo $' \'download\'*)'
  echo $' while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--force --help -f -h")" -- "$cur")'

support/runfile/example.rb

@@ -8,7 +8,9 @@ def examples
  end
 
  def fixtures
- filter_dirs('spec/fixtures/workspaces').map { |dir| new dir, type: :fixture }
+ filter_dirs('spec/fixtures/workspaces')
+ .select { |dir| File.exist? "#{dir}/src/bashly.yml" }
+ .map { |dir| new dir, type: :fixture }
  end
 
  def all

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
  assert_string "#{key}.label", value['label']
  assert_optional_string "#{key}.help", value['help']
  assert_boolean "#{key}.required", value['required']
+ assert_boolean "#{key}.catch_help", value['catch_help']
  end
 
  def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
  class CatchAll
  class << self
  def option_keys
- @option_keys ||= %i[label help required]
+ @option_keys ||= %i[label help required catch_help]
  end
 
  def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
  when String
  { label: config }
  when Hash
-{ label: config['label'], help: config['help'], required: config['required'] }
+ config.transform_keys(&:to_sym).slice(*option_keys)
  else
  {}
  end
@@ -22,11 +22,12 @@ def from_config(config)
  end
  end
 
- def initialize(label: nil, help: nil, required: false, enabled: true)
+ def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
  @label = label
  @help = help
  @required = required
  @enabled = enabled
+ @catch_help = catch_help
  end
 
  def enabled?
@@ -45,6 +46,10 @@ def required?
  @required
  end
 
+ def catch_help?
+ @catch_help
+ end
+
  def usage_string
  return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
  end
  end
 
+ # Returns true if there is at least one fixed flag (--version / --help)
+ # Root command always has --version and subcommands always have --help
+ # except when it is consumed by catch_all
+ def fixed_flags?
+ root_command? || !catch_all.catch_help?
+ end
+
  # Returns true if this command's flags should be considered as gloal
  # flags, and cascade to subcommands
  def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
  > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
-> long_usage=yes
-> <%= function_name %>_usage
-> exit
-> ;;
-> 
+unless catch_all.catch_help?
+ = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+ > long_usage=yes
+ > <%= function_name %>_usage
+ > exit
+ > ;;
+ > 
+end
 
 if global_flags?
  flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
- options_caption = strings[:global_options]
-end
-
-> printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
- > printf " %s\n" "{{ '--help'.color(:flag) }}"
-else
- > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+ if short_flag_exist?("-h")
+ > printf " %s\n" "{{ '--help'.color(:flag) }}"
+ else
+ > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
+ end
 
-> printf " {{ strings[:help_flag_text] }}\n"
-> echo
+ > printf " {{ strings[:help_flag_text] }}\n"
+ > echo
+end
 
 if root_command?
  if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+ options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
  "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
  "type": "boolean",
  "default": false
+ },
+ "catch_help": {
+ "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+ "type": "boolean",
+ "default": false
  }
  },
  "additionalProperties": false

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [OPTIONS] [--] [PARAMS...]
+ cli docker --help | -h
+
+Options:
+ --show-help-anyway
+ Show this help message
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/fixtures/catch-all-no-fixed-flags

@@ -0,0 +1,22 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker show-hidden-usage
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [--] [PARAMS...]
+ cli docker --help | -h
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/validations/command_catch_all_catch_help

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.catch_all.catch_help must be a boolean>

spec/fixtures/script/validations.yml

@@ -94,6 +94,13 @@
  help: catch_all must be boolean, string, or hash
  catch_all: [1,2]
 
+:command_catch_all_catch_help:
+ name: invalid
+ help: catch_all.catch_help must be boolean
+ catch_all:
+ label: params
+ catch_help: "this is not a help string"
+
 :command_catch_all_valid:
  name: invalid
  catch_all:

spec/fixtures/workspaces/catch-all-including-help/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-including-help/README.md

@@ -0,0 +1 @@
+This fixture tests that catch all with catch_help is catching the --help flag

spec/fixtures/workspaces/catch-all-including-help/src/bashly.yml

@@ -0,0 +1,18 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true
+
+ # We want to see that the internal usage command still prints normally
+ flags:
+ - long: --show-help-anyway
+ help: Show this help message

spec/fixtures/workspaces/catch-all-including-help/src/docker_command.sh

@@ -0,0 +1,8 @@
+show_help=${args["--show-help-anyway"]-}
+
+if [[ $show_help ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-including-help/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker --show-help-anyway

spec/fixtures/workspaces/catch-all-no-fixed-flags/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-no-fixed-flags/README.md

@@ -0,0 +1,3 @@
+This fixture tests that when catch all is set with catch_help and no other
+flags, the usage text - if called by the developer - is not showing the 
+"Options" caption (since there are now zero options to show)

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/bashly.yml

@@ -0,0 +1,13 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/docker_command.sh

@@ -0,0 +1,6 @@
+if [[ "${other_args[0]}" == "show-hidden-usage" ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-no-fixed-flags/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker show-hidden-usage

spec/fixtures/workspaces/lib-upgrade/src/lib/send_completions.sh

@@ -11,24 +11,46 @@ send_completions() {
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
  echo $' local result=()'
  echo $''
+ echo $' # words the user already typed (excluding the command itself)'
+ echo $' local used=()'
+ echo $' if ((COMP_CWORD > 1)); then'
+ echo $' used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
+ echo $''
  echo $' if [[ "${cur:0:1}" == "-" ]]; then'
+ echo $' # Completing an option: offer everything (including options)'
  echo $' echo "$words"'
  echo $''
  echo $' else'
+ echo $' # Completing a non-option: offer only non-options,'
+ echo $' # and don\'t re-offer ones already used earlier in the line.'
  echo $' for word in $words; do'
- echo $' [[ "${word:0:1}" != "-" ]] && result+=("$word")'
+ echo $' [[ "${word:0:1}" == "-" ]] && continue'
+ echo $''
+ echo $' local seen=0'
+ echo $' for u in "${used[@]}"; do'
+ echo $' if [[ "$u" == "$word" ]]; then'
+ echo $' seen=1'
+ echo $' break'
+ echo $' fi'
+ echo $' done'
+ echo $' ((!seen)) && result+=("$word")'
  echo $' done'
  echo $''
  echo $' echo "${result[*]}"'
- echo $''
  echo $' fi'
  echo $'}'
  echo $''
  echo $'_cli_completions() {'
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
- echo $' local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")'
+ echo $' local compwords=()'
+ echo $' if ((COMP_CWORD > 0)); then'
+ echo $' compwords=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
  echo $' local compline="${compwords[*]}"'
  echo $''
+ echo $' COMPREPLY=()'
+ echo $''
  echo $' case "$compline" in'
  echo $' \'download\'*)'
  echo $' while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--force --help -f -h")" -- "$cur")'

support/runfile/example.rb

@@ -8,7 +8,9 @@ def examples
  end
 
  def fixtures
- filter_dirs('spec/fixtures/workspaces').map { |dir| new dir, type: :fixture }
+ filter_dirs('spec/fixtures/workspaces')
+ .select { |dir| File.exist? "#{dir}/src/bashly.yml" }
+ .map { |dir| new dir, type: :fixture }
  end
 
  def all

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
  assert_string "#{key}.label", value['label']
  assert_optional_string "#{key}.help", value['help']
  assert_boolean "#{key}.required", value['required']
+ assert_boolean "#{key}.catch_help", value['catch_help']
  end
 
  def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
  class CatchAll
  class << self
  def option_keys
- @option_keys ||= %i[label help required]
+ @option_keys ||= %i[label help required catch_help]
  end
 
  def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
  when String
  { label: config }
  when Hash
-{ label: config['label'], help: config['help'], required: config['required'] }
+ config.transform_keys(&:to_sym).slice(*option_keys)
  else
  {}
  end
@@ -22,11 +22,12 @@ def from_config(config)
  end
  end
 
- def initialize(label: nil, help: nil, required: false, enabled: true)
+ def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
  @label = label
  @help = help
  @required = required
  @enabled = enabled
+ @catch_help = catch_help
  end
 
  def enabled?
@@ -45,6 +46,10 @@ def required?
  @required
  end
 
+ def catch_help?
+ @catch_help
+ end
+
  def usage_string
  return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
  end
  end
 
+ # Returns true if there is at least one fixed flag (--version / --help)
+ # Root command always has --version and subcommands always have --help
+ # except when it is consumed by catch_all
+ def fixed_flags?
+ root_command? || !catch_all.catch_help?
+ end
+
  # Returns true if this command's flags should be considered as gloal
  # flags, and cascade to subcommands
  def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
  > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
-> long_usage=yes
-> <%= function_name %>_usage
-> exit
-> ;;
-> 
+unless catch_all.catch_help?
+ = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+ > long_usage=yes
+ > <%= function_name %>_usage
+ > exit
+ > ;;
+ > 
+end
 
 if global_flags?
  flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
- options_caption = strings[:global_options]
-end
-
-> printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
- > printf " %s\n" "{{ '--help'.color(:flag) }}"
-else
- > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+ if short_flag_exist?("-h")
+ > printf " %s\n" "{{ '--help'.color(:flag) }}"
+ else
+ > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
+ end
 
-> printf " {{ strings[:help_flag_text] }}\n"
-> echo
+ > printf " {{ strings[:help_flag_text] }}\n"
+ > echo
+end
 
 if root_command?
  if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+ options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
  "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
  "type": "boolean",
  "default": false
+ },
+ "catch_help": {
+ "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+ "type": "boolean",
+ "default": false
  }
  },
  "additionalProperties": false

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [OPTIONS] [--] [PARAMS...]
+ cli docker --help | -h
+
+Options:
+ --show-help-anyway
+ Show this help message
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/fixtures/catch-all-no-fixed-flags

@@ -0,0 +1,22 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker show-hidden-usage
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [--] [PARAMS...]
+ cli docker --help | -h
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/validations/command_catch_all_catch_help

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.catch_all.catch_help must be a boolean>

spec/fixtures/script/validations.yml

@@ -94,6 +94,13 @@
  help: catch_all must be boolean, string, or hash
  catch_all: [1,2]
 
+:command_catch_all_catch_help:
+ name: invalid
+ help: catch_all.catch_help must be boolean
+ catch_all:
+ label: params
+ catch_help: "this is not a help string"
+
 :command_catch_all_valid:
  name: invalid
  catch_all:

spec/fixtures/workspaces/catch-all-including-help/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-including-help/README.md

@@ -0,0 +1 @@
+This fixture tests that catch all with catch_help is catching the --help flag

spec/fixtures/workspaces/catch-all-including-help/src/bashly.yml

@@ -0,0 +1,18 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true
+
+ # We want to see that the internal usage command still prints normally
+ flags:
+ - long: --show-help-anyway
+ help: Show this help message

spec/fixtures/workspaces/catch-all-including-help/src/docker_command.sh

@@ -0,0 +1,8 @@
+show_help=${args["--show-help-anyway"]-}
+
+if [[ $show_help ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-including-help/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker --show-help-anyway

spec/fixtures/workspaces/catch-all-no-fixed-flags/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-no-fixed-flags/README.md

@@ -0,0 +1,3 @@
+This fixture tests that when catch all is set with catch_help and no other
+flags, the usage text - if called by the developer - is not showing the 
+"Options" caption (since there are now zero options to show)

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/bashly.yml

@@ -0,0 +1,13 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/docker_command.sh

@@ -0,0 +1,6 @@
+if [[ "${other_args[0]}" == "show-hidden-usage" ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-no-fixed-flags/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker show-hidden-usage

spec/fixtures/workspaces/lib-upgrade/src/lib/send_completions.sh

@@ -11,24 +11,46 @@ send_completions() {
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
  echo $' local result=()'
  echo $''
+ echo $' # words the user already typed (excluding the command itself)'
+ echo $' local used=()'
+ echo $' if ((COMP_CWORD > 1)); then'
+ echo $' used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
+ echo $''
  echo $' if [[ "${cur:0:1}" == "-" ]]; then'
+ echo $' # Completing an option: offer everything (including options)'
  echo $' echo "$words"'
  echo $''
  echo $' else'
+ echo $' # Completing a non-option: offer only non-options,'
+ echo $' # and don\'t re-offer ones already used earlier in the line.'
  echo $' for word in $words; do'
- echo $' [[ "${word:0:1}" != "-" ]] && result+=("$word")'
+ echo $' [[ "${word:0:1}" == "-" ]] && continue'
+ echo $''
+ echo $' local seen=0'
+ echo $' for u in "${used[@]}"; do'
+ echo $' if [[ "$u" == "$word" ]]; then'
+ echo $' seen=1'
+ echo $' break'
+ echo $' fi'
+ echo $' done'
+ echo $' ((!seen)) && result+=("$word")'
  echo $' done'
  echo $''
  echo $' echo "${result[*]}"'
- echo $''
  echo $' fi'
  echo $'}'
  echo $''
  echo $'_cli_completions() {'
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
- echo $' local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")'
+ echo $' local compwords=()'
+ echo $' if ((COMP_CWORD > 0)); then'
+ echo $' compwords=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
  echo $' local compline="${compwords[*]}"'
  echo $''
+ echo $' COMPREPLY=()'
+ echo $''
  echo $' case "$compline" in'
  echo $' \'download\'*)'
  echo $' while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--force --help -f -h")" -- "$cur")'

support/runfile/example.rb

@@ -8,7 +8,9 @@ def examples
  end
 
  def fixtures
- filter_dirs('spec/fixtures/workspaces').map { |dir| new dir, type: :fixture }
+ filter_dirs('spec/fixtures/workspaces')
+ .select { |dir| File.exist? "#{dir}/src/bashly.yml" }
+ .map { |dir| new dir, type: :fixture }
  end
 
  def all

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
  assert_string "#{key}.label", value['label']
  assert_optional_string "#{key}.help", value['help']
  assert_boolean "#{key}.required", value['required']
+ assert_boolean "#{key}.catch_help", value['catch_help']
  end
 
  def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
  class CatchAll
  class << self
  def option_keys
- @option_keys ||= %i[label help required]
+ @option_keys ||= %i[label help required catch_help]
  end
 
  def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
  when String
  { label: config }
  when Hash
-{ label: config['label'], help: config['help'], required: config['required'] }
+ config.transform_keys(&:to_sym).slice(*option_keys)
  else
  {}
  end
@@ -22,11 +22,12 @@ def from_config(config)
  end
  end
 
- def initialize(label: nil, help: nil, required: false, enabled: true)
+ def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
  @label = label
  @help = help
  @required = required
  @enabled = enabled
+ @catch_help = catch_help
  end
 
  def enabled?
@@ -45,6 +46,10 @@ def required?
  @required
  end
 
+ def catch_help?
+ @catch_help
+ end
+
  def usage_string
  return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
  end
  end
 
+ # Returns true if there is at least one fixed flag (--version / --help)
+ # Root command always has --version and subcommands always have --help
+ # except when it is consumed by catch_all
+ def fixed_flags?
+ root_command? || !catch_all.catch_help?
+ end
+
  # Returns true if this command's flags should be considered as gloal
  # flags, and cascade to subcommands
  def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
  > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
-> long_usage=yes
-> <%= function_name %>_usage
-> exit
-> ;;
-> 
+unless catch_all.catch_help?
+ = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+ > long_usage=yes
+ > <%= function_name %>_usage
+ > exit
+ > ;;
+ > 
+end
 
 if global_flags?
  flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
- options_caption = strings[:global_options]
-end
-
-> printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
- > printf " %s\n" "{{ '--help'.color(:flag) }}"
-else
- > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+ if short_flag_exist?("-h")
+ > printf " %s\n" "{{ '--help'.color(:flag) }}"
+ else
+ > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
+ end
 
-> printf " {{ strings[:help_flag_text] }}\n"
-> echo
+ > printf " {{ strings[:help_flag_text] }}\n"
+ > echo
+end
 
 if root_command?
  if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+ options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
  "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
  "type": "boolean",
  "default": false
+ },
+ "catch_help": {
+ "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+ "type": "boolean",
+ "default": false
  }
  },
  "additionalProperties": false

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [OPTIONS] [--] [PARAMS...]
+ cli docker --help | -h
+
+Options:
+ --show-help-anyway
+ Show this help message
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/fixtures/catch-all-no-fixed-flags

@@ -0,0 +1,22 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker show-hidden-usage
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [--] [PARAMS...]
+ cli docker --help | -h
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/validations/command_catch_all_catch_help

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.catch_all.catch_help must be a boolean>

spec/fixtures/script/validations.yml

@@ -94,6 +94,13 @@
  help: catch_all must be boolean, string, or hash
  catch_all: [1,2]
 
+:command_catch_all_catch_help:
+ name: invalid
+ help: catch_all.catch_help must be boolean
+ catch_all:
+ label: params
+ catch_help: "this is not a help string"
+
 :command_catch_all_valid:
  name: invalid
  catch_all:

spec/fixtures/workspaces/catch-all-including-help/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-including-help/README.md

@@ -0,0 +1 @@
+This fixture tests that catch all with catch_help is catching the --help flag

spec/fixtures/workspaces/catch-all-including-help/src/bashly.yml

@@ -0,0 +1,18 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true
+
+ # We want to see that the internal usage command still prints normally
+ flags:
+ - long: --show-help-anyway
+ help: Show this help message

spec/fixtures/workspaces/catch-all-including-help/src/docker_command.sh

@@ -0,0 +1,8 @@
+show_help=${args["--show-help-anyway"]-}
+
+if [[ $show_help ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-including-help/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker --show-help-anyway

spec/fixtures/workspaces/catch-all-no-fixed-flags/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-no-fixed-flags/README.md

@@ -0,0 +1,3 @@
+This fixture tests that when catch all is set with catch_help and no other
+flags, the usage text - if called by the developer - is not showing the 
+"Options" caption (since there are now zero options to show)

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/bashly.yml

@@ -0,0 +1,13 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/docker_command.sh

@@ -0,0 +1,6 @@
+if [[ "${other_args[0]}" == "show-hidden-usage" ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-no-fixed-flags/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker show-hidden-usage

spec/fixtures/workspaces/lib-upgrade/src/lib/send_completions.sh

@@ -11,24 +11,46 @@ send_completions() {
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
  echo $' local result=()'
  echo $''
+ echo $' # words the user already typed (excluding the command itself)'
+ echo $' local used=()'
+ echo $' if ((COMP_CWORD > 1)); then'
+ echo $' used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
+ echo $''
  echo $' if [[ "${cur:0:1}" == "-" ]]; then'
+ echo $' # Completing an option: offer everything (including options)'
  echo $' echo "$words"'
  echo $''
  echo $' else'
+ echo $' # Completing a non-option: offer only non-options,'
+ echo $' # and don\'t re-offer ones already used earlier in the line.'
  echo $' for word in $words; do'
- echo $' [[ "${word:0:1}" != "-" ]] && result+=("$word")'
+ echo $' [[ "${word:0:1}" == "-" ]] && continue'
+ echo $''
+ echo $' local seen=0'
+ echo $' for u in "${used[@]}"; do'
+ echo $' if [[ "$u" == "$word" ]]; then'
+ echo $' seen=1'
+ echo $' break'
+ echo $' fi'
+ echo $' done'
+ echo $' ((!seen)) && result+=("$word")'
  echo $' done'
  echo $''
  echo $' echo "${result[*]}"'
- echo $''
  echo $' fi'
  echo $'}'
  echo $''
  echo $'_cli_completions() {'
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
- echo $' local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")'
+ echo $' local compwords=()'
+ echo $' if ((COMP_CWORD > 0)); then'
+ echo $' compwords=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
  echo $' local compline="${compwords[*]}"'
  echo $''
+ echo $' COMPREPLY=()'
+ echo $''
  echo $' case "$compline" in'
  echo $' \'download\'*)'
  echo $' while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--force --help -f -h")" -- "$cur")'

support/runfile/example.rb

@@ -8,7 +8,9 @@ def examples
  end
 
  def fixtures
- filter_dirs('spec/fixtures/workspaces').map { |dir| new dir, type: :fixture }
+ filter_dirs('spec/fixtures/workspaces')
+ .select { |dir| File.exist? "#{dir}/src/bashly.yml" }
+ .map { |dir| new dir, type: :fixture }
  end
 
  def all

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
  assert_string "#{key}.label", value['label']
  assert_optional_string "#{key}.help", value['help']
  assert_boolean "#{key}.required", value['required']
+ assert_boolean "#{key}.catch_help", value['catch_help']
  end
 
  def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
  class CatchAll
  class << self
  def option_keys
- @option_keys ||= %i[label help required]
+ @option_keys ||= %i[label help required catch_help]
  end
 
  def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
  when String
  { label: config }
  when Hash
-{ label: config['label'], help: config['help'], required: config['required'] }
+ config.transform_keys(&:to_sym).slice(*option_keys)
  else
  {}
  end
@@ -22,11 +22,12 @@ def from_config(config)
  end
  end
 
- def initialize(label: nil, help: nil, required: false, enabled: true)
+ def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
  @label = label
  @help = help
  @required = required
  @enabled = enabled
+ @catch_help = catch_help
  end
 
  def enabled?
@@ -45,6 +46,10 @@ def required?
  @required
  end
 
+ def catch_help?
+ @catch_help
+ end
+
  def usage_string
  return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
  end
  end
 
+ # Returns true if there is at least one fixed flag (--version / --help)
+ # Root command always has --version and subcommands always have --help
+ # except when it is consumed by catch_all
+ def fixed_flags?
+ root_command? || !catch_all.catch_help?
+ end
+
  # Returns true if this command's flags should be considered as gloal
  # flags, and cascade to subcommands
  def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
  > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
-> long_usage=yes
-> <%= function_name %>_usage
-> exit
-> ;;
-> 
+unless catch_all.catch_help?
+ = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+ > long_usage=yes
+ > <%= function_name %>_usage
+ > exit
+ > ;;
+ > 
+end
 
 if global_flags?
  flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
- options_caption = strings[:global_options]
-end
-
-> printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
- > printf " %s\n" "{{ '--help'.color(:flag) }}"
-else
- > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+ if short_flag_exist?("-h")
+ > printf " %s\n" "{{ '--help'.color(:flag) }}"
+ else
+ > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
+ end
 
-> printf " {{ strings[:help_flag_text] }}\n"
-> echo
+ > printf " {{ strings[:help_flag_text] }}\n"
+ > echo
+end
 
 if root_command?
  if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+ options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
  "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
  "type": "boolean",
  "default": false
+ },
+ "catch_help": {
+ "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+ "type": "boolean",
+ "default": false
  }
  },
  "additionalProperties": false

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [OPTIONS] [--] [PARAMS...]
+ cli docker --help | -h
+
+Options:
+ --show-help-anyway
+ Show this help message
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/fixtures/catch-all-no-fixed-flags

@@ -0,0 +1,22 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker show-hidden-usage
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [--] [PARAMS...]
+ cli docker --help | -h
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/validations/command_catch_all_catch_help

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.catch_all.catch_help must be a boolean>

spec/fixtures/script/validations.yml

@@ -94,6 +94,13 @@
  help: catch_all must be boolean, string, or hash
  catch_all: [1,2]
 
+:command_catch_all_catch_help:
+ name: invalid
+ help: catch_all.catch_help must be boolean
+ catch_all:
+ label: params
+ catch_help: "this is not a help string"
+
 :command_catch_all_valid:
  name: invalid
  catch_all:

spec/fixtures/workspaces/catch-all-including-help/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-including-help/README.md

@@ -0,0 +1 @@
+This fixture tests that catch all with catch_help is catching the --help flag

spec/fixtures/workspaces/catch-all-including-help/src/bashly.yml

@@ -0,0 +1,18 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true
+
+ # We want to see that the internal usage command still prints normally
+ flags:
+ - long: --show-help-anyway
+ help: Show this help message

spec/fixtures/workspaces/catch-all-including-help/src/docker_command.sh

@@ -0,0 +1,8 @@
+show_help=${args["--show-help-anyway"]-}
+
+if [[ $show_help ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-including-help/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker --show-help-anyway

spec/fixtures/workspaces/catch-all-no-fixed-flags/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-no-fixed-flags/README.md

@@ -0,0 +1,3 @@
+This fixture tests that when catch all is set with catch_help and no other
+flags, the usage text - if called by the developer - is not showing the 
+"Options" caption (since there are now zero options to show)

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/bashly.yml

@@ -0,0 +1,13 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/docker_command.sh

@@ -0,0 +1,6 @@
+if [[ "${other_args[0]}" == "show-hidden-usage" ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-no-fixed-flags/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker show-hidden-usage

spec/fixtures/workspaces/lib-upgrade/src/lib/send_completions.sh

@@ -11,24 +11,46 @@ send_completions() {
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
  echo $' local result=()'
  echo $''
+ echo $' # words the user already typed (excluding the command itself)'
+ echo $' local used=()'
+ echo $' if ((COMP_CWORD > 1)); then'
+ echo $' used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
+ echo $''
  echo $' if [[ "${cur:0:1}" == "-" ]]; then'
+ echo $' # Completing an option: offer everything (including options)'
  echo $' echo "$words"'
  echo $''
  echo $' else'
+ echo $' # Completing a non-option: offer only non-options,'
+ echo $' # and don\'t re-offer ones already used earlier in the line.'
  echo $' for word in $words; do'
- echo $' [[ "${word:0:1}" != "-" ]] && result+=("$word")'
+ echo $' [[ "${word:0:1}" == "-" ]] && continue'
+ echo $''
+ echo $' local seen=0'
+ echo $' for u in "${used[@]}"; do'
+ echo $' if [[ "$u" == "$word" ]]; then'
+ echo $' seen=1'
+ echo $' break'
+ echo $' fi'
+ echo $' done'
+ echo $' ((!seen)) && result+=("$word")'
  echo $' done'
  echo $''
  echo $' echo "${result[*]}"'
- echo $''
  echo $' fi'
  echo $'}'
  echo $''
  echo $'_cli_completions() {'
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
- echo $' local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")'
+ echo $' local compwords=()'
+ echo $' if ((COMP_CWORD > 0)); then'
+ echo $' compwords=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
  echo $' local compline="${compwords[*]}"'
  echo $''
+ echo $' COMPREPLY=()'
+ echo $''
  echo $' case "$compline" in'
  echo $' \'download\'*)'
  echo $' while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--force --help -f -h")" -- "$cur")'

support/runfile/example.rb

@@ -8,7 +8,9 @@ def examples
  end
 
  def fixtures
- filter_dirs('spec/fixtures/workspaces').map { |dir| new dir, type: :fixture }
+ filter_dirs('spec/fixtures/workspaces')
+ .select { |dir| File.exist? "#{dir}/src/bashly.yml" }
+ .map { |dir| new dir, type: :fixture }
  end
 
  def all

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
  assert_string "#{key}.label", value['label']
  assert_optional_string "#{key}.help", value['help']
  assert_boolean "#{key}.required", value['required']
+ assert_boolean "#{key}.catch_help", value['catch_help']
  end
 
  def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
  class CatchAll
  class << self
  def option_keys
- @option_keys ||= %i[label help required]
+ @option_keys ||= %i[label help required catch_help]
  end
 
  def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
  when String
  { label: config }
  when Hash
-{ label: config['label'], help: config['help'], required: config['required'] }
+ config.transform_keys(&:to_sym).slice(*option_keys)
  else
  {}
  end
@@ -22,11 +22,12 @@ def from_config(config)
  end
  end
 
- def initialize(label: nil, help: nil, required: false, enabled: true)
+ def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
  @label = label
  @help = help
  @required = required
  @enabled = enabled
+ @catch_help = catch_help
  end
 
  def enabled?
@@ -45,6 +46,10 @@ def required?
  @required
  end
 
+ def catch_help?
+ @catch_help
+ end
+
  def usage_string
  return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
  end
  end
 
+ # Returns true if there is at least one fixed flag (--version / --help)
+ # Root command always has --version and subcommands always have --help
+ # except when it is consumed by catch_all
+ def fixed_flags?
+ root_command? || !catch_all.catch_help?
+ end
+
  # Returns true if this command's flags should be considered as gloal
  # flags, and cascade to subcommands
  def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
  > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
-> long_usage=yes
-> <%= function_name %>_usage
-> exit
-> ;;
-> 
+unless catch_all.catch_help?
+ = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+ > long_usage=yes
+ > <%= function_name %>_usage
+ > exit
+ > ;;
+ > 
+end
 
 if global_flags?
  flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
- options_caption = strings[:global_options]
-end
-
-> printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
- > printf " %s\n" "{{ '--help'.color(:flag) }}"
-else
- > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+ if short_flag_exist?("-h")
+ > printf " %s\n" "{{ '--help'.color(:flag) }}"
+ else
+ > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
+ end
 
-> printf " {{ strings[:help_flag_text] }}\n"
-> echo
+ > printf " {{ strings[:help_flag_text] }}\n"
+ > echo
+end
 
 if root_command?
  if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+ options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
  "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
  "type": "boolean",
  "default": false
+ },
+ "catch_help": {
+ "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+ "type": "boolean",
+ "default": false
  }
  },
  "additionalProperties": false

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [OPTIONS] [--] [PARAMS...]
+ cli docker --help | -h
+
+Options:
+ --show-help-anyway
+ Show this help message
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/fixtures/catch-all-no-fixed-flags

@@ -0,0 +1,22 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker show-hidden-usage
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [--] [PARAMS...]
+ cli docker --help | -h
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/validations/command_catch_all_catch_help

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.catch_all.catch_help must be a boolean>

spec/fixtures/script/validations.yml

@@ -94,6 +94,13 @@
  help: catch_all must be boolean, string, or hash
  catch_all: [1,2]
 
+:command_catch_all_catch_help:
+ name: invalid
+ help: catch_all.catch_help must be boolean
+ catch_all:
+ label: params
+ catch_help: "this is not a help string"
+
 :command_catch_all_valid:
  name: invalid
  catch_all:

spec/fixtures/workspaces/catch-all-including-help/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-including-help/README.md

@@ -0,0 +1 @@
+This fixture tests that catch all with catch_help is catching the --help flag

spec/fixtures/workspaces/catch-all-including-help/src/bashly.yml

@@ -0,0 +1,18 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true
+
+ # We want to see that the internal usage command still prints normally
+ flags:
+ - long: --show-help-anyway
+ help: Show this help message

spec/fixtures/workspaces/catch-all-including-help/src/docker_command.sh

@@ -0,0 +1,8 @@
+show_help=${args["--show-help-anyway"]-}
+
+if [[ $show_help ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-including-help/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker --show-help-anyway

spec/fixtures/workspaces/catch-all-no-fixed-flags/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-no-fixed-flags/README.md

@@ -0,0 +1,3 @@
+This fixture tests that when catch all is set with catch_help and no other
+flags, the usage text - if called by the developer - is not showing the 
+"Options" caption (since there are now zero options to show)

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/bashly.yml

@@ -0,0 +1,13 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/docker_command.sh

@@ -0,0 +1,6 @@
+if [[ "${other_args[0]}" == "show-hidden-usage" ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-no-fixed-flags/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker show-hidden-usage

spec/fixtures/workspaces/lib-upgrade/src/lib/send_completions.sh

@@ -11,24 +11,46 @@ send_completions() {
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
  echo $' local result=()'
  echo $''
+ echo $' # words the user already typed (excluding the command itself)'
+ echo $' local used=()'
+ echo $' if ((COMP_CWORD > 1)); then'
+ echo $' used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
+ echo $''
  echo $' if [[ "${cur:0:1}" == "-" ]]; then'
+ echo $' # Completing an option: offer everything (including options)'
  echo $' echo "$words"'
  echo $''
  echo $' else'
+ echo $' # Completing a non-option: offer only non-options,'
+ echo $' # and don\'t re-offer ones already used earlier in the line.'
  echo $' for word in $words; do'
- echo $' [[ "${word:0:1}" != "-" ]] && result+=("$word")'
+ echo $' [[ "${word:0:1}" == "-" ]] && continue'
+ echo $''
+ echo $' local seen=0'
+ echo $' for u in "${used[@]}"; do'
+ echo $' if [[ "$u" == "$word" ]]; then'
+ echo $' seen=1'
+ echo $' break'
+ echo $' fi'
+ echo $' done'
+ echo $' ((!seen)) && result+=("$word")'
  echo $' done'
  echo $''
  echo $' echo "${result[*]}"'
- echo $''
  echo $' fi'
  echo $'}'
  echo $''
  echo $'_cli_completions() {'
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
- echo $' local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")'
+ echo $' local compwords=()'
+ echo $' if ((COMP_CWORD > 0)); then'
+ echo $' compwords=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
  echo $' local compline="${compwords[*]}"'
  echo $''
+ echo $' COMPREPLY=()'
+ echo $''
  echo $' case "$compline" in'
  echo $' \'download\'*)'
  echo $' while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--force --help -f -h")" -- "$cur")'

support/runfile/example.rb

@@ -8,7 +8,9 @@ def examples
  end
 
  def fixtures
- filter_dirs('spec/fixtures/workspaces').map { |dir| new dir, type: :fixture }
+ filter_dirs('spec/fixtures/workspaces')
+ .select { |dir| File.exist? "#{dir}/src/bashly.yml" }
+ .map { |dir| new dir, type: :fixture }
  end
 
  def all

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
  assert_string "#{key}.label", value['label']
  assert_optional_string "#{key}.help", value['help']
  assert_boolean "#{key}.required", value['required']
+ assert_boolean "#{key}.catch_help", value['catch_help']
  end
 
  def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
  class CatchAll
  class << self
  def option_keys
- @option_keys ||= %i[label help required]
+ @option_keys ||= %i[label help required catch_help]
  end
 
  def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
  when String
  { label: config }
  when Hash
-{ label: config['label'], help: config['help'], required: config['required'] }
+ config.transform_keys(&:to_sym).slice(*option_keys)
  else
  {}
  end
@@ -22,11 +22,12 @@ def from_config(config)
  end
  end
 
- def initialize(label: nil, help: nil, required: false, enabled: true)
+ def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
  @label = label
  @help = help
  @required = required
  @enabled = enabled
+ @catch_help = catch_help
  end
 
  def enabled?
@@ -45,6 +46,10 @@ def required?
  @required
  end
 
+ def catch_help?
+ @catch_help
+ end
+
  def usage_string
  return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
  end
  end
 
+ # Returns true if there is at least one fixed flag (--version / --help)
+ # Root command always has --version and subcommands always have --help
+ # except when it is consumed by catch_all
+ def fixed_flags?
+ root_command? || !catch_all.catch_help?
+ end
+
  # Returns true if this command's flags should be considered as gloal
  # flags, and cascade to subcommands
  def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
  > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
-> long_usage=yes
-> <%= function_name %>_usage
-> exit
-> ;;
-> 
+unless catch_all.catch_help?
+ = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+ > long_usage=yes
+ > <%= function_name %>_usage
+ > exit
+ > ;;
+ > 
+end
 
 if global_flags?
  flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
- options_caption = strings[:global_options]
-end
-
-> printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
- > printf " %s\n" "{{ '--help'.color(:flag) }}"
-else
- > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+ if short_flag_exist?("-h")
+ > printf " %s\n" "{{ '--help'.color(:flag) }}"
+ else
+ > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
+ end
 
-> printf " {{ strings[:help_flag_text] }}\n"
-> echo
+ > printf " {{ strings[:help_flag_text] }}\n"
+ > echo
+end
 
 if root_command?
  if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+ options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
  "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
  "type": "boolean",
  "default": false
+ },
+ "catch_help": {
+ "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+ "type": "boolean",
+ "default": false
  }
  },
  "additionalProperties": false

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [OPTIONS] [--] [PARAMS...]
+ cli docker --help | -h
+
+Options:
+ --show-help-anyway
+ Show this help message
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/fixtures/catch-all-no-fixed-flags

@@ -0,0 +1,22 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker show-hidden-usage
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [--] [PARAMS...]
+ cli docker --help | -h
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/validations/command_catch_all_catch_help

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.catch_all.catch_help must be a boolean>

spec/fixtures/script/validations.yml

@@ -94,6 +94,13 @@
  help: catch_all must be boolean, string, or hash
  catch_all: [1,2]
 
+:command_catch_all_catch_help:
+ name: invalid
+ help: catch_all.catch_help must be boolean
+ catch_all:
+ label: params
+ catch_help: "this is not a help string"
+
 :command_catch_all_valid:
  name: invalid
  catch_all:

spec/fixtures/workspaces/catch-all-including-help/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-including-help/README.md

@@ -0,0 +1 @@
+This fixture tests that catch all with catch_help is catching the --help flag

spec/fixtures/workspaces/catch-all-including-help/src/bashly.yml

@@ -0,0 +1,18 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true
+
+ # We want to see that the internal usage command still prints normally
+ flags:
+ - long: --show-help-anyway
+ help: Show this help message

spec/fixtures/workspaces/catch-all-including-help/src/docker_command.sh

@@ -0,0 +1,8 @@
+show_help=${args["--show-help-anyway"]-}
+
+if [[ $show_help ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-including-help/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker --show-help-anyway

spec/fixtures/workspaces/catch-all-no-fixed-flags/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-no-fixed-flags/README.md

@@ -0,0 +1,3 @@
+This fixture tests that when catch all is set with catch_help and no other
+flags, the usage text - if called by the developer - is not showing the 
+"Options" caption (since there are now zero options to show)

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/bashly.yml

@@ -0,0 +1,13 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/docker_command.sh

@@ -0,0 +1,6 @@
+if [[ "${other_args[0]}" == "show-hidden-usage" ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-no-fixed-flags/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker show-hidden-usage

spec/fixtures/workspaces/lib-upgrade/src/lib/send_completions.sh

@@ -11,24 +11,46 @@ send_completions() {
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
  echo $' local result=()'
  echo $''
+ echo $' # words the user already typed (excluding the command itself)'
+ echo $' local used=()'
+ echo $' if ((COMP_CWORD > 1)); then'
+ echo $' used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
+ echo $''
  echo $' if [[ "${cur:0:1}" == "-" ]]; then'
+ echo $' # Completing an option: offer everything (including options)'
  echo $' echo "$words"'
  echo $''
  echo $' else'
+ echo $' # Completing a non-option: offer only non-options,'
+ echo $' # and don\'t re-offer ones already used earlier in the line.'
  echo $' for word in $words; do'
- echo $' [[ "${word:0:1}" != "-" ]] && result+=("$word")'
+ echo $' [[ "${word:0:1}" == "-" ]] && continue'
+ echo $''
+ echo $' local seen=0'
+ echo $' for u in "${used[@]}"; do'
+ echo $' if [[ "$u" == "$word" ]]; then'
+ echo $' seen=1'
+ echo $' break'
+ echo $' fi'
+ echo $' done'
+ echo $' ((!seen)) && result+=("$word")'
  echo $' done'
  echo $''
  echo $' echo "${result[*]}"'
- echo $''
  echo $' fi'
  echo $'}'
  echo $''
  echo $'_cli_completions() {'
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
- echo $' local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")'
+ echo $' local compwords=()'
+ echo $' if ((COMP_CWORD > 0)); then'
+ echo $' compwords=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
  echo $' local compline="${compwords[*]}"'
  echo $''
+ echo $' COMPREPLY=()'
+ echo $''
  echo $' case "$compline" in'
  echo $' \'download\'*)'
  echo $' while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--force --help -f -h")" -- "$cur")'

support/runfile/example.rb

@@ -8,7 +8,9 @@ def examples
  end
 
  def fixtures
- filter_dirs('spec/fixtures/workspaces').map { |dir| new dir, type: :fixture }
+ filter_dirs('spec/fixtures/workspaces')
+ .select { |dir| File.exist? "#{dir}/src/bashly.yml" }
+ .map { |dir| new dir, type: :fixture }
  end
 
  def all

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
  assert_string "#{key}.label", value['label']
  assert_optional_string "#{key}.help", value['help']
  assert_boolean "#{key}.required", value['required']
+ assert_boolean "#{key}.catch_help", value['catch_help']
  end
 
  def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
  class CatchAll
  class << self
  def option_keys
- @option_keys ||= %i[label help required]
+ @option_keys ||= %i[label help required catch_help]
  end
 
  def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
  when String
  { label: config }
  when Hash
-{ label: config['label'], help: config['help'], required: config['required'] }
+ config.transform_keys(&:to_sym).slice(*option_keys)
  else
  {}
  end
@@ -22,11 +22,12 @@ def from_config(config)
  end
  end
 
- def initialize(label: nil, help: nil, required: false, enabled: true)
+ def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
  @label = label
  @help = help
  @required = required
  @enabled = enabled
+ @catch_help = catch_help
  end
 
  def enabled?
@@ -45,6 +46,10 @@ def required?
  @required
  end
 
+ def catch_help?
+ @catch_help
+ end
+
  def usage_string
  return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
  end
  end
 
+ # Returns true if there is at least one fixed flag (--version / --help)
+ # Root command always has --version and subcommands always have --help
+ # except when it is consumed by catch_all
+ def fixed_flags?
+ root_command? || !catch_all.catch_help?
+ end
+
  # Returns true if this command's flags should be considered as gloal
  # flags, and cascade to subcommands
  def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
  > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
-> long_usage=yes
-> <%= function_name %>_usage
-> exit
-> ;;
-> 
+unless catch_all.catch_help?
+ = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+ > long_usage=yes
+ > <%= function_name %>_usage
+ > exit
+ > ;;
+ > 
+end
 
 if global_flags?
  flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
- options_caption = strings[:global_options]
-end
-
-> printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
- > printf " %s\n" "{{ '--help'.color(:flag) }}"
-else
- > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+ if short_flag_exist?("-h")
+ > printf " %s\n" "{{ '--help'.color(:flag) }}"
+ else
+ > printf " %s\n" "{{ '--help, -h'.color(:flag) }}"
+ end
 
-> printf " {{ strings[:help_flag_text] }}\n"
-> echo
+ > printf " {{ strings[:help_flag_text] }}\n"
+ > echo
+end
 
 if root_command?
  if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+ options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
  "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
  "type": "boolean",
  "default": false
+ },
+ "catch_help": {
+ "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+ "type": "boolean",
+ "default": false
  }
  },
  "additionalProperties": false

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [OPTIONS] [--] [PARAMS...]
+ cli docker --help | -h
+
+Options:
+ --show-help-anyway
+ Show this help message
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/fixtures/catch-all-no-fixed-flags

@@ -0,0 +1,22 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker show-hidden-usage
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+ cli docker [--] [PARAMS...]
+ cli docker --help | -h
+
+Arguments:
+ PARAMS...
+ Parameters to pass to docker
+

spec/approvals/validations/command_catch_all_catch_help

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.catch_all.catch_help must be a boolean>

spec/fixtures/script/validations.yml

@@ -94,6 +94,13 @@
  help: catch_all must be boolean, string, or hash
  catch_all: [1,2]
 
+:command_catch_all_catch_help:
+ name: invalid
+ help: catch_all.catch_help must be boolean
+ catch_all:
+ label: params
+ catch_help: "this is not a help string"
+
 :command_catch_all_valid:
  name: invalid
  catch_all:

spec/fixtures/workspaces/catch-all-including-help/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-including-help/README.md

@@ -0,0 +1 @@
+This fixture tests that catch all with catch_help is catching the --help flag

spec/fixtures/workspaces/catch-all-including-help/src/bashly.yml

@@ -0,0 +1,18 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true
+
+ # We want to see that the internal usage command still prints normally
+ flags:
+ - long: --show-help-anyway
+ help: Show this help message

spec/fixtures/workspaces/catch-all-including-help/src/docker_command.sh

@@ -0,0 +1,8 @@
+show_help=${args["--show-help-anyway"]-}
+
+if [[ $show_help ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-including-help/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker --show-help-anyway

spec/fixtures/workspaces/catch-all-no-fixed-flags/.gitignore

@@ -0,0 +1 @@
+cli

spec/fixtures/workspaces/catch-all-no-fixed-flags/README.md

@@ -0,0 +1,3 @@
+This fixture tests that when catch all is set with catch_help and no other
+flags, the usage text - if called by the developer - is not showing the 
+"Options" caption (since there are now zero options to show)

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/bashly.yml

@@ -0,0 +1,13 @@
+name: cli
+help: Showing catch all including the help flag
+version: 0.1.0
+
+commands:
+- name: docker
+ help: Pass all arguments to the docker cli
+ catch_all:
+ label: params
+ help: Parameters to pass to docker
+ required: false
+ # Also catch --help | -h as any other param
+ catch_help: true

spec/fixtures/workspaces/catch-all-no-fixed-flags/src/docker_command.sh

@@ -0,0 +1,6 @@
+if [[ "${other_args[0]}" == "show-hidden-usage" ]]; then
+ long_usage=yes
+ cli_docker_usage
+else
+ inspect_args
+fi

spec/fixtures/workspaces/catch-all-no-fixed-flags/test.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+rm -f ./cli
+
+set -x
+
+bundle exec bashly generate
+
+./cli docker --help
+./cli docker show-hidden-usage

spec/fixtures/workspaces/lib-upgrade/src/lib/send_completions.sh

@@ -11,24 +11,46 @@ send_completions() {
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
  echo $' local result=()'
  echo $''
+ echo $' # words the user already typed (excluding the command itself)'
+ echo $' local used=()'
+ echo $' if ((COMP_CWORD > 1)); then'
+ echo $' used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
+ echo $''
  echo $' if [[ "${cur:0:1}" == "-" ]]; then'
+ echo $' # Completing an option: offer everything (including options)'
  echo $' echo "$words"'
  echo $''
  echo $' else'
+ echo $' # Completing a non-option: offer only non-options,'
+ echo $' # and don\'t re-offer ones already used earlier in the line.'
  echo $' for word in $words; do'
- echo $' [[ "${word:0:1}" != "-" ]] && result+=("$word")'
+ echo $' [[ "${word:0:1}" == "-" ]] && continue'
+ echo $''
+ echo $' local seen=0'
+ echo $' for u in "${used[@]}"; do'
+ echo $' if [[ "$u" == "$word" ]]; then'
+ echo $' seen=1'
+ echo $' break'
+ echo $' fi'
+ echo $' done'
+ echo $' ((!seen)) && result+=("$word")'
  echo $' done'
  echo $''
  echo $' echo "${result[*]}"'
- echo $''
  echo $' fi'
  echo $'}'
  echo $''
  echo $'_cli_completions() {'
  echo $' local cur=${COMP_WORDS[COMP_CWORD]}'
- echo $' local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")'
+ echo $' local compwords=()'
+ echo $' if ((COMP_CWORD > 0)); then'
+ echo $' compwords=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")'
+ echo $' fi'
  echo $' local compline="${compwords[*]}"'
  echo $''
+ echo $' COMPREPLY=()'
+ echo $''
  echo $' case "$compline" in'
  echo $' \'download\'*)'
  echo $' while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--force --help -f -h")" -- "$cur")'

support/runfile/example.rb

@@ -8,7 +8,9 @@ def examples
  end
 
  def fixtures
- filter_dirs('spec/fixtures/workspaces').map { |dir| new dir, type: :fixture }
+ filter_dirs('spec/fixtures/workspaces')
+ .select { |dir| File.exist? "#{dir}/src/bashly.yml" }
+ .map { |dir| new dir, type: :fixture }
  end
 
  def all