Learn to use the Vault CLI

19min
|
Vault

You can use the API, command line interface (CLI), or web user interface (UI) to interact with Vault. The Vault CLI is available for common architectures and operating systems.

Scenario

(Persona: Developer)

Danielle is on the development team, and builds applications and plugins which interface with Vault. They installed the Vault binary on their computer, and set up a dev mode server for development and testing.

You can assume Danielle's role to learn about using the Vault CLI with a dev server by checking the server status, and enabling an auth method and secrets engine.

Prerequisites

To complete this tutorial, you need the following:

Vault binary installed and configured in your system PATH.

Set up the lab

Open a terminal and start a Vault dev server with the literal string root as the root token value, and enable TLS.
```
$ vault server -dev -dev-root-token-id root -dev-tls
```
The dev server listens on the loopback interface at 127.0.0.1 on TCP port 8200 with TLS enabled. At runtime, the dev server also automatically unseals, and prints the unseal key and initial root token values to the standard output.
Root tokens
The dev mode server starts with an initial root token value set.
Root token use should be extremely guarded in production environments because they enable full access to the Vault server.
You use the root token here for convenience, and to keep the tutorial steps focused on what you'll learn.
In a new terminal, export the VAULT_ADDR and VAULT_CACERT environment variables using the commands suggested in your Vault dev server output.
Copy each command (without the $) from the server output, and paste it into the new terminal session.
Example:
```
export VAULT_ADDR='https://127.0.0.1:8200'
```
Example:
```
$ export VAULT_CACERT='/var/folders/qr/zgztx0sj6n1dxy86sl36ntnw0000gn/T/vault-tls3037226588/vault-ca.pem'
```
Remember to use your dev server's values, not the examples shown here.
Tip
Exporting the configuration as environment variables is convenient, but you can also configure the same information through the CLI flags -address and -ca-cert. You can learn more about these flags in the HTTP Options section of the help output.

Authenticate with Vault by logging in with the initial root token value.

$ vault login root

Example output:

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                root
token_accessor       X1scHLP6vaPYnJMh7rN7Dh1h
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

The Vault server is ready.

Check the server status

It's always a good idea to check your server status after starting Vault to ensure that it is available for use, and operating under the desired configuration.

You can get a quick summary of the status sub-command by using an abbreviated form of the --help output.

$ vault status --help | head -n 12

Example output:

Usage: vault status [options]

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.

The exit code reflects the seal status:

      - 0 - unsealed
      - 1 - error
      - 2 - sealed

Check the your dev server status.

$ vault status

Example output:

Key             Value
---             -----
Seal Type       shamir
Initialized     true
Sealed          false
Total Shares    1
Threshold       1
Version         1.16.1
Build Date      2024-04-03T12:35:53Z
Storage Type    inmem
Cluster Name    vault-cluster-3b13e7d6
Cluster ID      ad6de78c-ecbd-b92c-c4c3-df54935f4645
HA Enabled      false

You can learn from this output that the server is active, initialized, and unsealed. You can also learn about the server configuration, including the Vault version, storage type, cluster name, and more.

You learned earlier that the Vault CLI can also output JSON. Try getting the server status, but requesting that Vault return the output as a JSON object.

$ vault status -format=json

Example output:

{
 "type": "shamir",
 "initialized": true,
 "sealed": false,
 "t": 1,
 "n": 1,
 "progress": 0,
 "nonce": "",
 "version": "1.16.1",
 "build_date": "2024-04-03T12:35:53Z",
 "migration": false,
 "cluster_name": "vault-cluster-50f9ef0f",
 "cluster_id": "4c97e057-62f1-0a90-22bb-daecaafbc621",
 "recovery_seal": false,
 "storage_type": "inmem",
 "ha_enabled": false,
 "active_time": "0001-01-01T00:00:00Z"
}

Vault returns the server status information as a JSON object.

The Vault dev server is ready for use.

Understand the Vault CLI

Vault features a command-line interface (CLI) that wraps API functionality, and formats output in a tabular style by default. If you've followed along since the beginning of the tutorial, you learned that the CLI can also output JSON.

