### Running Positional Argument Examples

Source: https://context7.com/sigoden/argc/llms.txt

Examples of how to run scripts with different positional argument configurations and their expected output or errors.

```bash
./script.sh cmd_required myfile.txt
# Output: File: myfile.txt

./script.sh cmd_multi file1.txt file2.txt file3.txt
# Output: Files: file1.txt file2.txt file3.txt

./script.sh cmd_default
# Output: Format: json

./script.sh cmd_choices warn
# Output: Level: warn

./script.sh cmd_choices invalid
# Error: invalid value `invalid` for `<LEVEL>`
```

--------------------------------

### Multiline Description Example

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

Demonstrates how to provide multiline descriptions for commands or arguments using the `@describe` directive.

```sh
# @describe Can be multiline 
#
# Extra lines after the comment tag accepts description, which don't start with an `@`,
# are treated as the long description. A line which is not a comment ends the block.
```

--------------------------------

### Install Argc in GitHub Actions

Source: https://github.com/sigoden/argc/blob/main/README.md

Use the install-binary action to install Argc within a GitHub Actions workflow.

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

--------------------------------

### Executing Script with Hooks

Source: https://context7.com/sigoden/argc/llms.txt

Shows the output of running the 'test' and 'build' commands on a script that utilizes before and after hooks for setup and cleanup.

```bash
./script.sh test
# Output:
# === Setup: Loading configuration ===
# Running tests...
# === Cleanup: Took 1 seconds ===

./script.sh build
# Output:
# === Setup: Loading configuration ===
# Building project...
# === Cleanup: Took 2 seconds ===
```

--------------------------------

### Bash Script with Before and After Hooks

Source: https://context7.com/sigoden/argc/llms.txt

A bash script demonstrating the use of `_argc_before` for setup and `_argc_after` for cleanup logic, including timing execution.

```bash
#!/usr/bin/env bash
set -e

# @describe Script with hooks

_argc_before() {
    echo "=== Setup: Loading configuration ==="
    export START_TIME=$(date +%s)
}

_argc_after() {
    END_TIME=$(date +%s)
    echo "=== Cleanup: Took $((END_TIME - START_TIME)) seconds ==="
}

# @cmd Run tests
test() {
    echo "Running tests..."
    sleep 1
}

# @cmd Build project
build() {
    echo "Building project..."
    sleep 2
}

main() {
    echo "Running main..."
}

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

--------------------------------

### Install Argc via Pacman

Source: https://context7.com/sigoden/argc/llms.txt

Install Argc on Arch Linux using the Pacman package manager.

```bash
yay -S argc
```

--------------------------------

### Install Argc via curl

Source: https://github.com/sigoden/argc/blob/main/README.md

Download and install the latest Argc release using curl. Ensure the binary is added to your PATH.

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

--------------------------------

### Displaying Subcommands

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

This is an example of how subcommands defined with `@cmd` are presented in the CLI's usage help message.

```text
USAGE: prog <COMMAND>

COMMANDS:
  upload    Upload a file
  download  Download a file
```

--------------------------------

### Install Argc via Cargo

Source: https://context7.com/sigoden/argc/llms.txt

Install Argc using the Cargo package manager if you are a Rust developer.

```bash
cargo install argc
```

--------------------------------

### Displaying Subcommands with Aliases

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

This example shows how subcommands with defined aliases appear in the CLI's usage help message.

```text
USAGE: prog <COMMAND>

COMMANDS:
  test  Run tests [aliases: t, tst]
```

--------------------------------

### Install Argc via Homebrew

Source: https://context7.com/sigoden/argc/llms.txt

Install Argc on macOS or Linux using the Homebrew package manager.

```bash
brew install argc
```

--------------------------------

### Example Output of Argc-Generated Variables

Source: https://github.com/sigoden/argc/blob/main/docs/variables.md

Illustrates the expected output when running a script with defined options, flags, and arguments, showing how values are parsed and displayed.

```shell
--oa: a
--ob: b1 b2
--fa: 1
  va: foo
  vb: bar baz
