CLI

Boundary's CLI has predictable behavior throughout its various commands. This page details the common patterns used to help you 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]

options - Client and connection options to specify additional settings
args - API arguments specific to the operation

Examples

The following example shows the use of the -addr flag to specify which Boundary controller to send a 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.

Autocompletion

Boundary's CLI supports autocompletion, which allows tab completion of commands, flags, and in some case, the parameters to those flags.

Run the following command to install autocompletion to the CLI:

$ boundary config autocomplete install

If you want to install autocompletion manually using Bash, add the following line in a ~/.bash_profile or a similar file:

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. On Windows and macOS, the platform-specific options are the defaults. The Unix password manager pass is available on all platforms. You can also set -keyring-type to none or use the environment variable BOUNDARY_KEYRING_TYPE to disable storage and retrieval of the token on all platforms.

Additionally, you can store or retrieve more than one token at once using the -token-name flag or BOUNDARY_TOKEN_NAME environment variable. Configuring multiple tokens lets you store tokens used by different Boundary installations, or other needs.

On Windows, Boundary uses the default Windows credential store, wincred.

Available keyring types include:

Map to collections and sub-types

Generally speaking, Boundary's CLI commands map to the collections they operate on. For example, when you operate on roles, the command is boundary roles ....

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

The read and delete commands always operate on a particular resource identifier, so they require an -id parameter. The list command operates on collections, so it requires either a -scope-id parameter or, depending on the type, a higher level resource identifier, such as -auth-method-id.

Creating and updating resources may require an extra parameter, if the resource type is abstract. An abstract resource 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. Therefore, you can operate directly on a role as demonstrated in the following examples:

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 you create or update a target:

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

Similar to read, the update command operates on an existing target, so it always requires an -id parameter. Similar to list, the create command operates on a collection, so it always either requires a -scope-id parameter or a parameter that defines 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. You can specify the arguments to those flags using an equals sign, as in -id=r_1234567890, or a space, like -id r_1234567890.

To see the 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 example, the following commands are equivalent:

But the following example results in an error:

boundary roles -name foo -scope-id global create

This structure applies to using the -h command 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, and revert it to Boundary's default value. In many cases this default value is empty, but in other cases it's not. For example, a name or description parameter is empty by default, but a password auth method's minimum password length is not 0, but rather 8.

Additionally, you are not typically allowed to set string values to the empty string "", since specific values must be non-empty. You should use null to clear a value to ensure that you revert it to Boundary's recommended default value.

Note

Boundary uses null because 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 the 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.

To print out all available CLI command options, run the command with -help or the -h flag.

$ boundary dev -help

-addr (string: "") - The address of the Boundary controller, as a complete URL, for example https://boundary.example.com:9200. You can also specify the address using the BOUNDARY_ADDR environment variable.
-ca-cert (string: "") - The path on the local disk to a single PEM-encoded CA certificate that is used to verify the controller or worker's server's SSL certificate. This value takes precedence over -ca-path. You can also specify the path using the BOUNDARY_CACERT environment variable.
-ca-path (string: "") - The path on the local disk to a directory of PEM-encoded CA certificates to verify the controller's SSL certificate. You can also specify the path using the BOUNDARY_CAPATH environment variable.
-client-cert (string: "") - The path on the local disk to a single PEM-encoded CA certificate to use for TLS authentication to the Boundary controller. If you specify this flag, the -client-key flag is also required. You can also specify the path using the BOUNDARY_CLIENT_CERT environment variable.
-client-key (string: "") - The path on the local disk to a single PEM-encoded private key matching the client certificate from -client-cert. You can also specify the path using the BOUNDARY_CLIENT_KEY environment variable.
-tls-insecure - If set, disables 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. You can also disable verification of TLS certificates using the BOUNDARY_TLS_INSECURE environment variable.
-tls-server-name (string: "") - The name to use as the SNI host when you connect to the Boundary server using TLS. You can also specify the SNI host name using 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 include the following:

