Version: 16.x

tsh CLI reference

tsh is a CLI client used by Teleport users. It allows users to interact with current and past sessions on the cluster, copy files to and from nodes, and list information about the cluster.

tsh environment variables

Environment variables configure your tsh client and can help you avoid using flags repetitively.

Environment Variable	Description	Example Value
TELEPORT_AUTH	Any defined authentication connector, including `passwordless` and `local` (i.e., no authentication connector)	okta
TELEPORT_MFA_MODE	Preferred mode for MFA and Passwordless assertions	otp
TELEPORT_CLUSTER	Name of a Teleport root or leaf cluster	cluster.example.com
TELEPORT_LOGIN	Login name to be used by default on the remote host	root
TELEPORT_LOGIN_BIND_ADDR	Address in the form of host:port to bind to for login command webhook	host:port
TELEPORT_LOGIN_BROWSER	Set to `none` to stop the system default browser from opening for SSO logins. If the value is not `none`, `tsh` will open the system default browser.	none
TELEPORT_PROXY	Address of the Teleport proxy server	cluster.example.com:3080
TELEPORT_HOME	Home location for tsh configuration and data	/directory
TELEPORT_USER	A Teleport user name	alice
TELEPORT_ADD_KEYS_TO_AGENT	Specifies if the user certificate should be stored on the running SSH agent	yes, no, auto, only
TELEPORT_USE_LOCAL_SSH_AGENT	Disable or enable local SSH agent integration	true, false
TELEPORT_GLOBAL_TSH_CONFIG	Override location of global `tsh` config file from default `/etc/tsh.yaml`	/opt/teleport/tsh.yaml
TELEPORT_HEADLESS	Use headless authentication	true, false, 1, 0
TELEPORT_IDENTITY_FILE	File path to identity file	/opt/identity

tsh global flags

Name	Default Value(s)	Allowed Value(s)	Description
`-l, --login`	none	an identity name	The login identity that the Teleport user will use
`--proxy`	none	`host:https_port[,ssh_proxy_port]`	Teleport Proxy Service address
`--user`	`$USER`	none	The Teleport username
`--ttl`	`720` (12 hours)	integer	Number of minutes a certificate issued for the `tsh` user will be valid for
`-i, --identity`	none	string filepath	Identity file
`--cert-format`	`standard`	`standard` or `oldssh`	SSH certificate format. `oldssh` supports older versions of OpenSSH servers that do not allow for custom metadata, which is how Teleport encodes a user's roles in their SSH certificate.
`--insecure`	none	none	Do not verify the server's certificate and host name. Use only in test environments.
`--auth`	`local`	Any defined authentication connector, including `passwordless` and `local` (i.e., no authentication connector)	Specify the type of authentication connector to use.
`--mfa-mode`	auto	`auto`, `cross-platform`, `platform` or `otp`	Preferred mode for MFA and Passwordless assertions.
`--skip-version-check`	none	none	Skip version checking between server and client.
`-d, --debug`	none	none	Verbose logging to stdout
`-J, --jumphost`	none	A jump host	SSH jumphost
`--headless`	none	none	Use Headless WebAuthn for authentication
`--mlock`	`auto`	`auto`, `off`, `best_effort`, `strict`	Lock process memory to protect client secrets stored in memory from being swapped to disk.

tsh apps ls

List all available applications:

$ tsh apps ls

tsh clusters

$ tsh clusters [<flags>]

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-q, --quiet`	none	none	no headers in output

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

$ tsh clusters

# Cluster Name Status
# ------------ ------
# staging          online
# production       offline

$ tsh clusters --quiet

# staging online
# production offline

tsh config

Print OpenSSH configuration details to allow using an SSH client with credentials managed by Teleport to connect to hosts in your cluster.

$ tsh config

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-l, --login`	none	Linux username	Default Linux username to use. Will translate to SSH config's `User` option.
`-p`, `--port`	3022	port	Default SSH port to use. Will translate to SSH config's `Port` option.

Examples

# Print OpenSSH config file to console
$ tsh config

# Append Teleport configuration to ssh config
$ tsh config >> ~/.ssh/config

tsh device enroll

Enroll the current device as a trusted device.

Requires a device enrollment token created via tctl devices enroll.

$ tsh device enroll --token=TOKEN

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--token`	none	String	Device enrollment token

Examples

$ tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example
Device "C00AA0AAAA0A"/macOS enrolled

tsh gcloud

Proxy gcloud CLI commands through the Teleport Application Service. gcloud is a tool for interacting with Google Cloud. A user must already be authenticated to a Google Cloud application in Teleport before they can execute tsh gcloud commands.

$ tsh gcloud [--app] [<command>]

Arguments

command: A gcloud command to run, including arguments and flags.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--app`	Currently logged in Google Cloud application	The name of a Google Cloud application as listed via `tsh apps ls`.	The Google Cloud application to run the command against, if logged in to multiple Google Cloud applications.

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

$ tsh gcloud compute instances list

tsh gsutil

Proxy gsutil CLI commands through the Teleport Application Service. gsutil is a tool for interacting with Google Cloud Storage. A user must already be authenticated to a Google Cloud application in Teleport before they can execute tsh gsutil commands.

$ tsh gsutil [--app] [<command>]

Arguments

command: A gsutil command to run, including arguments and flags.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--app`	Currently logged in Google Cloud application	The name of a Google Cloud application as listed via `tsh apps ls`.	The Google Cloud application to run the command against, if logged in to multiple Google Cloud applications.

Global flags

Examples

$ tsh gsutil ls

tsh help

Prints help:

$ tsh help

tsh join

Joins an active session:

$ tsh join [<flags>] <session-id>

Arguments

<session-id>

session-id The UUID of an active Teleport Session obtained by teleport status within the session.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--cluster`	none	a cluster_name	Specify the cluster to connect

Global flags

Examples

# join session using teleport user joe as ec2-user
$ tsh --user=joe --login=ec2-user join <session-id>

Log into a Kubernetes cluster. Discover connected clusters by using tsh kube ls.

$ tsh kube login <kube-cluster>

# tsh kube login to k8s cluster (gke_bens-demos_us-central1-c_gks-demo)
$ tsh kube login gke_bens-demos_us-central1-c_gks-demo
# Logged into kubernetes cluster "gke_bens-demos_us-central1-c_gks-demo". Try 'kubectl version' to test the connection.

# On login, kubeconfig is pointed at the first cluster (alphabetically)
$ kubectl config current-context
# aws-gke_bens-demos_us-central1-c_gks-demo

# But all clusters are populated as contexts
$ kubectl config get-contexts

# CURRENT   NAME                                        CLUSTER                       AUTHINFO                                    NAMESPACE
# *         aws-gke_bens-demos_us-central1-c_gks-demo   aws                           aws-gke_bens-demos_us-central1-c_gks-demo
#          aws-microk8s                                aws                           aws-microk8s

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--all`	false	Boolean	Whether to generate a kubeconfig for every Kubernetes cluster the current Teleport user has access to. If this is false, `tsh` will only generate a kubeconfig for the cluster specified in the `tsh kube login` command.
`--as`	none	string	The Kubernetes user that the current Teleport user will log in as when they authenticate to the specified Kubernetes cluster. This uses Kubernetes impersonation, so the Teleport user's Kubernetes user must have permissions to impersonate the target user.
`--as-groups`	none	string	A Kubernetes group that the current Teleport user will log in as when they authenticate to the specified Kubernetes cluster. This uses Kubernetes impersonation, so the Teleport user's Kubernetes user must have permissions to impersonate the target group. You can include this flag multiple times to enable impersonation of multiple Kubernetes groups.
`--cluster`	none	string	Name of the Teleport cluster to log into in order to connect to the given Kubernetes cluster.
`-n`, `--kube-namespace`	none	string	The name of the Kubernetes namespace to configure as the default within the cluster the user is logging into.

tsh kube ls

List Kubernetes clusters:

$ tsh kube ls

Examples

$ tsh kube ls

# Kube Cluster Name                     Selected
# ------------------------------------- --------
# gke_bens-demos_us-central1-c_gks-demo *
# microk8s

Logs in to the cluster. When tsh logs in, the auto-expiring key is stored in ~/.tsh and is valid for 12 hours by default unless you specify another interval via --ttl flag (capped by the server-side configuration).

$ tsh login [<flags>] [<cluster>]

Arguments

<cluster> - the name of the cluster, see Trusted Cluster for more information.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--bind-addr`	none	host:port	Address in the form of host:port to bind to for login command webhook
`--callback`	none	host:port	Override the base URL (host:port) of the link shown when opening a browser for cluster logins. Must be used with --bind-addr.
`-o, --out`	none	filepath	Identity output filepath
`--format`	`file`	`file`, `openssh` or `kubernetes`	Identity format: file, openssh (for OpenSSH compatibility) or kubernetes (for kubeconfig)
`--browser`	none	`none`	Set to 'none' to suppress opening system default browser for `tsh login` commands
`--request-roles`	none		Request one or more extra roles
`--request-reason`	none		Reason for requesting additional roles
`--request-nowait`	none		Finish without waiting for request resolution
`--request-id`	none		Login with the roles requested in the given request
`--no-use-local-ssh-agent`			Do not load generated SSH certificates into the local ssh-agent (specified via `$SSH_AUTH_SOCK`). Useful when using `gpg-agent` or Yubikeys. You can also set the `TELEPORT_USE_LOCAL_SSH_AGENT` environment variable to `false` (default `true`)