```

--------------------------------

### Basic CLI Script Setup with Argc

Source: https://context7.com/sigoden/argc/llms.txt

Set up a basic CLI script using Argc. The `eval` line activates argument parsing. Define flags, options, and positional arguments using comment tags.

```bash
#!/usr/bin/env bash

# @describe A demo CLI application
# @flag -F --foo  Flag parameter
# @option --bar   Option parameter
# @option --baz*  Option parameter (multi-occurs)
# @arg val*       Positional parameter

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

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

--------------------------------

### Argc Generated Help Information

Source: https://github.com/sigoden/argc/blob/main/README.md

Example of automatically generated help message for an Argc-defined CLI. Use `--help` to display it.

```text
USAGE: example [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

```

--------------------------------

### Configure Script Metadata and Behavior

Source: https://context7.com/sigoden/argc/llms.txt

Demonstrates using the `@meta` tag for script-level configurations such as version, dotenv files, required tools, combining short flags, and inheriting flag options. Includes examples of subcommands.

```bash
# @describe My CLI application
# @meta version 1.0.0
# @meta dotenv .env.local
# @meta require-tools git,docker
# @meta combine-shorts
# @meta inherit-flag-options

# @flag -v --verbose  Enable verbose output

# @cmd Build the project
# @meta require-tools make
build() {
    echo "Building..."
}

# @cmd Deploy the project
# @meta default-subcommand
deploy() {
    echo "Deploying..."
}

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

```bash
# Shows version
./script.sh --version
# Output: 1.0.0

# Default subcommand runs when no command specified
./script.sh
# Output: Deploying...

# Inherited flags work on subcommands
./script.sh build -v
# verbose flag available in build command

# Missing required tool error
./script.sh build  # when 'make' is not installed
# Error: require-tools: make
```

--------------------------------

### Install Bash and GNU Tools on MacOS

Source: https://github.com/sigoden/argc/blob/main/README.md

On macOS, it's recommended to install Bash version 5 and GNU tools using Homebrew for better compatibility and functionality. Update the PATH environment variable to include these tools.

```bash
brew install bash coreutils gawk gnu-sed grep

export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gawk/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/grep/libexec/gnubin:$PATH"
```

--------------------------------

### Basic Alias Usage in Argc

Source: https://context7.com/sigoden/argc/llms.txt

Demonstrates the use of simple aliases 'b' and 't' with the argc command. These are fundamental examples of how argc can be invoked.

```bash
argc b
```

```bash
argc t
```

--------------------------------

### Argcfile.sh - Command Runner Script

Source: https://context7.com/sigoden/argc/llms.txt

An example `Argcfile.sh` script that defines various project tasks like build, test, check, fix, and deploy, with aliases and options.

```bash
#!/usr/bin/env bash
set -e

# @meta dotenv

# @cmd Build the project
# @alias b
build() {
    echo "Building..."
    cargo build --release
}

# @cmd Run tests
# @alias t
# @option --filter  Filter tests by name
test() {
    cargo test ${argc_filter:+--test $argc_filter}
}

# @cmd Format and lint code
# @alias c
check() {
    cargo fmt --all --check
    cargo clippy --all
}

# @cmd Fix formatting issues
# @alias f
fix() {
    cargo fmt --all
    cargo clippy --fix --all --allow-dirty
}

# @cmd Deploy to environment
# @arg env![dev|staging|prod]  Target environment
deploy() {
    echo "Deploying to $argc_env..."
}

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

--------------------------------

### Get Completion Candidates with Argc

Source: https://github.com/sigoden/argc/blob/main/README.md

The core of all completion scripts involves calling `argc --argc-compgen` to obtain completion candidates for a given script and arguments.

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

--------------------------------

### Basic Argc CLI Example

Source: https://github.com/sigoden/argc/blob/main/README.md

Define a simple CLI with flags, options, and positional arguments using Argc comment tags. The `eval "$(argc --argc-eval \"$0\" \"$@\")"` line activates Argc's parsing.

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

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

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

--------------------------------

### Shell Completion Scripts for Argc

Source: https://context7.com/sigoden/argc/llms.txt

Provides examples of how to source shell completion scripts for argc-generated CLIs in various shells like Bash, Zsh, Fish, PowerShell, Elvish, and Tcsh.

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

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

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

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

