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.

  • Note: An option cannot precedecome before a (sub)command.
  command
  or subcommand.

• Any non-option string (a string that does not precededstart bywith a hyphen) string that follows the last (sub)command or subcommand is called a positional argument. PositionalIn 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 (applicationsapplications), 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 precedebe specified before a positional argument, and a positional argument cannot precedecome before a command or subcommand.

UsageCommand patternsusage and help text

You can view the command usage of any command by running <command> help or <command> -h. AsIn mentionedgeneral, above,StorONE the displayedCLI 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 that is in square brackets ([ ]) is optional.
• The pipe (|) symbolssymbol indicates mutually exclosiveexclusive options or arguments.
• ParenthesisParentheses ( ) indicatesindicate grouping.

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

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

For this example, you have the option tocan use any subset of options --opt1, --opt2, or --opt3 with their respective option arguments. Hence,All allof the following command usages are all correct: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;bracket. forFor 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;optional. however,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 optional --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 mustcan decide between usinguse the option --either-this and its required argument <and-that>, or the positional argument <or-this>.

Consider the following usage pattern:

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

The group (--capacity | userDataConsumedSize|--dataretention | retentionConsumedSize|--iops| --latency) must be used;used, however,but only one option from thesethe group is allowed. The group [--interactiveChart | --saveChart] is optional;optional, however,but usingyou this group means thatcan only specify one of thesethe options is allowed.options.