From d5668f47cab2163165a10a9ab8d933edaad0b244 Mon Sep 17 00:00:00 2001 From: Yoko Date: Tue, 15 Jan 2019 11:24:50 -0800 Subject: [PATCH] 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 | 47 +++++++++++++++++-- website/source/docs/commands/login.html.md | 54 +++++++++++++++------- 2 files changed, 81 insertions(+), 20 deletions(-) diff --git a/website/source/docs/commands/index.html.md b/website/source/docs/commands/index.html.md index 40d7a2c3ab..d047546062 100644 --- a/website/source/docs/commands/index.html.md +++ b/website/source/docs/commands/index.html.md @@ -39,6 +39,47 @@ To get help for a subcommand, run: $ vault -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 [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 ` 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` diff --git a/website/source/docs/commands/login.html.md b/website/source/docs/commands/login.html.md index 2f2176d85c..c32108eed0 100644 --- a/website/source/docs/commands/login.html.md +++ b/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 -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. +$ vault login s.3jnbMAKl1i4YS3QoKdbHzGXq +Success! You are now authenticated. The token information displayed below +is already stored in the token helper. You do NOT need to run "vault login" +again. Future Vault requests will automatically use this token. -token: 10862232-fd55-701c-9013-d764b5bc3953 -accessor: 121533e1-20e7-0b4e-04d6-a8c18b8566d5 -renewable: true -policies: [my-policy] +Key Value +--- ----- +token s.3jnbMAKl1i4YS3QoKdbHzGXq +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 -accessor: e0857619-3912-9981-4e03-8d6c4b2f6c56 -duration: 768h -renewable: true -policies: [default] +Key Value +--- ----- +token s.2y4SU3Sk46dK3p2Y8q2jSBwL +token_accessor 8J125x9SZyB76MI9uF2jSJZf +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 -accessor: 2ae9b1cd-6d17-3428-bd44-986e97f6d2f3 -renewable: 22bc4d76-aa3b-1c53-4349-b230b459b56b -policies: [root] +Key Value +--- ----- +token s.2f3c5L1MHtnqbuNCbx90utmC +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