HCP Vault Secrets Centralized secrets lifecycle management for developers. Learn More
Boundary
Boundary Home

CLI

Boundary's CLI has predictable behavior throughout its various commands. This page details the common patterns used in order to help users make better use of the CLI.

CLI command structure

There are a number of command and subcommand options available. To see all available command options, run boundary -h and to see all available subcommand options run boundary <command> -h.

Below is the typical structure for most Boundary CLI commands:

boundary <command> <subcommand> [options] [args]

Examples

The following shows use of the -addr flag to specify which Boundary controller to send the request to.

$ boundary authenticate password \
    -addr=https://boundary.example.com:9200 \
    -auth-method-id=ampw_1234567890

Instead of specifying the -addr flag for every command, you can set an environment variable BOUNDARY_ADDR=https://boundary.controller.com:9200.

Completion

Before detailing how parameters work, it's useful to note that Boundary's CLI supports autocompletion, which allows tab completion of commands, flags, and in some cases the parameters to those flags.

This can be installed via the CLI itself:

boundary config autocomplete install

If you want to install it manually, for Bash, the following line in a ~/.bash_profile or similar file will work:

complete -C /path/to/boundary boundary

Keyring token storage

Boundary uses various mechanisms, depending on platform, to allow for secure storage of authentication tokens for later use. Each platform has a platform-specific option (which on Windows and macOS are the default); pass is also available on all platforms. On all platforms, setting -keyring-type to none (or setting it via BOUNDARY_KEYRING_TYPE) disables storage and retrieval of the token.

Additionally, more than one token can be stored or retrieved at once via the -token-name flag or BOUNDARY_TOKEN_NAME env var. This allows for storing tokens used by different Boundary installations, or other needs.

Windows

On Windows, the Windows credential store (wincred) is used.

Available keyring types:

macOS

On macOS, Keychain is used via /usr/bin/security. (Using this binary allows us to keep the Boundary binary statically linked, which we prefer.)

Available keyring types:

Other platforms

On all other platforms, the default is pass. However, if an implementation of the freedesktop.org secret service is available (via gnome-keyring, kwallet, or others) it can be used.

Available keyring types:

Map to collections and sub-types

Generally speaking, Boundary's CLI commands map to the collections they operate on. For instance, when operating on roles, the command will be boundary roles ....

As a result, the patterns for reading, deleting, and listing are predictable:

read and delete will always operate on a particular resource identifier, so will always take in an -id parameter. list operates on collections so will either take a -scope-id parameter or, depending on type, a higher level resource identifier, e.g. -auth-method-id.

Creating and updating resources may take an extra parameter if the resource type is abstract, that is, if the type cannot be operated on directly but must be operated on through an implementation. As an example, a role is not an abstract type, and does not have various implementations of it. As a result, a role can be operated on directly:

However, a target can be one of many types of targets, and a concrete implementation of a target is a tcp type of target. Therefore an extra parameter is required when creating or updating a target:

This allows the CLI to perform proper presentation and validation of parameters and functions for the given type.

Similar to read, update operates on an existing target so will always take an -id parameter. Similar to list, create operates on a collection so will either take a -scope-id parameter or a parameter defining the parent resource.

Parameter handling

All parameters specified on the CLI are specified as a Go-style flag with a single dash, e.g. -id. The arguments to those flags can be specified via an equals sign, as in -id=r_1234567890, or a space, like -id r_1234567890.

To see available parameters, pass the -h flag to any command.

Flags are semi-position dependent. The flags must come after the command definition, but are otherwise order independent.

For instance, the following are equivalent:

But the following results in an error:

This applies to -h as well!

Clear/default values

On the CLI, you can use null as a value to indicate to Boundary that you want to unset a value, reverting to Boundary's default. In many cases this default will be empty (e.g. for a name or description parameter) but in other cases it's not. For instance, for a password auth method's minimum password length, the default is not 0 but rather 8. Additionally, attempting to set string values to the empty string "" is usually not an allowed operation, since when set to a specific value it must be non-empty. Using null to clear a value ensures you'll revert to Boundary's recommended default.

Note: null is used because of the fact that the API is JSON. Using null as the value causes the key for the parameter to be inserted into the eventual API call's JSON object but with the value set to the JSON null. This in turn informs the Controller that this value should be set to its default. Keep in mind that this is not a direct translation to database NULL semantics!

Connection options

Every command that results in an API call contains a set of flags that control connection options, which control TLS and other settings for the connection. You can also run boundary dev -h to see the available connection options.

  • -addr=<string>: Address of the Boundary controller, as a complete URL (e.g. https://boundary.example.com:9200). Instead of passing the -addr argument with every command, the BOUNDARY_ADDR environment variable can be set. In both cases, the value denotes the address of the Boundary environment (specifically the controller) you wish to send CLI commands to.

  • -ca-cert=<string>: Path on the local disk to a single PEM-encoded CA certificate to verify the Controller or Worker's server's SSL certificate. This takes precedence over -ca-path. This can also be specified via the BOUNDARY_CACERT environment variable.

  • -ca-path=<string>: Path on the local disk to a directory of PEM-encoded CA certificates to verify the SSL certificate of the Controller. This can also be specified via the BOUNDARY_CAPATH environment variable.

  • -client-cert=<string>: Path on the local disk to a single PEM-encoded CA certificate to use for TLS authentication to the Boundary Controller. If this flag is specified, -client-key is also required. This can also be specified via the BOUNDARY_CLIENT_CERT environment variable.

  • -client-key=<string>: Path on the local disk to a single PEM-encoded private key matching the client certificate from -client-cert. This can also be specified via the BOUNDARY_CLIENT_KEY environment variable.

  • -tls-insecure: Disable verification of TLS certificates. Using this option is highly discouraged as it decreases the security of data transmissions to and from the Boundary server. The default is false. This can also be specified via the BOUNDARY_TLS_INSECURE environment variable.

  • -tls-server-name=<string>: Name to use as the SNI host when connecting to the Boundary server via TLS. This can also be specified via the BOUNDARY_TLS_SERVER_NAME environment variable.

Client options

Every command that results in an API call contains a set of flags that control client options. Some notable options:

  • output-curl-string: This will format the command that would have been run as a string using curl that can be used directly on the command line. This is a great way to discover how CLI functions map to API calls.

  • token-name: When the CLI authenticates, it stores the token in the platform-specific OS credential store. By using the token-name parameter, more than one token can be stored at a time. Specifying this parameter at authentication time uses the given name as part of the key for storage; specifying it for any other command will cause the corresponding token to be used for that call.

  • recovery-config: This is used to specify a configuration file that contains the information necessary to access a KMS configured to be used for the recovery workflow within a Boundary controller.

Output options

Nearly every command supports having its success output be formatted as JSON via -format json. For commands that result in an API call, the JSON output will be the exact output from the controller. If using the output of the CLI in scripts or as parameters to other tools, always use formatted output. The default text output is meant for human users and the formatting or the information included within that output from the original JSON may change at any time.

Note that using -format json on a boundary authenticate command results in Boundary not saving the token to the system password store. In this case, the authentication information will only be printed to your terminal in JSON format. You can use the BOUNDARY_TOKEN environment variable or -token flag to provide the token in subsequent commands.

Edit this page on GitHub