DEV Community

Cover image for Hashicorp Vault CLI Part 1: Initialization, Authentication & Plugin Management
Sebastian
Sebastian

Posted on

Hashicorp Vault CLI Part 1: Initialization, Authentication & Plugin Management

#hashicorp #vault

The Hashicorp Vault secrets management tool comes as an executable binary supporting all major operating systems. The binary itself is a multi-purpose tool, providing several commands to start and configure single vault instances or a cluster of multiple servers, define authentication mechanisms and policies, and configure and work with secret engines.

This and the following blog posts provide a complete coverage of all CLI commands. In this first part, three aspects are explored: commands that perform a startup of Vaults’ system processes, authentication with a Vault instance, and high-level plugin management.

The technical context of this article is hashicorp_vault_v.1.20, published 2025-06-25. All provided information and command examples should be valid with newer versions too, baring update to the syntax of CLI commands.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared on my blog admantium.com.

CLI Overview: Basic Commands

As every CLI, the Hashicorp Vault binary, aptly named vault, provides built-in documentation, exposed by passing --help to the root-level or its subcommands. Available commands are printed in a flat list, but they are applicable to different lifecycles of operating and using vault.

Grouping the commands accordingly yields the following structure:

  • Initialization
    • server: Starts a server process
    • agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
    • proxy: Starts a vault proxy process
  • Authentication
    • login: Authenticates access to a Vault server, supporting different authentication methods like user credentials, token, certificates and even external services like GitHub
  • Plugin Management
    • plugin: Manage and install additional plugins
  • Operation
    • operator: Cluster management operations, including memberships, encryption and unseal keys
    • runtime: Show runtime information
    • status: Show status information of the vault server
    • debug: Shows debug information of the connected Vault server
    • events: Subscribe to the event stream of a running vault instance
    • monitor: Print vault log messages
    • print: Detailed view of the vault’s server runtime configuration
    • version-history: Shows detailed version information about the vault server
  • Special Purpose Configuration
    • audit: Interact with connected audit devices
    • auth: Interact with configured authentication options
  • Multi Purpose Configuration
    • read / list: Access stored configuration and secrets
    • write / patch : Modify or create any data
    • delete: Delete stored secrets and data
  • Secrets Management
    • secrets: General configuration of secret engines
    • kv: Access to the essential key-value store
    • pki: Access the private key infrastructure secrets engine
    • policies: Manage policy definitions (governing mostly secrets, but also other vault operations)
    • lease: Manage current token leases, including renewal, revocation and TTL modification
    • tokens: General token management
    • transform: Interact with rate the transform secrets engine
    • transit: Interact with the Vaults transit secrets engine
    • ssh: Initiates SSH sessions via the SSH secrets engine
  • Miscellaneous
    • unwrap: Work with encrypted data to unwrap
    • hcp: Operate a managed Hashicorp Vault Cluster
    • namespace: Interact with configured namespaces of the cluster
    • path-help: Additional examples for using the patch command

In this blog article, only the commands from groups initialization, authentication, and plugin management are explored.

Initialization Commands

This group contains all commands that start a Vault process or a process that communicates transparently with Vault servers are grouped together.

server

This command starts a new vault instance. The most important configuration options can be provided either as flags to this command, or expressed in a configuration file that itself becomes an argument. Defining attributes are these:

  • address: The local IP address and port to which the vault process is bound
  • ca-path: A directory with PEM-encoded certificates that vault uses for encrypting all local traffic
  • client-cert: One of Vaults authentication mechanisms are client certificates in PEM format. This flag designates a local folder from which the certificates will be loaded.
  • dev: This flag starts a non-production, no-encryption and in-memory only instance of a Vault server

agent

Agent mode provides a process-level communication mode of any server with a Vault instance or cluster. Agents work be being configured with special template formats in which plaintext secrets are rendered. The default options of the server command are available as well, with the following additions:

Subcommands

  • generate-config: As the name suggests, this command generates an agent configuration. In hashicorp_vault_v.1.20, the only option is to append -type="env-template". The resulting file is as follows: 
