using-argc-argcfile

Create and modify Argcfiles using the special syntax required. Use this when editing Argcfile.sh, @argc, or any shell script that contains `argc --argc-eval`.

⭐13stars🔀3forks📁View on GitHub🕐Updated Jan 2, 2026

When & Why to Use This Skill

This Claude skill facilitates the creation and modification of Argcfiles, a specialized Bash command-line framework. By utilizing a comment-driven syntax, it allows developers to transform standard shell scripts into sophisticated CLI tools with automated argument parsing, subcommand routing, and help documentation generation, significantly improving script maintainability and usability.

Use Cases

  • Developing robust CLI applications: Quickly generate Argc-compliant Bash scripts that handle complex arguments, flags, and options automatically without manual parsing logic.
  • Standardizing DevOps scripts: Enhance infrastructure-as-code or deployment scripts with structured metadata and auto-generated help menus for better team collaboration.
  • Refactoring legacy shell scripts: Convert manual 'getopts' or positional argument logic into clean, maintainable, and declarative comment-driven Argc syntax.
  • Creating interactive runbooks: Build self-documenting scripts that provide clear usage instructions and validation for IT automation and system administration tasks.
nameUsing `argc` / `Argcfile`
descriptionCreate and modify Argcfiles using the special syntax required. Use this when editing Argcfile.sh, @argc, or any shell script that contains `argc --argc-eval`.

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 argc_foo variables, so prefer using ${argc_foo:?} 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.

Tag Description
@describe Sets the description for the command.
@cmd Defines a subcommand.
@alias Sets aliases for the subcommand.
@arg Defines a positional argument.
@option Defines an option argument.
@flag Defines a flag argument.
@env Defines an environment variable.
@meta Adds metadata.

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 _choice_fn, it should print candidates, one per line. _choice_fn and _default_fn 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.