-keyring-type (string: "") - The type of keyring to use. The default value is auto, which uses the Windows credential manager, OSX keychain, or cross-platform password store, depending on platform. Set this value to none to disable keyring functionality. Available keyring types, depending on platform, are:
You can also specify the keyring type using the BOUNDARY_KEYRING_TYPE environment variable.
-output-curl-string - If set, formats the command that would have been run as a string using curl that you can use directly on the command line. This is a great way to discover how CLI functions map to API calls. The default is false.
-recovery-config (string: "") - If set, specifies a configuration file that contains the information necessary to access a KMS configured to be used for the recovery workflow within a Boundary controller. You can also specify the configuration file using the BOUNDARY_RECOVERY_CONFIG environment variable.
-skip-cache-daemon - If set, skips starting the caching daemon or sending the current used or retrieved token to the caching daemon. The default is false. You can also specify this value using the BOUNDARY_SKIP_CACHE_DAEMON environment variable.
-token (string: "") - A URL that points to a file on disk (file://) or an environment variable (env://) from which the token is read. This value overrides the token-name parameter.
-token-name (string: "") - The name of the token. When the CLI authenticates, it stores the token in the platform-specific OS credential store. You can use the token-name parameter to store more than one token at a time. When you specify this parameter during authentication, Boundary uses the given name as part of the key for storage. If you specify it for any other command, Boundary uses the corresponding token for that call. You can also specify the token name using the BOUNDARY_TOKEN_NAME environment variable.

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 is the exact output from the controller. If you use the output of the CLI in scripts or as parameters to other tools, always use the 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 is only 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.

-format (string: "") - The given format to print the output. Valid formats are table or json. The default value is table. You can also specify the format using the BOUNDARY_CLI_FORMAT environment variable.

Environment variables

The CLI reads the following environment variables to set behavioral defaults. Environment variables can alleviate the need to repetitively type a flag. Flags always take precedence over the environment variables.

Connection options

Boundary includes the following environment variables to help you configure connection options.

`BOUNDARY_ADDR`

The address of the Boundary controller as a complete URL, for example https://boundary.example.com:9200.

`BOUNDARY_CACERT`

The path on the local disk to a single PEM-encoded CA certificate to verify the controller or worker's SSL certificate. This variable takes precedence over the BOUNDARY_CAPATH variable or -ca-path connection option, if specified.

`BOUNDARY_CAPATH`

The path on the local disk to a directory of PEM-encoded CA certificates to verify the SSL certificate of the controller.

`BOUNDARY_CLIENT_CERT`

The path on the local disk to a single PEM-encoded CA certificate to use for TLS authentication to the Boundary controller. If you set the path, you must also specify a client key using the BOUNDARY_CLIENT_KEY variable or -client-key connection option.

`BOUNDARY_CLIENT_KEY`

The path on the local disk to a single PEM-encoded private key that matches the client certificate specified by the BOUNDARY_CLIENT_CERT variable or the -client-cert connection option.

`BOUNDARY_SKIP_CACHE_DAEMON`

Prevents Boundary from starting the caching demon or sending the current used or retrieved token to the caching daemon. You can use the BOUNDARY_SKIP_CACHE_DAEMON variable or the -skip-cache-daemon connection option.

`BOUNDARY_TLS_INSECURE`

If set, disables 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 value is false.

`BOUNDARY_TLS_SERVER_NAME`

The name to use as the SNI host when you connect to the Boundary server using TLS.

Client options

Boundary includes the following environment variables to help you configure client options.

`BOUNDARY_KEYRING_TYPE`

The type of keyring to use. Defaults to auto which uses the Windows credential manager, OSX keychain, or cross-platform password store, depending on the platform. Set the value to none to disable keyring functionality. Available keyring types, depending on the platform, include:

`BOUNDARY_RECOVERY_CONFIG`

If set, determines if the given config file is parsed for a "kms" block with the purpose recovery. If you specify a value, Boundary uses the recovery mechanism to authorize the call.

`BOUNDARY_TOKEN_NAME`

The token name when stored in the system credential store. You can specify a token name to allow switching user identities for different commands.

Connect options

Boundary includes the following environment variables to help you configure connect options.

`BOUNDARY_CONNECT_AUTHZ_TOKEN`

The authorization string returned from the Boundary controller when an "authorize-session" action is used against a target. If you set the string to -, the command attempts to read in the authorization string from standard input.

`BOUNDARY_CONNECT_EXEC`

If set, executes the given binary after connecting to the worker. This enviornment variable should be a binary on your path or an absolute path. If you follow any command flags with -- (space, two hyphens, space), then any arguments that follow are set directly to the binary.

`BOUNDARY_CONNECT_LISTEN_ADDR`

If set, attempts to bind the listening address to the given value, which must be an IP address. If the CLI cannot bind the address, the command produces an error. If you don't set this value, it defaults to the most common IPv4 loopback address, 127.0.0.1.

`BOUNDARY_CONNECT_LISTEN_PORT`

If set, attempts to bind the listening port to the given value, if you set this variable. If the CLI cannot bind the address, the command produces an error.

`BOUNDARY_CONNECT_TARGET_SCOPE_ID`

The target scope ID, if you authorize the session using scope parameters and target name. This variable is mutually exclusive with BOUNDARY_CONNECT_TARGET_SCOPE_NAME.

`BOUNDARY_CONNECT_TARGET_SCOPE_NAME`

The target scope name, if you authorize the session using scope parameters and target name. This variable is mutually exclusive with BOUNDARY_CONNECT_TARGET_SCOPE_ID.

Command options

Boundary includes the following environment variables to help you configure command options.

`BOUNDARY_AUTH_METHOD_ID`

An auth method ID.

`BOUNDARY_LOG_LEVEL`

The log verbosity level, mostly as a fallback for events. Supported values, listed in order of more detail to less, are:

`BOUNDARY_SCOPE_ID`

The scope to use for the operation.

Output options

Boundary includes the following environment variables to help you configure output options.

`BOUNDARY_CLI_FORMAT`

The given format in which to print the output. Valid formats are table and json. The default value is table.