Marketplace 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`.

install

source · Clone the upstream repo

git clone https://github.com/aiskillstore/marketplace

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/aiskillstore/marketplace "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/cgamesplay/using-argc-argcfile" ~/.claude/skills/aiskillstore-marketplace-using-argc-argcfile && rm -rf "$T"

manifest: skills/cgamesplay/using-argc-argcfile/SKILL.md

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.