Vault Commands (CLI)
Note: The Vault command-line interface (CLI) changed substantially in 0.9.2+ and may cause confusion while using older versions of Vault with this documentation. Read our upgrade guide for more information.
In addition to a verbose HTTP API, Vault features a command-line interface (CLI) that wraps common functionality and formats output. The Vault CLI is a single static binary. It is a thin wrapper around the HTTP API. Every CLI command maps directly to the HTTP API internally.
CLI Command Structure
Each command is represented as a command or subcommand, and 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:
NOTE: Use the command help to display available options and arguments.
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
(password="long-password"
) at last.
If multiple options (-address
and -namespace
) and
arguments (password
and
policies
) are specified, the command would look like:
The options (flags) come after the command (or subcommand) preceding the path, and the args always follow the path to set API parameter values.
The four most common operations in Vault are read, write, delete, and list. These operations work on most paths in Vault. Some paths will contain secrets while other paths may contain configuration. Whatever it is, the primary interface for reading and writing data to Vault is similar.
Print cURL Command
To see the equivalent API call to perform the same operation, use the
-output-curl-string
flag after the subcommand.
Command Help
There are two primary ways to get help in Vault: CLI help (help
)
and API help (path-help
).
CLI Help
Use help
(or -h
for shorthand) to see the CLI help output which corresponds
to your Vault version.
To get CLI help:
Example: To get help on the kv
command.
The help output displays available subcommands, parameters, and command flags.
API Help
To invoke the Vault API paths, you can use the read (for HTTP GET), write (for HTTP PUT or POST), delete (for HTTP DELETE), and list (for HTTP LIST) commands.
Use path-help
to get Vault API help:
The path-help
retrieves API help on any API paths. Vault API paths provide
built-in help in markdown format. This includes system paths, secret engines,
and auth methods.
Example: API help on the sys/mounts/
path.
The help output displays supported child-paths and available parameters if there are any.
Command Input
To write data to Vault, the input can be a part of the command in key-value format.
However, some Vault API require more advanced structures such as maps. You can use stdin or file input instead.
stdin
Some commands in Vault can read data from stdin using -
as the value. If -
is the entire argument, Vault expects to read a JSON object from stdin:
In addition to reading full JSON objects, Vault can read just a value from stdin:
Files
Some commands can also read data from a file on disk. The usage is similar to
stdin as documented above. If an argument starts with @
, Vault will read it as
a file:
Or specify the contents of a file as a value:
Note that if an argument is supplied in a @key=value format, Vault will treat that as a
kv pair with the key being @key
, not a file called key=value
. This also means that Vault
does not support filenames with =
in them.
Exit Codes
The Vault CLI aims to be consistent and well-behaved unless documented otherwise.
Local errors such as incorrect flags, failed validations, or wrong numbers of arguments return an exit code of 1.
Any remote errors such as API failures, bad TLS, or incorrect API parameters return an exit status of 2
Some commands override this default where it makes sense. These commands document this anomaly.
Autocompletion
The vault
command features opt-in autocompletion for flags, subcommands, and
arguments (where supported).
Enable autocompletion by running:
Be sure to restart your shell after installing autocompletion!
When you start typing a Vault command, press the <tab>
character to show a
list of available completions. Type -<tab>
to show available flag completions.
If the VAULT_*
environment variables are set, the autocompletion will
automatically query the Vault server and return helpful argument suggestions.
Token Helper
By default, the Vault CLI uses a "token helper" to cache the token after authentication. This is conceptually similar to how a website securely stores your session information as a cookie in the browser. Token helpers are customizable, and you can even build your own.
The default token helper stores the token in ~/.vault-token
. You can delete
this file at any time to "logout" of Vault.
Environment Variables
The CLI reads the following environment variables to set behavioral defaults. This can alleviate the need to repetitively type a flag. Flags always take precedence over the environment variables. Each of the following environment variables must be set on the Vault process. In Vault 1.13+, all environment variables available to the Vault process will be logged during startup.
VAULT_TOKEN
Vault authentication token. Conceptually similar to a session token on a
website, the VAULT_TOKEN
environment variable holds the contents of the token.
For more information, please see the token
concepts page.
VAULT_ADDR
Address of the Vault server expressed as a URL and port, for example:
https://127.0.0.1:8200/
.
VAULT_CACERT
Path to a PEM-encoded CA certificate file on the local disk. This file is used
to verify the Vault server's SSL certificate. This environment variable takes
precedence over VAULT_CAPATH
.
VAULT_CAPATH
Path to a directory of PEM-encoded CA certificate files on the local disk. These certificates are used to verify the Vault server's SSL certificate.
VAULT_CLIENT_CERT
Path to a PEM-encoded client certificate on the local disk. This file is used for TLS communication with the Vault server.
VAULT_CLIENT_KEY
Path to an unencrypted, PEM-encoded private key on disk which corresponds to the matching client certificate.
VAULT_CLIENT_TIMEOUT
Timeout variable. The default value is 60s.
VAULT_CLUSTER_ADDR
Address that should be used for other cluster members to connect to this node when in High Availability mode.
VAULT_FORMAT
Provide Vault output (read/status/write) in the specified format. Valid formats are "table", "json", or "yaml".
VAULT_LICENSE
[Enterprise, Server only] Specify a license to use for this node. This takes precedence over #VAULT_LICENSE_PATH and license_path in config.
VAULT_LICENSE_PATH
[Enterprise, Server only] Specify a path to a license on disk to use for this node. This takes precedence over license_path in config.
VAULT_MAX_RETRIES
Maximum number of retries when certain error codes are encountered. The default
is 2
, for three total attempts. Set this to 0
or less to disable retrying.
Error codes that are retried are 412 (client consistency requirement not satisfied) and all 5xx except for 501 (not implemented).
VAULT_REDIRECT_ADDR
Address that should be used when clients are redirected to this node when in High Availability mode.
VAULT_SKIP_VERIFY
Do not verify Vault's presented certificate before communicating with it. Setting this variable is not recommended and voids Vault's security model.
VAULT_TLS_SERVER_NAME
Name to use as the SNI host when connecting via TLS.
VAULT_CLI_NO_COLOR
If provided, Vault output will not include ANSI color escape sequence characters.
VAULT_RATE_LIMIT
This environment variable will limit the rate at which the vault
command
sends requests to Vault.
This environment variable has the format rate[:burst]
(where items in []
are
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
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 environment variable is most useful when using the Go
Vault client API.
VAULT_NAMESPACE
The namespace to use for the command. Setting this is not necessary but allows using relative paths.
VAULT_SRV_LOOKUP
Enables the client to lookup the host through DNS SRV look up as described in this draft. This is not designed for high-availability, just discovery. The draft specifies that the SRV record lookup is ignored if a port is given.
VAULT_MFA
ENTERPRISE ONLY
MFA credentials in the format mfa_method_name[:key[=value]]
(items in []
are
optional). Note that when using the environment variable, only one credential
can be supplied. If a MFA method expects multiple credential values, or if there
are multiple MFA methods specified on a path, then the CLI flag -mfa
should be
used.
VAULT_HTTP_PROXY
HTTP proxy location which should be used to access Vault. When present, this
overrides any other proxies found in the environment. Format should be
http://server:port
.
Flags
There are different CLI flags that are available depending on subcommands. Some flags, such as those used for setting HTTP and output options, are available globally, while others are specific to a particular subcommand. For a complete list of available flags, run: