Vault CLI

The Vault CLI is a static binary that wraps the Vault API. While every CLI command maps directly to one or more APIs internally, not every endpoint is exposed publicly and not every API endpoint has a corresponding CLI command.

Usage

$ vault <command> [subcommand(s)] [flag(s)] [command-argument(s)]

$ vault <command> [subcommand(s)] [-help | -h]

Tip

Use the -help flag with any command to see a description of the command and a list of supported options and flags.

The Vault CLI returns different exit codes depending on whether and where an error occurred:

0 - Success
1 - Local/terminal error (invalid flags, failed validation, wrong numbers of arguments, etc.)
2 - Remote/server error (API failures, bad TLS, incorrect API parameters, etc.)

Authenticating to Vault

Unauthenticated users can use CLI commands with the --help flag, but must use vault login or set the VAULT_TOKEN environment variable to use the CLI.

The CLI uses a token helper to cache access tokens after authenticating with vault login The default file for cached tokens is ~/.vault-token and deleting the file forcibly logs the user out of Vault.

If you prefer to use a custom token helper, you can create your own and configure the CLI to use it.

Passing command arguments

Command arguments include any relevant configuration settings and command-specific options. Command options pass input data as key=value pairs, which you can provided inline, as a stdin stream, or from a local file.

To pass input inline with the command, use the <option-name>=<value> syntax:

$ vault audit enable file file_path="/var/log/vault.log"

To pass input from stdin, use - as a stand-in for the entire key=value pair or a specific option value.

To pipe the option and value, use a JSON object with the option name and value:

$ echo -n '{"file_path":"/var/log/vault.log"}' | vault audit enable file -

To pipe the option value by itself, provide the option name inline:

$ echo -n "/var/log/vault.log" | vault audit enable file file_path=-

To pass data as a file, use @ as a stand-in for the entire <option-name>=<value> pair or a specific option value.

To pass the option and value, use a JSON file:

data.json:
{
  "file_path":"/var/log/vault.log"
}

$ vault audit enable file @data.json

To pass the option value by itself, use the option name inline and pass the value as text:

data.txt:
/var/log/vault.log

$ vault audit enable file file_path=@data.txt

If you use @ as part of an argument name in <option-name>=<value> format, Vault treats the @ as part of the key name, rather than a file reference. As a result, Vault does not support filenames that include the = character.

Escape literal '@' values

To keep Vault from parsing values that begin with a literal @, escape the value with a backslash (\):

$ vault login -method userpass  \
    username="mitchellh"        \
    password="\@badpasswordisbad"

Calling API endpoints

To invoke an API endpoint with the Vault CLI, you can use one of the following CLI commands with the associated endpoint path:

CLI command	HTTP verbs
`vault read`	`GET`
`vault write`	`PUT`, `POST`
`vault delete`	`DELETE`
`vault list`	`LIST`

For example, to call the UpsertLDAPGroup endpoint, /auth/ldap/groups/{group-name} to create a new LDAP group called admin:

$ vault write /auth/ldap/groups/admin policies="admin,default"

Core plugins have dedicated commands

You can use read, write, delete, or list with the relevant paths for any valid API endpoint, but some plugins are central to the functionality of Vault and have dedicated CLI commands:

Enable autocomplete

The CLI does not autocomplete commands by default. To enable autocomplete for flags, subcommands, and arguments (where supported), use the -autocomplete-install flag and restart your shell session:

$ vault -autocomplete-install

To use autocomplete, press <tab> while typing a command to show a list of available completions. Or, use the -<tab> flag to show available flag completions for the current command.

Tip

If you have configured the VAULT_* environment variables needed to connect to your Vault instance, the autocomplete feature automatically queries the Vault server and returns helpful argument suggestions.

Configure environment variables

You can use environment variables to configure the CLI globally. Some configuration settings have a corresponding CLI flag to configure a specific command.

For example, export VAULT_ADDR='http://localhost:8200' sets the address of your Vault server globally, while -address='http://someotherhost:8200' overrides the value for a specific command.

[-address | VAULT_ADDR] (string : 'https://127.0.0.1:8200')

Address of the Vault server.

Examples:

CLI flag: -address "https://mydomain/vault:8200"
Environment variable: export VAULT_ADDR="https://mydomain/vault:8200"

[-agent-address | VAULT_AGENT_ADDR] (string : "")

Address of the Vault Agent, if used.

Examples:

CLI flag: -agent-address "https://mydomain/vault-agent:8200"
Environment variable: export VAULT_AGENT_ADDR="https://mydomain/vault-agent:8200"

[-ca-cert | VAULT_CA_CERT] (string : "")

Path to a PEM-encoded CA certificate file on the local disk. Used to verify SSL certificates for the server. Takes precedence over -ca_path.

Examples:

CLI flag: -ca-cert "/path/to/certs/mycert.pem"
Environment variable: export VAULT_CA_CERT="/path/to/certs/mycert.pem"

[-ca-path | VAULT_CAPATH] (string : "")