Global flags

Examples

The proxy endpoint can take a https and ssh port in this format host:https_port[,ssh_proxy_port]

# Try both ports 443 and 3080 for https
$ tsh --proxy=proxy.example.com login

# Use ports 8080 and 8023 for https and SSH proxy:
$ tsh --proxy=proxy.example.com:8080,8023 login

# Use port 8080 and 3023 (default) for SSH proxy:
$ tsh --proxy=proxy.example.com:8080 login

# Use port 23 as custom SSH port, keep HTTPS proxy port as default
$ tsh --proxy=work.example.com:,23 login

# Login and select cluster "two":
$ tsh --proxy=proxy.example.com login two

# Select cluster "two" using existing credentials and proxy:
$ tsh login two

# Login to the  cluster with a very short-lived certificate
$ tsh --ttl=1 login

# Login using the local Teleport 'admin' user:
$ tsh --proxy=proxy.example.com --auth=local --user=admin login

# Login using GitHub as an SSO provider, assuming the GitHub connector is called "github"
$ tsh --proxy=proxy.example.com --auth=github login

# Suppress the opening of the system default browser for external provider logins
$ tsh --proxy=proxy.example.com --browser=none

# Login to cluster and output a local kubeconfig
$ tsh login --proxy=proxy.example.com --format=kubernetes -o kubeconfig

# Request access to a cluster.
$ tsh login --proxy=proxy.example.com --request-reason="I need to run a debug script on production"

tsh logout

Deletes the client's cluster certificate:

$ tsh logout

tsh ls

List cluster nodes:

$ tsh ls [<flags>] [<label>]

Not seeing Nodes?

When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to display Nodes in the Web UI or via tsh ls), it only returns the Nodes that the current user is authorized to view.

For each Node in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the Node from the user:

None of the user's roles contain a deny rule that matches the Node's labels.
At least one of the user's roles contains an allow rule that matches the Node's labels.

If you are not seeing Nodes when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the Teleport Access Controls Reference.

Arguments

<labels> - comma-separated list of key=value labels to filter nodes by, e.g., env=dev,host=foo.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-v, --verbose`	none	none	also print Node ID

Global flags

Examples

$ tsh ls

# Node Name Address            Labels
# --------- ------------------ ------
# grav-00   10.164.0.0:3022    os:linux
# grav-01   10.156.0.2:3022    os:linux
# grav-02   10.156.0.7:3022    os:osx

$ tsh ls -v

# Node Name Node ID                              Address            Labels
# --------- ------------------------------------ ------------------ ------
# grav-00   52e3e46a-372f-494b-bdd9-a1d25b9d6dec 10.164.0.0:3022    os:linux
# grav-01   73d86fc7-7c4b-42e3-9a5f-c46e177a29e8 10.156.0.2:3022    os:linux
# grav-02  24503590-e8ae-4a0a-ad7a-dd1865c04e30 10.156.0.7:3022     os:osx

# Only show nodes with os label set to 'osx':
$ tsh ls os=osx

# Node Name Address            Labels
# --------- ------------------ ------
# grav-02   10.156.0.7:3022    os:osx

tsh mfa add

$ tsh mfa add

Examples

$ tsh mfa add

# Choose device type [TOTP, WEBAUTHN]: webauthn
# Enter device name: desktop yubikey
# Tap any *registered* security key
# Tap your *new* security key
# MFA device "desktop yubikey" added.

$ tsh mfa add

# Choose device type [TOTP, WEBAUTHN]: totp
# Enter device name: android
# Tap any *registered* security key
# Open your TOTP app and create a new manual entry with these fields:
# Name: awly@example.com:3080
# Issuer: Teleport
# Algorithm: SHA1
# Number of digits: 6
# Period: 30s
# Secret: 6DHDR7GWA7ZKLLWEWRIF55WXJKZ52UVJ

# Once created, enter an OTP code generated by the app: 123456
# MFA device "android" added.

tsh mfa ls

List all registered Multi-Factor Authentication (MFA) devices:

$ tsh mfa ls

tsh mfa rm

Remove a registered Multi-Factor Authentication (MFA) device. You can view your registered devices using tsh mfa ls.

$ tsh mfa rm <device-name>

tsh play

Plays back a prior session:

$ tsh play [<flags>] <id-or-file>

Arguments

<id-or-file>

id-or-file The UUID of a past Teleport session, or the path to a local recording file.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--cluster`	none	a cluster_name	Specify the cluster to connect
`--format`	`pty`	`json`, `yaml`, `pty`, `text`	Format for playback
`--speed`	`1x`	`0.5x`, `1x`, `2x`, `4x`, `8x`	Playback speed
`--skip-idle-time`	`false`	`true,` false`	Skip idle time during playback

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format. Run tsh help <subcommand> or see the Global Flags section.

Examples

$ tsh --proxy proxy.example.com play <session-id>

# Playing back a session streamed from the server.
$ tsh play 1fe153d1-ce8b-4ef4-9908-6539457ba4ad

# Playing back a local session in JSON format using jq to filter on events
$ tsh play --format=json ~/play/0c0b81ed-91a9-4a2a-8d7c-7495891a6ca0.tar | jq '.event

# Playing back a session at 2x speed while also skipping idle time
$ tsh play --speed=2x --skip-idle-time 1fe153d1-ce8b-4ef4-9908-6539457ba4ad

# Dump an SSH session recording to standard out, without respecting timing data.
$ tsh play --format=text 1fe153d1-ce8b-4ef4-9908-6539457ba4ad

tsh proxy app

Starts a local TLS proxy for Application Service connections. You can use this proxy to connect to an application repeatedly after a single login to your Teleport cluster, which is especially useful for interacting with an application via a CLI.

$ tsh proxy app [<flags>] <app>

Arguments

<app>

app The name of the application to start the local proxy for. To see a list of available applications, run tsh apps ls.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-p, --port`	none	port number	Specify the source port for the local proxy

