tsh Reference — Teleport SSH Client Command Line

tsh is the user-facing CLI client for Teleport. It lets you authenticate to a Teleport cluster and interact with all protected infrastructure: SSH nodes, Kubernetes clusters, databases, and web applications — all using short-lived certificates.

tsh [<flags>] <command> [<args> ...]

tsh communicates through the Teleport Proxy Service. Make sure you have network access to the proxy address before running any tsh commands.

Global Flags

These flags apply to every tsh subcommand.

Flag	Default	Description
`--proxy`	no default	Teleport proxy address.
`--user`	no default	Teleport user, defaults to current local user.
`--auth`	no default	Specify the name of authentication connector to use.
`--ttl`	no default	Minutes to live for a session.
`-i`, `--identity`	no default	Identity file.
`-l`, `--login`	no default	Remote host login.
`-k`, `--add-keys-to-agent`	`auto`	Controls how keys are handled. Valid values are `[auto no yes only]`.
`--mfa-mode`	`auto`	Preferred mode for MFA and Passwordless assertions: `auto`, `cross-platform`, `platform`, `otp`, `sso`, `browser`.
`--mlock`	`auto`	Determines whether process memory will be locked and whether failure to do so will be accepted (`off`, `auto`, `best_effort`, `strict`).
`--piv-slot`	no default	Specify a PIV slot key to use for Hardware Key support instead of the default. Ex: `"9d"`.
`--relay`	no default	Teleport relay address, `"none"` to explicitly disable relay use, or `"default"` to use the cluster-provided address.
`--callback`	no default	Override the base URL (host:port) shown when opening a browser for cluster logins. Must be used with `--bind-addr`.
`--bind-addr`	no default	Override host:port used when opening a browser for cluster logins.
`--cert-format`	no default	SSH certificate format.
`-J`, `--jumphost`	no default	SSH jumphost.
`-d`, `--[no-]debug`	`false`	Verbose logging to stdout.
`--[no-]enable-escape-sequences`	`true`	Enable support for SSH escape sequences. Type `~?` during an SSH session to list supported sequences.
`--[no-]headless`	`false`	Use headless login (shorthand for `--auth=headless`).
`--[no-]insecure`	`false`	Do not verify server certificate. Use only in test environments.
`--[no-]os-log`	`false`	Verbose logging to the unified logging system. Implies `--debug`.
`--[no-]skip-version-check`	`false`	Skip version checking between client and server.

Global Environment Variables

Variable	Default	Description
`TELEPORT_ADD_KEYS_TO_AGENT`	`auto`	Controls how keys are handled. Valid values are `[auto no yes only]`.
`TELEPORT_AUTH`	no default	Specify the name of authentication connector to use.
`TELEPORT_CLUSTER`	no default	Name of a Teleport root or leaf cluster.
`TELEPORT_GLOBAL_TSH_CONFIG`	no default	Override location of global `tsh` config file from default `/etc/tsh.yaml`.
`TELEPORT_HEADLESS`	`false`	Use headless login. Shorthand for `--auth=headless`.
`TELEPORT_HOME`	no default	Home location for tsh configuration and data.
`TELEPORT_IDENTITY_FILE`	no default	Identity file.
`TELEPORT_LOGIN`	no default	Remote host login.
`TELEPORT_LOGIN_BIND_ADDR`	no default	Override host:port used when opening a browser for cluster logins.
`TELEPORT_MFA_MODE`	`auto`	Preferred mode for MFA and Passwordless assertions.
`TELEPORT_MLOCK_MODE`	`auto`	Determines whether process memory will be locked and whether failure to do so will be accepted.
`TELEPORT_PIV_SLOT`	no default	Specify a PIV slot key to use for Hardware Key support instead of the default.
`TELEPORT_PROXY`	no default	Teleport proxy address.
`TELEPORT_RELAY`	no default	Teleport relay address.
`TELEPORT_USER`	no default	Teleport user.

Auth Commands

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