# Elvish (~/.config/elvish/rc.elv)
eval (argc --argc-completions elvish mycli | slurp)

# Tcsh (~/.tcshrc)
eval `argc --argc-completions tcsh mycli`
```

--------------------------------

### Building a Standalone Argc Script

Source: https://context7.com/sigoden/argc/llms.txt

Command to build a standalone Bash script from an existing argc-based CLI, allowing it to run without the argc interpreter installed.

```bash
# Build standalone version
argc --argc-build ./mycli.sh ./dist/

# The built script works without argc installed
./dist/mycli.sh --help
```

--------------------------------

### Creating and Running Argcfile Tasks

Source: https://context7.com/sigoden/argc/llms.txt

Demonstrates creating a starter `Argcfile.sh` and then running defined tasks like 'build', 'test' with filters, and 'deploy'.

```bash
# Create starter Argcfile.sh
argc --argc-create build test deploy

# Run tasks
argc build
argc test --filter=integration
argc deploy prod
```

--------------------------------

### Running a Basic CLI Script and Help Output

Source: https://context7.com/sigoden/argc/llms.txt

Demonstrates how to run the basic CLI script with various arguments and how to view the auto-generated help text.

```bash
# Run the script
./example.sh -F --bar=xyz --baz a --baz b v1 v2

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

# Auto-generated help
./example.sh --help

# Output:
# USAGE: example [OPTIONS] [VAL]...
# 
# ARGS:
#   [VAL]...  Positional parameter
# 
# OPTIONS:
#   -F, --foo           Flag parameter
#       --bar <BAR>     Option parameter
#       --baz [BAZ]...  Option parameter (multi-occurs)
#   -h, --help          Print help
#   -V, --version       Print version
```

--------------------------------

### List and Create Builders

Source: https://context7.com/sigoden/argc/llms.txt

Demonstrates listing available builders and creating new image manifests using the script.sh utility.

```bash
./script.sh builder imagetools create
```

```bash
./script.sh builder --help
```

--------------------------------

### Running Subcommands and Aliases

Source: https://context7.com/sigoden/argc/llms.txt

Demonstrates how to run defined subcommands, including using aliases and passing options.

```bash
# Run upload subcommand
./demo.sh upload myfile.txt
# Output: Uploading: myfile.txt

# Run download with options
./demo.sh download -f --tries=3 https://example.com/file.zip output.zip
# Output:
# Downloading from: https://example.com/file.zip
# Saving to: output.zip
# Force: 1
# Tries: 3

# Use alias
./demo.sh d https://example.com/file.zip
```

--------------------------------

### Create Argcfile.sh

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Use `--argc-create` to generate a basic Argcfile.sh with specified recipes. This sets up the initial structure for your commands.

```sh
argc --argc-create build test
```

--------------------------------

### Deploying with Environment Variable Binding

Source: https://context7.com/sigoden/argc/llms.txt

Illustrates deploying a service by setting environment variables, and shows how CLI arguments can override these environment variable bindings.

```bash
# Set via environment variables
HOST=myserver.com APP_PORT=3000 API_TOKEN=secret123 ENVIRONMENT=production \
./script.sh deploy

# Output:
# Host: myserver.com
# Port: 3000
# Token: secret123
# Environment: production

# CLI args override env vars
HOST=default ./script.sh deploy --host=override.com production
# Output:
# Host: override.com
```

--------------------------------

### Define and Use Various Option Types

Source: https://context7.com/sigoden/argc/llms.txt

Demonstrates defining options with different types like basic, short/long form, required, multi-occurs, file completion, default values, and choices. Ensure the `options_demo` function is defined and evaluated with `argc`.

```bash
# @cmd Various option types
# @option --config              Basic option
# @option -o --output           Short and long form
# @option --port!               Required option
# @option --tag*                Multi-occurs (can be repeated)
# @option --include+            Required + multi-occurs
# @option --hosts*,             Multi-occurs, comma-separated
# @option --file <PATH>         With value notation (enables file completion)
# @option --src <FILE> <FILE>   Two required values
# @option --level=info          With default value
# @option --format[json|yaml|toml]     With choices
# @option --env[=dev|prod|staging]     Choices + default
# @option --target[`_choice_target`]   Dynamic choices
options_demo() {
    echo "config: $argc_config"
    echo "output: $argc_output"
    echo "port: $argc_port"
    echo "tags: ${argc_tag[@]}"
    echo "includes: ${argc_include[@]}"
    echo "hosts: ${argc_hosts[@]}"
    echo "file: $argc_file"
    echo "level: $argc_level"
    echo "format: $argc_format"
    echo "env: $argc_env"
}

