zli
is an exec level command line interface client that provides users the ability to connect, tunnel, and manage their targets' policies.zli
is an open-source project licensed under the Apache License, version 2.0. Details on how to download are available here.zli
into your bin $PATH
. (Read more about $PATH
)zli
commands and their functions.zli help
at any time to list all the available commands in the CLI.zli login
is the same as zli LoGiN
)bctl
daemonzli
connectionzli
connectionzli
connectionsssh-proxy
commandzli
clientzli
includes a few global options that can be used with any command.--version
zli
version number--debug
-s
, --silent
zli
output messages--help
login
login
command authenticates a user to the BastionZero service. When executed, a new window is opened in the user's default browser. The user may then select their SSO provider and authenticate by supplying their username and password. This is accomplished using the Open ID Connect (OIDC) specification.-m
, --mfa
: MFA code to pass to BastionZero if the organization has required MFA.connect
connect
command spawns an interactive shell to any type of target (SSM, Kubernetes, Web, Db or dynamic access target (DAT)) as indicated by the <targetString>
.<targetString>
is required and must be in the format [targetUser]@targetName
:targetUser
: The UNIX username to login as. In cases where only a single targetUser
can be used to connect to this target via policy then targetUser
may be omitted. In cases where there are more than one targetUser
s that can be used to connect to this target targetUser
is required and otherwise a warning will be printed and the command will fail. Use zli lt -d
to see which target users are allowed for targets.targetName
: The name or UUID of an SSM target or DAT configuration. In cases where there is a name conflict, i.e., two or more targets with the same name, then the UUID must be supplied.zli
user must have a Target Connect policy that covers this targetUser
and target combination.<targetString>
must be in the format [email protected]
:targetUser
: The Kubernetes RBAC user to impersonate as. All Kubernetes API calls forwarded by the bctl
daemon will authenticate as this user and assume that user's role and cluster bindings.targetName
: The name of the Kubernetes cluster.zli
user must have a Kubernetes policy that covers this targetUser
and target combination.<targetString>
must be in the format targetName
:targetName
: The name of the Web or DB target.zli
user must have a Proxy policy that covers this targetName
.kubeconfig
file to the daemon's localhost
HTTP server. You can learn more about using third party tools with BastionZero and Kubernetes here.--targetType dynamic
: Specifies that this connection is to a DAT.--targetGroup system:masters
: For Kubernetes connections only, comma separated list of Kubernetes RBAC groups to impersonate as. In addition to authenticating as the specified targetUser, the bctl daemon will authenticate as these groups and assume their role and cluster bindings. The logged-in zli user must have a Kubernetes Access policy that covers this list of groups and cluster target.--customPort
: Forces the bctl
daemon to run on a specific port.zli connect [email protected]
- Connect as UNIX user ssm-user
to the uniquely named SSM target my-target
.zli connect my-target
- Connects as a default UNIX user if only exactly one is allowed by policy to the uniquely named SSM target my-target
zli connect [email protected]
- Connect as UNIX user john
to an SSM target by referring to its unique UUID.zli connect [email protected] --targetType dynamic
- Connect to a DAT backed by the my-dat-config
Dynamic Access configuration.zli connect [email protected]
- Start the bctl
daemon and connect it to my-cluster
as Kubernetes RBAC user admin
.zli connect [email protected] --targetGroup system:masters
- Start the bctl
daemon and connect it to my-cluster
as Kubernetes RBAC user alice
and RBAC group system:masters
.zli connect my-db-target
- Start the bctl
daemon and connect it to my-db-target
.tunnel
connect
in zli version 5.5.0
zli tunnel
has been deprecated across all version of zli, to connect to Kubernetes targets please make sure to update zli to version >=5.5.0default-targetgroup
default-targetgroup
command updates a local configuration value that specifies the default target groups to use when executing zli tunnel
. If no argument is provided, this command displays what is currently set as the default targetGroup.--set
: Comma separated list of Kubernetes RBAC groups. Pass no value in order to remove any default target groups set (i.e. zli default-targetgroup -set
). This will reset your default target group and no default will be assigned.policy
policy
command lists the organization's policies.-t
, --type
: Policy type filter. If this flag is not provided, then all types of policies will be returned.-j
, --json
: Output the list of policies in JSON format.zli policy --json --silent | jq
- List all policies. Output as JSON.jq
for pretty formatting.describe-cluster-policy
describe-cluster-policy
command returns detailed information about what policies apply to the <clusterName>
cluster.disconnect
attach
attach
command attaches to an open zli
connection. A zli
connection is defined as one that exists in the cli-space
; all connections created with the connect
command exist in this space.close
close
command closes an open zli
connection. A connection that has been closed can no longer be attached to. A zli
connection is defined as one that exists in the cli-space
; all connections created with the connect
command exist in this space.-a
, --all
: Closes all connections in the cli-space
.list-targets
list-targets
command lists all the organization's targets. Optional result filters can be applied by passing in flags as described below. The returned table of targets includes the type, name, and environment of all targets.lt
-u
, --user
: Admin-only option. Filter targets based on targets that a particular user in your organization has access to via policy. A valid user email address must be provided. To help find the email address of any user in your organization you can use zli user
to list all users.-t
, --targetType
: Target type filter. Use zli lt --help
to see full list of valid target types.-e
, --env
: Environment name filter.-n
, --name
: Target name filter.-u
, --status
: Target status filter. Use zli lt --help
to see full list of valid statuses.-d
, --detail
: Returns extra detail in the output. The additional information includes the target's agent version, status, and suitable target users to use in the user portion of the <targetString>
and <tunnelString>
syntax.-i
, --showId
: Display the target's UUID in the output.-j
, --json
: Output the list of targets in JSON format.zli lt -i -t cluster
- List all Kubernetes cluster targets. Display the target's UUID.zli lt --json --silent | jq
- List all targets. Output as JSON. Pipe into jq
for pretty formatting.zli lt --user [email protected]
- Lists all targets that [email protected]
has access to through policylist-connections
list-connections
command lists all open zli
connections. A zli
connection is defined as one that exists in the cli-space
; all connections created with the connect
command exist in this space.lc
-j
, --json
: Output the list of connections in JSON format.user
user
command lists all the organization's SSO users or adds/removes a user to/from a specific policy.zli user
is executed by itself), then a list of all the organization's users is returned. The returned table includes the user's name, <ssoUserEmail>
, role (admin or user), and time of last login.--add
or --delete
), both <policyName>
and <ssoUserEmail>
must be provided. <policyName>
should refer to a policy that exists in the list of the organization's policies (see the policy
command). <ssoUserEmail>
should refer to the email of one of the organization's users.-a
, --add
: Specifies that the provided user should be added to the policy.-d
, --delete
: Specifies that the provided user should be removed from the policy.-j
, --json
: Output the list of users in JSON format.zli user my-policy [email protected] --add
- Adds SSO user with email [email protected]
to the my-policy
policy.zli user my-policy [email protected] --delete
- Removes SSO user with email [email protected]
from the my-policy
policy.zli user --json --silent | jq
- List all the organization's users. Output as JSON. Pipe into jq
for pretty formatting.group
group
command lists all the organization's SSO groups or adds/removes a group to/from a specific policy.zli group
is executed by itself), then a list of all the organization's groups is returned.--add
or --delete
), both <policyName>
and <ssoGroupName>
must be provided. <policyName>
should refer to a policy that exists in the list of the organization's policies (see the policy
command). <ssoGroupName>
should refer to the name of one of the organization's groups.-a
, --add
: Specifies that the provided group should be added to the policy.-d
, --delete
: Specifies that the provided group should be removed from the policy.-j
, --json
: Output the list of groups in JSON format.targetuser
targetuser
command lists, adds, or removes a specific policy's target users. Target users determine what UNIX users or Kubernetes RBAC users are permissible to use in the connect
and tunnel
commands respectively.<policyName>
positional argument is provided, then a list of that policy's target users is returned.--add
or --delete
), <targetUser>
must be provided. <targetUser>
refers to a UNIX username when editing a Target Connect policy. <targetUser>
refers to a Kubernetes RBAC user when editing a Kubernetes Access policy.-a
, --add
: Specifies that the provided target user should be added to the policy.-d
, --delete
: Specifies that the provided target user should be removed from the policy.-j
, --json
: Output the list of target users in JSON format.targetgroup
targetgroup
command lists, adds, or removes a specific policy's target groups. Target groups determine which Kubernetes RBAC groups are permissible to use in the connect
command. This command only applies to Kubernetes Access policies.<policyName>
positional argument is provided, then a list of that policy's target groups is returned.--add
or --delete
),<targetGroup>
must be provided. <targetGroup>
refers to a Kubernetes RBAC group.-a
, --add
: Specifies that the provided target group should be added to the policy.-d
, --delete
: Specifies that the provided target group should be removed from the policy.-j
, --json
: Output the list of target groups in JSON format.ssh-proxy-config
ssh-proxy-config
has been deprecated in favor of generate ssh-proxy
in zli version 6.0.8
ssh-proxy-config
command generates an ssh
configuration block to be added to the user's ssh_config
file. The generated configuration block allows the ssh
command to tunnel SSH connections to SSM targets by calling the zli
's ssh-proxy
command behind the scenes.ssh_config
($HOME/.ssh/config
) file. After doing so, the user may utilize SSH tunneling by using ssh
and specifying the correct hostname prefix (i.e., bzero-*
).ssh-proxy
ssh-proxy
command allows for proxying an SSH connection to an SSM target. The captured SSH connection can be an interactive shell or a port forwarding tunnel.ssh
call it via the ProxyCommand directive.<hostString>
includes the SSM target's name or UUID in the case there are two or more targets with the same name. <userName>
is the UNIX username to login as. <portNumber>
refers to the port number on the SSM target running the sshd
daemon. <identityFile>
refers to the private SSH key generated by the zli
.zli
user must have a Target Connect policy that covers this userName
and target combination. The Tunnel action must be enabled in the policy.configure
configure
command returns the file path of both the zli
's configuration and the logs kept as part of normal client operation. These files typically do not need to be configured or modified by a user.generate-bash
generate-bash
has been deprecated in favor of generate bash
in zli version 6.0.8
generate-bash
command generates a bash script that is used to autodiscover an SSM target. The script should be executed on the target machine to connect with BastionZero.-e
, --environment
: Specifies the environment the target will belong to once registered. Defaults to the Default
environment if this flag is not provided.--agentVersion
: Use a specific version of the agent when installing the agent on the target. Defaults to the latest version if this flag is not provided.--os
: Force the script to assume the target is running a specific operating system. If this flag is not provided, the script will automatically infer the target machine's OS.-o
, --outputFile
: Writes the bash script to a file on the user's machine.-n
, --targetName
: Sets the target name explicitly.--targetNameScheme
: Configures the target name from a specific source. Defaults to the hostname
source if this flag is not provided.do
: If the target machine is a DigitalOcean droplet, the target name will be set to the droplet's name.aws
: If the target machine is an AWS EC2 machine, the target name will be set to the instance's ID.time
: The target name will be set to target-%m%d-%H%M%S
, where the variables are date
formats. The formatted timestamp is the time the script is executed on the target machine.quickstart
quickstart
command starts an interactive onboarding session that adds the user's SSH hosts, as specified by the the ssh_config
file, to BastionZero.-c
, --sshConfigFile
: Path to ssh_config
file. Defaults to $HOME/.ssh/config
if this flag is not provided.generate
generate
command generates files for Kubernetes or SSHzli generate kubeConfig
(Access):zli generate kubeConfig
creates the kubeconfig
file that sets up the user's local Kubernetes tools (e.g. kubectl
, Lens) to communicate with a registered Kubernetes cluster. The generated kubeconfig
configures a new context, bctl-agent-context
, which when set as the current-context
, allows for local Kubernetes tools to talk with the bctl
daemon. The bctl
daemon forwards all Kubernetes API calls to the currently connected Kubernetes cluster (see connect
command).zli generate kubeYaml <clusterName>
(Registration):zli generate sshConfig
:zli generate sshConfig
creates an SSH config file based on the targets to which you have SSH tunnel access, so that your connection to those targets can be proxied through BastionZero. Specifically, it will write to a new file (stored by default in $HOME/.ssh/bz-config
), and link it to your existing configuration (by default in $HOME/.ssh/config
) via the Include
keyword. After this file is generated, you will not need to provide an identity file or proxy command when SSHing to your BastionZero targets.zli generate bash
:zli generate bash
generates a bash script that is used to autodiscover an SSM target. The script should be executed on the target machine to connect with BastionZero.zli generate ssh-proxy
:zli generate ssh-proxy
generates an ssh
configuration block to be added to the user's ssh_config
file. The generated configuration block allows the ssh
command to tunnel SSH connections to SSM targets by calling the zli
's ssh-proxy
command behind the scenes.ssh_config
($HOME/.ssh/config
) file. After doing so, the user may utilize SSH tunneling by using ssh
and specifying the correct hostname prefix (i.e., bzero-*
).--customPort
: Configures the bctl-agent-context
to connect to the bctl
daemon server on a different port than the one currently listed in the user's local configuration.-o
, --outputFile
: Writes the generated configuration to a file on the user's machine.--update
: Updates the user's existing kubeconfig
file (defaults to $HOME/.kube/config
unless KUBECONFIG
is set). Requires kubectl
to be installed on the user's machine and exist in their $PATH
.--labels
: Comma separated list of Kubernetes labels to add to the bctl-agent
deployment that is installed when registering a cluster with BastionZero.--environmentName
: Sets the BastionZero environment this cluster should be added to once registered.--namespace
: Sets the namespace for all bctl-agent
-related Kubernetes objects that are created during registration and used during the lifetime of the agent.--mySshPath
: (only used with generate sshConfig
) specify an alternate location for your personal SSH config file--bzSshPath
: (only used with generate sshConfig
) specify an alternate location for the BastionZero config file to be written-e
, --environment
: (only used with generate bash
) Specifies the environment the target will belong to once registered. Defaults to the Default
environment if this flag is not provided.--agentVersion
: (only used with generate bash
) Use a specific version of the agent when installing the agent on the target. Defaults to the latest version if this flag is not provided.-o
, --outputFile
: (only used with generate bash
) Writes the bash script to a file on the user's machine.--targetNameScheme
: (only used with generate bash
) Configures the target name from a specific source. Defaults to the hostname
source if this flag is not provided.do
: If the target machine is a DigitalOcean droplet, the target name will be set to the droplet's name.aws
: If the target machine is an AWS EC2 machine, the target name will be set to the instance's ID.time
: The target name will be set to target-%m%d-%H%M%S
, where the variables are date
formats. The formatted timestamp is the time the script is executed on the target machine.zli generate kubeYaml testcluster
zli generate kubeYaml --labels testkey:testvalue
zli generate kubeConfig
zli generate kubeConfig --update kube config
- Defaults KUBECONFIG to $HOME/.kube/configzli generate sshConfig
- Create and link an ssh config file based on your organization's policieszli generate sshConfig --mySshPath path/to/config --bzSshPath path/to/bz-config
- Optionally specify filepaths (defaults to $HOME/.ssh/config and $HOME/.ssh/bz-config respectively)zli generate bash --targetNameScheme time
zli generate bash -o script.sh
- Writes the script to a file "script.sh" in the current directoryzli generate ssh-proxy
logout
logout
command de-authenticates the client. The user must run login
again to be able to run other zli
commands.kube
kubectl
must be installed on the user's machine and exist in their $PATH
.current-context
configured in their kubeconfig
file should be set to the bctl
context (see zli generate kubeConfig
).