Global Flags

Examples

$ tsh proxy app <app>

# Proxy a connection to grafana on local port 10700
$ tsh proxy --port 10700 app grafana &
# Proxying connections to grafana on 127.0.0.1:10700
$ curl http://127.0.0.1:10700/api/users

tsh proxy aws

Start a local proxy for AWS access. The user must already be logged in to at least one AWS application via Teleport before the proxy can start.

$ tsh proxy aws [<flags>]

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--app`	Currently logged in AWS app	string	Optional name of the AWS application (as shown in `tsh apps ls`) to use if logged in to multiple
`-p`, `--port`	none	port number	Specify the source port for the local proxy
`-e`, `--endpoint-url`	HTTP Proxy	Endpoint URL	Run the local proxy to serve as an AWS endpoint URL. If not specified, the local proxy serves as an HTTPS proxy.
`-f`, `--format`	unix	`text`, `unix`, `command-prompt`, or `powershell`	Optional format for printing environment variables for the AWS proxy

Global Flags

Examples

# Proxy a connection to AWS with the default settings
$ tsh apps login awsapp
$ tsh proxy aws
# Set env variables from output
$ aws s3 ls

# Proxying connections to AWS on 127.0.0.1:10700 to app awsapp2
$ tsh apps logins awsapp2
$ tsh proxy aws --port=10700 --app=awsapp2
# Set env variables from output
$ aws s3 ls

tsh proxy azure

Starts a local proxy server that provides secure access to an Azure managed service identity endpoint. This is useful for managing access to Azure from custom client applications. The local proxy forwards traffic to the Teleport Application Service, which uses an Azure managed identity to fetch an authentication token from Azure.

$ tsh proxy azure [<flags>]

The command will print the address of the local proxy server along with export commands for environment variables required to connect:

Started Azure proxy on http://127.0.0.1:54321.
To avoid port randomization, you can choose the listening port using the --port flag.

Use the following credentials and HTTPS proxy setting to connect to the proxy:

  export AZURE_CONFIG_DIR=/Users/myuser/.tsh/azure/my.teleport.cluster/azure
  export HTTPS_PROXY=http://127.0.0.1:54321
  export HTTP_PROXY=http://127.0.0.1:54321
  export MSI_ENDPOINT=https://azure-msi.teleport.dev/123456789abcdef01234
  export REQUESTS_CA_BUNDLE=/Users/myuser/.tsh/keys/teleport.example.com/myuser-app/teleport.example.com/azure-cli-localca.pem

tip

tsh proxy azure runs the local proxy in the foreground, so don't interrupt the process or exit the terminal where you ran the command until you're ready to close the local proxy.

Copy the export commands and paste them into a second terminal.

To run the local proxy server, one of the user's roles must include the spec.allow.azure_identities field with one of the identities used by the Application Service. To learn how to set up secure access to Azure via Teleport, read Protect the Azure CLI with Teleport Application Access.

Arguments

This command does not accept any arguments.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--app`	none	string	Name of the Teleport application representing Azure (i.e., based on `tsh apps ls`). Use this flag if your Teleport user has access to multiple Azure applications.
`--port`	none	port number	The port on `localhost` where the local proxy will listen for connections.
`--format`	`powershell` if on Windows, `unix` otherwise	`text`, `unix`, `command-prompt`, or `powershell`	The format to use for listing environment variables for Azure client applications connecting to the local proxy.

