diff options
Diffstat (limited to 'doc/source/commands.rst')
| -rw-r--r-- | doc/source/commands.rst | 56 |
1 files changed, 37 insertions, 19 deletions
diff --git a/doc/source/commands.rst b/doc/source/commands.rst index 0c278d05..7cd05951 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -2,33 +2,50 @@ Commands ======== + Command Structure ================= -OpenStack Client uses a command form ``verb object``. - -Note that 'object' here refers to the target of a command's action. In coding -discussions 'object' has its usual Python meaning. Go figure. +OpenStackClient has a consistent and predictable format for all of its commands. Commands take the form:: - openstack [<global-options>] <verb> <object> [<command-local-arguments>] + openstack [<global-options>] <object> <action> [<second-object>] [<command-arguments>] + +* All long options names begin with two dashes ('--') and use a single dash ('-') internally between words (--like-this) + + +Global Options +-------------- + +Global options are global in the sense that the apply to every command invocation regardless of action to be performed. This includes 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, ``--os-username`` can be set from the environment via ``OS_USERNAME``. + + +Command Object(s) and Action +---------------------------- -Command Arguments ------------------ +Commands consist of an object described by one or more words followed by an action. +In commands requiring two objects be acted upon, the primary object appears ahead of the action and the secondary object appears after the action. +If both objects have cooresponding positional arguments the arguments 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)." - * All long option names use two dashes ('--') as the prefix and a single dash - ('-') as the interpolation character. Some common options also have the - traditional single letter name prefixed by a single dash ('-'). - * Global options generally 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 can be derived from - the option name by dropping the leading '--', converting all embedded dashes - ('-') to underscores ('_'), and converting the name to upper case. - * Positional arguments trail command options. In commands that require two or - more objects be acted upon, such as 'attach A to B', both objects appear - as positional arguments. If they also appear in the command object they are - in the same order. +:: + + <object-1> <action> <object-2> + +Examples:: + + group add user <group> <user> + + volume type list # 'volume type' is a two-word single object + + +Command Arguments and Options +----------------------------- + +Commands have their 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 arguemnts the command may require. Implementation @@ -38,6 +55,7 @@ The command structure is designed to support seamless addition of extension command modules via entry points. The extensions are assumed to be subclasses of Cliff's command.Command object. + Command Entry Points -------------------- |