The Vault CLI functionality is part of the same single static binary that powers the server and agent. It is a thin wrapper around the HTTP API, and the CLI commands internally map directly to the HTTP API.

The CLI command features a range of sub-commands, accepts options in the form of flags or environment variables, and handles arguments provided by the user.

The general command syntax is:

vault <command> [options] [path] [args]

Open a new terminal session if necessary, and try some commands.

Try getting the Vault version.

$ vault version

Example output:

Vault v1.16.1 (6b5986790d7748100de77f7f127119c4a0f78946), built 2024-04-03T12:35:53Z

The output includes Vault version, the binary SHA summary, and build timestamp.

Tip

This example uses the version sub-command, but you can also pass the --version flag to vault, and get the same output.

Try getting help.

$ vault help

Example output:

Usage: vault <command> [args]

Common commands:
    read        Read data and retrieves secrets
    write       Write data, configuration, and secrets
    delete      Delete secrets and configuration
    list        List data or secrets
    login       Authenticate locally
    agent       Start a Vault agent
    server      Start a Vault server
    status      Print seal and HA status
    unwrap      Unwrap a wrapped secret

Other commands:
    audit                Interact with audit devices
    auth                 Interact with auth methods
    debug                Runs the debug command
    events
    hcp
    kv                   Interact with Vault's Key-Value storage
    lease                Interact with leases
    monitor              Stream log messages from a Vault server
    namespace            Interact with namespaces
    operator             Perform operator-specific tasks
    patch                Patch data, configuration, and secrets
    path-help            Retrieve API help for paths
    pki                  Interact with Vault's PKI Secrets Engine
    plugin               Interact with Vault plugins and catalog
    policy               Interact with policies
    print                Prints runtime configurations
    proxy                Start a Vault Proxy
    secrets              Interact with secrets engines
    ssh                  Initiate an SSH session
    token                Interact with tokens
    transform            Interact with Vault's Transform Secrets Engine
    transit              Interact with Vault's Transit Secrets Engine
    version-history      Prints the version history of the target Vault server

Vault provides a listing of common sub-commands and other sub-commands. The first 4 common sub-commands are the most commonly used for most CLI users.

You can get help for any of these commands by invoking the sub-command with the --help flag. Tokens are an essential authentication idea in Vault, so try getting help for the token sub-command.

$ vault token --help

Example output:

Usage: vault token <sub-command> [options] [args]

  This command groups sub-commands for interacting with tokens. Users can
  create, lookup, renew, and revoke tokens.

  Create a new token:

      $ vault token create

  Revoke a token:

      $ vault token revoke 96ddf4bc-d217-f3ba-f9bd-017055595017

  Renew a token:

      $ vault token renew 96ddf4bc-d217-f3ba-f9bd-017055595017

  Please see the individual sub-command help for detailed usage information.

sub-commands:
    capabilities    Print capabilities of a token on a path
    create          Create a new token
    lookup          Display information about a token
    renew           Renew a token lease
    revoke          Revoke a token and its children

Help output provides usage format, and examples for the token sub-command's own commands to create, look up, renew, revoke, or learn the capabilities for a given token identifier.

What command-line flag can you pass to the Vault CLI to get more information about a command or sub-command?

Reveal answer

You can use --help to get more information about a command or subcommand.

Enable and configure an auth method

You can use the CLI auth sub-command to enable an auth method.

Before you enable an auth method, check out the help for auth.

$ vault auth --help

Example output:

Usage: vault auth <sub-command> [options] [args]

This command groups sub-commands for interacting with Vault's auth methods.
Users can list, enable, disable, and get help for different auth methods.

To authenticate to Vault as a user or machine, use the "vault login" command
instead. This command is for interacting with the auth methods themselves, not
authenticating to Vault.

List all enabled auth methods:

    $ vault auth list

Enable a new auth method "userpass";

    $ vault auth enable userpass

Get detailed help information about how to authenticate to a particular auth
method:

    $ vault auth help github

Please see the individual sub-command help for detailed usage information.

