Skip to main content
Version: 14.x

Command-Line Tools

Teleport is made up of four CLI tools.

  • teleport: Supports the Teleport Access Platform by starting and configuring various Teleport services.
  • tsh: Allows end users to authenticate to Teleport and access resources in a cluster.
  • tctl: Used to configure the Teleport Auth Service.
  • tbot: Supports Machine ID, which provides short lived credentials to service accounts (e.g, a CI/CD server).
Best practices for production security

When running Teleport in production, you should adhere to the following best practices to avoid security incidents:

  • Avoid using sudo in production environments unless it's necessary.
  • Create new, non-root, users and use test instances for experimenting with Teleport.
  • Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443).
  • Follow the principle of least privilege. Don't give users permissive roles when more a restrictive role will do. For example, don't assign users the built-in access,editor roles, which give them permissions to access and edit all cluster resources. Instead, define roles with the minimum required permissions for each user and configure access requests to provide temporary elevated permissions.
  • When you enroll Teleport resources—for example, new databases or applications—you should save the invitation token to a file. If you enter the token directly on the command line, a malicious user could view it by running the history command on a compromised system.

You should note that these practices aren't necessarily reflected in the examples used in documentation. Examples in the documentation are primarily intended for demonstration and for development environments.

Improve the CLI experience: enable shell completion

Teleport's CLI tools can provide completion hints for bash and zsh. For example, typing tsh and pressing Tab will show all available subcommands, typing tsh -- and pressing Tab will show all available flags.

To enable completion, add an additional statement to your shell configuration file.

Example (.bashrc):

eval "$(tsh --completion-script-bash)"

Example (.zshrc):

# enable completion feature
autoload -Uz compinit
compinit

eval "$(tsh --completion-script-zsh)"

Reload your shell to see the changes.

You can repeat the same process for tctl, teleport, and tbot.

Warning

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

Resource filtering​

Both tsh and tctl allow you to filter servers, applications, databases, desktops, and Kubernetes clusters using the --search and --query flags.

The --search flag performs a simple fuzzy search on resource fields. For example, --search=mac searches for resources containing mac.

The --query flag allows you to perform more sophisticated searches using a predicate language.

In both cases, you can further refine the results by appending a list of comma-separated labels to the command. For example:

$ tsh ls --search=foo,bar labelKey1=labelValue1,labelKey2=labelValue2

Filter Examples​

# List all nodes
$ tsh ls

# List nodes using label argument
$ tsh ls env=staging,os=mac

# List nodes using search keywords
$ tsh ls --search=staging,mac

# List nodes using predicate language. This query searches for nodes with labels
# with key `env` equal to `staging` and key `os` equal to `mac`.
$ tsh ls --query='labels["env"] == "staging" && equals(labels["os"], "mac")'