Skip to main content

OpenBao commands (CLI)

In addition to a verbose HTTP API, OpenBao features a command-line interface (CLI) that wraps common functionality and formats output. The OpenBao CLI is a single static binary. It is a thin wrapper around the HTTP API. Every CLI command maps directly to the HTTP API internally.

CLI command structure​

Each command is represented as a command or subcommand, and there are a number of command and subcommand options available: HTTP options, output options, and command-specific options.

Construct your OpenBao CLI command such that the command options precede its path and arguments if any:

bao <command> [options] [path] [args]
  • options - Flags to specify additional settings
  • args - API arguments specific to the operation
info

NOTE: Use the command help to display available options and arguments.

Examples:​

The following write command creates a new user (bob) in the userpass auth method. It passes the -address flag to specify the OpenBao server address which precedes the path (auth/userpass/users/bob) and its argument (password="long-password") at last.

$ bao write -address="http://127.0.0.1:8200" auth/userpass/users/bob password="long-password"

If multiple options (-address and -namespace) and arguments (password and policies) are specified, the command would look like:

$ bao write -address="http://127.0.0.1:8200" -namespace="my-organization" \
        auth/userpass/users/bob password="long-password" policies="admin"

The options (flags) come after the command (or subcommand) preceding the path, and the args always follow the path to set API parameter values.

The four most common operations in OpenBao are read, write, delete, and list. These operations work on most paths in OpenBao. Some paths will contain secrets while other paths may contain configuration. Whatever it is, the primary interface for reading and writing data to OpenBao is similar.

To see the equivalent API call to perform the same operation, use the -output-curl-string flag after the subcommand.

$ bao write -output-curl-string  auth/userpass/users/bob password="long-password"

curl -X PUT -H "X-Vault-Request: true" -H "X-Vault-Token: $(bao print token)" -d '{"password":"long-password"}' http://127.0.0.1:8200/v1/auth/userpass/users/bob

To view the policy requirements to perform an operation, use the -output-policy flag after the subcommand.

$ bao kv put -output-policy kv/secret value=itsasecret

path "kv/data/secret" {
  capabilities = ["create", "update"]
}

Command help​

There are two primary ways to get help in OpenBao: CLI help (help) and API help (path-help).

CLI help​

Use help (or -h for shorthand) to see the CLI help output which corresponds to your OpenBao version.

To get CLI help:

$ bao help

Example: To get help on the kv command.

$ bao kv help

The help output displays available subcommands, parameters, and command flags.

API help​

To invoke the OpenBao API paths, you can use the read (for HTTP GET), write (for HTTP PUT or POST), delete (for HTTP DELETE), and list (for HTTP LIST) commands.

Use path-help to get OpenBao API help:

$ bao path-help -h

The path-help retrieves API help on any API paths. OpenBao API paths provide built-in help in markdown format. This includes system paths, secret engines, and auth methods.

Example: API help on the sys/mounts/ path.

$ bao path-help sys/mounts
Request:        mounts
Matching Route: ^mounts$

List the currently mounted backends.

## DESCRIPTION

This path responds to the following HTTP methods.

    GET /
        Lists all the mounted secret backends.

    GET /<mount point>
        Get information about the mount at the specified path.

    POST /<mount point>
        Mount a new secret backend to the mount point in the URL.

    POST /<mount point>/tune
        Tune configuration parameters for the given mount point.

    DELETE /<mount point>
        Unmount the specified mount point.

The help output displays supported child-paths and available parameters if there are any.

Command input​

To write data to OpenBao, the input can be a part of the command in key-value format.

$ bao kv put secret/password value=itsasecret

However, some OpenBao API require more advanced structures such as maps. You can use stdin or file input instead.

stdin​

Some commands in OpenBao can read data from stdin using - as the value. If - is the entire argument, OpenBao expects to read a JSON object from stdin:

$ echo -n '{"value":"itsasecret"}' | bao kv put secret/password -

In addition to reading full JSON objects, OpenBao can read just a value from stdin:

$ echo -n "itsasecret" | bao kv put secret/password value=-

Files​

Some commands can also read data from a file on disk. The usage is similar to stdin as documented above. If an argument starts with @, OpenBao will read it as a file:

$ bao kv put secret/password @data.json

Or specify the contents of a file as a value:

$ bao kv put secret/password value=@data.txt

Note that if an argument is supplied in a @key=value format, OpenBao will treat that as a kv pair with the key being @key, not a file called key=value. This also means that OpenBao does not support filenames with = in them.

Mount flag syntax (KV)​

All kv commands can alternatively refer to the path to the KV secrets engine using a flag-based syntax like $ bao kv get -mount=secret password instead of $ bao kv get secret/password. The mount flag syntax was created to mitigate confusion caused by the fact that for KV v2 secrets, their full path (used in policies and raw API calls) actually contains a nested /data/ element (e.g. secret/data/password) which can be easily overlooked when using the above KV v1-like syntax secret/password. To avoid this confusion, all KV-specific docs pages will use the -mount flag.

Exit codes​

The OpenBao CLI aims to be consistent and well-behaved unless documented otherwise.

  • Local errors such as incorrect flags, failed validations, or wrong numbers of arguments return an exit code of 1.

  • Any remote errors such as API failures, bad TLS, or incorrect API parameters return an exit status of 2

Some commands override this default where it makes sense. These commands document this anomaly.

Autocompletion​

The bao command features opt-in autocompletion for flags, subcommands, and arguments (where supported).

