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]

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.

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

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

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

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

$ vault audit enable file @data.json

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

$ vault audit enable file file_path=@data.txt

$ 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:

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"

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.

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 of the Vault server.

Examples:

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

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"

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_CACERT="/path/to/certs/mycert.pem"

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"

Exclude ANSI color escape sequence characters from the CLI output.

Example: export VAULT_CLI_NO_COLOR=0

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"

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"

Amount of time, in <number>[s|m|h|d] format, the CLI should wait on a response from Vault.

Example: export VAULT_CLIENT_TIMEOUT="2m"

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 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

Set the CLI output format.

Examples:

• CLI flag: -format json
• Environment variable: export VAULT_FORMAT=json

Legacy alias for VAULT_PROXY_ADDR.

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 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..."

Format of log data:

• standard - Write log data as basic text.
• json - Write log data as JSON.

Examples:

• CLI flag: -log-format json
• Environment variable: export VAULT_LOG_FORMAT=json

Default logging level for the Vault server.

Examples:

• CLI flag: -log-level debug
• Environment variable: export VAULT_LOG_LEVEL=debug

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

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"

Format of log data:

• standard - Write log data as basic text.
• json - Write log data as JSON.

Examples:

• CLI flag: -log-format json
• Environment variable: export VAULT_LOG_FORMAT=json

Default logging level for the Vault server.

Examples:

• CLI flag: -log-level debug
• Environment variable: export VAULT_LOG_LEVEL=debug

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"

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"

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"

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"

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

Example: export VAULT_SKIP_VERIFY=1

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

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"

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

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"

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"]
}