_choice_target() {
    echo "x86_64-linux"
    echo "aarch64-linux"
    echo "x86_64-darwin"
}

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

```bash
./script.sh options_demo \
    --config=app.conf \
    -o build/ \
    --port=8080 \
    --tag=v1 --tag=v2 \
    --include=src --include=lib \
    --hosts=host1,host2,host3 \
    --file=/path/to/file.txt \
    --format=yaml \
    --target=x86_64-linux

# Output:
# config: app.conf
# output: build/
# port: 8080
# tags: v1 v2
# includes: src lib
# hosts: host1 host2 host3
# file: /path/to/file.txt
# level: info
# format: yaml
# env: dev
```

--------------------------------

### Running Tasks in Parallel

Source: https://context7.com/sigoden/argc/llms.txt

Demonstrates executing the `run_all` command, which triggers tasks 1, 2, and 3 to run in parallel, significantly reducing total execution time.

```bash
time ./script.sh run_all
# All three tasks run concurrently, completing in ~2 seconds instead of ~6

# Output:
# Task 1 complete: arg1
# Task 2 complete: arg2
# Task 3 complete: arg3
# real    0m2.XXXs
```

--------------------------------

### Define and Use Flags, Options, and Arguments

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Define flags (`@flag`), options (`@option`), and positional arguments (`@arg`) for recipes. The values are then available in variables prefixed with `argc_`.

```sh
# @cmd  A simple command
# @flag -f --flag   A flag parameter
# @option -option   A option parameter
# @arg arg          A positional parameter
cmd() {
  echo "flag:    $argc_flag"
  echo "option:  $argc_option"
  echo "arg:     $argc_arg"
}
```

--------------------------------

### Set Default Recipe with `@meta default-subcommand`

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Alternatively, use the `@meta default-subcommand` tag above a recipe to designate it as the default command to run.

```sh
# @cmd
# @meta default-subcommand
build() { :; }

# @cmd
test() { :; }
```

--------------------------------

### Testing Shell Completion Generation

Source: https://context7.com/sigoden/argc/llms.txt

Shows how to test shell completion generation for a specific script and command using `argc --argc-compgen`.

```bash
# Test completion generation
argc --argc-compgen bash ./script.sh script --
# Output:
# --verbose (Enable verbose mode)
# --help (Print help)
# --version (Print version)
```

--------------------------------

### Initializing and Using Argc-Generated Variables

Source: https://github.com/sigoden/argc/blob/main/docs/variables.md

Shows how to initialize Argc variables using the eval command and access them, including options, flags, and positional arguments. Multiple values for options/arguments are accessed as arrays.

```shell
# @option --oa
# @option --ob*  # Multiple values allowed
# @flag   --fa
# @arg va
# @arg vb*

eval "$(argc --argc-eval \"$0\" "$@")"  # Initializes Argc variables

echo '--oa:' $argc_oa
echo '--ob:' ${argc_ob[@]}  # Accessing multiple values as an array
echo '--fa:' $argc_fa
echo '  va:' $argc_va
echo '  vb:' ${argc_vb[@]}
```

--------------------------------

### Set Default Recipe with `main` Function

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Define a `main` function to specify a default recipe that runs automatically when Argc is invoked without a specific command.

```sh
# @cmd
build() { :; }

# @cmd
test() { :; }

main() {
  build
}
```

--------------------------------

### Require Tools and Set Man Section

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

Specify required system tools with `@meta require-tools` and override the man page section with `@meta man-section`.

```sh
# @meta require-tools git,yq
```

```sh
# @meta man-section 8
```

--------------------------------

### Set Version and Load Dotenv

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

