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.

tsh global flags

tsh apps ls

List all available applications:

tsh apps ls

tsh clusters

tsh clusters [<flags>]

Flags

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

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

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

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

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 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

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

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

tsh kube login

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

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

tsh login

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

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

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>]

Arguments

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

Flags

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 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

Register a new Multi-Factor Authentication (MFA) device:

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

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

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 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

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

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

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

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

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

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

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

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

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 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

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

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

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

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

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 UTCc0a02222-70dc-4be8-9308-7b7901d2d600 kube alice                  Nov 26 20:36:16 UTCd0a04442-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

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

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

tsh request create

Create a new Access Request.

tsh request create [<flags>]

Flags

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

tsh request review

Review an Access Request

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

Flags

Arguments

• <request-id> - ID of the target request

tsh request search

Search for resources to request access to

tsh request search [<flags>]

Flags

tsh request show

Show Access Request details

tsh request show <request-id>

Flags

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

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 --proxy=proxy.example.com scp example.txt user@host:/destination/dir

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

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

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>]

Examples

tsh version
Teleport v16.4.8 git: go1.22Proxy version: 16.4.8Proxy: 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