Scaling Privileged Access for Modern Infrastructure: Real-World Insights
Apr 25
Virtual
Register Today
Teleport logoTry For Free
Fork me on GitHub

Teleport

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 VariableDescriptionExample Value
TELEPORT_AUTHName of a defined SAML, OIDC, or GitHub auth connector (or a local user)okta
TELEPORT_MFA_MODEPreferred mode for MFA and Passwordless assertionsotp
TELEPORT_CLUSTERName of a Teleport root or leaf clustercluster.example.com
TELEPORT_LOGINLogin name to be used by default on the remote hostroot
TELEPORT_LOGIN_BIND_ADDRAddress in the form of host:port to bind to for login command webhookhost:port
TELEPORT_LOGIN_BROWSERSet 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_PROXYAddress of the Teleport proxy servercluster.example.com:3080
TELEPORT_HOMEHome location for tsh configuration and data/directory
TELEPORT_USERA Teleport user namealice
TELEPORT_ADD_KEYS_TO_AGENTSpecifies if the user certificate should be stored on the running SSH agentyes, no, auto, only
TELEPORT_USE_LOCAL_SSH_AGENTDisable or enable local SSH agent integrationtrue, false
TELEPORT_GLOBAL_TSH_CONFIGOverride location of global tsh config file from default /etc/tsh.yaml/opt/teleport/tsh.yaml
TELEPORT_HEADLESSUse headless authenticationtrue, false, 1, 0

tsh global flags

NameDefault Value(s)Allowed Value(s)Description
-l, --loginnonean identity nameThe login identity that the Teleport user will use
--proxynonehost:https_port[,ssh_proxy_port]Teleport Proxy Service address
--user$USERnoneThe Teleport username
--ttl720 (12 hours)integerNumber of minutes a certificate issued for the tsh user will be valid for
-i, --identitynonestring filepathIdentity file
--cert-formatstandardstandard or oldsshSSH 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.
--insecurenonenoneDo not verify the server's certificate and host name. Use only in test environments.
--authlocalAny defined authentication connector, including passwordless and local (i.e., no authentication connector)Specify the type of authentication connector to use.
--mfa-modeautoauto, cross-platform, platform or otpPreferred mode for MFA and Passwordless assertions.
--skip-version-checknonenoneSkip version checking between server and client.
-d, --debugnonenoneVerbose logging to stdout
-J, --jumphostnoneA jump hostSSH jumphost
--headlessnonenoneUse Headless WebAuthn for authentication
--mlockautoauto, off, best_effort, strictLock 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

NameDefault Value(s)Allowed Value(s)Description
-q, --quietnonenoneno 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

Generates OpenSSH configuration to use currently logged in teleport as a bastion host.

tsh config

Flags

NameDefault Value(s)Allowed Value(s)Description
-l, --loginnoneLinux usernameDefault Linux username to use. Will translate to SSH config's User option.
-p, --port3022portDefault 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

NameDefault Value(s)Allowed Value(s)Description
--tokennoneStringDevice 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

NameDefault Value(s)Allowed Value(s)Description
--appCurrently logged in Google Cloud applicationThe 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

NameDefault Value(s)Allowed Value(s)Description
--appCurrently logged in Google Cloud applicationThe 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 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

NameDefault Value(s)Allowed Value(s)Description
--clusternonea cluster_nameSpecify the cluster to connect

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

NameDefault Value(s)Allowed Value(s)Description
--allfalseBooleanWhether 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.
--asnonestringThe 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-groupsnonestringA 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.
--clusternonestringName of the Teleport cluster to log into in order to connect to the given Kubernetes cluster.
-n, --kube-namespacenonestringThe 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

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

NameDefault Value(s)Allowed Value(s)Description
--bind-addrnonehost:portAddress in the form of host:port to bind to for login command webhook
-o, --outnonefilepathIdentity output filepath
--formatfilefile, openssh or kubernetesIdentity format: file, openssh (for OpenSSH compatibility) or kubernetes (for kubeconfig)
--browsernonenoneSet to 'none' to suppress opening system default browser for tsh login commands
--request-rolesnoneRequest one or more extra roles
--request-reasonnoneReason for requesting additional roles
--request-nowaitnoneFinish without waiting for request resolution
--request-idnoneLogin with the roles requested in the given request
--no-use-local-ssh-agentDo 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

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

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