Use `@meta version` to specify the application version and `@meta dotenv` to load environment variables from a file.

```sh
# @meta version 1.0.0
# @meta dotenv
```

```sh
# @meta dotenv .env.local
```

--------------------------------

### Create Recipe Aliases

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Use the `@alias` tag to provide alternative names for invoking recipes from the command line, simplifying command execution.

```sh
# @cmd
# @alias t
test() {
  echo test
}
```

--------------------------------

### Organize Recipes into Groups

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Group related recipes using specific naming conventions like `foo:bar`, `foo.bar`, or `foo@bar` for better organization and readability.

```sh
# @cmd
test() { :; }
# @cmd
test-unit() { :; }
# @cmd
test-bin() { :; }
```

--------------------------------

### Define Nested Subcommands

Source: https://context7.com/sigoden/argc/llms.txt

Illustrates creating multi-level command hierarchies using `::` in function names for nested subcommands. This allows for a Docker-like CLI structure.

```bash
# @describe Docker-like CLI with nested commands

# @cmd Manage builds
builder() { :; }

# @cmd List builders
builder::ls() {
    echo "Listing builders..."
}

# @cmd Remove build cache
builder::prune() {
    echo "Pruning build cache..."
}

# @cmd Manage images
builder::imagetools() { :; }

# @cmd Create image manifest
builder::imagetools::create() {
    echo "Creating image manifest..."
}

# @cmd Inspect image
builder::imagetools::inspect() {
    echo "Inspecting image..."
}

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

```bash
./script.sh builder ls
```

--------------------------------

### Option Arguments with Argc

Source: https://context7.com/sigoden/argc/llms.txt

This section would typically demonstrate defining and using option arguments with the `@option` tag in Argc.

```bash
#!/usr/bin/env bash


```

--------------------------------

### Handle Recipe Dependencies

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Manage dependencies between recipes by calling them sequentially within other recipe functions. This ensures proper execution order.

```sh
# @cmd
current() { before;
  echo current
after; }

# @cmd
before() {
  echo before
}

# @cmd
after() {
  echo after
}
```

--------------------------------

### Generate Man Pages with Argc

Source: https://github.com/sigoden/argc/blob/main/README.md

Use `argc --argc-mangen` to generate man pages for your argc-based CLI scripts. Specify the script path and an output directory.

```bash
argc --argc-mangen ./example.sh man/

man man/example.1
```

--------------------------------

### Set Command Description with @describe

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

Use the `@describe` tag to set the description for a command. This description is typically displayed in the help message.

```sh
# @describe A demo CLI
```

--------------------------------

### Generate Shell Completions with Argc

Source: https://github.com/sigoden/argc/blob/main/README.md

Argc automatically provides shell completions. Use `argc --argc-completions` to generate completion scripts for various shells by specifying the shell type and the commands.

```bash
# bash (~/.bashrc)
source <(argc --argc-completions bash cmd1 cmd2)

# elvish (~/.config/elvish/rc.elv)
eval (argc --argc-completions elvish cmd1 cmd2 | slurp)

# fish (~/.config/fish/config.fish)
argc --argc-completions fish cmd1 cmd2 | source

# nushell (~/.config/nushell/config.nu)
argc --argc-completions nushell cmd1 cmd2 # update config.nu manually according to output

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

# xonsh (~/.config/xonsh/rc.xsh)
exec($(argc --argc-completions xonsh cmd1 cmd2))

# zsh (~/.zshrc)
source <(argc --argc-completions zsh cmd1 cmd2)

# tcsh (~/.tcshrc)
eval `argc --argc-completions tcsh cmd1 cmd2`
```

--------------------------------

### Load Environment Variables from `.env` File

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Use the `@meta dotenv` directive to automatically load environment variables from a specified `.env` file into the current shell session.

```sh
# @meta dotenv                                    # Load .env
# @meta dotenv .env.local                         # Load .env.local
```

--------------------------------

### Define and Validate Environment Variables

Source: https://context7.com/sigoden/argc/llms.txt

Shows how to define and validate environment variables using the `@env` tag. Supports required variables, defaults, and choices. The `@meta dotenv` directive can load variables from a file.

```bash
# @meta dotenv
# @env DATABASE_URL!              Required env var
# @env LOG_LEVEL=info             With default
# @env NODE_ENV[dev|prod|test]    With choices
# @env DEBUG[=false|true]         Choices + default

