Command reference

hvac-cli is CLI to Hashicorp Vault with additional features. It does not support extensions that are not available as Free Software such as namespaces, Sentinel, Policy Overrides or Multi-factor Authentication (MFA).
hvac-cli
    [--version]
    [-v | -q]
    [--log-file LOG_FILE]
    [--debug]
    [--dry-run]
    [--token TOKEN]
    [--address ADDRESS]
    [--tls-skip-verify]
    [--ca-cert CA_CERT]
    [--client-cert CLIENT_CERT]
    [--client-key CLIENT_KEY]
--version

show program’s version number and exit

-v, --verbose

Increase verbosity of output. Can be repeated.

-q, --quiet

Suppress output except warnings and errors.

--log-file <LOG_FILE>

Specify a file to log output. Disabled by default.

--debug

Show tracebacks on errors.

--dry-run

Show what would be done but do nothing

--token <TOKEN>

Vault token. It will be prompted interactively if unset. This can also be specified via the VAULT_TOKEN environment variable.

--address <ADDRESS>, --agent-address <ADDRESS>

Address of the Vault server or the Vault agent. –agent-address was introduced with vault 1.1.0. This can also be specified via the VAULT_ADDR or the VAULT_AGENT_ADDR environment variable. If both VAULT_AGENT_ADDR and VAULT_ADDR are in the environment VAULT_AGENT_ADDR has precedence

--tls-skip-verify

Disable verification of TLS certificates. Using this option is highly discouraged and decreases the security of data transmissions to and from the Vault server. The default is false. This can also be specified via the VAULT_SKIP_VERIFY environment variable.

--ca-cert <CA_CERT>

Path on the local disk to a single PEM-encoded CA certificate to verify the Vault server’s SSL certificate. This can also be specified via the VAULT_CACERT environment variable.

--client-cert <CLIENT_CERT>

Path on the local disk to a single PEM-encoded CA certificate to use for TLS authentication to the Vault server. If this flag is specified, –client-key is also required. This can also be specified via the VAULT_CLIENT_CERT environment variable.

--client-key <CLIENT_KEY>

Path on the local disk to a single PEM-encoded private key matching the client certificate from -client-cert. This can also be specified via the VAULT_CLIENT_KEY environment variable.

kv delete

Deletes the data for the provided version and path in the key-value store The versioned data will not be fully removed, but marked as deleted and will no longer be returned in normal get requests.

To delete the latest version of the key “foo”:

$ hvac-cli kv delete secret/foo

To delete version 3 of key foo:

$ hvac-cli kv delete –versions=3 secret/foo
hvac-cli kv delete
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    [--versions VERSIONS]
    key
--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

--versions <VERSIONS>

The comma separate list of version numbers to delete

key

key to delete

This command is provided by the hvac-cli plugin.

kv destroy

Permanently removes the specified versions data from the key-value store If no key exists at the path, no action is taken.

To destroy version 3 of key foo:

$ hvac-cli kv destroy –versions=3 secret/foo
hvac-cli kv destroy
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    --versions VERSIONS
    key
--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

--versions <VERSIONS>

The comma separate list of version numbers to destroy

key

key to destroy

This command is provided by the hvac-cli plugin.

kv dump

Dump all secrets as a JSON object where the keys are the path and the values are the secrets. For instance:

{
  "a/secret/path": { "key1": "value1" },
  "another/secret/path": { "key2": "value2" }
}
hvac-cli kv dump [--mount-point MOUNT_POINT] [--kv-version {1,2}]
--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

This command is provided by the hvac-cli plugin.

kv erase

Erase all secrets

hvac-cli kv erase [--mount-point MOUNT_POINT] [--kv-version {1,2}]
--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

This command is provided by the hvac-cli plugin.

kv get

Retrieves the value from Vault key-value store at the given key name If no key exists with that name, an error is returned. If a key exists with that name but has no data, nothing is returned.

$ hvac-cli kv get secret/foo

To view the given key name at a specific version in time, specify the “–from-version” flag:

$ hvac-cli kv get –from-version=1 secret/foo
hvac-cli kv get
    [-f {json,shell,table,value,yaml}]
    [-c COLUMN]
    [--noindent]
    [--prefix PREFIX]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    [--from-version FROM_VERSION]
    key
-f <FORMATTER>, --format <FORMATTER>

the output format, defaults to table

-c COLUMN, --column COLUMN

specify the column(s) to include, can be repeated

--noindent

whether to disable indenting the JSON

--prefix <PREFIX>

add a prefix to all variable names

--max-width <integer>

Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width

Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty

Print empty table if there is no data to show.

--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

--from-version <FROM_VERSION>

If passed, the value at the version number will be returned. (KvV2 only)

key

key to fetch

This command is provided by the hvac-cli plugin.

kv list

Lists data from Vault key-value store at the given path.

List values under the “my-app” folder of the key-value store:

$ hvac-cli kv list secret/my-app/
hvac-cli kv list
    [-f {csv,json,table,value,yaml}]
    [-c COLUMN]
    [--quote {all,minimal,none,nonnumeric}]
    [--noindent]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--sort-column SORT_COLUMN]
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    path
-f <FORMATTER>, --format <FORMATTER>

the output format, defaults to table

-c COLUMN, --column COLUMN

specify the column(s) to include, can be repeated

--quote <QUOTE_MODE>

when to include quotes, defaults to nonnumeric

--noindent

whether to disable indenting the JSON

--max-width <integer>

Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width

Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty

Print empty table if there is no data to show.

--sort-column SORT_COLUMN

specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated

--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

path

path to list

This command is provided by the hvac-cli plugin.

kv load

Load secrets from a JSON object for which the key is the path and the value is the secret. For instance:

{
  "a/secret/path": { "key1": "value1" },
  "another/secret/path": { "key2": "value2" }
}
hvac-cli kv load
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    [--rewrite-key]
    [--no-workaround-6282]
    path
--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

--rewrite-key

Rewrite the key to avoid UI problems and print a warning. Workaround https://github.com/hashicorp/vault/issues/6282; https://github.com/hashicorp/vault/issues/6213; replace control characters and percent with an underscore

--no-workaround-6282

Do not workaround bug https://github.com/hashicorp/vault/issues/6282

path

path containing secrets in JSON

This command is provided by the hvac-cli plugin.

kv metadata delete

Deletes all versions and metadata for the provided key

$ hvac-cli kv metadata delete secret/foo
hvac-cli kv metadata delete
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    key
--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

key

key to delete

This command is provided by the hvac-cli plugin.

kv metadata get

Retrieves the metadata from Vault key-value store at the given key name If no key exists with that name, an error is returned.

$ hvac-cli kv metadata get secret/foo

This command only works with KVv2

hvac-cli kv metadata get
    [-f {json,shell,table,value,yaml}]
    [-c COLUMN]
    [--noindent]
    [--prefix PREFIX]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    key
-f <FORMATTER>, --format <FORMATTER>

the output format, defaults to table

-c COLUMN, --column COLUMN

specify the column(s) to include, can be repeated

--noindent

whether to disable indenting the JSON

--prefix <PREFIX>

add a prefix to all variable names

--max-width <integer>

Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width

Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty

Print empty table if there is no data to show.

--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

key

get metadata for this key

This command is provided by the hvac-cli plugin.

kv metadata put

Update the metadata associated with an existing key

Set a max versions setting on the key:

$ hvac-cli kv metadata put –max-versions=5 secret/foo

Require Check-and-Set for this key:

$ hvac-cli kv metadata put –cas-required=true secret/foo

This command only works with KVv2

hvac-cli kv metadata put
    [-f {json,shell,table,value,yaml}]
    [-c COLUMN]
    [--noindent]
    [--prefix PREFIX]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    [--cas-required CAS_REQUIRED]
    [--max-versions MAX_VERSIONS]
    key
-f <FORMATTER>, --format <FORMATTER>

the output format, defaults to table

-c COLUMN, --column COLUMN

specify the column(s) to include, can be repeated

--noindent

whether to disable indenting the JSON

--prefix <PREFIX>

add a prefix to all variable names

--max-width <integer>

Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width

Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty

Print empty table if there is no data to show.

--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

--cas-required <CAS_REQUIRED>

If true the key will require the cas parameter to be set on all write requests. If false, the backend’s configuration will be used. The default is false.

--max-versions <MAX_VERSIONS>

The number of versions to keep. If not set, the backend’s configured max version is used.

key

set metadata for this key

This command is provided by the hvac-cli plugin.

kv patch

Read the data from the given path and merge it with the data provided If the existing data is a dictionary named OLD and the data provided is a dictionary named NEW, the data stored is the merge of OLD and NEW. If a key exists in both NEW and OLD, the one from NEW takes precedence.

$ hvac-cli kv patch secret/foo bar=baz

The data can also be consumed from a JSON file on disk. For example:

$ hvac-cli kv patch secret/foo –file=/path/data.json
hvac-cli kv patch
    [-f {json,shell,table,value,yaml}]
    [-c COLUMN]
    [--noindent]
    [--prefix PREFIX]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    [--rewrite-key]
    [--no-workaround-6282]
    [--file FILE]
    key
    [kvs [kvs ...]]