auto_auth {
  method {
    type = "token_file"

    config {
      token_file_path = "/home/users/.vault-token"
    }
  }
}

template_config {
  static_secret_render_interval = "5m"
  exit_on_retry_failure         = true
  max_connections_per_host      = 10
}

vault {
  address = "http://127.0.0.1:8200"
}

exec {
  command                   = ["env"]
  restart_on_secret_changes = "always"
  restart_stop_signal       = "SIGTERM"
}
Enter fullscreen mode Exit fullscreen mode

proxy

This command starts a local process that mimics the API of a Vault instance or cluster. Once authenticated with a Vault, it handles all client requests transparently. An additional benefit is the ability of local client caching, storing responses from authentication methods and leased secrets likewise. To facilitate the usage of a Vault proxy, the initial authentication with vault can be configured as auto authentication. This requires a supported authentication option and a "sink", a place where the auth information is stored.

No additional subcommands are provided, and as before, the default options of the server command are available too.

Authentication Commands

Any other CLI command that follow the initialization of a Vault process first needs authorized access to Vault. These requirements are embodied by the login command.

login

The default authentication mechanism is token, accepting the initial root token created during vault initialization, or any other token that was added manually. Several other authentication methods are supported as well, used by passing the flag -method to this command. Subcommands for different authentication mechanisms expose several flags for passing specific arguments such as in -method=userpass username=my-username.

To see all available authentication methods, two options can be used.

First, the interactive Vault GUI shows them graphically.

Second, running a dedicated command for listing the available plugins, which are explained in more detail in the next section.

> vault plugin list database

# Log messages
Name                                 Version
----                                 -------
cassandra-database-plugin            v1.20.0+builtin.vault
couchbase-database-plugin            v0.14.0+builtin
elasticsearch-database-plugin        v0.18.0+builtin
hana-database-plugin                 v1.20.0+builtin.vault
influxdb-database-plugin             v1.20.0+builtin.vault
mongodb-database-plugin              v1.20.0+builtin.vault
mongodbatlas-database-plugin         v0.15.0+builtin
mssql-database-plugin                v1.20.0+builtin.vault
mysql-aurora-database-plugin         v1.20.0+builtin.vault
mysql-database-plugin                v1.20.0+builtin.vault
mysql-legacy-database-plugin         v1.20.0+builtin.vault
mysql-rds-database-plugin            v1.20.0+builtin.vault
postgresql-database-plugin           v1.20.0+builtin.vault
redis-database-plugin                v0.6.0+builtin
redis-elasticache-database-plugin    v0.7.0+builtin
redshift-database-plugin             v1.20.0+builtin.vault
snowflake-database-plugin            v0.14.1+builtin
Enter fullscreen mode Exit fullscreen mode

Plugin Management

Plugin is the technical name and architectural implementation of extended Vault functionality. There are three groups of plugins: auth, database, and secrets.

The plugin subcommands interacts with a plugin catalog, a dynamic information base, or the runtime plugins of a Vault instance. They are structured in respective subsections each.

Plugin Catalog

plugin list

Show all available plugins that are configured in a Vaults instance plugin catalog. Naturally, on a fresh installation, these plugins reflect the complete list of built-in variants.

For v.1.20, the following secret plugins are available:

> vault plugin list -detailed secret

# Log messages
Name            Version
----            -------
ad              v0.21.0+builtin
alicloud        v0.20.0+builtin
aws             v1.20.0+builtin.vault
azure           v0.22.0+builtin
consul          v1.20.0+builtin.vault
gcp             v0.22.0+builtin
gcpkms          v0.21.0+builtin
kubernetes      v0.11.0+builtin
kv              v0.24.0+builtin
ldap            v1.20.0+builtin.vault
mongodbatlas    v0.15.0+builtin
nomad           v1.20.0+builtin.vault
openldap        v0.16.0+builtin
pki             v1.20.0+builtin.vault
rabbitmq        v1.20.0+builtin.vault
ssh             v1.20.0+builtin.vault
terraform       v0.12.0+builtin
totp            v1.20.0+builtin.vault
transit         v1.20.0+builtin.vault
Enter fullscreen mode Exit fullscreen mode

