CLI overview

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. An option cannot come before a command or subcommand.

• Any non-option string (a string that does not start with a hyphen) that follows the last command or subcommand is called a positional argument. In the help and usage text, 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 command (applications), three subcommands (objects, access_keys, and create), one positional argument (accessKey), and two options (secretKey and role) with option arguments (secretKey and objectPermissions, respectively).
  
  

  Options cannot be specified before a positional argument, and a positional argument cannot come before a command or subcommand.

Command usage and help text

You can view the command usage of any command by running <command> help or <command> -h. In general, StorONE CLI command usage follows the docopt notation with slight differences. Some of the common conventions are as follows:

• Strings between angle bracket delimiters < > refer to either positional or option arguments. For repeating arguments (a list of arguments separated by space characters), an ellipsis (...) is appended to the argument. Unlike the docopt notation, in the StorONE CLI the ellipsis is inside the angle brackets before the closing angle bracket.
• Anything in square brackets ([ ]) is optional.
• The pipe (|) symbol indicates mutually exclusive options or arguments.
• Parentheses ( ) indicate grouping.

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

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

For this example, you can use any subset of options --opt1, --opt2, or --opt3 with their respective option arguments. All of the following command usages are valid:

	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 is not limited to option elements. For example, consider the usage pattern:

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

In this example, all of the following use cases are permitted:

	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 mutually exclusive (|) operator may also appear inside square bracket. For example, consider the following usage pattern:

cmd2 [ --opt1 arg1 | --opt2 ]

In this case, you can either use the cmd2 command with no options or use the command with only one option. All possible permutations of this command are as follows:

cmd2  
cmd2 --opt1 arg1
cmd2 --opt2

Required elements

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

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

In this example, the two options are grouped together in parentheses and wrapped in square brackets. The square brackets indicate that the listed options are optional. However, options within the parentheses are mutually inclusive (using one of the options requires using the other one).

The following pattern uses the mutually exclusive (|) 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 and --mask options with or without the --gateway option. All of the other elements in this command are required.

Consider the following usage pattern:

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

In this command, you can use the option --either-this and its required argument <and-that>, or the positional argument <or-this>.

Consider the following usage pattern:

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

The group (--userDataConsumedSize|--retentionConsumedSize|--iops|--latency) must be used, but only one option from the group is allowed. The group [--interactiveChart | --saveChart] is optional, but you can only specify one of the options.