Global Flags

tsh proxy db

Start a local TLS proxy for database connections when using Teleport with TLS Routing enabled. Clients can connect to a Teleport-registered database through the local proxy.

$ tsh proxy db [<flags>] <db>

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--cluster`	none	string	The name of the Teleport cluster to connect to.
`--db-name`	see below	string	The database name to log in to.
`--db-user`	see below	string	The database user to log in as.
`--port`	none	string	Source port used by the local proxy.
`--tunnel`	none	Boolean	Open an authenticated tunnel using a database's client certificate so clients don't need to authenticate.

If --db-user or --db-name are required, then default settings are chosen from either an active database certificate obtained via a prior use of tsh db login or from the user's allowed db_users or db_names.

The database user is always required. The database name is required for PostgreSQL, MongoDB, and Oracle databases.

Global Flags

Examples

Proxy a DB connection to a named database

$ tsh proxy db <db>

Proxy a connection to mysql db on local port 10700:

$ tsh proxy db --port 10700  mysql-db
# Started DB proxy on 127.0.0.1:10700

# Use following credentials to connect to the mysql-db proxy:
#  ca_file=/Users/jeff/.tsh/keys/teleport.example.com/cas/teleport.example.com.pem
#  cert_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff-db/tele1c/mysql-db-x509.pem
#  key_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff

Proxy a connection to mysql db with no credentials required:

$ tsh proxy db --tunnel mysql-db
Started authenticated tunnel for the MySQL database "mysql-db" in cluster "teleport.example.com" on 127.0.0.1:49415.

Use the following command to connect to the database:
  $ mysql --port 49415 --host localhost --protocol TCP

tsh proxy gcloud

Start a local proxy for Google Cloud API access. The user must already be logged in to at least one Google Cloud application via Teleport before the proxy can start.

$ tsh proxy gcloud [<flags>]

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--app`	Currently logged in Google Cloud app	string	Optional name of the Google Cloud application (as shown in `tsh apps ls`) to use if logged in to multiple
`-p`, `--port`	none	port number	Specify the source port for the local proxy
`-e`, `--endpoint-url`	HTTP Proxy	Endpoint URL	Run the local proxy to serve as a Google Cloud endpoint URL. If not specified, the local proxy serves as an HTTPS proxy.
`-f`, `--format`	unix	`text`, `unix`, `command-prompt`, or `powershell`	Optional format for printing environment variables for the Google Cloud proxy

Global Flags

Examples

$ tsh apps login google-cloud-app
$ tsh proxy gcloud
# Set env variables from output
$ gcloud compute instances list
$ gsutil ls

tsh proxy ssh

Start a local TLS proxy for ssh connections when using Teleport in TLS Routing mode. This is typically used as part of the SSH client configuration to use ssh as a client through Teleport. See the OpenSSH Guide guide on configuring OpenSSH servers and clients. The tsh config output will include tsh proxy ssh within a ProxyCommand directive.

$ tsh proxy ssh [<flags>] <[user@]host>

Arguments

<[user@]host> Remote hostname and the login to use

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--cluster`	none	Teleport Cluster	The name of the Teleport cluster to connect to.

Global Flags

Examples

Run the following command to generate an OpenSSH client configuration:

$ tsh config

This command produces the following configuration:

# Common flags for all example.com hosts
Host *.example.com example.com
    UserKnownHostsFile "/Users/jeff/.tsh/known_hosts"
    IdentityFile "/Users/jeff/.tsh/keys/enterprise.teleportdemo.com/jeff"
    CertificateFile "/Users/jeff/.tsh/keys/example.com/jeff-ssh/example.com-cert.pub"
    PubkeyAcceptedKeyTypes +ssh-rsa-cert-v01@openssh.com
    HostKeyAlgorithms ssh-rsa-cert-v01@openssh.com

# Flags for all example.com hosts except the proxy
Host *.example.com !example.com
    Port 3022
    ProxyCommand "/usr/local/bin/tsh" proxy ssh --cluster=example.com --proxy=example.com %r@%h:%p

This output should be placed into the default SSH Config for environment, ~/.ssh/config for Mac/Linux or .ssh\config in the Windows User home directory. You can use this as a standalone SSH config file too.

When you run an ssh command against a host with a subdomain of your Proxy Service's domain, this SSH configuration will use the ProxyCommand to run tsh proxy ssh:

$ ssh myuser@node1.example.com

tsh puttyconfig

Adds a PuTTY saved session to the Windows registry for the currently logged in Windows user.

$ tsh puttyconfig [--leaf <leaf-cluster-name>] [login@]hostname

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-l, --login`	none	Linux username	Default Linux username to use. Will translate to SSH config's `User` option.
`-p`, `--port`	3022	port	Default SSH port to use. Will translate to SSH config's `Port` option.
`--leaf`	none	Leaf cluster name	Leaf cluster name to add to the saved session.

Examples

# Add a saved PuTTY session on 'node' for the user 'ec2-user'
$ tsh puttyconfig ec2-user@node

# Add a saved PuTTY session for the Teleport-registered OpenSSH node 'openssh' for the user 'ubuntu'
$ tsh puttyconfig --port 22 ubuntu@openssh

# Add a saved PuTTY session on leaf-node for the user 'ec2-user' on the leaf cluster 'example.teleport.sh'
$ tsh puttyconfig --leaf example.teleport.sh ec2-user@leaf-node

See full docs on tsh puttyconfig here.

tsh recordings ls

List recorded sessions.

$ tsh recordings ls [<flags>]

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--from-utc`	24 hours ago	date	Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago.
`--to-utc`	current	date	Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago.
`--limit`	50	number	Maximum number of recordings to show.
`--last`	none	duration	Duration into the past from which session recordings should be listed. Format 5h30m40s

Global flags

Examples

# get the recorded sessions from the last 24 hours
$ tsh --proxy proxy.example.com recordings ls
ID                                   Type Participants Hostname Timestamp
------------------------------------ ---- ------------ -------- -------------------
b0a04442-70dc-4be8-9308-7b7901d2d600 ssh  jeff         dev       Nov 26 16:36:16 UTC
c0a02222-70dc-4be8-9308-7b7901d2d600 kube alice                  Nov 26 20:36:16 UTC
d0a04442-70dc-4be8-9308-7b7901d2d600 ssh  navin        test      Nov 26 16:36:16 UTC

# The session can be played with tsh play
$ tsh play c0a02222-70dc-4be8-9308-7b7901d2d60

# List recorded sessions that occurred between Nov 1, 2022 to Nov 3, 2022
$ tsh recordings ls --from-utc=2022-11-01 --to-utc=2022-11-3

# Retrieve recorded sessions in the last 6 hours
$ tsh recordings ls --last=6h0m0s

Recorded Sessions Availability

Recorded sessions are linked from the audit events to session recordings files in their storage backend. The following error can occur if a session recording file is not available or when employing multiple auth servers with directory storage backend for recorded sessions. When using a directory storage backend for audit logs and recorded sessions, only the auth server with that recorded session can retrieve it.

$ tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b
ERROR: Recording for session c8e1b2c5-322a-4095-89e3-391edfd2da9b not found.

Using a Security Information and Event Management (SIEM) service that combines the audit logs will help consolidate the list of available recordings.

Downloaded recorded session are directly playable as a file.

$ tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b.tar

tsh request create

Create a new Access Request.

$ tsh request create [<flags>]

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--roles`	none	Comma-separated strings	List of Teleport roles to request
`--resource`	none	String (flag can be repeated to request multiple resources)	Resource ID to be requested
`--reason`	none	String	Reason for making the request (optional)
`--reviewers`	none	Comma-separated strings	Suggested reviewers for the request (optional)
`--nowait`	`false`	`true` or `false`	Finish without waiting for request resolution
`--request-ttl`	1 hour	Relative duration like `5s`, `2m`, or `3h`,	Defines how long the Access Request will be in a `PENDING` state before becoming invalid
`--session-ttl`	Time left on current session	Relative duration like `5s`, `2m`, or `3h`	Defines how long the elevated session will be valid for
`--max-duration`	none	Relative duration like `5s`, `2m`, `3h`, or `7d`	Defines the maximum duration of the elevated session up to 7 days. The assigned role also must have `max_duration` option specified (optional)
`--assume-start-time`	none	String	Sets time roles can be assumed by requestor (RFC3339)

Note

The --request-ttl and --session-ttl values can not be greater than the following:

Maximum certificate lifetime.
Time left on an existing session (certificate).
Maximum session duration defined by the user's roles.

Use --max-duration to request access for longer than the maximum certificate lifetime.

tsh request drop

Drop one or more access requests from current identity

$ tsh request drop [<request-id>...]

Arguments

<request-id> - IDs of requests to "drop" from the current identity so that your certificate will lose elevated roles and/or resource restrictions. If no request ID is given, the default is to drop all Access Requests.

tsh request ls

List Access Requests

$ tsh request ls

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--format`	`text`	`text`, `json`, or `yaml`	Format output
`--reviewable`	`false`	`true` or `false`	Only show requests reviewable by current user
`--suggested`	`false`	`true` or `false`	Only show requests that suggest current user as reviewer
`--my-requests`	`false`	`true` or `false`	Only show requests created by current user

tsh request review

Review an Access Request

$ tsh request review [<flags>] <request-id>

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--approve`	`false`	`true` or `false`	Review proposes approval
`--deny`	`false`	`true` or `false`	Review proposes denial
`--reason`	none	String	Review reason message
`--assume-start-time`	none	String	Sets time roles can be assumed by requestor (RFC3339)

Arguments

<request-id> - ID of the target request

tsh request search

Search for resources to request access to

$ tsh request search [<flags>]

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--kind`	none	`node`, `kubernetes_cluster`, `db`, `app`, `windows_desktop`	Resource kind to search for (required)
`--search`	none	Comma-separated strings	List of comma-separated search keywords or phrases enclosed in single quotes
`--query`	none	String	Query by predicate language enclosed in single quotes
`--labels`	none	Comma-separated strings	List of comma-separated labels to filter by labels (e.g. `key=value1,key2=value2`)

tsh request show

Show Access Request details

$ tsh request show <request-id>

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--format`	text	`text`, `json`, or `yaml`	Format output

Arguments

<request-id> - ID of the target request

tsh scp

Copies files from source to dest:

$ tsh scp [<flags>] <source>... <dest>

Arguments

<source> - filepath to copy
<dest> - target destination

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--cluster`	none	a cluster_name	Specify the cluster to connect
`-r, --recursive`	none	none	Recursive copy of subdirectories
`-P, --port`	none	port number	Port to connect to on the remote host
`-q, --quiet`	none	none	Quiet mode

Global flags

Examples

$ tsh --proxy=proxy.example.com scp example.txt user@host:/destination/dir

note

tsh scp will not work from the CLI if the user requires session moderation. You can transfer files in a moderated session by joining the SSH session from the Web UI and requesting the file transfer there. Both the session initiator and moderators must be present in the Web UI in order to approve the file transfer request.

tsh ssh

Run shell or execute a command on a remote SSH node:

$ tsh ssh [<flags>] <[user@]host> [<command>...]

Arguments

<[user@]host> [<command>...]

user The login identity to use on the remote host. If [user] is not specified the user defaults to $USER or can be set with --user. If the flag --user and positional argument [user] are specified the arg [user] takes precedence.
host The nodename of a cluster Node or a label specification like env=aws to run on all matching hosts.
command The command to execute on a remote host.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-p, --port`	none	port	SSH port on a remote host
`-A, --forward-agent`	none	none	Forward agent to target node like `ssh -A`
`-L, --forward`	none	none	Forward localhost connections to remote server
`-D, --dynamic-forward`	none	none	Forward localhost connections to remote server using SOCKS5
`-R, --remote-forward`	none	none	Forward remote connections to localhost
`-N, -no-remote-exec`	none	none	Don't execute remote command, useful for port forwarding
`--local`	none		Execute command on localhost after connecting to SSH node
`-t, --tty`	`file`		Allocate TTY
`--cluster`	none		Specify the cluster to connect
`-o, --option`	`local`		OpenSSH options in the format used in the configuration file
`--enable-escape-sequences`			Enable support for SSH escape sequences. Type `~?` during an SSH session to list supported sequences.
`--no-use-local-ssh-agent`			Do not load generated SSH certificates into the local ssh-agent (specified via `$SSH_AUTH_SOCK`). Useful when using `gpg-agent` or Yubikeys. You can also set the `TELEPORT_USE_LOCAL_SSH_AGENT` environment variable to `false` (default `true`)
`-X, --x11-untrusted`	none	none	Requests untrusted (secure) X11 forwarding for this session.
`-Y, --x11-trusted`	none	none	Requests trusted (insecure) X11 forwarding for this session. This can make your local machine vulnerable to attacks, use with caution.
`--x11-untrusted-timeout`	10m	duration	Sets a timeout for untrusted X11 forwarding, after which the client will reject any forwarding requests from the server.

