Hashicorp Vault is a flexible and highly configurable tool for RBAC-based access and management of secrets. Similarly, flexible is the Vault CLI binary, a tool for effective managing both single Vault instances or whole clusters.
This article is the second part of a series about the Vault CLI commands. It details the root-level vault operator command, with which actions such as sealing and unsealing, root and encryption key generation, cluster management, and additional metainformation can be provided. All commands will be explained as well as used in the context of a locally running cluster.
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.
Vault CLI Overview
The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows:
- Initialization
server: Starts a server processagent: Starts an agent process, a utility to communicate with a vault server to gain access to tokensproxy: 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 keysruntime: Show runtime informationstatus: Show status information of the vault serverdebug: Shows debug information of the connected Vault serverevents: Subscribe to the event stream of a running vault instancemonitor: Print vault log messagesprint: Detailed view of the vault’s server runtime configurationversion-history: Shows detailed version information about the vault server
- Special Purpose Configuration
audit: Interact with connected audit devicesauth: Interact with configured authentication options
- Multi Purpose Configuration
read/list: Access stored configuration and secretswrite/patch: Modify or create any datadelete: Delete stored secrets and data
- Secrets Management
secrets: General configuration of secret engineskv: Access to the essential key-value storepki: Access the private key infrastructure secrets enginepolicies: Manage policy definitions (governing mostly secrets, but also other vault operations)lease: Manage current token leases, including renewal, revocation and TTL modificationtokens: General token managementtransform: Interact with rate the transform secrets enginetransit: Interact with the Vaults transit secrets enginessh: Initiates SSH sessions via the SSH secrets engine
- Misc:
unwrap: Work with encrypted data to unwraphcp: Operate a managed Hashicorp Vault Clusternamespace: Interact with configured namespaces of the clusterpath-help: Additional examples for using thepatchcommand
In this blog article, only the command vault operator is explored.
Vault Operator CLI
A freshly started Vault instance is a single, sealed node. The operator commands get the instance operational, allow the formation of a cluster, and output metainformation about operational health. Operator subcommands can be grouped as shown:
- Startup
init: Initializes a vault instance with root key and encryption keysseal: Removes the encryption key from memory, stopping all secret management processesunseal: Reconstructs the root key, then load the encryption key into memory
- Key Management
generate-root: Generate a new root tokenrekey: Generates new unseal keys or encryption keys, with configured type, key shares and key thresholdsrotate: Create and append a new encryption key to the internal keyring
- Storage Management
raft snapshot: Generate and apply backups of the raft storage backendmigrate: Migrates Vault data between different storage backends
- Raft Cluster Management
list-peers: Show the status and role of all registered membersjoin: Adds a configured member to the cluster, making it an active noderemove-peer: Removes a registered member, changing it to an inactive nodeautopilot: A special purpose configuration and process that ensures leader-follower roles of all configured nodes
- General Cluster Management
members: Returns the list of nodes in the clusterstep-down: Changes the currently active node with the leader role, and triggers a new leader election among all nodes
- Information
diagnose: Checks the physical and logical directory storagekey-status: Usage statistics about the currently active encryption keyusage: Statistics about token generation for different clientsutilization: Vault enterprise function to create a license utilization report
Startup Commands
init
The essential command to start a new Vault instance.
When called without any additional flags, it will default to Shamir unseal keys, creating 5 key shares a threshold of three key shares to unseal the vault. Also, a root token will be created. These options can be tweaked at will with additional flags.
> vault operator init
# Log messages
Unseal Key 1: R6hz5iAr3oJo2ZFWCGLhdDoiZ7jT4B484gZah31o/3m/
Unseal Key 2: pP0ov5glEql+JJElikDPKcHC1celjCvMFBSMJwBDBj0J
Unseal Key 3: d4qVXwIrNx8bd+dK/7HDoeN6HrNBM+OV/QKg0pbfac12
Unseal Key 4: Wlc/mCkQZdPqH4lIToEWRbYFIqxJjOJ5cq6D0g1++IdV
Unseal Key 5: 3MTAMDEOQePqPHZsmzDZ6DS3kXADaXWJ7bIi6svG1QAV
Initial Root Token: hvs.Hxik8PHjAlw0IOk0PgSRBen4
Other options are to use self-provided PGP keys. A vault server can only be initialized once. The state backend stores the key shares and the master key used for encrypting all data. The only option is to manually delete the state, which obvious is something to only do in the first minutes of setup before any other configuration data is added.
seal
Immediately unloads the master key from memory, which is used for encryption and decryption of all secrets data in a Vault instance.
A sealed Vault offers only limited functionality. Access to secrets of other configuration items are barred, the HTTP Endpoints returning an error as shown in the following:
> curl --header "X-Vault-Token: hvs.uzEHZBQpWuWKlmeUYx4KY6UZ" -I http://127.0.0.1:8200/v1/kv2/data/apps
# Log messages
HTTP/1.1 503 Service Unavailable
Cache-Control: no-store
Content-Type: application/json
Strict-Transport-Security: max-age=31536000; includeSubDomains
Date: Sun, 20 Jul 2025 07:28:26 GMT
Content-Length: 31
{"errors":["Vault is sealed"]}
unseal
The contrary instruction to reload the master key into memory. The concrete unseal process is governed by the chosen unseal method, defaulting to Shamir key shares. For this default method, the unseal command needs to be called consecutively until the key share threshold value is reached.
Here is an example log of the final unseal command:
> vault operator unseal
# Log messages
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
Total Shares 5
Threshold 3
Version 1.20.0
Build Date 2025-06-23T10:21:30Z
Storage Type raft
Cluster Name vault
Cluster ID a8c988d1-f2c6-eaec-80da-e2bef042dfef
Removed From Cluster false
HA Enabled true
HA Cluster n/a
HA Mode standby
Active Node Address <none>
Raft Committed Index 51
Raft Applied Index 51
Configuration Commands
generate-root
This command starts the process of generating a new root token. In early versions of vault, this process required successive commands for generating a new nonce for the root token, signing it with key shares or PGP tokens, generating OTPs for decrypting the generated nonce and for the final root token.
In the version used in this tutorial, all steps boil down to just one: vault operator generate-root -init. The following listing shows the complete root token regeneration process.
vault operator generate-root -init
# Log messages
A One-Time-Password has been generated for you and is shown in the OTP field.
You will need this value to decode the resulting root token, so keep it safe.
Nonce bfd01e24-1349-2579-d726-4ae2020ee7aa
Started true
Progress 0/3
Complete false
OTP zWQSrrVYZwz9lGrgfZDahDP3S87T
OTP Length 28
Use the existing key shares and enter the command the same amount of times as key shares for majority rules are required:
> vault operator generate-root
# Log messages
Operation nonce: 6bb2d09a-0412-9f14-3bc6-266ed2f6e915
Unseal Key (will be hidden):
After completing all key shares, the final screen shows this:
Nonce 6bb2d09a-0412-9f14-3bc6-266ed2f6e915
Started true
Progress 3/3
Complete true
Encoded Token HSE8YBsMOAcsKhk5dx01DRkvHyE8YmU6JGkeJg
Now the encoded token needs to be decided with the initial nonce.
> vault operator generate-root -decode=HSE8YBsMOAcsKhk5dx01DRkvHyE8YmU6JGkeJg -otp=uWONzDADGCLc0eYLnMRJJ0QxjQvm
# Log messages
hvs.aHyCkiUZGxlAwbMkvR4BN8hK
rekey
This command starts a similarly involved process to generate either new unseal keys or recovery keys.
The generation of unseal keys exposes the same options as the initial setup: Determining the number of key shares generated, the key share threshold, and the key type.
Here is an example to regenerate 5 keys and using 2 as the threshold:
> vault operator rekey -init -key-shares=5 -key-threshold=2
# Log messages
Key Value
--- -----
Nonce eca9cb95-dd7a-93e6-4d65-7c8238ddc0ec
Started true
Rekey Progress 0/2
New Shares 5
New Threshold 2
Verification Required false
Use the same command again and provide an old unseal key as the argument:
vault operator rekey R6hz5iAr3oJo2ZFWCGLhdDoiZ7jT4B484gZah31o/3m/
vault operator rekey pP0ov5glEql+JJElikDPKcHC1celjCvMFBSMJwBDBj0J
Once completed, the new unseal keys are shown:
# Log messages
Key 1: e86YF9bSIFhuXGuP9CveJMa06ze8xD0kuLZURxiAhVs9
Key 2: AhhIbezOQMPwfui+YqPqZXkLBLGN8K/gScndnz9PYIg0
Key 3: bciZj+c9UIM8cazNW58V9zdFUnn+D2E3Gqeau7zgNdS6
Key 4: waZ9Zl4mKHgI1kk7ZTUsbeGTwFMINlrCHIH6VdRaInV6
Key 5: Rl6gfgJ9TvsxHl592TjQXI/9+/5OyinBliOCDaZDdjeK
Operation nonce: 86354d34-d57d-92e0-31bf-a22681f3789d
Vault unseal keys rekeyed with 5 key shares and a key threshold of 2. Please
securely distribute the key shares printed above. When Vault is re-sealed,
restarted, or stopped, you must supply at least 2 of these keys to unseal it
before it can start servicing requests.
When using PGP keys, an interesting option is offered: The current PGP keys can be stored as backup decryption data in Vaults core data. If the newly generated keys should get lost, the old keys can be reused instead.
rotate
This command creates a new encryption key used for en- and decryption of all data stored in Vault. The new key is inserted into the keyring. When Vault targets decrypting a secret, it will check the applicable key from the keyring, then encrypt the data with the new key.
Here is an example:
> vault operator rotate
# Log messages
Success! Rotated key
Key Term 2
Install Time 21 Jul 25 15:50 UTC
Encryption Count 2
This operation does not incur any downtime to a Vault instance or Cluster. Furthermore, an internal, configurable timespan is applied after which the encryption key will be automatically rotated.
Storage Management
Vault support several different storage backends. Two commands can be found in this group.
migrate
Vault instances are configured with one specific backend. To improve the storage performance, or use advanced features of Vault that require a specific storage backend, data can be migrated with this command. The migrate command expects a new configuration file that includes the new storage target, and it exposes some flags controlling the parallelism of the copying, and to control which keys are copied.
Here is an example for copying from one raft location to another.
First, create a completely new configuration file, and add the two blocks storage_source and storage_destination.
storage_source "raft" {
path = "/Users/work/development/vault/backup/"
node_id = "node01"
}
storage_destination "raft" {
path = "/Users/work/development/vault/node04/raft/"
node_id = "node04"
}
Then, without starting the new server, execute the migrate command. Log message indicate how the copy is performed.
> vault operator migrate -config=./node04/vault_config.hcl
# Log messages
[INFO] creating Raft: config="&raft.Config{ProtocolVersion:3, HeartbeatTimeout:5000000000, ElectionTimeout:5000000000, CommitTimeout:50000000, MaxAppendEntries:64, BatchApplyCh:true, ShutdownOnRemove:true, TrailingLogs:0x2800, SnapshotInterval:120000000000, SnapshotThreshold:0x2000, LeaderLeaseTimeout:2500000000, LocalID:\"node04\", NotifyCh:(chan<- bool)(0xc001222080), LogOutput:io.Writer(nil), LogLevel:\"DEBUG\", Logger:(*hclog.intLogger)(0xc001226000), NoSnapshotRestoreOnStart:true, PreVoteDisabled:false, NoLegacyTelemetry:false, skipStartup:false}"
[INFO] initial configuration: index=1 servers="[{Suffrage:Voter ID:node04 Address:127.0.0.1:8241}]"
[INFO] entering leader state: leader="Node at node04 [Leader]"
[INFO] copied key: path=core/keyring
[INFO] copied key: path=core/local-mounts
[INFO] copied key: path=core/local-audit
[INFO] copied key: path=core/index-header-hmac-key
...
Success! All of the keys have been migrated.
Once completed, in the configuration file, remove the storage_source block and modify storage_destination to storage, then start the new vault server.
raft snapshot
Raft is the integrated storage format that comes bundles with the vault binary. While other raft commands exist, its storage management variant is concerned with one task: Handling data snapshots. Examples for all available subcommands are shown in the following.
For saving a snapshot, a local file path must be provided.
> vault operator raft snapshot save 2025-07-22_raft_backup.bin
# Log messages
[INFO] storage.raft: starting snapshot up to: index=163
[INFO] storage.raft: snapshot complete up to: index=163
Inspecting the snapshot file reveals detailed information about the included backup files.
> vault operator raft snapshot inspect 2025-07-22_raft_backup.bin
# Log messages
ID bolt-snapshot
Size 22661
Index 163
Term 7
Version 1
Key Name Count Size
---- ---- ----
logical/92c4f3fb-d41c-d7ff-493f-101147aa3266 10 3.2KB
logical/a62a4624-543e-42c4-9f11-d7d71f0ee325 6 5.9KB
sys/policy 3 3.2KB
sys/token 3 904B
core/cluster 2 219B
core/raft 2 3.3KB
core/audit 1 104B
core/auth 1 298B
core/canary-keyring 1 75B
core/hsm 1 112B
core/index-header-hmac-key 1 99B
core/keyring 1 718B
core/leader 1 1.5KB
core/local-audit 1 110B
core/local-auth 1 108B
core/local-mounts 1 357B
core/lock 1 49B
core/master 1 163B
core/mounts 1 604B
core/seal-config 1 183B
core/shamir-kek 1 84B
core/versions 1 164B
core/wrapping 1 560B
sys/counters 1 81B
---- ----
Total Size 22.1KB
Finally, during restoring the snapshot, detailed log messages
> vault operator raft snapshot restore 2025-07-22_raft_backup.bin
# Log messages
[INFO] storage.raft: starting snapshot up to: index=163
[INFO] core: shutting down prior to restoring snapshot
[INFO] core: pre-seal teardown starting
...
[INFO] core: pre-seal teardown complete
[INFO] core: applying snapshot
[INFO] storage.raft.snapshot: creating new snapshot: path=/etc/hashicorp_vault/raft_storage/raft/snapshots/7-164-1753199964065.tmp
[INFO] storage.raft: copied to local snapshot: bytes=22661
[INFO] storage.raft.fsm: installing snapshot to FSM
[INFO] storage.raft: snapshot restore progress: id=7-164-1753199964065 last-index=164 last-term=7 size-in-bytes=0 read-bytes=0 percent-complete="NaN%"
...
[INFO] expiration: lease restore complete
[INFO] core: post-unseal setup complete
Raft Cluster Management
Vault instances can be joined to form a cluster. A key requirement is that its storage backend provides high-availability, which means that a shared data state can be synced between its members with a reliable, consistent and integrity-keeping process. The raft storage format provides these capabilities.
When several Vault instances are configured with the raft storage format, the same-named operator command can be used for cluster management.
As the context for the following commands, a local three node cluster is assumed to have been setup.
raft list-peers
Lists all configured cluster members, their status and their role,
Assuming that the example cluster has been setup, but only the leader node is active, the output will be as shown.
> vault operator list-peers
# Log messages
Node Address State Voter
---- ------- ----- -----
node01 127.0.0.1:8211 leader true
node02 127.0.0.1:8221 follower false
node03 127.0.0.1:8231 follower false
raft join
Add the current Vault instance to another Vault server. The target can be either a server instance identified by an URI, or in the case of auto-join configuration, several key-value pairs identifying a target server in a cloud environment.
To add the second node to the cluster, following command can be used:
> vault operator raft join "http://127.0.0.2:8220"
# Log messages
Key Value
--- -----
Joined true
This changes the peer overview as follows:
Node Address State Voter
---- ------- ----- -----
node01 127.0.0.1:8211 leader true
node02 127.0.0.1:8221 follower true
node03 127.0.0.1:8231 follower false
raft remove-peer
Remove a Vault instance from the cluster, providing the target as and URI or an ID that is via the instance’s configuration file.
Here is an example usage:
> vault operator raft remove-peer node02
# Log messages
Peer removed successfully!
This changes the peer overview as follows:
Node Address State Voter
---- ------- ----- -----
node01 127.0.0.1:8211 leader true
node02 127.0.0.1:8221 follower false
node03 127.0.0.1:8231 follower false
raft autopilot
The autopilot functionality of the raft storage backend simplifies peer management and data duplication between the peers. This feature requires an active configuration, and once setup, peer’s communication and exchange data automatically.
The autopilot command interacts with this configuration by three subcommands:
autopilot get-config
Print the current autopilot configuration used in the cluster.
> vault operator raft autopilot get-config
# Log messages
Key Value
--- -----
Cleanup Dead Servers false
Last Contact Threshold 10s
Dead Server Last Contact Threshold 24h0m0s
Server Stabilization Time 10s
Min Quorum 0
Max Trailing Logs 1000
Disable Upgrade Migration false
autopilot set-config
Patch the configuration with new values.
> vault operator raft autopilot set-config -server-stabilization-time 10s
# Log messages
storage.raft: updated autopilot configuration: config="CleanupDeadServers:false LastContactThreshold:10s DeadServerLastContactThreshold:24h0m0s MaxTrailingLogs:1000 MinQuorum:0 ServerStabilizationTime:10s DisableUpgradeMigration:false RedundancyZoneTag:redundancy_zone UpgradeVersionTag:upgrade_version"
state
See operational information about the autopilot status.
> vault operator raft autopilot state
# Log messages
Healthy: true
Failure Tolerance: 1
Leader: node01
Voters:
node01
node02
node03
Servers:
node01
Name: node01
Address: 127.0.0.1:8211
Status: leader
Node Status: alive
Healthy: true
Last Contact: 0s
Last Term: 3
Last Index: 47
Version: 1.20.0
Node Type: voter
node02
Name: node02
Address: 127.0.0.1:8221
Status: voter
Node Status: alive
Healthy: true
Last Contact: 2.60827123s
Last Term: 3
Last Index: 47
Version: 1.20.0
Node Type: voter
node03
Name: node03
Address: 127.0.0.1:8231
Status: voter
Node Status: alive
Healthy: true
Last Contact: 4.302644971s
Last Term: 3
Last Index: 47
Version: 1.20.0
Node Type: voter
General Cluster Management
Vault instances can be joined into a cluster, and the commands in this group provide essential cluster management.
The context of the following examples continues the above cluster that was created via a joined raft storage backend.
members
Returns an overview of all cluster nodes, providing an easy way to see the API and cluster addresses, Vault version, and last connection timestamps.
> vault operator members
# Log messages
Host Name API Address Cluster Address Active Node Version Upgrade Version Redundancy Zone Last Echo
--------- ----------- --------------- ----------- ------- --------------- --------------- ---------
midi.local http://127.0.0.1:8210 https://127.0.0.1:8211 true 1.20.0 1.20.0 n/a n/a
midi.local http://127.0.0.1:8220 https://127.0.0.1:8221 false 1.20.0 1.20.0 n/a 2025-07-26T12:45:26+02:00
midi.local http://127.0.0.1:8230 https://127.0.0.1:8231 false 1.20.0 1.20.0 n/a 2025-07-26T12:45:25+02:00
step-down
In each cluster, one node acts as the leader. This command forces the active leader to become a voter, and another node inside the cluster will get promoted to leader status instead.
The following example shows the effect of this command as indicated in the logfiles.
> vault operator step-down
# Log messages
Success! Stepped down: http://127.0.0.1:8210
[WARN] core: stepping down from active operation to standby
...
[INFO] core: pre-seal teardown complete
...
[INFO] storage.raft: entering follower state: follower="Node at 127.0.0.1:8211 [Follower]" leader-address= leader-id=
Information
The last group of commands provides general metainformation about a Vault instance, helping to diagnose and anticipate potential problems.
diagnose
This command provides an overview about the general health of the filesystem structure of the Vault server as well as the structure and integrity of the configured internal storage.
This command is intended to be run when the Vault server is not running, intending to diagnose problems that prevent starting
Here is an example:
> vault operator diagnose -config=node04/vault_config.hcl
# Log messages
[ warning ] Vault Diagnose: HCP link check will not run on OSS Vault.
[ warning ] Check Operating System
[ success ] Check Open File Limits: Open file limits are set to
61440.
[ success ] Check Disk Usage: / usage ok.
[ warning ] Check Disk Usage: /dev is 100.00 percent full.
It is recommended to have more than five percent of the partition
free.
[ success ] Check Disk Usage: /System/Volumes/VM usage ok.
[ success ] Check Disk Usage: /System/Volumes/Preboot usage ok.
[ success ] Check Disk Usage: /System/Volumes/Update usage ok.
[ success ] Check Disk Usage: /System/Volumes/Data usage ok.
[ warning ] Check Disk Usage: /System/Volumes/Data/home has 0 B
free.
It is recommended to have at least 1 GB of space free per
partition.
[ success ] Parse Configuration
[ warning ] Check Telemetry: Telemetry is using default configuration
By default only Prometheus and JSON metrics are available. Ignore this
warning if you are using telemetry or are using these metrics and are
satisfied with the default retention time and gauge period.
[ warning ] Check Storage
[ success ] Create Storage Backend
[ warning ] Check Raft Folder Permissions: too many permissions:
perms are drwxr-xr-x
[ warning ] Check For Raft Quorum: Only one server node found.
Vault is not running in high availability mode.
[ skipped ] Check Service Discovery: No service registration
configured.
[ success ] Create Vault Server Configuration Seals
[ skipped ] Check Transit Seal TLS: No transit seal found in seal
configuration.
[ success ] Create Core Configuration
[ success ] Initialize Randomness for Core
[ success ] HA Storage
[ success ] Create HA Storage Backend
[ skipped ] Check HA Consul Direct Storage Access: No HA storage
stanza is configured.
[ success ] Determine Redirect Address
[ success ] Check Cluster Address: Cluster address is logically valid
and can be found.
[ success ] Check Core Creation
[ skipped ] Check For Autoloaded License: License check will not run
on OSS Vault.
[ warning ] Start Listeners
[ warning ] Check Listener TLS: Listener at address 127.0.0.1:8240:
TLS is disabled in a listener config stanza.
[ success ] Create Listeners
[ skipped ] Check Autounseal Encryption: Skipping barrier encryption
test. Only supported for auto-unseal.
[ success ] Check Server Before Runtime
[ success ] Finalize Shamir Seal
key-status
When Vault is unsealed, the root-key is reconstructed, and this decrypts the current encryption key of the internal keyring. The key-status command shows a brief summary about this encryption key.
> vault operator key-status
# Log messages
Key Term 1
Install Time 26 Jul 25 10:37 UTC
Encryption Count 12
utilization
The vault enterprise only command distills a report about the license utilization. When used with the community version, it merely produces an error because the internally used endpoint is not available.
usage
Vaults provides token-based access to secrets, credentials, and certificates. This command outputs a usage statistic of generated tokens for different client types.
Here is an example output - alas, on a non-production local cluster, the statistics are rather negligible.
> vault operator usage
# Log messages
Period start: 0001-01-01T00:00:00Z
Period end: 2025-06-30T23:59:59Z
Namespace path Entity Clients Non-Entity clients Secret syncs ACME clients Active clients
-------------- -------------- ------------------ ------------ ------------ --------------
Total 0 0 0 0 0
Conclusion
The Vault CLIs operator command provides access to high-level configuration of a server instance or cluster. Commands are grouped into a) startup, for starting and getting a Vault instance operation, b) key management, allowing the generation of root, unseal and recovery keys, c) storage management, allowing the migration between storage backends and the generation of raft snapshots, d) raft cluster management, configuring members of a Vault cluster that use raft as their storage backend, e) general cluster management, showing cluster status and triggering leader voting, and finally f) information, commands that diagnose operational health and metainformation about encryption keys or the license. This article covered all subcommands with an explanation and output example, and should help you to get more familiar with operating a Vault instance or cluster.