And the following database secret plugins are configurable:

> vault plugin list database

# Log messages
Name                                 Version
----                                 -------
cassandra-database-plugin            v1.20.0+builtin.vault
couchbase-database-plugin            v0.14.0+builtin
elasticsearch-database-plugin        v0.18.0+builtin
hana-database-plugin                 v1.20.0+builtin.vault
influxdb-database-plugin             v1.20.0+builtin.vault
mongodb-database-plugin              v1.20.0+builtin.vault
mongodbatlas-database-plugin         v0.15.0+builtin
mssql-database-plugin                v1.20.0+builtin.vault
mysql-aurora-database-plugin         v1.20.0+builtin.vault
mysql-database-plugin                v1.20.0+builtin.vault
mysql-legacy-database-plugin         v1.20.0+builtin.vault
mysql-rds-database-plugin            v1.20.0+builtin.vault
postgresql-database-plugin           v1.20.0+builtin.vault
redis-database-plugin                v0.6.0+builtin
redis-elasticache-database-plugin    v0.7.0+builtin
redshift-database-plugin             v1.20.0+builtin.vault
snowflake-database-plugin            v0.14.1+builtin
Enter fullscreen mode Exit fullscreen mode

plugin info

Prints detailed information about a plugin. For example, the built-in kv secret plugin is shown as this:

> vault plugin info secret kv   

# Log messages
Key                   Value
---                   -----
args                  []
builtin               true
command               n/a
deprecation_status    supported
name                  kv
oci_image             n/a
runtime               n/a
sha256                n/a
version               v0.24.0+builtin
Enter fullscreen mode Exit fullscreen mode

plugin register

In addition to the built-in plugins provided with the vault binary itself, several external and community plugins can be added too. This command assumes that the plugin is provided as a binary, executable file stored in the plugin directory path. Additional flags to this command control metainformations like the version, plugin parameters, and a sh256 sum of the binary file.

The documentation about Vault plugin ecosystem provides additional information and sources for different plugin types.

plugin deregister

Removes a manually added plugin from the local catalog, either completely, or a dedicated version by passing the same named flag to the command.

It is not possible to remove a built-in plugin - an attempt is shown in the following:

> vault plugin deregister secret aws

# Log messages
Plugin "aws" (type: "secret") is a built-in plugin and cannot be deregistered
Enter fullscreen mode Exit fullscreen mode

Runtime Plugins

plugin reload

Re-initializes a configured plugin with the default options. This method is helpful when a newer version of a plugin is installed, and should be loaded without a shutdown of the complete Vault instance. All type of plugins can be reloaded as shown by the following example.

> vault plugin reload -type=secret -plugin=kv              

# Log messages
Success! Reloaded plugin: kv
Enter fullscreen mode Exit fullscreen mode

plugin reload-status

Shows metainformation about a concrete reload action, requiring the reload ID. However, I could not find information about where to obtain a reload ID - it is not returned by the reload command, and also not included in the Vault logfile, even when extending the LOG_LEVEL to debug.

plugin runtime

This subcommand interacts directly with the running Vault instance plugins, and supports the sub-subcommands info, list, register and deregister which work similarly as their plugin catalog counterparts.

At the time of writing, the runtime command only supports custom plugins of type container as the following explanation from the CLI itself exposes:

> vault plugin runtime --help 

# Log messages
Usage: vault plugin runtime <subcommand> [options] [args]

  This command groups subcommands for interacting with Vaults plugin runtimes and the
  plugin runtime catalog. The plugin runtime catalog is divided into types. Currently,
  Vault only supports "container" plugin runtimes
Enter fullscreen mode Exit fullscreen mode

Conclusion

The Hashicorp Vault binary is a multipurpose CLI tool. In this blog article, commands from the first lifecycle phase were detailed. You learned how to start a Vault process that acts as a complete server, as an agent for lightweight Vault interaction that renders secrets to template files, and as a proxy server for thin replica of the vault REST API. Continuing from there, the Vault CLI needs to be authenticated with the Vault server. Finally, you learned about interacting with the plugin catalog and runtime plugins. The next article continues with operator configuration commands.

Top comments (0)