Path to a directory with PEM-encoded CA certificate files on the local disk. Used to verify SSL certificates for the server.

Examples:

CLI flag: -ca-path "/path/to/certs/dir"
Environment variable: export VAULT_CAPATH="/path/to/certs/dir"

VAULT_CLI_NO_COLOR (bool : true)

Exclude ANSI color escape sequence characters from the CLI output.

Example: export VAULT_CLI_NO_COLOR=0

[-client-cert | VAULT_CLIENT_CERT] (string : "")

Path to a PEM-encoded CA certificate file on the local disk. Used for TLS communication with the server. The specified certificate must match to the private key specified with -client-cert.

Examples:

CLI flag: -client-cert "/path/to/certs/mycert.pem"
Environment variable: export VAULT_CLIENT_CERT="/path/to/certs/mycert.pem"

[-client-key | VAULT_CLIENT_KEY] (string : "")

Path to a PEM-encoded private key that matches the client certificate set with -client-cert.

Examples:

CLI flag: -client-key "/path/to/keys/myprivatekey.pem"
Environment variable: export VAULT_CLIENT_KEY="/path/to/keys/myprivatekey.pem"

VAULT_CLIENT_TIMEOUT (string : "60s")

Default time in <number>[s|m|h|d] format for the CLI to wait on a response from Vault.

Example: export VAULT_CLIENT_TIMEOUT="2m"

VAULT_CLUSTER_ADDR (string : "")

Address of the local Vault node. Vault uses cluster addresses for cluster-to-cluster communication when running in high-availability mode.

Example: export VAULT_CLUSTER_ADDR="https://127.0.0.1:8201"

[-disable-redirects | VAULT_DISABLE_REDIRECTS] (bool : false)

Disable the default CLI redirect behavior so the CLI honors the first redirect response from the underlying API instead of following the full HTTP redirect chain.

Examples:

CLI flag: -disable-redirects
Environment variable: export VAULT_DISABLE_REDIRECTS=1

Warning

Disabling the default redirect behavior may cause commands that redirect requests to primary cluster notes (like vault operator raft snapshot) to misbehave.

[-format | VAULT_FORMAT] (enum: json)

Set the CLI output format.

Value	Description
`table`	Structure the response as a table
`json`	Structure the response as JSON data
`yaml`	Structure the response as YAML data
`jsonx`	Structure information as XML data

Examples:

CLI flag: -format table
Environment variable: export VAULT_FORMAT=table

VAULT_HTTP_PROXY (string : "")

Legacy alias for VAULT_PROXY_ADDR.

VAULT_LICENSE_PATH (string : "") Enterprise

Local path to a file containing a valid Vault Enterprise license for the server or node. VAULT_LICENSE_PATH takes precedence over the license_path parameter in the Vault configuration file.

Example: export VAULT_LICENSE_PATH=/local/path/to/vault.hclic

VAULT_LICENSE (string : "") Enterprise

Vault Enterprise license string for the local server or node. VAULT_LICENSE takes precedence over VAULT_LICENSE_PATH and the license_path parameter in the Vault configuration file.

Example: export VAULT_LICENSE="02MV4UU43BK5..."

VAULT_LOG_LEVEL (enum : info)

Default logging level for the Vault server.

Enum	Logging behavior
`trace`	Log everything including details about process flow within the server
`debug`	`info` level logging and detailed server state
`info`	`warn` level logging, server events, and general server state
`warn`	`err` level logging, deprecations, and potentially harmful events/states in the server
`err`	Log information about non-fatal errors and handled exceptions

Example: export VAULT_LOG_LEVEL=debug

VAULT_MAX_RETRIES (integer : 2)

The number of times the CLI should retry a request to the Vault server when the CLI receives one of the following recoverable error codes:

412 - "Client consistency requirement not satisfied"
5xx - Any server error except 501, which Vault does not use.

To disable retrying, set VAULT_MAX_RETRIES to 0.

Example: export VAULT_MAX_RETRIES=5

[-mfa | VAULT_MFA] (string : "") Enterprise

A multi-factor authentication (MFA) credential, in the format mfa_method_name[:key[=value]], that the CLI should use to authenticate to Vault. The CLI adds MFA credentials to the X-Vault-MFA header when calling the underlying API endpoint.

Examples:

CLI flag: -mfa "totp:password=12345"
Environment variable: export VAULT_MFA="totp:password=12345"

Note

The VAULT_MFA environment variable only accepts one MFA method specification and one credential for the specified method. To supply multiple credentials or MFA methods, use the -mfa CLI flag and repeat the flag as needed.

[-namespace | -ns | VAULT_NAMESPACE] (string : <unset>)

Root namespace for the CLI command. Setting a default namespace allow relative mount paths.

Examples:

CLI flag: -namespace "admin"
Environment variable: export VAULT_NAMESPACE="admin"

VAULT_PROXY_ADDR (string : "")