# @cmd Show environment
show_env() {
    echo "DATABASE_URL: $DATABASE_URL"
    echo "LOG_LEVEL: $LOG_LEVEL"
    echo "NODE_ENV: $NODE_ENV"
    echo "DEBUG: $DEBUG"
}

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

```bash
# Create .env file
echo "DATABASE_URL=postgres://localhost/mydb" > .env

# Run with environment validation
DATABASE_URL=postgres://localhost/db NODE_ENV=prod ./script.sh show_env

# Output:
# DATABASE_URL: postgres://localhost/db
# LOG_LEVEL: info
# NODE_ENV: prod
# DEBUG: false

# Missing required env var
./script.sh show_env
# Error: the following required environments were not provided:
#   DATABASE_URL
```

--------------------------------

### Align Project Root Directory

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Argc automatically changes the directory (`cd`) to the location of the `Argcfile.sh` it finds. `PWD` reflects the project root, while `ARGC_PWD` reflects the current working directory.

```sh
# @cmd
build() {
    echo $PWD
    echo $ARGC_PWD
}
```

--------------------------------

### Generating Man Pages with Argc

Source: https://context7.com/sigoden/argc/llms.txt

Command to generate man pages for an argc-based CLI, outputting them to a specified directory.

```bash
# Generate man pages
argc --argc-mangen ./mycli.sh ./man/

# View the generated man page
man ./man/mycli.1
```

--------------------------------

### Document and Validate Environment Variables

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Document environment variables using `@env`, specifying their name, description, and optional validation rules like required status (`BAR!`) or allowed values (`MODE[dev|prod]`).

```sh
# @env  FOO               A env var
# @env  BAR!              A required env var
# @env  MODE[dev|prod]    A env var with possible values
```

--------------------------------

### Accessing Shell Variables in Argc

Source: https://github.com/sigoden/argc/blob/main/docs/variables.md

Demonstrates how standard shell variables can be used directly within argc-based scripts without special handling.

```shell
# @cmd
cmd() {
  echo $1 $2  # Accessing positional arguments
  echo "$*"   # All arguments as a single string
  echo "$@"   # All arguments as separate strings
}
```

--------------------------------

### Define Subcommands with @cmd

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

The `@cmd` tag is used to define subcommands for your CLI. Each subcommand can have its own description.

```sh
# @cmd Upload a file
upload() {
  echo Run upload
}

# @cmd Download a file
download() {
  echo Run download
}
```

--------------------------------

### Basic Argcfile.sh Structure

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

A standard Argcfile.sh contains shell functions marked with `@cmd` comments. It includes `set -e` for error handling and `eval "$(argc --argc-eval "$0" "$@")"` to process arguments.

```sh
#!/usr/bin/env bash

set -e

# @cmd
build() {
    echo TODO build
}

# @cmd
test() {
    echo TODO test
}

# See more details at https://github.com/sigoden/argc
eval "$(argc --argc-eval \"$0\" \"$@\")"
```

--------------------------------

### Environment Variable Binding in Bash Script

Source: https://context7.com/sigoden/argc/llms.txt

A bash script demonstrating how to bind environment variables to command options and arguments using `$$` for auto-binding or `$NAME` for specific variable names.

```bash
#!/usr/bin/env bash

# @cmd Deploy with env binding
# @option --host $$           Auto-bind to HOST env var
# @option --port $APP_PORT    Bind to specific env var name
# @option --token $API_TOKEN  Bind to API_TOKEN
# @arg environment $$         Auto-bind to ENVIRONMENT env var
deploy() {
    echo "Host: $argc_host"
    echo "Port: $argc_port"
    echo "Token: $argc_token"
    echo "Environment: $argc_environment"
}

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

--------------------------------

### Make .sh Files Executable on Windows

Source: https://github.com/sigoden/argc/blob/main/README.md

Configure PowerShell to execute .sh files directly by associating them with Git Bash. This involves modifying the PATHEXT environment variable and setting up registry keys for file association.

```powershell
# Add .sh to PATHEXT
[Environment]::SetEnvironmentVariable("PATHEXT", [Environment]::GetEnvironmentVariable("PATHEXT", "Machine") + ";.SH", "Machine")