-f <FORMATTER>, --format <FORMATTER>

the output format, defaults to table

-c COLUMN, --column COLUMN

specify the column(s) to include, can be repeated

--noindent

whether to disable indenting the JSON

--prefix <PREFIX>

add a prefix to all variable names

--max-width <integer>

Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width

Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty

Print empty table if there is no data to show.

--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

--rewrite-key

Rewrite the key to avoid UI problems and print a warning. Workaround https://github.com/hashicorp/vault/issues/6282; https://github.com/hashicorp/vault/issues/6213; replace control characters and percent with an underscore

--no-workaround-6282

Do not workaround bug https://github.com/hashicorp/vault/issues/6282

--file <FILE>

A JSON object containing the secrets

key

key to set

kvs

k=v secrets that can be repeated. They are ignored if –file is set.

This command is provided by the hvac-cli plugin.

kv put

Writes the data to the given path in the key-value store The data can be of any type.

$ hvac-cli kv put secret/foo bar=baz

The data can also be consumed from a JSON file on disk. For example:

$ hvac-cli kv put secret/foo –file=/path/data.json
hvac-cli kv put
    [-f {json,shell,table,value,yaml}]
    [-c COLUMN]
    [--noindent]
    [--prefix PREFIX]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    [--rewrite-key]
    [--no-workaround-6282]
    [--file FILE]
    [--cas CAS]
    key
    [kvs [kvs ...]]
-f <FORMATTER>, --format <FORMATTER>

the output format, defaults to table

-c COLUMN, --column COLUMN

specify the column(s) to include, can be repeated

--noindent

whether to disable indenting the JSON

--prefix <PREFIX>

add a prefix to all variable names

--max-width <integer>

Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width

Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty

Print empty table if there is no data to show.

--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

--rewrite-key

Rewrite the key to avoid UI problems and print a warning. Workaround https://github.com/hashicorp/vault/issues/6282; https://github.com/hashicorp/vault/issues/6213; replace control characters and percent with an underscore

--no-workaround-6282

Do not workaround bug https://github.com/hashicorp/vault/issues/6282

--file <FILE>

A JSON object containing the secrets

--cas <CAS>

Specifies to use a Check-And-Set operation. If not set the write will be allowed. If set to 0 a write will only be allowed if the key doesn’t exist. If the index is non-zero the write will only be allowed if the key’s current version matches the version specified in the cas parameter. (KvV2 only)

key

key to set

kvs

k=v secrets that can be repeated. They are ignored if –file is set.

This command is provided by the hvac-cli plugin.

kv rollback

Restores a given previous version to the current version at the given path The value is written as a new version; for instance, if the current version is 5 and the rollback version is 2, the data from version 2 will become version 6.

$ hvac-cli kv rollback –from-version=2 secret/foo
hvac-cli kv rollback
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    --from-version FROM_VERSION
    key
--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

--from-version <FROM_VERSION>

The version number that should be made current again

key

key to rollback

This command is provided by the hvac-cli plugin.

kv undelete

Undeletes the data for the provided version and path in the key-value store This restores the data, allowing it to be returned on get requests.

To undelete version 3 of key “foo”:

$ hvac-cli kv undelete –versions=3 secret/foo
hvac-cli kv undelete
    [--mount-point MOUNT_POINT]
    [--kv-version {1,2}]
    --versions VERSIONS
    key
--mount-point <MOUNT_POINT>

KV path mount point, as found in vault read /sys/mounts

--kv-version <KV_VERSION>

Force the Vault KV backend version (1 or 2). Autodetect from vault read /sys/mounts if not set.

--versions <VERSIONS>

The comma separate list of version numbers to undelete

key

key to undelete

This command is provided by the hvac-cli plugin.

status

Prints the current state of Vault including whether it is sealed and if HA mode is enabled. This command prints regardless of whether the Vault is sealed.

$ hvac-cli status
hvac-cli status
    [-f {json,shell,table,value,yaml}]
    [-c COLUMN]
    [--noindent]
    [--prefix PREFIX]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
-f <FORMATTER>, --format <FORMATTER>

the output format, defaults to table

-c COLUMN, --column COLUMN

specify the column(s) to include, can be repeated

--noindent

whether to disable indenting the JSON

--prefix <PREFIX>

add a prefix to all variable names

--max-width <integer>

Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width

Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty

Print empty table if there is no data to show.

This command is provided by the hvac-cli plugin.

Indices and tables