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.
There are a number of command and subcommand options available.
To see all available command options, run
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
The following example shows the use of the
-addr flag to specify which Boundary controller to send a request to:
$ boundary authenticate password \
Instead of specifying the
-addr flag for every command, you can set an environment variable
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
Boundary uses various mechanisms, depending on platform, to allow for secure
storage of authentication tokens for later use. Each platform has a
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
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.
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:
delete commands always operate on a particular resource identifier, so
they require an
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
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.
update command operates on an existing target, so it always requires
-id parameter. Similar to
create command operates on a collection, so it always either requires a
-scope-id parameter or a parameter that defines the parent resource.
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
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:
This structure applies to using the
-h command as well.
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
description parameter is empty by default, but a password auth method's minimum password length is not
0, but rather
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.
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
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
$ boundary dev -help
(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.
(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.
(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.
(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-keyflag is also required. You can also specify the path using the BOUNDARY_CLIENT_CERT environment variable.
(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.
(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.
Every command that results in an API call contains a set of flags that control client options. Some notable options include the following:
(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
noneto 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
curlthat 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
(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.
(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
(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-nameparameter 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.
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.
(string: "")- The given format to print the output. Valid formats are
json. The default value is
table. You can also specify the format using the
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.
Boundary includes the following environment variables to help you configure connection options.
The address of the Boundary controller as a complete URL, for example
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.
The path on the local disk to a directory of PEM-encoded CA certificates to verify the SSL certificate of the controller.
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.
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.
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
The name to use as the SNI host when you connect to the Boundary server using TLS.
Boundary includes the following environment variables to help you configure client options.
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:
If set, determines if the given config file is parsed for a "kms" block with the purpose
If you specify a value, Boundary uses the recovery mechanism to authorize the call.
The token name when stored in the system credential store. You can specify a token name to allow switching user identities for different commands.
Boundary includes the following environment variables to help you configure connect options.
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.
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.
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.
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.
The target scope ID, if you authorize the session using scope parameters and target name.
This variable is mutually exclusive with
The target scope name, if you authorize the session using scope parameters and target name.
This variable is mutually exclusive with
Boundary includes the following environment variables to help you configure command options.
An auth method ID.
The log verbosity level, mostly as a fallback for events. Supported values, listed in order of more detail to less, are:
The scope to use for the operation.
Boundary includes the following environment variables to help you configure output options.
The given format in which to print the output. Valid formats are
json. The default value is