# Associate the .sh file extension with Git Bash
New-Item -Path Registry::HKEY_CLASSES_ROOT\.sh
New-ItemProperty -Path Registry::HKEY_CLASSES_ROOT\.sh -Name "(Default)" -Value "sh_auto_file" -PropertyType String -Force
New-Item -Path Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Classes\sh_auto_file\shell\open\command -Force
New-ItemProperty -Path Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Classes\sh_auto_file\shell\open\command -Name '(default)' -Value '"C:\Program Files\Git\bin\bash.exe" "%1" %*' -PropertyType String -Force
```

--------------------------------

### Defining Subcommands with Argc

Source: https://context7.com/sigoden/argc/llms.txt

Define subcommands for your CLI using the `@cmd` tag. Each subcommand can have its own flags, options, and arguments.

```bash
#!/usr/bin/env bash

# @describe A demo CLI

# @cmd Upload a file
# @alias u
# @arg target!  File to upload (required)
upload() {
    echo "Uploading: $argc_target"
}

# @cmd Download a file
# @alias d
# @flag -f --force           Override existing file
# @option -t --tries <NUM>   Set number of retries
# @arg source!               URL to download from (required)
# @arg target                Save file to (optional)
download() {
    echo "Downloading from: $argc_source"
    echo "Saving to: $argc_target"
    echo "Force: $argc_force"
    echo "Tries: $argc_tries"
}

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

--------------------------------

### Define Symbolic Parameter

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

Use `@meta symbol` to define symbolic parameters, which can be used for choices or function references.

```sh
# @meta symbol +toolchain[`_choice_fn`]
```

--------------------------------

### Build Independent Bash Script with Argc

Source: https://github.com/sigoden/argc/blob/main/README.md

Use `argc --argc-build` to generate a standalone Bash script from a given script. The generated script can be executed without the `argc` dependency.

```bash
argc --argc-build ./example.sh build/

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

--------------------------------

### Define and Use Boolean Flags

Source: https://context7.com/sigoden/argc/llms.txt

Illustrates defining boolean flags that do not accept values. The `@flag` tag is used, and flags can be combined using `@meta combine-shorts`.

```bash
# @meta combine-shorts

# @cmd Flag examples
# @flag --verbose           Basic flag
# @flag -f --force          Short and long form
# @flag -q                  Short only
# @flag --debug*            Multi-occurs (count occurrences)
flags_demo() {
    echo "verbose: $argc_verbose"
    echo "force: $argc_force"
    echo "quiet: $argc_q"
    echo "debug level: $argc_debug"
}

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

```bash
./script.sh flags_demo --verbose -f
# Output:
# verbose: 1
# force: 1
# quiet: 
# debug level: 

# With combine-shorts, can use -vfq
./script.sh flags_demo -vf --debug --debug --debug
# Output:
# verbose: 1
# force: 1
# quiet: 
# debug level: 3
```

--------------------------------

### Access Positional Arguments

Source: https://github.com/sigoden/argc/blob/main/docs/command-runner.md

Positional arguments passed to a recipe are accessible through standard shell positional variables like `$1`, `$2`, `$@`, and `$*`.

```sh
# @cmd
build() {
  echo $1 $2
  echo $@
  echo $*
}
```

--------------------------------

### Define Positional Arguments with @arg

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

The `@arg` tag defines positional arguments. Various modifiers and value notations can be specified.

```sh
# @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 fn
# @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 fn
# @arg vfb[?`_choice_fn`]         choice from fn + no validation
# @arg vfc*[`_choice_fn`]         multi-values + choice from fn
# @arg vfd*,[`_choice_fn`]        multi-values + choice from fn + comma-separated list
# @arg vxa~                       capture all remaining args
# @arg vea $$                     bind-env
# @arg veb $BE <PATH>             bind-named-env
```

--------------------------------

### Positional Arguments with Argc

Source: https://context7.com/sigoden/argc/llms.txt