sub-commands:
    disable    Disables an auth method
    enable     Enables a new auth method
    help       Prints usage for an auth method
    list       Lists enabled auth methods
    move       Move an auth method to a new path
    tune       Tunes an auth method configuration

Danielle needs an instance of the userpass auth method. With it they can authenticate to Vault with a username and password, and later get a secret value.

Enable the userpass auth method.

$ vault auth enable userpass

Example output:

Success! Enabled userpass auth method at: userpass/

List the enabled auth methods.
```
$ vault auth list
```
Example output:
```
Path         Type        Accessor                  Description                Version
----         ----        --------                  -----------                -------
token/       token       auth_token_976119cb       token based credentials    n/a
userpass/    userpass    auth_userpass_53c1801f    n/a                        n/a
```
By default, Vault enables all auth methods under the path /auth/. In this case, you enabled an instance of the userpass auth method at the path userpass/, so the fully qualified path to this auth method becomes /auth/userpass.
Tip
You can override the default path for enabled auth methods and secrets engines to specify your own path with the -path flag.
Vault also assigns this auth method instance a unique accessor identifier, in this case auth_userpass_53c1801f. You can use this accessor to refer to this auth method instance when you use other commands.

The power of path-help

The Vault CLI features extensive self-documentation. This extends even to the paths created as the result of enabling auth methods and secrets engines. As explained earlier, you enabled a new instance of the userpass auth method with the defaults, so this auth method path is /auth/userpass.

You can use the path-help sub-command to learn more about what is possible at this path by passing it in as an argument like this.

$ vault path-help /auth/userpass

The output includes help for all possible operations against this path:

Example output:

## DESCRIPTION

The "userpass" credential provider allows authentication using
a combination of a username and password. No additional factors
are supported.

The username/password combination is configured using the "users/"
endpoints by a user with root access. Authentication is then done
by supplying the two fields for "login".

## PATHS

The following paths are supported by this backend. To view help for
any of the paths below, use the help command with any route matching
the path pattern. Note that depending on the policy of your auth token,
you may or may not be able to access certain paths.

    ^login/(?P<username>\w(([\w-.]+)?\w)?)$
        Log in with a username and password.

    ^users/(?P<username>\w(([\w-.]+)?\w)?)$
        Manage users allowed to authenticate.

    ^users/(?P<username>\w(([\w-.]+)?\w)?)/password$
        Reset user's password.

    ^users/(?P<username>\w(([\w-.]+)?\w)?)/policies$
        Update the policies associated with the username.

    ^users/?$
        Manage users allowed to authenticate.

Create the ACL policy

When Danielle authenticates to Vault with the userpass auth method, Vault can attach access control list policies (ACL policies) to tokens that it issues to them.

In this case, Danielle needs the ability to create, list, read, and update new key/value secrets at the path dev-secrets. You write ACL policies in HashiCorp Configuration Language (HCL), as shown in this example:

path "dev-secrets/+/creds" {
  capabilities = ["create", "list", "read", "update"]
}

Policy helper

Vault CLI offers the -output-policy flag to help identify necessary policy to execute an operation.

For example, the following command returns the policy required to read secrets from dev-secrets/creds.

$ vault kv get -output-policy dev-secrets/creds

Example output:

path "dev-secrets/data/creds" {
  capabilities = ["read"]
}

The command returns the minimum policy required, and it will not include wildcards.

Write the policy to Vault with the name developer-vault-policy.
```
$ vault policy write developer-vault-policy - << EOF
path "dev-secrets/+/creds" {
   capabilities = ["create", "list", "read", "update"]
}
EOF
```
Example output:
```
Success! Uploaded policy: developer-vault-policy
```
Once you've created an ACL policy and enabled a userpass auth method, you can create users who can authenticate using the write sub-command.

Create a user with the username danielle-vault-user, and set their password to Flyaway Cavalier Primary Depose.

$ vault write /auth/userpass/users/danielle-vault-user \
    password='Flyaway Cavalier Primary Depose' \
    policies=developer-vault-policy

Example output:

Success! Data written to: auth/userpass/users/danielle-vault-user