Global flags

Examples

# Log in to node `grav-00` as OS User `root` with Teleport User `teleport`
$ tsh ssh --proxy proxy.example.com --user teleport -d root@grav-00
# `tsh ssh` takes the same arguments as OpenSSH client:
$ tsh ssh -o ForwardAgent=yes root@grav-00
$ tsh ssh -o AddKeysToAgent=yes root@grav-00
# Run `hostname` on all nodes with the `env: aws` label
$ tsh ssh root@env=aws hostname

tsh status

Display the list of proxy servers and retrieved certificates:

$ tsh status

Examples

$ tsh status

# > Profile URL:  https://proxy.example.com:3080
#   Logged in as:       benarent
#   Cluster:            aws
#   Roles:              access, editor, auditor
#   Logins:             benarent, root, ec2-user, ubunutu
#   Kubernetes:         enabled
#   Kubernetes cluster: "gke_bens-demos_us-central1-c_gks-demo"
#   Kubernetes groups:  system:masters
#  Valid until:        2020-11-21 01:50:23 -0800 PST [valid for 11h52m0s]
#  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

tsh version

Prints the version of your tsh binary and the Teleport Proxy Service in the current tsh profile

$ tsh version [<flags>]

Name	Default Value(s)	Allowed Value(s)	Description
`-f, --format`	`text`	text, json, yaml	Format for version output
`--client`	none	none	Show the client version only (no server required).

Examples

$ tsh version
Teleport v16.4.8 git: go1.22
Proxy version: 16.4.8
Proxy: teleport.example.com:443

Display in JSON format:

$ tsh version --format=json

{
  "version": "16.4.8",
  "gitref": "",
  "runtime": "go1.22",
  "proxyVersion": "16.4.8",
  "proxyPublicAddress": "teleport.example.com:443"
}

Only display the tsh binary version:

$ tsh version --client
Teleport v16.4.8 git: go1.22

The Teleport Access Platform

Featured Resource

Integrations

Featured Resource

Use Cases

Featured Resource

Industries

Featured Resource

Compliance

Featured Resource

Strategic Partners

Featured AWS Webinar

Featured Blog Post

Featured Event

tsh environment variables​

tsh global flags​

tsh apps ls​

tsh clusters​

Flags​

Global flags​

Examples​

tsh config​

Flags​

Examples​

tsh device enroll​

Flags​

Examples​

tsh gcloud​

Arguments​

Flags​

Global flags​

Examples​

tsh gsutil​

Arguments​

Flags​

Global flags​

Examples​

tsh help​

tsh join​

Arguments​

Flags​

Global flags​

Examples​

tsh kube login​

Flags​

tsh kube ls​

Examples​

tsh login​

Arguments​

Flags​

Global flags​

Examples​

tsh logout​

tsh ls​

Arguments​

Flags​

Global flags​

Examples​

tsh mfa add​

Examples​

tsh mfa ls​

tsh mfa rm​

tsh play​

Arguments​

Flags​

Global flags​

Examples​

tsh proxy app​

Arguments​

Flags​

Global Flags​

Examples​

tsh proxy aws​

Flags​

Global Flags​

Examples​

tsh proxy azure​

Arguments​

Flags​

Global Flags​

tsh environment variables

tsh global flags

tsh apps ls

tsh clusters

Flags

Global flags

Examples

tsh config

Flags

Examples

tsh device enroll

Flags

Examples

tsh gcloud

Arguments

Flags

Global flags

Examples

tsh gsutil

Arguments

Flags

Global flags

Examples

tsh help

tsh join

Arguments

Flags

Global flags

Examples

tsh kube login

Flags

tsh kube ls

Examples

tsh login

Arguments

Flags

Global flags

Examples

tsh logout

tsh ls

Arguments

Flags

Global flags

Examples

tsh mfa add

Examples

tsh mfa ls

tsh mfa rm

tsh play

Arguments

Flags

Global flags

Examples

tsh proxy app

Arguments

Flags

Global Flags

Examples

tsh proxy aws

Flags

Global Flags

Examples

tsh proxy azure

Arguments

Flags

Global Flags

tsh proxy db

Flags

Global Flags

Examples

tsh proxy gcloud

Flags

Global Flags

Examples

tsh proxy ssh

Arguments

Flags

Global Flags

Examples

tsh puttyconfig