Define various types of positional arguments using the `@arg` tag, including required, multiple values, defaults, and dynamic choices.

```bash
#!/usr/bin/env bash

# @cmd Basic argument
# @arg file
cmd_basic() {
    echo "File: $argc_file"
}

# @cmd Required argument (!)
# @arg file!
cmd_required() {
    echo "File: $argc_file"
}

# @cmd Multiple values (*)
# @arg files*
cmd_multi() {
    echo "Files: ${argc_files[@]}"
}

# @cmd Required + multiple (+)
# @arg files+
cmd_required_multi() {
    echo "Files: ${argc_files[@]}"
}

# @cmd With default value
# @arg format=json
cmd_default() {
    echo "Format: $argc_format"
}

# @cmd With choices
# @arg level[debug|info|warn|error]
cmd_choices() {
    echo "Level: $argc_level"
}

# @cmd Choices with default
# @arg level[=info|debug|warn|error]
cmd_choices_default() {
    echo "Level: $argc_level"
}

# @cmd Dynamic choices from function
# @arg env[`_choice_env`]
cmd_dynamic_choices() {
    echo "Env: $argc_env"
}

_choice_env() {
    echo "development"
    echo "staging"
    echo "production"
}

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

--------------------------------

### Define Environment Variables with @env

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

The `@env` tag defines environment variables that the CLI can use. It supports required, default, and choice specifications.

```sh
# @env EA                 optional
# @env EB!                required
# @env EC=true            default
# @env EDA[dev|prod]      choices
# @env EDB[=dev|prod]     choices + default
```

--------------------------------

### Define Option Arguments with @option

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

The `@option` tag defines named options. It supports short and long forms, modifiers, value notations, and defaults.

```sh
# @option    --oa                   
# @option -b --ob                   short
# @option -c                        short only
# @option    --oc!                  required
# @option    --od*                  multi-occurs
# @option    --oe+                  required + multi-occurs
# @option    --of*,                 multi-occurs + comma-separated list
# @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 fn
# @option    --oca[a|b]             choice
# @option    --ocb[=a|b]            choice + default
# @option    --occ*[a|b]            multi-occurs + choice
# @option    --ocd+[a|b]            required + multi-occurs + choice
# @option    --ofa[`_choice_fn`]    choice from fn
# @option    --ofb[?`_choice_fn`]   choice from fn + no validation
# @option    --ofc*[`_choice_fn`]   multi-occurs + choice from fn
# @option    --ofd*,[`_choice_fn`]  multi-occurs + choice from fn + comma-separated list
# @option    --oxa~                 capture all remaining args
# @option    --oea $$               bind-env
# @option    --oeb $BE <PATH>       bind-named-env
```

--------------------------------

### Bash Script for Parallel Task Execution

Source: https://context7.com/sigoden/argc/llms.txt

A bash script designed to run multiple tasks concurrently using `argc --argc-parallel`. Each task is defined as a separate function.

```bash
#!/usr/bin/env bash
set -e

# @cmd Task 1
task1() {
    sleep 2
    echo "Task 1 complete: $1"
}

# @cmd Task 2
task2() {
    sleep 2
    echo "Task 2 complete: $1"
}

# @cmd Task 3
task3() {
    sleep 2
    echo "Task 3 complete: $1"
}

# @cmd Run all tasks in parallel
run_all() {
    argc --argc-parallel "$0" \
        task1 arg1 ::: \
        task2 arg2 ::: \
        task3 arg3
}

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

--------------------------------

### Set Aliases for Subcommands with @alias

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

Use the `@alias` tag to define one or more aliases for a subcommand. Aliases are separated by commas.

```sh
# @cmd Run tests
# @alias t,tst
test() {
  echo Run test
}
```

--------------------------------

### Define Flag Arguments with @flag

Source: https://github.com/sigoden/argc/blob/main/docs/specification.md

The `@flag` tag defines flags, which are options that do not accept values. They support short and long forms and multi-occurrence.

```sh
# @flag     --fa 
# @flag  -b --fb         short
# @flag  -c              short only
# @flag     --fd*        multi-occurs
# @flag     --ea $$      bind-env
# @flag     --eb $BE     bind-named-env
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.