Enable and configure a secrets engine

You have learned quite a bit about the CLI by enabling a userpass auth method, creating an ACL policy, and creating a user. In this section, your goal is to enable an instance of the key/value secrets engine, and create a secret.

You can learn about the secrets command from help.

$ vault secrets --help

Example output:

Usage: vault secrets <sub-command> [options] [args]

This command groups sub-commands for interacting with Vault's secrets engines.
Each secret engine behaves differently. Please see the documentation for
more information.

List all enabled secrets engines:

    $ vault secrets list

Enable a new secrets engine:

    $ vault secrets enable database

Please see the individual sub-command help for detailed usage information.

sub-commands:
    disable    Disable a secret engine
    enable     Enable a secrets engine
    list       List enabled secrets engines
    move       Move a secrets engine to a new path
    tune       Tune a secrets engine configuration

List the enabled secrets engines before you enable a secrets engine instance.

$ vault secrets list

Example output:

Path          Type         Accessor              Description
----          ----         --------              -----------
cubbyhole/    cubbyhole    cubbyhole_1c400a85    per-token private secret storage
identity/     identity     identity_8cb29789     identity store
secret/       kv           kv_c9c9ce34           key/value secret storage
sys/          system       system_48c3d8d1       system endpoints used for control, policy and debugging

A Vault server starts with some secrets engines enabled by default, including the cubbyhole, identity, and sys secrets engines. Since this is a dev server, Vault also enables a default instance of the key/value secrets engine, version 1.

Enable a new instance of the version 2 key/value secrets engine, which features secret versioning at the path /dev-secrets.
```
$ vault secrets enable -path=dev-secrets -version=2 kv
```
Example output:
```
Success! Enabled the kv secrets engine at: dev-secrets/
```
You've enabled the auth method, created an ACL policy, and enabled secrets engine all with the power of the initial root token. You're now ready to authenticate with Vault as danielle-vault-user, and to try creating a new secret in dev-secrets.

Authenticate and create secret

Up to this point, you have been using the root token. You can use the login sub-command to authenticate with the userpass auth method as danielle-vault-user.

Get help for the login sub-command.

$ vault login --help

The help for login is quite long, so this abbreviated version of the output shows only the usage, output, and command options.

Abbreviated example output:

Usage: vault login [options] [AUTH K=V...]

Authenticates users or machines to Vault using the provided arguments. A
successful authentication results in a Vault token - conceptually similar to
a session token on a website. By default, this token is cached on the local
machine for future requests.

The default auth method is "token". If not supplied via the CLI,
Vault will prompt for input. If the argument is "-", the values are read
from stdin.

The -method flag allows using other auth methods, such as userpass, github, or
cert. For these, additional "K=V" pairs may be required. For example, to
authenticate to the userpass auth method:

      $ vault login -method=userpass username=my-username

For more information about the list of configuration parameters available for
a given auth method, use the "vault auth help TYPE" command. You can also use
"vault auth list" to see the list of enabled auth methods.

If an auth method is enabled at a non-standard path, the -method flag still
refers to the canonical type, but the -path flag refers to the enabled path.
If a github auth method was enabled at "github-prod", authenticate like this:

      $ vault login -method=github -path=github-prod

If the authentication is requested with response wrapping (via -wrap-ttl),
the returned token is automatically unwrapped unless:

   - The -token-only flag is used, in which case this command will output
      the wrapping token.

   - The -no-store flag is used, in which case this command will output the
      details of the wrapping token.
...snip...
Output Options:

-field=<string>
      Print only the field with the given name. Specifying this option will
      take precedence over other formatting directives. The result will not
      have a trailing newline making it ideal for piping to other processes.

-format=<string>
      Print the output in the given format. Valid formats are "table", "json",
      "yaml", or "pretty". "raw" is allowed for 'vault read' operations only.
      The default is table. This can also be specified via the VAULT_FORMAT
      environment variable.

Command Options:

-method=<string>
      Type of authentication to use such as "userpass" or "ldap". Note this
      corresponds to the TYPE, not the enabled path. Use -path to specify the
      path where the authentication is enabled. The default is token.

