command-runner.md

Command runner

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

This guide provides instructions on how to effectively use argc for this purpose.

Create an Argcfile.sh

Commands, called recipes, are stored in a file called argcfile .

Use --argc-create to quickly generate an Argcfile.sh for your project.

argc --argc-create build test

This creates a basic Argcfile.sh with sample build and test recipes.

#!/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" "$@")"

A recipe is a regular shell function with a @cmd comment tag above it.

Handle dependencies

Since recipe are functions, manage dependencies by calling them sequentially within other functions.

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

# @cmd
before() {
  echo before
}

# @cmd
after() { 
  echo after
}

This example demonstrates how the current recipe calls both before and after recipes.

$ argc current
before
current
after

Organize Recipes

Organize related recipes into groups for better readability.

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

Valid group formats include: foo:bar foo.bar foo@bar.

Set default recipe

When invoked without a specific recipe, Argc displays available recipes.

$ argc
USAGE: Argcfile.sh <COMMAND>

COMMANDS:
  build
  test

Use main function to set a default recipe to run automatically.

# @cmd
build() { :; }

# @cmd
test() { :; }

main() {
  build
}

Another way is to use @meta default-subcommand

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

# @cmd
test() { :; }

Remember, you can always use --help for detailed help information.

Aliases

Aliases allow recipes to be invoked on the command line with alternative names:

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

Now you can run the test recipe using the alias t:

$ argc t

Access positional arguments

Accessed through shell positional variables ($1, $2, $@, $* etc.).

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

$ argc build foo bar
foo bar
foo bar

Access Flag/option arguments

Define and use flags/options for more control.

# @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"
}

$ argc cmd -h
A simple command

USAGE: Argcfile.sh cmd [OPTIONS] [ARG]

ARGS:
  [ARG]  A positional parameter

OPTIONS:
  -f, --flag             A flag parameter
      --option <OPTION>  A option parameter
  -h, --help             Print help

$ argc cmd -f --option foo README.md
flag:    1
option:  foo
arg:     README.md

Load environment variables from dotenv file

Use @meta dotenv to load environment variables from a .env file.

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

Document and Validate environment variables

Define environment variables using @env.

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

Argc automatically generates help information for environment variables.

By running argc -h, you'll see a list of variables with descriptions and any restrictions.

$ argc -h
USAGE: Argcfiles.sh

ENVIRONMENTS:
  FOO   A env var
  BAR*  A required env var
  MODE  A env var with possible values [possible values: dev, prod]

Argc also validates environment variables as per the @env definitions.

If $BAR is missing, Argc will report an error:

error: the following required environments were not provided:
  BAR$MO

For $MODE, which has predefined values, Argc verifies the input values and reports errors if they do not match:

error: invalid value `abc` for environment variable `MODE`
  [possible values: dev, prod]

Align the project's rootdir

Argc automatically cds into the directory of the Argcfile.sh it finds in the parent hierarchy.

Project directory structure as follows:

$ tree /tmp/project

/tmp/project
├── Argcfile.sh
└── src

The code of build recipe as follows:

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

Run the build in the project dir:

$ argc build
/tmp/project
/tmp/project

Change directory (cd) into the subdirectory and run the build:

$ cd src && argc build
/tmp/project
/tmp/project/src

When running argc under the subdirectory other than project root, PWD points to the project root, while ARGC_PWD points to the current directory.