Skip to main content

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 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 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 precede a positional argument, and a positional argument cannot precede a subcommand.

Usage patterns

You can view the command usage of any command by running <command> help or <command> -h. As mentioned above, the displayed 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 | symbols indicates mutually exclosive options or arguments.
  • Parenthesis ( ) indicates grouping.

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 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, --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 must decide between using 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 | --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.

Back to top