Flag	Default	Description
`-o`, `--out`	no default	Identity output path.
`-f`, `--format`	`file`	Identity format: `file`, `openssh`, `kubernetes`.
`--kube-cluster`	no default	Name of the Kubernetes cluster to log in to.
`--request-roles`	no default	Request one or more extra roles.
`--request-reason`	no default	Reason for requesting additional roles.
`--request-reviewers`	no default	Suggested reviewers for role request.
`--request-id`	no default	Login with roles from a given request ID.
`--[no-]request-nowait`	`false`	Finish without waiting for request resolution.
`--[no-]overwrite`	`false`	Whether to overwrite the existing identity file.
`--scope`	no default	Scope pins credentials to a given scope. Use `""` to explicitly remove scoping.
`--browser`	no default	Set to `none` to suppress browser opening on login.
`-v`, `--[no-]verbose`	`false`	Show extra status information.

Example:

# Log in to a cluster
tsh login --proxy=teleport.example.com

# Log in and output an identity file
tsh login --proxy=teleport.example.com --out=/tmp/identity

# Log in to a leaf cluster
tsh login --proxy=teleport.example.com leaf-cluster

`tsh logout`

Delete the current cluster certificate.

tsh logout

`tsh status`

Display the list of proxy servers and retrieved certificates.

tsh status [<flags>]

Flag	Default	Description
`-f`, `--format`	`text`	Output format: `text`, `json`, `yaml`.
`-v`, `--[no-]verbose`	`false`	Show extra status information after successful login.
`--[no-]client`	`false`	Show client information only (no server required).

Example:

tsh status

SSH Commands

`tsh ssh`

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

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

Flag	Default	Description
`-p`, `--port`	no default	SSH port on the remote host.
`-A`, `--[no-]forward-agent`	`false`	Forward SSH agent to the target node.
`-L`, `--forward`	no default	Forward localhost connections to remote server.
`-R`, `--remote-forward`	no default	Forward remote connections to localhost.
`-D`, `--dynamic-forward`	no default	Forward via SOCKS5.
`-t`, `--[no-]tty`	`false`	Allocate a TTY.
`-N`, `--[no-]no-remote-exec`	`false`	Don’t execute remote command (useful for port forwarding).
`-f`, `--[no-]fork-after-authentication`	`false`	Run in background after authentication is complete.
`-o`, `--option`	no default	OpenSSH options in the format used in the configuration file.
`--log-dir`	no default	Directory to log separated command output when executing on multiple nodes.
`-c`, `--cluster`	no default	Specify the Teleport cluster to connect to.
`--request-reason`	no default	Reason for requesting access.
`--request-mode`	`resource`	Type of automatic Access Request to make: `off`, `resource`, `role`.
`--[no-]disable-access-request`	`false`	Disable automatic resource Access Requests (DEPRECATED: use `--request-mode=off`).
`--[no-]local`	`false`	Execute command on localhost after connecting to SSH node.
`--[no-]no-resume`	`false`	Disable SSH connection resumption.
`--[no-]participant-req`	`false`	Displays a verbose list of required participants in a moderated session.
`--[no-]relogin`	`true`	Permit performing an authentication attempt on a failed command.
`--reason`	no default	The purpose of the session.
`--invite`	no default	Comma-separated list of people to mark as invited for the session.
`-X`, `--[no-]x11-untrusted`	`false`	Requests untrusted (secure) X11 forwarding for this session.
`-Y`, `--[no-]x11-trusted`	`false`	Requests trusted (insecure) X11 forwarding for this session.
`--x11-untrusted-timeout`	`10m`	Sets a timeout for untrusted X11 forwarding.

Example:

# Open an interactive shell
tsh ssh user@node.example.com

# Run a command
tsh ssh user@node.example.com -- ls -la /tmp

# SSH to a node in a specific cluster
tsh ssh --cluster=leaf-cluster user@node

`tsh scp`

Transfer files to or from a remote SSH node.

tsh scp [<flags>] <from, to>...

