Adding the CLI flag placement info (#6027)

* Adding the CLI flag placement info

* Adding the definition of 'options' and 'args'

* tweaked the wording a little bit

* Added more description in the example

* Added a link to 'Flags' in the doc for options def

website/source/docs/commands/index.html.md

@@ -39,6 +39,47 @@ To get help for a subcommand, run:
 $ vault <subcommand> -h
 ```
 
+## CLI Command Structure
+
+There are a number of command and subcommand options available: HTTP options,
+output options, and command specific options.
+
+Construct your Vault CLI command such that the command options precede its path
+and arguments if any:
+
+```text
+vault <command> [options] [path] [args]
+```
+
+- `options` - [Flags](/docs/commands/index.html#flags) to specify additional settings
+- `args` - API arguments specific to the operation
+
+  -> **NOTE:** Run `vault path-help <path>` to see the list of args (parameters).
+
+#### Examples:
+
+The following `write` command creates a new user (`bob`) in the userpass auth
+method. It passes the `-address` flag to specify the Vault server address which
+precedes the path (`auth/userpass/users/bob`) and its
+[argument](/api/auth/userpass/index.html#create-update-user)
+(`password="long-password"`) at last.
+
+```text
+$ vault write -address="http://127.0.0.1:8200" auth/userpass/users/bob password="long-password"
+```
+
+If multiple options (`-address` and `-namespace`) and
+[arguments](/api/auth/userpass/index.html#create-update-user) (`password` and
+`policies`) are specified, the command would look like:
+
+```text
+$ vault write -address="http://127.0.0.1:8200" -namespace="my-organization" \
+        auth/userpass/users/bob password="long-password" policies="admin"
+```
+
+The options (flags) come after the command (or subcommand) preceding the path,
+and the args always follow the path to set API parameter values.
+
 ## Exit Codes
 
 The Vault CLI aims to be consistent and well-behaved unless documented
@@ -234,14 +275,14 @@ This enviroment variable will limit the rate at which the `vault` command
 sends requests to Vault.
 
 This enviroment variable has the format `rate[:burst]` (where items in `[]` are
-optional). If not specified, the burst value defaults to rate. Both rate and 
+optional). If not specified, the burst value defaults to rate. Both rate and
 burst are specified in "operations per second". If the environment variable is
-not specified, then the rate and burst will be unlimited *i.e.* rate 
+not specified, then the rate and burst will be unlimited *i.e.* rate
 limiting is off by default.
 
 *Note:* The rate is limited for each invocation of the `vault` CLI. Since
 each invocation of the `vault` CLI typically only makes a few requests,
-this enviroment variable is most useful when using the Go 
+this enviroment variable is most useful when using the Go
 [Vault client API](https://www.vaultproject.io/api/libraries.html#go).
 
 ### `VAULT_NAMESPACE`

website/source/docs/commands/login.html.md

@@ -40,15 +40,20 @@ the returned token is automatically unwrapped unless:
 By default, login uses a "token" method:
 
 ```text
-$ vault login 10862232-fd55-701c-9013-d764b5bc3953
+$ vault login s.3jnbMAKl1i4YS3QoKdbHzGXq
-Success! You are now authenticated. The token information below is already
+Success! You are now authenticated. The token information displayed below
-stored in the token helper. You do NOT need to run "vault login" again. Future
+is already stored in the token helper. You do NOT need to run "vault login"
-requests will use this token automatically.
+again. Future Vault requests will automatically use this token.
 
-token: 10862232-fd55-701c-9013-d764b5bc3953
+Key                  Value
-accessor: 121533e1-20e7-0b4e-04d6-a8c18b8566d5
+---                  -----
-renewable: true
+token                s.3jnbMAKl1i4YS3QoKdbHzGXq
-policies: [my-policy]
+token_accessor       7Uod1Rm0ejUAz77Oh7SxpAM0
+token_duration       767h59m49s
+token_renewable      true
+token_policies       ["admin" "default"]
+identity_policies    []
+policies             ["admin" "default"]
 ```
 
 To login with a different method, use `-method`:
@@ -60,13 +65,21 @@ Success! You are now authenticated. The token information below is already
 stored in the token helper. You do NOT need to run "vault login" again. Future
 requests will use this token automatically.
 
-token: a700ded8-28ed-907d-abf4-23514b783d52
+Key                    Value
-accessor: e0857619-3912-9981-4e03-8d6c4b2f6c56
+---                    -----
-duration: 768h
+token                  s.2y4SU3Sk46dK3p2Y8q2jSBwL
-renewable: true
+token_accessor         8J125x9SZyB76MI9uF2jSJZf
-policies: [default]
+token_duration         768h
+token_renewable        true
+token_policies         ["default"]
+identity_policies      []
+policies               ["default"]
+token_meta_username    my-username
 ```
 
+~> Notice that the command option (`-method=userpass`) precedes the command
+argument (`username=my-username`).
+
 If a github auth method was enabled at the path "github-ent":
 
 ```text
@@ -75,10 +88,17 @@ Success! You are now authenticated. The token information below is already
 stored in the token helper. You do NOT need to run "vault login" again. Future
 requests will use this token automatically.
 
-token: 7eab2aba-b476-af57-e0af-dfcab7c541f6
+Key                    Value
-accessor: 2ae9b1cd-6d17-3428-bd44-986e97f6d2f3
+---                    -----
-renewable: 22bc4d76-aa3b-1c53-4349-b230b459b56b
+token                  s.2f3c5L1MHtnqbuNCbx90utmC
-policies: [root]
+token_accessor         JLUIXJ6ltUftTt2UYRl2lTAC
+token_duration         768h
+token_renewable        true
+token_policies         ["default"]
+identity_policies      []
+policies               ["default"]
+token_meta_org         hashicorp
+token_meta_username    my-username
 ```
 
 ## Usage