Argbash skill

argbash

argbash turns declarative # ARG_* macro comments into pure-bash argument-parsing code. The macros are the source of truth; the parsing block is generated output — treat it like a compiled artifact: regenerate it, never hand-edit it. The generated script has no runtime dependency on argbash (plain bash only).

Workflow

The loop is declare macros → generate → edit macros → regenerate.

1. Scaffold a template with argbash-init (don't write one from scratch). Repeat the flags — one per argument. The output filename is positional:

   argbash-init --pos INPUT --opt OUTPUT --opt-bool VERBOSE script.m4
   

   --pos = positional, --opt = --name VALUE option, --opt-bool = flag. Done when: script.m4 has one ARG_* comment line per argument you need.

2. Fill in the macros. Edit each ARG_* line to add its help text and any default (see Common macros); replace every <...> placeholder. Done when: no <...> placeholders remain and each argument has help + default.

3. Generate the script:

   argbash script.m4 -o script.sh && chmod +x script.sh
   

   Done when: the command exits 0 and script.sh runs.

4. Verify against the real interface:

   ./script.sh --help        # every argument must appear
   ./script.sh <real args>   # $_arg_* must hold the expected values
   

   Done when: --help lists every argument and a real invocation sets each $_arg_<name> as expected.

Editing an existing argbash script: change the ARG_* comments in place, then rerun the same command over the script itself — argbash is idempotent:

argbash script.sh -o script.sh

Converting a hand-rolled getopts/while-case-shift script: read off its arguments, scaffold a matching template (step 1), then generate (step 3).

Common macros

Write these as bash comments — prefix # ARG_, no @. Parameters go in square brackets; leave optional ones blank (ARG_OPTIONAL_BOOLEAN([v], , [help], )).

Macro	Declares
ARG_POSITIONAL_SINGLE([name], [help], [default])	one positional (mandatory unless a default is given)
ARG_POSITIONAL_MULTI([name], [help], [count], [defaults...])	a fixed count of positionals → array
ARG_OPTIONAL_SINGLE([name], [short], [help], [default])	--name VALUE
ARG_OPTIONAL_BOOLEAN([name], [short], [help], [default])	--name / --no-name flag (on/off)
ARG_OPTIONAL_REPEATED([name], [short], [help], [default])	repeatable → appends to an array
ARG_OPTIONAL_INCREMENTAL([name], [short], [help], [default])	counter, e.g. -vvv
ARG_OPTIONAL_ACTION([name], [short], [help], [code])	runs code then exits
ARG_HELP([blurb])	-h / --help (usage is auto-generated even without this)
ARG_VERSION([code], [short])	-v / --version; code prints the version
ARG_DEFAULTS_POS	declare every positional's variable (silences shellcheck)
ARGBASH_GO	marks where the generated parser goes — required, place last

Using the results

Each argument becomes a shell variable: lowercased, dashes → underscores, prefixed _arg_. So --include-path → $_arg_include_path.

• Booleans are the strings on / off — [ "$_arg_verbose" = on ]. --no-verbose forces off.
• Repeated / multi land in bash arrays — "${_arg_include[@]}".
• Incremental is an integer — [ "$_arg_verbose" -ge 1 ].
• A die "<msg>" [<exit-code>] function is available in the generated script.

Template shape

argbash-init emits this skeleton. Keep the m4_ignore lines and the # [ / # ] guards — they make regeneration idempotent and stop argbash from stripping a bracket level out of your code:

#!/usr/bin/env bash
# m4_ignore(
echo "This is just a script template, not the script (yet) - pass it to 'argbash' to fix this." >&2
exit 11 #)Created by argbash-init v2.11.0
# ARG_POSITIONAL_SINGLE([name], [person to greet])
# ARG_OPTIONAL_SINGLE([times], [n], [how many times to greet], [1])
# ARG_OPTIONAL_BOOLEAN([shout], [s], [uppercase the greeting], [off])
# ARG_HELP([Greets a person a number of times.])
# ARGBASH_GO
# [ <-- needed because of Argbash

greeting="Hello, $_arg_name"
[ "$_arg_shout" = on ] && greeting="${greeting^^}"
for ((i = 0; i < _arg_times; i++)); do echo "$greeting"; done

# ] <-- needed because of Argbash

Gotchas

• -h and -v are already taken. ARG_HELP claims -h, ARG_VERSION claims -v. To use -v for verbose, move version's short option (ARG_VERSION([echo 1.0.0], [V])) or drop it — argbash errors on the collision.
• A defaulted positional can't precede ARG_POSITIONAL_MULTI — argbash can't know how many fixed values come first. Declare fixed-count positionals first.
• Square brackets in the body lose one level unless they sit between the # [ / # ] guards. Keep your code inside the guards; for heavy [...] (regex, globs) use a separate parsing file (see reference).
• You can't tell whether an optional was passed from its value alone (bash can't tell unset from empty). Use ARGBASH_INDICATE_SUPPLIED (see reference).
• No argbash locally? Use the web generator at https://argbash.dev or the Docker image (see reference) — only generating needs argbash, not running the result.

Advanced

For typed/validated args (int, enum, …), wrapping other argbash scripts, separate parsing files, verbose/leftovers/env/program macros, and alternate outputs (POSIX, bash-completion, manpage, docopt), see reference.md.