Enable autocompletion by running:

$ bao -autocomplete-install
warning

Be sure to restart your shell after installing autocompletion!

When you start typing an OpenBao command, press the <tab> character to show a list of available completions. Type -<tab> to show available flag completions.

If the BAO_* environment variables are set, the autocompletion will automatically query the OpenBao server and return helpful argument suggestions.

Token helper​

By default, the OpenBao CLI uses a "token helper" to cache the token after authentication. This is conceptually similar to how a website securely stores your session information as a cookie in the browser. Token helpers are customizable, and you can even build your own.

The default token helper stores the token in ~/.vault-token. You can delete this file at any time to "logout" of OpenBao.

Environment variables​

The CLI reads the following environment variables to set behavioral defaults. This can alleviate the need to repetitively type a flag. Flags always take precedence over the environment variables. Each of the following environment variables must be set on the OpenBao process. All environment variables available to the OpenBao process will be logged during startup.

VAULT_TOKEN​

OpenBao authentication token. Conceptually similar to a session token on a website, the VAULT_TOKEN environment variable holds the contents of the token. For more information, please see the token concepts page.

VAULT_ADDR​

Address of the OpenBao server expressed as a URL and port, for example: https://127.0.0.1:8200/.

VAULT_CACERT​

Path to a PEM-encoded CA certificate file on the local disk. This file is used to verify the OpenBao server's SSL certificate. This environment variable takes precedence over VAULT_CAPATH.

VAULT_CAPATH​

Path to a directory of PEM-encoded CA certificate files on the local disk. These certificates are used to verify the OpenBao server's SSL certificate.

VAULT_CLIENT_CERT​

Path to a PEM-encoded client certificate on the local disk. This file is used for TLS communication with the OpenBao server.

VAULT_CLIENT_KEY​

Path to an unencrypted, PEM-encoded private key on disk which corresponds to the matching client certificate.

VAULT_CLIENT_TIMEOUT​

Timeout variable. The default value is 60s.

VAULT_CLUSTER_ADDR​

Address that should be used for other cluster members to connect to this node when in High Availability mode.

BAO_FORMAT​

Provide OpenBao output (read/status/write) in the specified format. Valid formats are "table", "json", or "yaml".

BAO_LOG_LEVEL​

Set the OpenBao server's log level. The supported values are trace, debug, info, warn, and err. The default log leve is info.

VAULT_MAX_RETRIES​

Maximum number of retries when certain error codes are encountered. The default is 2, for three total attempts. Set this to 0 or less to disable retrying.

Error codes that are retried are 412 (client consistency requirement not satisfied) and all 5xx except for 501 (not implemented).

VAULT_REDIRECT_ADDR​

Address that should be used when clients are redirected to this node when in High Availability mode.

VAULT_SKIP_VERIFY​

Do not verify OpenBao's presented certificate before communicating with it. Setting this variable is not recommended and voids OpenBao's security model.

VAULT_TLS_SERVER_NAME​

Name to use as the SNI host when connecting via TLS.

BAO_CLI_NO_COLOR​

If provided, OpenBao output will not include ANSI color escape sequence characters.

VAULT_RATE_LIMIT​

This environment variable will limit the rate at which the bao command sends requests to OpenBao.

This environment variable has the format rate[:burst] (where items in [] are optional). If not specified, the burst value defaults to rate. Both rate and burst are specified in "operations per second". If the environment variable is not specified, then the rate and burst will be unlimited i.e. rate limiting is off by default.

Note: The rate is limited for each invocation of the bao CLI. Since each invocation of the bao CLI typically only makes a few requests, this environment variable is most useful when using the Go OpenBao client API.

VAULT_NAMESPACE​

The namespace to use for the command. Setting this is not necessary but allows using relative paths.

VAULT_SRV_LOOKUP​

Enables the client to lookup the host through DNS SRV look up as described in this draft. This is not designed for high-availability, just discovery. The draft specifies that the SRV record lookup is ignored if a port is given.

VAULT_HTTP_PROXY​

HTTP or HTTPS proxy location which should be used by all requests to access OpenBao. When present, this overrides the default proxy resolution behavior. Format should be http://server:port or https://server:port.

(See VAULT_PROXY_ADDR below).

VAULT_PROXY_ADDR​

HTTP or HTTPS proxy location which should be used by all requests to access OpenBao. When present, this overrides the default proxy resolution behavior. Format should be http://server:port or https://server:port.

warning

Note: When using VAULT_HTTP_PROXY or VAULT_PROXY_ADDR any of the standard proxy variables found in the environment will be ignored. Specifically HTTP_PROXY, HTTPS_PROXY and NO_PROXY. All requests will resolve the specified proxy; there is no way to exclude domains from consulting the proxy server.

warning

Note: If both VAULT_HTTP_PROXY and VAULT_PROXY_ADDR environment variables are supplied, VAULT_PROXY_ADDR will be prioritized and preferred.

VAULT_DISABLE_REDIRECTS​

Prevents the OpenBao client from following redirects. By default, the OpenBao client will automatically follow a single redirect.

warning

Note: Disabling redirect following behavior could cause issues with commands such as 'bao operator raft snapshot' as this command redirects the request to the cluster's primary node.

Flags​

There are different CLI flags that are available depending on subcommands. Some flags, such as those used for setting HTTP and output options, are available globally, while others are specific to a particular subcommand. For a complete list of available flags, run:

$ bao <subcommand> -h