Using the Vault CLI’s Built-In Help

If you’re managing secrets in 2023 and don’t want to be locked into a cloud provider’s secret storage solution, then you should be using HashiCorp Vault. But if you’ve used and administered Vault, then you know there is a bit of a learning curve. HashiCorp’s online documentation is excellent, but you still need to know exactly where to look for the information that you’re seeking.

I often find myself referring back to the API docs or particular tutorials when configuring Vault or managing secrets. Context switching between a terminal (or code editor) and a web browser consumes valuable time and often distracts me from my original goal (what API endpoint did I need again?). Thankfully, there’s a better way!

In this article, I’ll show you two helpful Vault command line interface (CLI) tricks that will boost your productivity as a Vault administrator and developer: the vault path-help command, and the --output-curl-string flag.

API Docs at your Fingertips

The vault path-help command is my go-to command for navigating the Vault API without ever leaving my terminal. This command obtains helpful information about an API endpoint in Vault. I often use vault path-help to explore the API, understand the purpose of different endpoints, and determine the parameters expected by those endpoints.

For example, I have the Kubernetes authentication mechanism enabled in my Vault environment:

$ vault auth list
Path           Type          Accessor                    Description                Version
----           ----          --------                    -----------                -------
kubernetes/    kubernetes    auth_kubernetes_f8127e01    n/a                        n/a
token/         token         auth_token_074414d8         token based credentials    n/a

Configuring Vault to talk to Kubernetes can be a complex undertaking, and I’d rather not leave the command-line to trawl through the Vault documentation for all of the proper API endpoints and corresponding options. This is where vault path-help comes in.

By simply running vault path-help with the endpoint that I’m interested in, I can view helpful information about that endpoint and any endpoints below it. Looking up path help for the auth/kubernetes endpoint reveals all of the relevant API endpoints that exist beneath the path. Each is denoted by a regular expression for the endpoint. For example, auth/kubernetes/role “lists all the roles registered with the backend.” Notice the regular expression difference between this endpoint and a named role.

$ vault path-help auth/kubernetes
## DESCRIPTION

The Kubernetes Auth Backend allows authentication for Kubernetes service accounts.

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

    ^config$
        Configures the JWT Public Key and Kubernetes API information.

    ^login$
        Authenticates Kubernetes service accounts with Vault.

    ^role/(?P<name>\w(([\w-.]+)?\w)?)$
        Register an role with the backend.

    ^role/?$
        Lists all the roles registered with the backend.

Looking up a specific endpoint provides information about the parameters expected by the API. Imagine that I need to configure the Kubernetes authentication mechanism, but I can’t remember all of the necessary parameters. I could context switch to a web browser to view the API documentation, or I could simply look at the help menu for the auth/kubernetes/config endpoint. The help gives me everything that I need, including all of the parameters to pass in a request to the endpoint:

$ vault path-help auth/kubernetes/config
Request:        config
Matching Route: ^config$

Configures the JWT Public Key and Kubernetes API information.

## PARAMETERS

    disable_iss_validation (bool)

        (DEPRECATED) Disable JWT issuer validation (Deprecated, will be removed in a future release)

    disable_local_ca_jwt (bool)

        Disable defaulting to the local CA cert and service account JWT when running in a Kubernetes pod

    issuer (string)

        (DEPRECATED) Optional JWT issuer. If no issuer is specified,
        then this plugin will use kubernetes.io/serviceaccount as the default issuer.
        (Deprecated, will be removed in a future release)

    kubernetes_ca_cert (string)

        PEM encoded CA cert for use by the TLS client used to talk with the API.

    kubernetes_host (string)

        Host must be a host string, a host:port pair, or a URL to the base of the Kubernetes API server.

    pem_keys (slice)

        Optional list of PEM-formated public keys or certificates
        used to verify the signatures of kubernetes service account
        JWTs. If a certificate is given, its public key will be
        extracted. Not every installation of Kubernetes exposes these keys.

    token_reviewer_jwt (string)

        A service account JWT used to access the
        TokenReview API to validate other JWTs during login. If not set
        the JWT used for login will be used to access the API.

## DESCRIPTION

The Kubernetes Auth backend validates service account JWTs and verifies their
existence with the Kubernetes TokenReview API. This endpoint configures the
public key used to validate the JWT signature and the necessary information to
access the Kubernetes API.

A great aspect of vault path-help is that it works even if you mount authentication mechanisms or secrets engines at different paths. For example, I can mount the GitHub authentication mechanism at a non-default path ( github.example.com ), and vault path-help still works as expected:

$ vault auth enable -path=github.example.com github
Success! Enabled github auth method at: github.example.com/


