mirror of https://github.com/hashicorp/boundary
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
250 lines
10 KiB
250 lines
10 KiB
---
|
|
layout: docs
|
|
page_title: CLI
|
|
description: |-
|
|
Boundary's CLI behavior
|
|
---
|
|
|
|
# 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:
|
|
|
|
```text
|
|
boundary <command> <subcommand> [options] [args]
|
|
```
|
|
|
|
- `options` - [Client](/docs/api-clients/cli#client-options) and [connection](/docs/api-clients/cli#connection-options) options to specify additional settings
|
|
- `args` - API arguments specific to the operation
|
|
|
|
#### Examples:
|
|
|
|
The following shows use of the [`-addr`](/docs/api-clients/cli#addr) flag to specify which Boundary controller to send the request to.
|
|
|
|
```shell-session
|
|
$ boundary authenticate password \
|
|
-addr=https://boundary.example.com:9200
|
|
-auth-method-id=ampw_1234567890 \
|
|
-login-name=admin \
|
|
-password=password
|
|
```
|
|
|
|
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](https://www.passwordstore.org/) 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:
|
|
|
|
- `wincred` (default)
|
|
- `pass`
|
|
- `none`
|
|
|
|
### 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:
|
|
|
|
- `keychain` (default)
|
|
- `pass`
|
|
- `none`
|
|
|
|
### Other platforms
|
|
|
|
On all other platforms, the default is `pass`. However, if an implementation of
|
|
the [freedesktop.org secret
|
|
service](https://specifications.freedesktop.org/secret-service/latest/) is
|
|
available (via `gnome-keyring`, `kwallet`, or others) it can be used.
|
|
|
|
Available keyring types:
|
|
|
|
- `pass` (default)
|
|
- `secret-service`
|
|
- `none`
|
|
|
|
## Mapping 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:
|
|
|
|
- `boundary <collection> read`
|
|
- `boundary <collection> delete`
|
|
- `boundary <collection> list`
|
|
|
|
`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:
|
|
|
|
- `boundary roles create`
|
|
- `boundary roles update`.
|
|
|
|
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:
|
|
|
|
- `boundary targets tcp create`
|
|
- `boundary targets tcp update`
|
|
|
|
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:
|
|
|
|
- `boundary roles create -scope-id global -name foo`
|
|
- `boundary roles create -name foo -scope-id global`
|
|
|
|
But the following results in an error:
|
|
|
|
- `boundary roles -name foo -scope-id global create`
|
|
|
|
This applies to `-h` as well!
|
|
|
|
### Clearing/Defaulting 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.
|
|
|
|
~> `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.
|