Version: 19.x (unreleased)

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_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_RELAY	Address of the Teleport relay server to use, "none" to disable the use of a relay, or "default" to use the default address specified by the control plane at login time. Defaults to port 443.	relay.example.com
TELEPORT_HEADLESS	Use headless authentication	true, false, 1, 0
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_MFA_MODE	Preferred mode for MFA and Passwordless assertions	auto, cross-platform, platform, otp, sso
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
`--relay`	none	`host[:port]	none
`--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`, `otp`, or `sso`	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 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, --relay, --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

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

A relay address specified (or explicitly disabled with the "none" value) at login time will be stored in the tsh configuration directory for the specified proxy; if unspecified, the relay address may fall back to a default value specified by the Teleport control plane. Use of a Relay requires tsh v18.3.0 or later.

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 the Teleport Auth Service receives a request to list Teleport-connected resources (e.g., to display resources in the Web UI or via tsh ls), it only returns the resources that the current user is authorized to view.

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

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

If you are not seeing resources when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the 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: [email protected]: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. If the session is encrypted, it must be streamed from the Teleport Auth Service and local file playback is not possible.

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

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, port pair	Specify the listening port for the local proxy. Accepts an optional target port of a multi-port TCP app after a colon, e.g. "1234:5678".

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

Start a local TLS proxy for Kubernetes requests when using Teleport with TLS Routing enabled. Clients can interact with a Teleport-registered Kubernetes cluster through the local proxy.

tsh proxy kube [<flags>] <kube-cluster>

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--cluster`	none	string	The name of the Teleport cluster to connect to.
`--kube-cluster`	none	string	The name of the Kubernetes cluster to proxy.
`--as`	none	string	The Kubernetes user to impersonate.
`--as-groups`	none	string	The Kubernetes group to impersonate.
`--namespace`	none	string	The Kubernetes namespace to use.
`--set-context-name`	none	string	A custom Kubernetes context name or template to use.
`--exec`	none	boolean	Runs the proxy in the background and spawns a new shell with the $KUBECONFIG automatically set.
`--port`	none	string	Source port used by the local proxy.

Global Flags

Examples

Proxy requests to a Kubernetes cluster

tsh proxy kube test-cluster
Preparing the following Teleport Kubernetes clusters:Teleport Cluster Name Kube Cluster Name Context Name--------------------- ----------------- -----------------teleport-test             test-cluster           teleport-test-test-cluster
Started local proxy for Kubernetes on 127.0.0.1:49487To avoid port randomization, you can choose the listening port using the --port flag.
Use the following config for your Kubernetes applications. For example:export KUBECONFIG="/home/alice/.tsh/keys/proxy.example.com/alice-kube/teleport-test/localproxy-49487-kubeconfig"kubectl version

Spawn a new shell with the Kubernetes proxy running in the background and the Kubernetes config automatically applied.

tsh proxy kube test-cluster --exec
Preparing the following Teleport Kubernetes clusters:Teleport Cluster Name Kube Cluster Name Context Name--------------------- ----------------- -----------------teleport-test             test-cluster           teleport-test-test-cluster
Started local proxy for Kubernetes Access in the background.
Warning! Teleport will initiate a new shell configured with kubectl for local proxy access.To conclude the session, simply use the "exit" command. Upon exiting, your original shell will be restored,the local proxy will be closed, and future access through this headless session won't be possible.

Try issuing a command, for example "kubectl version".

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 [email protected]
    HostKeyAlgorithms [email protected]

# 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 [email protected]

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

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 Service 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`, `kube_cluster`, `kube_resource`, `db`, `app`, `windows_desktop`	Resource kind to search for (required)
`--kube-kind`	none	string	Plural name of the kube resource (required when --kind is `kube_resource`)
`--kube-api-group`	none	string	API group of the kube resource (required when --kind is `kube_resource` depending on the resource)
`--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

Use of a relay (as specified at tsh login time or through the --relay flag) requires tsh v18.3.0 or later.

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

List active sessions. The resulting list includes only the sessions that the caller has permission to join, unless they have a role with explicit list access on the session_tracker resource.

tsh sessions ls

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-f, --format`	text	text, json, yaml	Format for output
`--kind`	none	ssh, k8s, db, app, desktop	Optionally filter by session kind(s)

Examples

list all active sessions
tsh sessions ls

list all SSH and desktop sessions
tsh sessions ls --kind=ssh --kind=desktop

list all Kubernetes sessions in JSON format
tsh sessions ls --kind=k8s --format=json

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 v19.0.0-dev git: go1.22Proxy version: 19.0.0-devProxy: teleport.example.com:443

Display in JSON format:

tsh version --format=json

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

Only display the tsh binary version:

tsh version --client
Teleport v19.0.0-dev git: go1.22

Teleport Infrastructure Identity Platform

Featured Resource

Protected Resources

Featured Resource

Teleport for AI Infrastructure

Teleport for Access & Governance

Teleport for Identity Security

Industries

Featured Resource

Compliance

Featured Resource

Strategic Partners

Featured AWS Webinar

Featured Blog Post

Featured Event

From Our Partners

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​

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 kube

Flags

Global Flags

Examples

tsh proxy ssh

Arguments