Skip to main content
logoTetrate Service ExpressVersion: Latest

Getting Started

Tetrate Service Bridge's command line interface (CLI) lets you interact with the TSB API allowing you for easy manipulation of objects and configurations in a programmatic, or interactive way. CLI works by submitting YAML representation of TSB or Istio objects.

Installation​

TSB CLI is a single binary which is available for Linux, MacOS and Windows.

Use curl or wget to download the binary, grant permissions to execute and place it somewhere in your $PATH.

mkdir -p ~/.tctl/bin
curl -Lo ~/.tctl/bin/tctl https://binaries.dl.tetrate.io/public/raw/versions/linux-$(uname -m | sed s/x86_64/amd64/)-undefined/tctl
chmod +x ~/.tctl/bin/tctl
export PATH=$PATH:~/.tctl/bin

Or with wget:

mkdir -p ~/.tctl/bin
wget -q -O ~/.tctl/bin/tctl https://binaries.dl.tetrate.io/public/raw/versions/linux-$(uname -m | sed s/x86_64/amd64/)-undefined/tctl
chmod +x ~/.tctl/bin/tctl
export PATH=$PATH:~/.tctl/bin

Configuration​

CLI configuration supports multiple profiles for easily manage different environments from the same CLI. A profile in the CLI is defined by a single pair of cluster and credentials.

Credentials​

Credentials in the CLI are referred to as user. The full reference for the user sub-command can be found in the CLI reference page. An example for creating an admin-user user is shown below.

tctl config users set admin-user --username admin --password 'MySuperSecret!' --org tetrate --tenant tenant1

Whenever the admin-user is used in a profile, the CLI will submit the admin user and MySuperSecret! password, as well as the tetrate organization and tenant1 tenant.

Special characters in passwords

Do be careful when you are using characters that may be considered special characters in your terminal. For example, if you include a '$' (dollar mark) and quote them using double quotes , it may be interpreted in an unexpected manner.

Since each terminal may behave ever so slightly differently, please always consult your manual for the exact syntax to avoid these special characters from being interpreted in an unexpected way. As a general rule, in most cases using single quotes should be safe.

This caveat applies to almost everything that you type on a terminal, but passwords have a higher risk as use of special characters is encouraged.

Clusters​

Clusters in the CLI map to a given TSB API endpoint. The full reference for the clusters sub-command can be found in the CLI reference page. An example for creating a my-tsb cluster is shown below.

tctl config clusters set my-tsb --bridge-address my.tsb.corp:8443

Whenever the my-tsb is used in a profile, the CLI will send the requests to the https://my.tsb.corp:8443/ endpoint.

Profiles​

A profile is a given combination of cluster and username. The result of that is the CLI sending requests to the endpoint specified by the cluster, authenticating with the username credentials. The full reference for the profiles sub-command can be found in the CLI reference page. An example for creating a demo-tsb profile is shown below.

tctl config profiles set demo-tsb --cluster my-tsb --username admin-user

The CLI can have multiple profiles using different combinations of clusters and users. One of the profiles will be used as default when the option --profile is not specified. You can change the current profile at any time as shown below.

tctl config profiles list
Output
  CURRENT  NAME      CLUSTER      ACCOUNT
  *        default
           demo-tsb  my-tsb       admin-user
tctl config profiles set-current demo-tsb

tctl config profiles list
Output
  CURRENT  NAME      CLUSTER      ACCOUNT
           default
  *        demo-tsb  my-tsb       admin-user

Command completion​

tctl provides completion for the bash shell, allowing for easy discovery of commands and their flags. Provided you have bash completion enabled, you can source the output of the completion command to get the auto completion of tctl commands for bash working.

source <(tctl completion bash)