Subcommands shall have three distinct parts to its commands (in order that they appear):
* global options
* command object(s) and action
* command options and arguments
Output formats:
* user-friendly tables with headers, etc
* machine-parsable delimited
Notes:
* All long options names shall begin with two dashes ('--') and use a single dash
('-') internally between words (:code:`--like-this`). Underscores ('_') shall not
be used in option names.
* Authentication options conform to the common CLI authentication guidelines in
:doc:`authentication`.
Global Options
~~~~~~~~~~~~~~
Global options are global in the sense that they apply to every command
invocation regardless of action to be performed. They include authentication
credentials and API version selection. Most global options have a corresponding
environment variable that may also be used to set the value. If both are present,
the command-line option takes priority. The environment variable names are derived
from the option name by dropping the leading dashes ('--'), converting each embedded
dash ('-') to an underscore ('_'), and converting to upper case.
For example, :code:`--os-username` can be set from the environment via
:code:`OS_USERNAME`.
--help
++++++
The standard :code:`--help` global option displays the documentation for invoking
the program and a list of the available commands on standard output. All other
options and commands are ignored when this is present. The traditional short
form help option (:code:`-h`) is also available.
--version
+++++++++
The standard :code:`--version` option displays the name and version on standard
output. All other options and commands are ignored when this is present.
Command Object(s) and Action
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Commands consist of an object described by one or more words followed by an action. Commands that require two objects have the primary object ahead of the action and the secondary object after the action. Any positional arguments identifying the objects shall appear in the same order as the objects. In badly formed English it is expressed as "(Take) object1 (and perform) action (using) object2 (to it)."
<object-1> <action> [<object-2>]
Examples:
*:code:`group add user <group> <user>`
*:code:`volume type list` # Note that :code:`volume type` is a two-word
single object
The :code:`help` command is unique as it appears in front of a normal command
and displays the help text for that command rather than execute it.
Object names are always specified in command in their singular form. This is
contrary to natural language use.
Command Arguments and Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each command may have its own set of options distinct from the global options.
They follow the same style as the global options and always appear between
the command and any positional arguments the command requires.
Option Forms
++++++++++++
***boolean**: boolean options shall use a form of :code:`--<true>|--<false>`
(preferred) or :code:`--<option>|--no-<option>`. For example, the
:code:`enabled` state of a project is set with :code:`--enable|--disable`.
Command Output
--------------
The default command output is pretty-printed using the Python
:code:`prettytable` module.
Machine-parsable output format may be specified with the :code:`--format`
option to :code:`list` and :code:`show` commands. :code:`list` commands
have an option (:code:`--format csv`) for CSV output and :code:`show` commands
have an option (:code:`--format shell`) for the shell variable assignment
syntax of :code:`var="value"`. In both cases, all data fields are quoted with `"`
Help Commands
-------------
The help system is considered separately due to its special status
among the commands. Rather than performing tasks against a system, it
provides information about the commands available to perform those
tasks. The format of the :code:`help` command therefore varies from the
form for other commands in that the :code:`help` command appears in front
of the first object in the command.
The options :code:`--help` and :code:`-h` display the global options and a
list of the supported commands. Note that the commands shown depend on the API
versions that are in effect; i.e. if :code:`--os-identity-api-version=3` is
present Identity API v3 commands are shown.
Examples
========
The following examples depict common command and output formats expected to be produces by the OpenStack client.
Authentication
--------------
Using global options:
..code-block:: bash
$ openstack --os-tenant-name ExampleCo --os-username demo --os-password secrete --os-auth-url http://localhost:5000:/v2.0 server show appweb01