-no-print
      Do not display the token. The token will be still be stored to the
      configured token helper. The default is false.

-no-store
      Do not persist the token to the token helper (usually the local
      filesystem) after authentication for use in future requests. The token
      will only be displayed in the command output. The default is false.

-path=<string>
      Remote path in Vault where the auth method is enabled. This defaults to
      the TYPE of method (e.g. userpass -> userpass/).

-token-only
      Output only the token with no verification. This flag is a shortcut for
      "-field=token -no-store". Setting those flags to other values will have
      no affect. The default is false.

Authenticate with Vault using the userpass auth method as danielle-vault-user.
```
$ vault login -method=userpass username=danielle-vault-user
```
Vault prompts you to input your password:
```
Password (will be hidden):
```

Enter your password (Flyaway Cavalier Primary Depose) at the prompt. Vault returns login details.

Example output:

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                    Value
---                    -----
token                  hvs.CAESIC_7j2ZkyuOYJGtL2pN179SMOV-QjREddgxjBEx3valdGh4KHGh2cy5zMGJKQU1DbFFQd29lRE9UdjZXTUljRWs
token_accessor         MQI3nzQnmPgSCNCFNZOidg1I
token_duration         768h
token_renewable        true
token_policies         ["default" "developer-vault-policy"]
identity_policies      []
policies               ["default" "developer-vault-policy"]
token_meta_username    danielle-vault-user

The output includes the actual token identifier, the token accessor, and details of the token's lifecycle along with metadata and policies.

Vault is flexible in accepting input and displaying output. The following example shows authentication with Vault using the same userpass auth method and user, but by specifying the password as an argument and instructing Vault to not print any output after the login.
```
$ vault login \
    -no-print \
    -method=userpass \
    username=danielle-vault-user \
    password='Flyaway Cavalier Primary Depose'
```
You're authenticated to Vault as danielle-vault-user.

You can put a new secret in the secrets engine at the path /dev-secrets with the kv command. Check the help for kv.

$ vault kv --help

Example output:

Usage: vault kv <sub-command> [options] [args]

This command has sub-commands for interacting with Vault's key-value
store. Here are some simple examples, and more detailed examples are
available in the sub-commands or the documentation.

Create or update the key named "foo" in the "secret" mount with the value
"bar=baz":

    $ vault kv put -mount=secret foo bar=baz

Read this value back:

    $ vault kv get -mount=secret foo

Get metadata for the key:

    $ vault kv metadata get -mount=secret foo

Get a specific version of the key:

    $ vault kv get -mount=secret -version=1 foo

The deprecated path-like syntax can also be used, but this should be avoided
for KV v2, as the fact that it is not actually the full API path to
the secret (secret/data/foo) can cause confusion:

    $ vault kv get secret/foo

Please see the individual sub-command help for detailed usage information.

sub-commands:
    delete               Deletes versions in the KV store
    destroy              Permanently removes one or more versions in the KV store
    enable-versioning    Turns on versioning for a KV store
    get                  Retrieves data from the KV store
    list                 List data or secrets
    metadata             Interact with Vault's Key-Value storage
    patch                Sets or updates data in the KV store without overwriting
    put                  Sets or updates data in the KV store
    rollback             Rolls back to a previous version of data
    undelete             Undeletes versions in the KV store

Try to put a secret named creds in the key/value secrets engine at the path /dev-secrets with the put sub-command.
```
$ vault kv put /dev-secrets/creds api-key=E6BED968-0FE3-411E-9B9B-C45812E4737A
```
You can use the get subcommand to get the secret details.
```
$ vault kv get /dev-secrets/creds
```

Clean up

Use CTRL+C to stop the server process in the terminal window where you started the server, or use this command to kill the server process from any local terminal session:

$ pkill vault

Unset the environment variables.

$ unset VAULT_ADDR VAULT_CACERT

Summary

The Vault CLI allows you to both manage your Vault cluster, and interact with Vault as a consumer. The built in help command provides more context for specific subcommands and their required parameters.

Introduction to roles

Learn to use the Vault UI