CLI reference guide

Usage pattern of the commands in this CLI follows the docopt (doc-opt) notation with slight differences. The docopt (doc-opt) notation provides a program interface description based on decades of conventions in help messages and man pages.

Terminology

• A command that follows another command is called a subcommand. For example, in the systems list command list is a subcommand of systems.
• Any string that begins with a hyphen is called an option.
  • Note: An option cannot precede a (sub)command.
• Any non-option (not preceded by a hyphen) string that follows the last (sub)command is called positional argument. Positional arguments always appear inside angle brackets. For example, consider the following usage pattern:

  applications objects access_keys create <accessKey> --secretKey=<secretKey> --role=<objectPermissions>
  

  This pattern has one commnad applications, three subcommands objects, access_keys, and create, one positional argument accessKey with an option argument secreteKey, and one additional option role with option argument objectPermissions.
  • Options cannot precede a positional argument.
  • Positional argument cannot proced a subcommand.
• Any non-option string (not preceded by a hyphen) that follows an option is called option argument. A positional argument sets the value of a command; option argument sets the value of an option.

Usage patterns

Unlike the docopt usage pattern, the first word in our usage patterns refer to a command and not to the name of the program.

• Strings between angle bracket delimiters < > refer to either positional or option arguments. For repeating arguments (list of arguments separated by space characters), we append elipsis (three dots) to the argument. The elipsis is inside the angle brackets, one character before the closing angle bracket.
• Anything that is in square brackbets [ ] is optional.
• The | symbols indicates the XOR operator (exclusive-OR logical operator).
• Parenthesis ( ) indicates grouping.

The following describes various usage patterns for command name cmd and subcommand name usbcmd

  cmd subcmd --option <argument>
  cmd  [<optional-positional-argument>]
  cmd --option1=<option1-arg> --option2=<option2-arg>
  cmd (--either-that-option | <or-this-argument>)
  cmd <repeating-argument> <repeating-argument…>

If two or more elements are in square brackets, then any subset of these elements can be used. For example, in usage pattern:

cmd1 [--opt1 arg1 --opt2 arg2  --opt3 ]

you have the option to use any subset of options opt1, opt2, or opt3 with their respective option arguments. Hence, all the following command usages are all correct:

	cmd1 
	cmd1 --opt1 arg1 --opt3 
	cmd1 --opt1 arg1
	cmd1 --opt2 arg2
	cmd1 --opt2 arg2 --opt1 arg1
	cmd1 --opt1 arg1 --opt2 arg2 --opt3
	cmd1 --opt2 arg2 --opt3
	cmd1 --opt3

This, of course, is not limited to option elements; for example, in usage pattern:

cmd1 [--opt1 [arg1 arg2] --opt2]

all the following use cases are correct

	cmd1 
	cmd1 --opt1
	cmd1 --opt1 --opt2
	cmd1 --opt2 
	cmd1 --opt1 arg1
	dma1 --opt1 arg2
	dma1 --opt1 arg1 arg2
	cmd1 --opt1 arg1 --opt2
	cmd1 --opt1 arg2 --opt2
	cmd1 --opt1 arg1 arg2 --opt2

The XOR operator may also appear inside square bracket; for example, in usage pattern:

cmd2 [ --opt1 arg1 | --opt2 ]

either use cmd2 command with no options or use the command with only one option. Hence, all options for this command are:

cmd2  
cmd2 --opt1 arg1
cmd2 --opt2

Required elements

All elements that are not in square brackets [ ] are required. Elements that are in square brackets are optional. In some cases, grouping elements with parenthesis marks them as required. For example, in the usage pattern

applications objects stores list [(--application=<name> --volume=<name>)]

the two options are grouped together in parenthesis and wrapped in square brackets. The square brackets indicate that the options are optional; however, options within the round brackets are mutually inclusive (using one of one of the options in the round brackets requires using the other one).

The following pattern uses the XOR operator with grouping.

floatingips create <name> (--dummy) | (--address=<ip> --mask=<subnet> [--gateway=<ip>]) --nodes=<name...>
--interfaces=<name...>

In this command you must decide between using the --dummy option or both the --address, --mask options with or without the optional --gateway option. All the other elements in this command are required.
Consider the following usage pattern:

cmd (--either-this <and-that> | <or-this>)

In this command, you must decide between using the option --either-this and its options argument <and-that> or the positional argument <or-this>.
Consider the following usage pattern:

monitoring top volumes (--capacity | --dataretention | --iops | --latency) [--fromDate=<date>] [--toDate=<date>] [--limit=<numbers>] [--interactiveChart | --saveChart]

The group (--capacity | --dataretention | --iops| --latency) must be used; however, only one option from these group is allowed. The group [--interactiveChart | --saveChart] is optional, however using this group means that only one of these options is allowed.