appspec-bash - Command line framework generator for bash


Generate commandline parser, completion and man pages


This script can generate a commandline parser for bash from a specification file written in YAML.

Writing a parser for commandline arguments isn't rocket science, but it's something you don't want to do manually for all of your scripts, especially in bash. Some tools exist, but they often don't support subcommands or validating of option values.

appspec/appspec-bash can generate pretty much everything for you:

Commandline parser for subcommands, options and parameters
Usage output
Shell completion files
man pages


Here is an example of a very simple script.

The following files are needed:

  lib/appspec                       # generated
  share/completion/zsh/_mytool      # generated
  share/completion/bash/mytool.bash # generated
  pod/mytool.pod                    # generated
  lib/help                          # generated

The spec:

  # share/mytool.yaml
  name: mytool           # commandname
  appspec: { version: 0.001 }
  plugins: [-Meta]       # not supported in bash
  title: My cool tool    # Will be shown in help
  class: MyTool          # "Class name" (means function prefix here)

      op: command1       # The function name (MyTool.command1)
      summary: cmd one   # Will be shown in help and completion
      - foo|f=s --Foo    # --foo or -f; '=s' means string
      - bar|b   --Bar    # --bar or -b; a flag

Your script mytool would look like this:

  # bin/mytool
  DIR="$( dirname $BASH_SOURCE )"
  source "$DIR/../lib/appspec"
  source "$DIR/../lib/mytool" $@

The actual app:

  # lib/mytool
  MyTool.command1() {
      echo "=== OPTION foo: $OPT_FOO"
      echo "=== OPTION bar: $OPT_BAR"

Generating the parser

Then generate the parser like this:

  $ appspec-bash generate parser share/mytool.yaml lib/appspec will parse the arguments and then call the function MyTool.command1. In this function you can use the options via $OPT_FOO and $OPT_BAR.

  $ ./bin/mytool command1 --foo x --bar
  # or
  $ mytool command1 -f x -b
  === OPTION foo: x
  === OPTION bar: true

Generate completion

    $ appspec completion share/mytool.yaml --zsh >share/completion/zsh/_mytool
    $ appspec completion share/mytool.yaml --bash >share/completion/bash/mytool.bash

Generate pod

    $ appspec pod share/mytool.yaml > pod/mytool.pod
    $ perldoc pod/mytool.pod

Generate help

    $ appspec-bash generate help share/mydemo.yaml lib/help

Generate a new app skeleton

  appspec-bash new --class MyTool --name mytool

This will create your app mytool in the directory MyTool and output some usage information like this:

  To generate the parser and help, do:

    % cd MyTool
    % appspec-bash generate parser share/mytool.yaml lib/appspec
    % appspec-bash generate help share/mytool.yaml lib/help

  Try it out:

    % bin/mytool cmd1 -ab --opt-x x -yfoo --opt-y bar
    % bin/mytool cmd2 -vvv
    % bin/mytool cmd2 -vvv foo


appspec-bash supports various types of options.


    # YAML
    - verbose|v -- Verbose output

    % mytool --verbose
    % mytool -v

You can also stack several flags:

    % mytool -abc

Options with values

    # YAML
    - color|c=s --Specify color

    % mytool --color red
    % mytool -c red
    % mytool -cred
    # Not yet supported
    # mytool --color=red

You can stack flags together with options. If you have the flags -a and -b and the option -c, then you can use this syntax:

    % mytool -abc23

Incremental flags

    # YAML
    - verbose|v+ --Verbose output (incremental)

    % mytool -vvv                # like: declare -i OPT_VERBOSE=3
    % mytool --verbose --verbose # like: declare -i OPT_VERBOSE=2

Options with multiple values

    # YAML
    - server|s=s@  --List of servers

    % mytool --server foo --server bar
    % mytool -s foo -s bar


    # YAML
    - name: server
      required: true
      summary: Server name

Option types

By default, an option is a flag. To accept a value, add a =. Then it will be a string by default:

    - foo=
    # or
    - foo=s

You can also create integer options:

    - max=i --Specify maximum value

Then you can treat it as an integer and use OPT_MAX+=1 for example.

There are also the types file, dir, filename and dirname. Currently they are only relevant for completion.

    # YAML
    - input= +file      --Input filename
    - source-dir= +dir  --Source directory
    - output= +filename --Output file
    - out-dir= +dirname --Output directory

In the future, file and dir will check for an existing file or directory. And filename and dirname can be used if the file or directory doesn't exist yet, but the tab completion will still offer file or directory names.

See the mydemo app in the example directory for examples of options and parameters.


    --help -h    Show command help (flag)



    appspec-bash  generate <subcommands>

Generate parser, help

generate help

    appspec-bash generate help <spec> <output>

Generate help functions


    spec    *  YAML Specification file   
    output  *  Output file, e.g. lib/help

generate parser

    appspec-bash generate parser <spec> <output>

Generate main commandline parser script


    spec    *  YAML Specification file      
    output  *  Output file, e.g. lib/appspec


    appspec-bash  new [options] [<path>]

Generate new app

This command creates a skeleton for a new app. It will create a directory for your app and write a skeleton spec file.


  appspec-bash new --name mytool --class MyTool MyTool


    --name -n       *  The (file) name of the app                                    
    --class -c      *  The main "class" (function prefix) for your app implementation
    --overwrite -o     Overwrite existing dist directory (flag)                      


    path    Path to the distribution directory (default is the classname in current directory)


    appspec-bash  help <subcommands> [options]

Show command help


    --all     (flag)


    appspec-bash  _meta <subcommands>

Information and utilities for this app

_meta completion

    appspec-bash _meta completion <subcommands>

Shell completion functions

_meta completion generate

    appspec-bash _meta completion generate [options]

Generate self completion


    --name    name of the program (optional, override name in spec)
    --zsh     for zsh (flag)                                       
    --bash    for bash (flag)                                      

_meta pod

    appspec-bash _meta pod <subcommands>

Pod documentation

_meta pod generate

    appspec-bash _meta pod generate

Generate self pod