CLI descriptor formats

[epage]

Every once in a while, ways to describe a CLI come up and figured it would be good to have a central place to list these.

[epage]

clap-serde

Example:

name: app_clap_serde
version : "1.0"
about : yaml_support!
author : yaml_supporter

args:
    - apple : 
        short: a
    - banana:
        short: b
        long: banana
        aliases :
            - musa_spp

subcommands:
    - sub1: 
        about : subcommand_1
    - sub2: 
        about : subcommand_2

[epage]

Built-in support was requested in #6299

[epage]

Also discussed in #3087.

[epage]

clap v2's YAML API

Example:

name: yml_app
version: "1.0"
about: an example using a .yml file to build a CLI
author: Kevin K. <kbknapp@gmail.com>

# AppSettings can be defined as a list and are **not** ascii case sensitive
settings:
    - ArgRequiredElseHelp

# All Args must be defined in the 'args:' list where the name of the arg, is the
# key to a Hash object
args:
    # The name of this argument, is 'opt' which will be used to access the value
    # later in your Rust code
    - opt:
        help: example option argument from yaml
        short: o
        long: option
        multiple: true
        takes_value: true
    - pos:
        help: example positional argument from yaml
        index: 1
        # A list of possible values can be defined as a list
        possible_values:
            - fast
            - slow
    - flag:
        help: demo flag argument
        short: F
        multiple: true
        global: true
        # Conflicts, mutual overrides, and requirements can all be defined as a
        # list, where the key is the name of the other argument
        conflicts_with:
            - opt
        requires:
            - pos
    - mode:
        long: mode
        help: shows an option with specific values
        # possible_values can also be defined in this list format
        possible_values: [ vi, emacs ]
        takes_value: true
    - mvals:
        long: mult-vals
        help: demos an option which has two named values
        # value names can be described in a list, where the help will be shown
        # --mult-vals <one> <two>
        value_names:
            - one
            - two
    - minvals:
        long: min-vals
        multiple: true
        help: you must supply at least two values to satisfy me
        min_values: 2
    - maxvals:
        long: max-vals
        multiple: true
        help: you can only supply a max of 3 values for me!
        max_values: 3

# All subcommands must be listed in the 'subcommand:' object, where the key to
# the list is the name of the subcommand, and all settings for that command are
# are part of a Hash object
subcommands:
    # The name of this subcommand will be 'subcmd' which can be accessed in your
    # Rust code later
    - subcmd:
        about: demos subcommands from yaml
        version: "0.1"
        author: Kevin K. <kbknapp@gmail.com>
        # Subcommand args are exactly like App args
        args:
            - scopt:
                short: B
                multiple: true
                help: example subcommand option
                takes_value: true
            - scpos1:
                help: example subcommand positional
                index: 1

# ArgGroups are supported as well, and must be sepcified in the 'groups:'
# object of this file
groups:
    # the name of the ArgGoup is specified here
    - min-max-vals:
        # All args and groups that are a part of this group are set here
        args:
            - minvals
            - maxvals
        # setting conflicts is done the same manner as setting 'args:'
        #
        # to make this group required, you could set 'required: true' but for
        # this example we won't do that.

[epage]

See #3087

[epage]

CWL

Specification: https://www.commonwl.org/v1.0/CommandLineTool.html
User guide: https://www.commonwl.org/user_guide/

Example

cwlVersion: v1.2

# What type of CWL process we have in this document.
class: CommandLineTool
# This CommandLineTool executes the linux "echo" command-line tool.
baseCommand: echo

# The inputs for this process.
inputs:
  message:
    type: string
    # A default value that can be overridden, e.g. --message "Hola mundo"
    default: "Hello World"
    # Bind this message value as an argument to "echo".
    inputBinding:
      position: 1
outputs: []

[epage]

Discussed in #1337.

[epage]

docopt

Example

Naval Fate.

Usage:
  naval_fate ship new <name>...
  naval_fate ship <name> move <x> <y> [--speed=<kn>]
  naval_fate ship shoot <x> <y>
  naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
  naval_fate -h | --help
  naval_fate --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.

[epage]

Usage specification

Example

flag "-v --verbose" "Enable verbose logging" global=#true count=#true
flag "-q --quiet" "Enable quiet logging" global=#true
flag "-u --user <user>" help="User to run as"

cmd "update" help="Update the CLI"
cmd "config" help="Manage the CLI config" {
  # "set" is an alias for "add"
  cmd "add" "Add/set a config" {
    alias "set"
    arg "<key>" help="The key for the config"
    arg "<value>" help="The new config value"
    flag "-f --force" help="Overwrite existing config"
  }
  cmd "remove" help="Remove a thing" {
    alias "rm"
    alias "delete" hide=#true # hide alias from docs and completions
    arg "<name>" help="The name of the thing"
  }
  cmd "list" help="List all things"
}
cmd "version" help="Print the CLI version"
cmd "help" help="Print the CLI help"