diff --git a/website/source/docs/commands/help.html.md b/website/source/docs/commands/help.html.md new file mode 100644 index 0000000000..a28292b3aa --- /dev/null +++ b/website/source/docs/commands/help.html.md @@ -0,0 +1,105 @@ +--- +layout: "docs" +page_title: "Help" +sidebar_current: "docs-commands-help" +description: |- + The Vault CLI has a built-in help system that can be used to get help for not only the CLI itself, but also any paths that the CLI can be used with within Vault. +--- + +# Help + +In addition to standard CLI help using the `-h` or `-help` flag for +commands, Vault has a built-in `help` command that can be used to get +help for specific paths within Vault. These paths are used with the +API or `read, write, delete` commands in order to interact with Vault. + +The help system is the easiest way to learn how to use the various systems +in Vault, and also allows you to discover new paths. + +-> **Important!** The help system is incredibly important in day-to-day +use of Vault. As a beginner or experienced user of Vault, you'll be using +the help command a lot to remember how to use different components of +Vault. + +## Discovering Paths + +Before using `help`, it is important to understand "paths" within Vault. +Paths are the parameters used for `vault read`, `vault write`, etc. An +example path is `secret/foo`, or `aws/config/root`. The paths available +depend on the mounted secret backends. Because of this, the interactive +help is an indispensible tool to finding what paths are supported. + +To discover what paths are supported, use `vault help `. +For example, if you mounted the AWS secret backend, you can use +`vault help aws` to find the paths supported by that backend. The paths +will be shown with regular expressions, which can make them hard to +parse, but they're also extremely exact. + +You can try it right away with any Vault with `vault help secret`, since +`secret` is always mounted initially. The output from this command is shown +below and contains both a description of what that backend is for, along with +the paths it supports. + +``` +$ vault help secret +## DESCRIPTION + +The generic backend reads and writes arbitrary secrets to the backend. +The secrets are encrypted/decrypted by Vault: they are never stored +unencrypted in the backend and the backend never has an opportunity to +see the unencrypted value. + +Leases can be set on a per-secret basis. These leases will be sent down +when that secret is read, and it is assumed that some outside process will +revoke and/or replace the secret at that path. + +## PATHS + +The following paths are supported by this backend. To view help for +any of the paths below, use the help command with any route matching +the path pattern. Note that depending on the policy of your auth token, +you may or may not be able to access certain paths. + + ^.*$ + Pass-through secret storage to the physical backend, allowing you to + read/write arbitrary data into secret storage. +``` + +## Single Path + +Once you've found a path you like, you can learn more about it by +using `vault help ` where "path" is a path that matches one of the +regular expressions from the backend help. + +Or, if you saw an example online with `vault write` or some similar +command, you can plug that directly into `vault help` to learn about it +(assuming you have the proper backends mounted!). + +For example, below we get the help for a single secret in the `secret/` +mount point. The help shows the operations that that path supports, the +parameters it takes (for write), and a description of that specific path. + +``` +$ vault help secret/password +Request: password +Matching Route: ^.*$ + +Pass-through secret storage to the physical backend, allowing you to +read/write arbitrary data into secret storage. + +## PARAMETERS + + lease (string) + Lease time for this key when read. Ex: 1h + +## DESCRIPTION + +The pass-through backend reads and writes arbitrary data into secret storage, +encrypting it along the way. + +A lease can be specified when writing with the "lease" field. If given, then +when the secret is read, Vault will report a lease with that duration. It +is expected that the consumer of this backend properly writes renewed keys +before the lease is up. In addition, revocation must be handled by the +user of this backend. +```