Flag	Default	Description
`-r`, `--[no-]recursive`	`false`	Recursive copy of subdirectories.
`-P`, `--port`	no default	Port to connect to on the remote host.
`-p`, `--[no-]preserve`	`false`	Preserve access and modification times.
`-q`, `--[no-]quiet`	`false`	Quiet mode.
`--[no-]no-resume`	`false`	Disable SSH connection resumption.
`--[no-]relogin`	`true`	Permit performing an authentication attempt on a failed command.
`-c`, `--cluster`	no default	Specify the Teleport cluster to connect to.

Example:

# Upload a file
tsh scp local-file.txt user@node:/remote/path/

# Download a file
tsh scp user@node:/remote/file.txt ./local-copy.txt

# Recursive copy
tsh scp -r ./local-dir user@node:/remote/dir

`tsh ls`

List remote SSH nodes accessible in the cluster.

tsh ls [<flags>] [<labels>]

Flag	Default	Description
`-f`, `--format`	`text`	Output format: `text`, `json`, `yaml`, `names`.
`-c`, `--cluster`	no default	Specify the Teleport cluster to connect to.
`-R`, `--[no-]all`	`false`	List nodes from all clusters and proxies.
`--search`	no default	Comma-separated search keywords.
`--query`	no default	Predicate language query.
`-v`, `--[no-]verbose`	`false`	Show one-line output including node UUIDs.

Example:

# List all nodes
tsh ls

# Filter by label
tsh ls env=production

# JSON output
tsh ls --format=json

Kubernetes Commands

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

Flag	Default	Description
`-c`, `--cluster`	no default	Specify the Teleport cluster to connect to.
`-n`, `--namespace`	no default	Configure the default Kubernetes namespace.
`--as`	no default	Configure custom Kubernetes user impersonation.
`--as-groups`	no default	Configure custom Kubernetes group impersonation.
`--labels`	no default	Filter by labels.
`--query`	no default	Filter by predicate language query.
`--[no-]all`	`false`	Generate kubeconfig for every accessible cluster.
`--[no-]disable-access-request`	`false`	Disable automatic resource Access Requests.
`--request-reason`	no default	Reason for requesting access.
`--set-context-name`	`{{.ClusterName}}-{{.KubeName}}`	Define a custom context name.

Example:

# Log in to a specific Kubernetes cluster
tsh kube login my-k8s-cluster

# Log in and generate kubeconfig for all accessible clusters
tsh kube login --all

`tsh kube ls`

List Kubernetes clusters accessible in the Teleport cluster.

tsh kube ls [<flags>] [<labels>]

Flag	Default	Description
`-f`, `--format`	`text`	Output format: `text`, `json`, `yaml`.
`-c`, `--cluster`	no default	Specify the Teleport cluster.
`-R`, `--[no-]all`	`false`	List from all clusters and proxies.
`-q`, `--[no-]quiet`	`false`	Quiet mode.
`--search`	no default	Search keywords.
`--query`	no default	Predicate language query.
`-v`, `--[no-]verbose`	`false`	Show an untruncated list of labels.

Example:

tsh kube ls
tsh kube ls --format=json

`tsh kube exec`

Execute a command in a Kubernetes pod.

tsh kube exec [<flags>] <target> <command>...

Flag	Default	Description
`-n`, `--namespace`	no default	Kubernetes namespace.
`-c`, `--container`	no default	Container name.
`-f`, `--filename`	no default	To use to exec into the resource.
`-s`, `--[no-]stdin`	`false`	Pass stdin to the container.
`-t`, `--[no-]tty`	`false`	Stdin is a TTY.
`-q`, `--[no-]quiet`	`false`	Only print output from the remote session.
`--[no-]participant-req`	`false`	Displays a verbose list of required participants in a moderated session.
`--reason`	no default	The purpose of the session.
`--invite`	no default	Comma-separated list of invited users.

Example:

# Execute a command in a pod
tsh kube exec my-pod -- ls /app

# Open an interactive shell in a pod
tsh kube exec -it my-pod -- /bin/bash

Database Commands

Retrieve short-lived credentials for a database.

tsh db login [<flags>] [<db>]

Flag	Default	Description
`-u`, `--db-user`	no default	Database user to configure as default.
`-n`, `--db-name`	no default	Database name to configure as default.
`-r`, `--db-roles`	no default	Comma-separated database roles for auto-provisioned user.
`--labels`	no default	Filter by labels.
`--query`	no default	Predicate language query.
`--request-reason`	no default	Reason for requesting access.
`--[no-]disable-access-request`	`false`	Disable automatic resource Access Requests.

Example:

# Log in to a database
tsh db login mydb

# Log in with specific user and database name
tsh db login --db-user=alice --db-name=myapp mydb

`tsh db ls`

List all available databases.

tsh db ls [<flags>] [<labels>]

Flag	Default	Description
`-f`, `--format`	`text`	Output format: `text`, `json`, `yaml`.
`-R`, `--[no-]all`	`false`	List from all clusters and proxies.
`--search`	no default	Search keywords.
`--query`	no default	Predicate language query.
`-v`, `--[no-]verbose`	`false`	Show extra database fields.

Example:

tsh db ls
tsh db ls env=production

`tsh db connect`

Connect to a database interactively.

tsh db connect [<flags>] [<db>]

Flag	Default	Description
`-u`, `--db-user`	no default	Database user to log in as.
`-n`, `--db-name`	no default	Database name to log in to.
`-r`, `--db-roles`	no default	Comma-separated database roles.
`--labels`	no default	Filter by labels.
`--query`	no default	Predicate language query.
`--request-reason`	no default	Reason for requesting access.
`--[no-]disable-access-request`	`false`	Disable automatic resource Access Requests.

Example:

# Connect to a PostgreSQL database
tsh db connect --db-user=alice --db-name=myapp mydb

Application Commands

Retrieve a short-lived certificate for an application.

tsh apps login [<flags>] <app>

Flag	Default	Description
`--aws-role`	no default	Amazon IAM role ARN or role name (for AWS CLI access).
`--azure-identity`	no default	Azure managed identity name (for Azure CLI access).
`--gcp-service-account`	no default	GCP service account name (for GCP CLI access).
`--target-port`	no default	Port to which connections should be routed. Valid only for multi-port TCP apps.
`-q`, `--[no-]quiet`	`false`	Quiet mode.

Example:

tsh apps login my-app

# Log in to an AWS app with a specific IAM role
tsh apps login --aws-role=arn:aws:iam::123456789:role/DevRole my-aws-app

`tsh apps ls`

List available applications.

tsh apps ls [<flags>] [<labels>]

Flag	Default	Description
`-f`, `--format`	`text`	Output format: `text`, `json`, `yaml`.
`-R`, `--[no-]all`	`false`	List from all clusters and proxies.
`--search`	no default	Search keywords.
`--query`	no default	Predicate language query.
`-v`, `--[no-]verbose`	`false`	Show extra application fields.

Example:

tsh apps ls
tsh apps ls --format=json

Session Commands

`tsh recordings ls`

List recorded sessions.

tsh recordings ls [<flags>]

Flag	Default	Description
`-f`, `--format`	`text`	Output format: `text`, `json`, `yaml`.
`--from-utc`	no default	Start of time range (format: `2006-01-02`). Defaults to 24 hours ago.
`--to-utc`	no default	End of time range (format: `2006-01-02`). Defaults to current time.
`--last`	no default	Duration into the past (e.g., `5h30m40s`).
`--limit`	`50`	Maximum number of recordings to show.

Example:

# List recent recordings
tsh recordings ls

# List recordings from the last 48 hours
tsh recordings ls --last=48h

# Export in JSON
tsh recordings ls --format=json

`tsh join`

Join an active SSH or Kubernetes session.

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

Flag	Default	Description
`-m`, `--mode`	`observer`	Mode of joining: `observer`, `moderator`, `peer`.
`-c`, `--cluster`	no default	Specify the Teleport cluster to connect to.

Example:

tsh join abc123-session-id
tsh join --mode=moderator abc123-session-id

Access Request Commands

`tsh request create`

Create a new Access Request for additional roles or resources.

tsh request create [<flags>]

Flag	Default	Description
`--roles`	no default	Roles to be requested.
`--resource`	no default	Resource ID to be requested.
`--reason`	no default	Reason for requesting.
`--reviewers`	no default	Suggested reviewers.
`--request-ttl`	no default	Expiration time for the Access Request.
`--session-ttl`	no default	Expiration time for the elevated certificate.
`--max-duration`	no default	How long the access should be granted for.
`--assume-start-time`	no default	Sets time roles can be assumed (RFC3339, e.g. `2023-12-12T23:20:50.52Z`).
`--[no-]nowait`	`false`	Finish without waiting for request resolution.

Example:

# Request a specific role
tsh request create --roles=db-admin --reason="Production incident investigation"

# Request access to a specific resource
tsh request create --resource=/teleport.cluster.local/node/abc123 --reason="Debugging"

`tsh request review`

Review an Access Request.

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

Flag	Default	Description
`--[no-]approve`	`false`	Review proposes approval.
`--[no-]deny`	`false`	Review proposes denial.
`--reason`	no default	Review reason message.
`--assume-start-time`	no default	Sets time roles can be assumed (RFC3339, e.g. `2023-12-12T23:20:50.52Z`).

Example:

# Approve a request
tsh request review --approve --reason="Verified and approved" abc123

# Deny a request
tsh request review --deny --reason="Not authorized for this resource" abc123

`tsh request ls`

List Access Requests.

tsh request ls [<flags>]

Flag	Default	Description
`-f`, `--format`	`text`	Output format: `text`, `json`, `yaml`.
`--[no-]my-requests`	`false`	Only show requests created by the current user.
`--[no-]reviewable`	`false`	Only show requests reviewable by the current user.
`--[no-]suggested`	`false`	Only show requests that suggest the current user as reviewer.

Example:

# List all pending requests
tsh request ls

# List only your own requests
tsh request ls --my-requests

Use tsh request drop to remove active Access Requests from your current identity, returning you to your base role permissions.

CLI Reference

Configuration & API

tsh Reference — Teleport SSH Client Command Line

Global Flags

Global Environment Variables

Auth Commands

`tsh logout`

`tsh status`

SSH Commands

`tsh ssh`

`tsh scp`

`tsh ls`

Kubernetes Commands

`tsh kube ls`

`tsh kube exec`

Database Commands

`tsh db ls`

`tsh db connect`

Application Commands

`tsh apps ls`

Session Commands

`tsh recordings ls`

`tsh join`

Access Request Commands

`tsh request create`

`tsh request review`

`tsh request ls`

Build docs developers (and LLMs) love

CLI Reference

Configuration & API

Documentation Index

​Global Flags

​Global Environment Variables

​Auth Commands

​tsh login

​tsh logout

​tsh status

​SSH Commands

​tsh ssh

​tsh scp

​tsh ls

​Kubernetes Commands

​tsh kube login

​tsh kube ls

​tsh kube exec

​Database Commands

​tsh db login

​tsh db ls

​tsh db connect

​Application Commands

​tsh apps login

​tsh apps ls

​Session Commands

​tsh recordings ls

​tsh join

​Access Request Commands

​tsh request create

​tsh request review

​tsh request ls

Build docs developers (and LLMs) love

Global Flags

Global Environment Variables

Auth Commands

`tsh login`

`tsh logout`

`tsh status`

SSH Commands

`tsh ssh`

`tsh scp`

`tsh ls`

Kubernetes Commands

`tsh kube login`

`tsh kube ls`

`tsh kube exec`

Database Commands

`tsh db login`

`tsh db ls`

`tsh db connect`

Application Commands

`tsh apps login`

`tsh apps ls`

Session Commands

`tsh recordings ls`

`tsh join`

Access Request Commands

`tsh request create`

`tsh request review`

`tsh request ls`