The HTTPS or HTTP address, including server and port, where clients can access Vault. Setting VAULT_HTTP_PROXY overrides the default proxy resolution behavior and tells Vault to ignore the following proxy-related environment variables: HTTP_PROXY, HTTPS_PROXY, and NO_PROXY.

Preferred over VAULT_HTTP_ADDR.

All CLI requests resolve the specified proxy and you cannot exclude domains from consulting the proxy server.

Example: export VAULT_PROXY_ADDR="https://gohereforvault:8200"

VAULT_RATE_LIMIT (string : unset)

The number of operations per second, in rate[:burst] format, used to throttle requests between the CLI and the server. The burst value is optional and defaults to rate when not specified.

Leaving VAULT_RATE_LIMIT unset disables request limiting.

Example: export VAULT_RATE_LIMIT="10:30"

Tip

The rate limit is not global and applies individually to each invocation of the CLI. As a result, the VAULT_RATE_LIMIT variable is most useful when using the Go SDK for Vault.

VAULT_REDIRECT_ADDR (string : "")

Local node address that listens for redirected client communication when Vault runs in high-availability mode.

Example: export VAULT_CLUSTER_ADDR="https://127.0.0.1:8201"

VAULT_SKIP_VERIFY (bool : false)

Allow communication between the CLI and Vault server before verifying the authentication certificate presented by Vault.

Example: export VAULT_SKIP_VERIFY=1

Not appropriate for production

Do not use VAULT_SKIP_VERIFY in production. Skipping certificate verification violates the Vault security model and voids any associated security guarantees.

VAULT_SRV_LOOKUP (bool : false)

Use SRV records instead of standard DNS to look up hostnames as described in the Network Working Group draft "Use of SRV records in conjunction with HTTP and URIs".

Example: export VAULT_SRV_LOOKUP=1

Not appropriate for production

SRV lookup is still in discovery and not designed for high-availability deployments.

[-tls-server-name | VAULT_TLS_SERVER_NAME] (string : "")

Name of the SNI host for TLS handshake resolution for TLS connections to Vault.

Examples:

CLI flag: -tls-server-name "hostname.domain"
Environment variable: export VAULT_TLS_SERVER_NAME="hostname.domain"

[-tls-skip-verify | VAULT_SKIP_VERIFY] (bool : false)

Disable verification for all TLS certificates. Use with caution. Disabling TLS certificate verification decreases the security of data transmissions to and from the Vault server.

Examples:

CLI flag: -tls-skip-verify
Environment variable: export VAULT_SKIP_VERIFY=1

VAULT_TOKEN (string : "")

A Vault-issued service token that authenticates the CLI user to Vault. See the tokens concepts page for more information on token types.

Example: export VAULT_TOKEN="hvs.CvmS4c0DPTvHv5eJgXWMJg9r"

[-wrap-ttl | VAULT_WRAP_TTL] (string : "")

Default time-to-live in <number>[s|m|h|d] format for the Cubbyhole token used to wrap CLI responses. You must use vault unwrap to view response data before the duration expires. Leave wrap_ttl unset to leave CLI responses unwrapped.

Examples:

CLI flag: -wrap-ttl "5m"
Environment variable: export VAULT_WRAP_TTL="5m"

Troubleshoot CLI errors

If you run into errors when executing a particular CLI command, the following flags and commands can help you track down the problem.

Confirm you are using the right endpoint or command

If a command behaves differently than expected or you need details about a specific endpoint, you can use the vault path-help command to see the help text for a given endpoint path.

For example, to see the help for sys/mounts:

$ vault path-help sys/mounts
Request:        mounts
Matching Route: ^mounts$

List the currently mounted backends.

## DESCRIPTION

This path responds to the following HTTP methods.

    GET /
        Lists all the mounted secret backends.

    GET /<mount point>
        Get information about the mount at the specified path.

    POST /<mount point>
        Mount a new secret backend to the mount point in the URL.

    POST /<mount point>/tune
        Tune configuration parameters for the given mount point.

    DELETE /<mount point>
        Unmount the specified mount point.

Construct the associated cURL command

To determine if the problem exists with the structure of your CLI command or the associated endpoint, you can use the -output-curl-string flag:

For example, to test that a vault write command to create a new user is not failing due to an issue with the /auth/userpass/users/{username} endpoint, use the generated cURL command to call the endpoint directly:

$ vault write -output-curl-string  auth/userpass/users/bob password="long-password"

curl -X PUT -H "X-Vault-Request: true" -H "X-Vault-Token: $(vault print token)" -d '{"password":"long-password"}' http://127.0.0.1:8200/v1/auth/userpass/users/bob

Construct the required Vault policy

To determine if the problem relates to insufficient permissions, you can use the -output-policy flag to construct a minimal Vault policy that grants the permissions needed to execute the relevant command.

For example, to confirm you have permission to write a secret to the kv plugin, mounted at kv/secret, use -output-policy then confirm you have the capabilities listed:

$ vault kv put -output-policy kv/secret value=itsasecret
 
path "kv/data/secret" {
  capabilities = ["create", "update"]
}