Argc

Argc is a Bash command line framework that utilizes a special comment-driven syntax to provide a command runner and argument parser.

Here is a simple Argcfile.sh:

# @describe Example Argcfile
# Arguments, options, and flags listed here apply to the main command and all
# subcommands.
#
# For more information about argc, see https://github.com/sigoden/argc
# @option    --name  Name to greet
# @flag -F --foo  Flag param
# @option --bar   Option param
# @option --baz*  Option param (multi-occurs)
# @arg val*       Positional param

main() {
    echo foo: $argc_foo
    echo bar: $argc_bar
    echo baz: ${argc_baz[@]}
    echo val: ${argc_val[@]}
}

if ! command -v argc >/dev/null; then
	echo "This command requires argc. Install from https://github.com/sigoden/argc" >&2
	exit 100
fi
eval "$(argc --argc-eval "$0" "$@")"

Run the script with some sample arguments:

./example.sh -F --bar=xyz --baz a --baz b v1 v2

Argc parses these arguments and creates variables prefixed with argc_:

foo: 1
bar: xyz
baz: a b
val: v1 v2

You can also run ./example.sh --help to see the automatically generated help information for your CLI.

Bash idioms

Prefer using Bash idioms when working with argc. For example, shellcheck isn't aware of the argcfoo variables, so prefer using ${argcfoo:?} for required values and values where argc is known to provide the default. For others, use ${argc_foo:-default}, as appropriate.

Argcfile.sh

Note that running argc directly will attempt to locate a file named Argcfile.sh in the current and parent directories. In this case, argc will always cd into the directory with the Argcfile before executing it, and $ARGC_PWD will be set to the directory the user ran the command from.

Comment Tags

Comment tags are standard Bash comments prefixed with @ and a specific tag. They provide instructions to Argc for configuring your script's functionalities.

Some common forms:

# @arg va
# @arg vb!                        required
# @arg vc*                        multi-values
# @arg vd+                        multi-values + required
# @arg vna <PATH>                 value notation
# @arg vda=a                      default
# @arg vdb=`_default_fn`          default from bash function
# @arg vca[a|b]                   choices
# @arg vcb[=a|b]                  choices + default
# @arg vcc*[a|b]                  multi-values + choice
# @arg vcd+[a|b]                  required + multi-values + choice
# @arg vfa[`_choice_fn`]          choice from bash function
# @arg vfb[?`_choice_fn`]         choice from bash function + no validation
# @arg vfc*[`_choice_fn`]         multi-values + choice from bash function
# @arg vfd*,[`_choice_fn`]        multi-values + choice from bash function + comma-separated list
# @arg vxa~                       capture all remaining args
# @arg vea $$                     bind-env
# @arg veb $BE <PATH>             bind-named-env
# @option    --oa
# @option -b --ob                   short
# @option -c                        short only
# @option    --of*,                 multi-occurs + comma-separated list (also supports all other patterns from @arg)
# @option    --ona <PATH>           value notation
# @option    --onb <FILE> <FILE>    two-args value notations
# @option    --onc <CMD> <FILE+>    unlimited-args value notations
# @option    --oda=a                default
# @option    --odb=`_default_fn`    default from bash function
# @option    --oca[a|b]             choice (supports all patterns from @arg)
# @option    --ofa[`_choice_fn`]    choice from bash function (supports all patterns from @arg)
# @option    --oxa~                 capture all remaining args
# @option    --oea $$               bind-env
# @option    --oeb $BE <PATH>       bind-named-env
# @flag     --fa
# @flag  -b --fb         short
# @flag  -c              short only
# @flag     --fd*        multi-occurs
# @flag     --ea $$      bind-env
# @flag     --eb $BE     bind-named-env
# @env EA                 optional
# @env EB!                required
# @env EC=true            default
# @env EDA[dev|prod]      choices
# @env EDB[=dev|prod]     choices + default

For choicefn, it should print candidates, one per line. choicefn and defaultfn must be bash functions, they are not arbitrary commands. "bind-env" means the variable default comes from the environment. For the environment variables, argc does not create argc_ variables (just validates existing variables).

Most common @meta options:

• Set a version on the top-level of the script: @meta version 1.0.0
• Require tools installed (usable at top-level and subcommands): @meta require-tools git,yq

Use @describe at the top level of the script and @cmd for subcommands. The first line is the short description, and subsequent comment lines that aren't comment tags are the long description.

Further Documentation

• Specification for the grammar and usage of all the comment tags.
• Variables that are predefined by argc.
• Examples for particularly complex scenarios.