$ vault path-help auth/github.example.com
## DESCRIPTION

The GitHub credential provider allows authentication via GitHub.

Users provide a personal access token to log in, and the credential
provider verifies they're part of the correct organization and then
maps the user to a set of Vault policies according to the teams they're
part of.

After enabling the credential provider, use the "config" route to
configure it.

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

    ^config$


    ^login$


    ^map/teams/(?P<key>[-\w]+)$
        Read/write/delete a single teams mapping

    ^map/teams/?$
        Read mappings for teams

    ^map/users/(?P<key>[-\w]+)$
        Read/write/delete a single users mapping

    ^map/users/?$
        Read mappings for users

The vault path-help command is truly one of my favorite Vault CLI tricks. It often prevents me from switching to a web browser and digging through a trove of API docs to find the exact information that I need, allowing me to stay focused on my current task.

Automatic Request Generation

The vault path help command is perfect if you administer and interact with a Vault environment from a terminal. However, the true power of Vault comes from its API-first design: everything, including the CLI, is just a wrapper around a robust HTTP-based API. I often develop scripts and tools to interact directly with the HTTP API.

This development cycle usually involves interacting with Vault via the CLI and then translating these interactions into HTTP calls. For example, imagine that I’m developing an application to request a Vault token via the HTTP API. I want to set certain properties of the token, such as the TTL, use limit, and token policy. Doing this via the CLI is easy:

$ vault token create -ttl=5m -use-limit=3 -policy=my-policy
Key                  Value
---                  -----
token                hvs.CAESIIpjmjpeYOh7ydxqPPJJ8bQRZ7pUcrJBLzxk7us9yktMGh4KHGh2cy5SOFBGQ0llUUNDSUQ4MHZFZkJSUzBqZmk
token_accessor       KY5Y5C6WUPd8pht4l7o8jr9J
token_duration       5m
token_renewable      true
token_policies       ["default" "my-policy"]
identity_policies    []
policies             ["default" "my-policy"]

However, doing this programmatically requires that I know:

1. The API endpoint
2. The HTTP method
3. The format of the parameters passed to Vault

I could context switch and review the web-based API documentation, or I could review the vault path-help docs. Either option requires me to parse a large amount of documentation despite knowing exactly what I need to do. Thankfully, Vault includes an easy way to print out the HTTP request for a Vault interaction: the --output-curl-string flag. This flag prints out a curl command that can be used to interact directly with the HTTP API.

$ vault token create --output-curl-string -ttl=5m -use-limit=3 -policy=my-policy
curl -X POST -H "X-Vault-Request: true" -H "X-Vault-Token: $(vault print token)" -d '{"policies":["my-policy"],"ttl":"5m0s","explicit_max_ttl":"0s","period":"0s","display_name":"","num_uses":3,"renewable":true,"type":"service","entity_alias":""}' http://localhost:8200/v1/auth/token/create

I regularly use the --output-curl-string flag when writing tools to interact directly with the API. It saves me quite a bit of time since I don’t have to context switch to a browser and dig through the API documentation. I can directly take the provided curl string and translate it into an HTTP request for the language that I’m using.

I also like to use --output-curl-string in combination with vault path-help . For example, the previous command shows me that the API endpoint is auth/token/create . I can also use the vault path-help command to see a list of all potential parameters for the HTTP request:

$ vault path-help auth/token/create
Request:        create
Matching Route: ^create$

The token create path is used to create new tokens.

## PARAMETERS

    display_name (string)

        Name to associate with this token

    entity_alias (string)

        Name of the entity alias to associate with this token

    explicit_max_ttl (string)

        Explicit Max TTL of this token

    id (string)

        Value for the token

    lease (string)

        (DEPRECATED) Use 'ttl' instead

    meta (keypair)

        Arbitrary key=value metadata to associate with the token

    no_default_policy (bool)

        Do not include default policy for this token

    no_parent (bool)

        Create the token with no parent

    num_uses (int)

        Max number of uses for this token

    period (string)

        Renew period

    policies (slice)

        List of policies for the token

    renewable (bool)

        Allow token to be renewed past its initial TTL up to system/mount maximum TTL

    ttl (string)

        Time to live for this token

    type (string)

        Token type

## DESCRIPTION

The token create path is used to create new tokens.

Wrapping Up

I’m always on the lookout for small efficiency gains, as they often have a large compounding impact. I’ve spent a lot of time as a Vault administrator digging through web-based API documentation to find the right API endpoint, HTTP method, or set of parameters for a particular Vault interaction. Discovering the vault path-help command and --output-curl-string flag have saved me hours of time and placed the information that I need directly in front of me when I need it. Hopefully, they also save you some time in your Vault journey!