Argc

Argc is a powerful Bash framework that simplifies building full-featured CLIs. It lets you define your CLI through comments, focusing on your core logic without dealing with argument parsing, usage text, error messages, and other boilerplate code.

Features

• Effortless Argument Parsing:
  • Handles flags, options, positional arguments, and subcommands.
  • Validates user input for robust error handling.
  • Generates information-rich usage text.
  • Maps arguments to corresponding variables.
• Standalone Bash Script Creation:
  • Build a bash script that incorporates all functionalities without depending on Argc itself.
• Cross-shell Autocompletion:
  • Generate autocompletion scripts for various shells (bash, zsh, fish, powershell, etc.).
• Man Page Generation:
  • Automatically create comprehensive man page documentation for your script.
• Environment Variable Integration:
  • Define, validate, and bind environment variables to options and positional arguments.
• Task Automation:
  • A Bash-based command runner that automates tasks via Argcfile.sh.
• Cross-Platform Compatibility:
  • Seamlessly run your Argc-based scripts on macOS, Linux, Windows, and BSD systems.

Install

Package Managers

• Rust Developers: cargo install argc
• Homebrew/Linuxbrew Users: brew install argc
• Pacman Users: yay -S argc

Pre-built Binaries

Alternatively, download pre-built binaries for macOS, Linux, and Windows from GitHub Releases, extract it, and add the argc binary to your $PATH.

You can use the following command on Linux, MacOS, or Windows to download the latest release.

curl -fsSL https://raw.githubusercontent.com/sigoden/argc/main/install.sh | sh -s -- --to /usr/local/bin

GitHub Actions

install-binary can be used to install argc in a GitHub Actions workflow.

  - uses: sigoden/install-binary@v1
    with:
      repo: sigoden/argc

Get Started

Building a command-line program using Argc is a breeze. Just follow these two steps:

1. Design Your CLI Interface:

Describe options, flags, positional parameters, and subcommands using comment tags (explained later).

2. Activate Argument Handling:

Add this line to your script: eval "$(argc --argc-eval "$0" "$@")". This integrates Argc's parsing magic into your program.

Let's illustrate with an example:

# @flag -F --foo  Flag param
# @option --bar   Option param
# @option --baz*  Option param (multi-occurs)
# @arg val*       Positional param

eval "$(argc --argc-eval "$0" "$@")"

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

Run the script with some sample arguments:

./mycli -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

Just run ./mycli --help to see the automatically generated help information for your CLI:

Usage: mycli [OPTIONS] [VAL]...

Args:
  [VAL]...  Positional param

Options:
  -F, --foo           Flag param
      --bar <BAR>     Option param
      --baz [BAZ]...  Option param (multi-occurs)
  -h, --help          Print help
  -V, --version       Print version

argc reads the comment tags, parses the command line, and prints shell code that sets the argc_* variables and calls the selected function. The final eval executes that code, which is why the script works with plain Bash.

With these simple steps, you're ready to leverage Argc and create robust command-line programs!

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.

See the comment tag for tag formats and behavior, and the grammar for formal syntax.

Argcscript

Argc is also a command runner built for those who love the efficiency and flexibility of Bash scripting.

Similar to how Makefile define commands for the make tool, Argcscript uses an Argcfile.sh to store your commands, referred to as "recipes".

Why Choose Argc for Your Projects?

• Leverage Bash Skills: No need to learn a new language, perfect for Bash aficionados.
• GNU Toolset Integration: Utilize familiar tools like awk, sed, grep, find, and others.
• Environment variables Management: Load dotenv, document, and validate environment variables effortlessly.
• Powerful Shell Autocompletion: Enjoy autocomplete suggestions for enhanced productivity.
• Cross-Platform Compatibility: Works seamlessly across Linux, macOS, Windows, and BSD systems.

Use argc --argc-create to quickly generate a boilerplate Argcfile.sh:

argc --argc-create - build test     # '-' is an alias for Argcfile.sh

You can also generate a standalone argc-based script with a custom name, or an explicit path:

argc --argc-create mycli foo bar    # Create ./mycli
argc --argc-create /tmp/mycli foo   # Create /tmp/mycli

Any argc script can also be used as a project command runner. Name it Argcfile.sh and run its recipes through argc:

mv mycli Argcfile.sh
argc build
argc test

argc finds Argcfile.sh in the current directory or one of its parents, so you can run recipes from a subdirectory without changing back to the project root.

See command runner for more details.

Completions

Argc automatically provides shell completions for all argc-based scripts.

argc --argc-completions <SHELL> [CMDS]...

In the following, we use mycli and mycli2 as examples to show how to add a completion script for various shells.

# bash (~/.bashrc)
source <(argc --argc-completions bash mycli mycli2)

# zsh (~/.zshrc)
source <(argc --argc-completions zsh mycli mycli2)

# powershell ($PROFILE)
Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete
argc --argc-completions powershell mycli mycli2 | Out-String | Invoke-Expression

# fish (~/.config/fish/config.fish)
argc --argc-completions fish mycli mycli2 | source

# nushell (~/.config/nushell/config.nu)
argc --argc-completions nushell | save --append $nu.config-path

The core of all completion scripts is to call argc --argc-compgen to obtain completion candidates.

$ argc --argc-compgen bash ./mycli mycli --
--foo (Flag param)
--bar (Option param)
--baz (Option param (multi-occurs))
--help (Print help)
--version (Print version)

So argc is also a completion engine, see argc-completions.

See Compgen for the completion engine and completion values.

Argc-build

Generate an independent bash script that incorporates all functionalities typically available when the argc command is present.

The generated script removes the argc dependency, enhances compatibility, and enables deployment in a wider range of environments.

argc --argc-build <SCRIPT> [OUTPATH]

argc --argc-build ./mycli ./build/mycli

./build/mycli -h     # The script's functionality does not require the `argc` dependency

Argc-mangen

Generate man pages for your argc-based CLI.

argc --argc-mangen <SCRIPT> <OUTDIR>

argc --argc-mangen ./mycli man/

man man/mycli.1

Documentation

The full documentation is in docs/README.md.

• Comment Tags — every tag, its format, behavior, and examples
• Argc Tooling — standalone builds, man pages, JSON export, and parallel execution
• Command Runner — recipes, dependencies, hooks, and environment variables
• Metadata - Every supported @meta key and its behavior
• Compgen — completion engine, candidate protocol, and patterns
• External Subcommands — delegating to scripts discovered next to the main script
• Examples - Runnable example scripts for tags and runner features

License

Copyright (c) 2023-2026 argc developers.

argc is made available under the terms of either the MIT License or the Apache License 2.0, at your option.

See the LICENSE-APACHE and LICENSE-MIT files for license details.