NameDefault Value(s)Allowed Value(s)Description
-v, --verbosenonenonealso print Node ID

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: [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>] <session-id>

Arguments

<session-id>

  • session-id The UUID of a past Teleport Session obtained by teleport status within the session or from the Web UI.

Flags

NameDefault Value(s)Allowed Value(s)Description
--clusternonea cluster_nameSpecify the cluster to connect
--formatptyjson, ptyFormat for 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 using pty format using a downloaded session recording.

tsh play --format=pty 1fe153d1-ce8b-4ef4-9908-6539457ba4ad.tar

Playing back a session in json format using jq to filter on events

tsh play --format=json ~/play/0c0b81ed-91a9-4a2a-8d7c-7495891a6ca0.tar | jq '.event

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

NameDefault Value(s)Allowed Value(s)Description
-p, --portnoneport numberSpecify the source port for the local proxy

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

NameDefault Value(s)Allowed Value(s)Description
--appCurrently logged in AWS appstringOptional name of the AWS application (as shown in tsh apps ls) to use if logged in to multiple
-p, --portnoneport numberSpecify the source port for the local proxy
-e, --endpoint-urlHTTP ProxyEndpoint URLRun the local proxy to serve as an AWS endpoint URL. If not specified, the local proxy serves as an HTTPS proxy.
-f, --formatunixtext, unix, command-prompt, or powershellOptional format for printing environment variables for the AWS proxy

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:54330.
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:54330
  export HTTP_PROXY=http://127.0.0.1:54330
  export MSI_ENDPOINT=https://azure-msi.teleport.dev/eedfd5b55257c0aaa58f
  export REQUESTS_CA_BUNDLE=/Users/myuser/.tsh/keys/teleport.example.com/myuser-app/teleport.example.com/azure-cli-localca.pem

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

NameDefault Value(s)Allowed Value(s)Description
--appnonestringName 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.
--portnoneport numberThe port on localhost where the local proxy will listen for connections.
--formatpowershell if on Windows, unix otherwisetext, unix, command-prompt, or powershellThe format to use for listing environment variables for Azure client applications connecting to the local proxy.

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

NameDefault Value(s)Allowed Value(s)Description
--clusternonestringThe name of the Teleport cluster to connect to.
--db-namesee belowstringThe database name to log in to.
--db-usersee belowstringThe database user to log in as.
--portnonestringSource port used by the local proxy.
--tunnelnoneBooleanOpen 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

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

NameDefault Value(s)Allowed Value(s)Description
--appCurrently logged in Google Cloud appstringOptional name of the Google Cloud application (as shown in tsh apps ls) to use if logged in to multiple
-p, --portnoneport numberSpecify the source port for the local proxy
-e, --endpoint-urlHTTP ProxyEndpoint URLRun the local proxy to serve as a Google Cloud endpoint URL. If not specified, the local proxy serves as an HTTPS proxy.
-f, --formatunixtext, unix, command-prompt, or powershellOptional format for printing environment variables for the Google Cloud proxy

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

NameDefault Value(s)Allowed Value(s)Description
--clusternoneTeleport ClusterThe name of the Teleport cluster to connect to.

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

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

NameDefault Value(s)Allowed Value(s)Description
-l, --loginnoneLinux usernameDefault Linux username to use. Will translate to SSH config's User option.
-p, --port3022portDefault SSH port to use. Will translate to SSH config's Port option.
--leafnoneLeaf cluster nameLeaf 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 export

Export recorded desktop sessions to video.

tsh recordings export <session_id> [<flags>]

Flags

NameDefault Value(s)Allowed Value(s)Description
--out<session_id>.avia filenameOverride the output file name.

Examples

tsh recordings export c8e1b2c5-322a-4095-89e3-391edfd2da9b --out=recording.avi
wrote recording to recording.avi

tsh recordings ls

List recorded sessions.

tsh recordings ls [<flags>]

Flags

NameDefault Value(s)Allowed Value(s)Description
--from-utc24 hours agodateStart of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago.
--to-utccurrentdateStart of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago.
--limit50numberMaximum number of recordings to show.
--lastnonedurationDuration into the past from which session recordings should be listed. Format 5h30m40s

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

NameDefault Value(s)Allowed Value(s)Description
--rolesnoneComma-separated stringsList of Teleport roles to request
--resourcenoneString (flag can be repeated to request multiple resources)Resource ID to be requested
--reasonnoneStringReason for making the request (optional)
--reviewersnoneComma-separated stringsSuggested reviewers for the request (optional)
--nowaitfalsetrue or falseFinish without waiting for request resolution
--request-ttl1 hourRelative duration like 5s, 2m, or 3h,Defines how long the Access Request will be in a PENDING state before becoming invalid
--session-ttlTime left on current sessionRelative duration like 5s, 2m, or 3hDefines how long the elevated session will be valid for
--max-durationnoneRelative duration like 5s, 2m, 3h, or 7dDefines the maximum duration of the elevated session up to 7 days. The assigned role also must have max_duration option specified (optional)
--assume-start-timenoneStringSets 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

NameDefault Value(s)Allowed Value(s)Description
--formattexttext, json, or yamlFormat output
--reviewablefalsetrue or falseOnly show requests reviewable by current user
--suggestedfalsetrue or falseOnly show requests that suggest current user as reviewer
--my-requestsfalsetrue or falseOnly show requests created by current user

tsh request review

Review an Access Request

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

Flags

NameDefault Value(s)Allowed Value(s)Description
--approvefalsetrue or falseReview proposes approval
--denyfalsetrue or falseReview proposes denial
--reasonnoneStringReview reason message
--assume-start-timenoneStringSets time roles can be assumed by requestor (RFC3339)

Arguments

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

Search for resources to request access to

tsh request search [<flags>]

Flags

NameDefault Value(s)Allowed Value(s)Description
--kindnonenode, kubernetes_cluster, db, app, windows_desktopResource kind to search for (required)
--searchnoneComma-separated stringsList of comma-separated search keywords or phrases enclosed in single quotes
--querynoneStringQuery by predicate language enclosed in single quotes
--labelsnoneComma-separated stringsList 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

NameDefault Value(s)Allowed Value(s)Description
--formattexttext, json, or yamlFormat 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

NameDefault Value(s)Allowed Value(s)Description
--clusternonea cluster_nameSpecify the cluster to connect
-r, --recursivenonenoneRecursive copy of subdirectories
-P, --portnoneport numberPort to connect to on the remote host
-q, --quietnonenoneQuiet mode

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

NameDefault Value(s)Allowed Value(s)Description
-p, --portnoneportSSH port on a remote host
-A, --forward-agentnonenoneForward agent to target node like ssh -A
-L, --forwardnonenoneForward localhost connections to remote server
-D, --dynamic-forwardnonenoneForward localhost connections to remote server using SOCKS5
-R, --remote-forwardnonenoneForward remote connections to localhost
-N, -no-remote-execnonenoneDon't execute remote command, useful for port forwarding
--localnoneExecute command on localhost after connecting to SSH node
-t, --ttyfileAllocate TTY
--clusternoneSpecify the cluster to connect
-o, --optionlocalOpenSSH options in the format used in the configuration file
--enable-escape-sequencesEnable support for SSH escape sequences. Type ~? during an SSH session to list supported sequences.
--no-use-local-ssh-agentDo 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-untrustednonenoneRequests untrusted (secure) X11 forwarding for this session.
-Y, --x11-trustednonenoneRequests trusted (insecure) X11 forwarding for this session. This can make your local machine vulnerable to attacks, use with caution.
--x11-untrusted-timeout10mdurationSets a timeout for untrusted X11 forwarding, after which the client will reject any forwarding requests from the server.

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>]
NameDefault Value(s)Allowed Value(s)Description
-f, --formattexttext, json, yamlFormat for version output
--clientnonenoneShow the client version only (no server required).

Examples

tsh version
Teleport v15.2.2 git: go1.21Proxy version: 15.2.2Proxy: teleport.example.com:443

Display in JSON format:

tsh version --format=json
{
  "version": "15.2.2",
  "gitref": "",
  "runtime": "go1.21",
  "proxyVersion": "15.2.2",
  "proxyPublicAddress": "teleport.example.com:443"
}

Only display the tsh binary version:

tsh version --client
Teleport v15.2.2 git: go1.21