tsh Reference

Report an Issue

Is this page helpful?

How can we improve this page?

This guide provides a comprehensive list of commands, arguments, and flags for tsh.

tsh is a CLI client for accessing Teleport-protected resources. 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 [<flags>] <command> [<args> ...]

Global flags:

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

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	none	Specify the name of authentication connector to use.
TELEPORT_CLUSTER	none	Name of a Teleport root or leaf cluster
TELEPORT_GLOBAL_TSH_CONFIG	none	Override location of global tsh config file from default /etc/tsh.yaml
TELEPORT_HEADLESS	false	Use headless login. Shorthand for --auth=headless.
TELEPORT_HOME	none	Home location for tsh configuration and data
TELEPORT_IDENTITY_FILE	none	Identity file.
TELEPORT_LOGIN	none	Remote host login.
TELEPORT_LOGIN_BIND_ADDR	none	Override host:port used when opening a browser for cluster logins.
TELEPORT_MFA_MODE	auto	Preferred mode for MFA and Passwordless assertions (auto, cross-platform, platform, otp, sso).
TELEPORT_MLOCK_MODE	auto	Determines whether process memory will be locked and whether failure to do so will be accepted (off, auto, best_effort, strict).
TELEPORT_PIV_SLOT	none	Specify a PIV slot key to use for Hardware Key support instead of the default. Ex: "9d".
TELEPORT_PROXY	none	Teleport proxy address.
TELEPORT_RELAY	none	Teleport relay address, "none" to explicitly disable the use of a relay, or "default" to use the cluster-provided address even if a different address was specified at login time.
TELEPORT_USER	none	Teleport user, defaults to current local user.

tsh apps config

Print app connection information.

Usage:

tsh apps config [<flags>] [<app>]

Flags:

Flag	Default	Description
-f, --format	none	Optional print format, one of: "uri" to print app address, "ca" to print CA cert path, "cert" to print cert path, "key" print key path, "curl" to print example curl command, "json" or "yaml" to print everything as JSON or YAML.

Arguments:

Argument	Default	Description
app	none (optional)	App to print information for. Required when logged into multiple apps.

tsh apps login

Retrieve short-lived certificate for an app.

Usage:

tsh apps login [<flags>] <app>

Flags:

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

Arguments:

Argument	Default	Description
app	none (required)	App name to retrieve credentials for. Can be obtained from tsh apps ls output.

tsh apps logout

Remove app certificate.

Usage:

tsh apps logout [<app>]

Arguments:

Argument	Default	Description
app	none (optional)	App to remove credentials for.

tsh apps ls

List available applications.

Usage:

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

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
-R, --[no-]all	false	List apps from all clusters and proxies.
--search	none	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").
-v, --[no-]verbose	false	Show extra application fields.

Arguments:

Argument	Default	Description
labels	none (optional)	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).

tsh aws

Access AWS API.

Usage:

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

Flags:

Flag	Default	Description
--app	none	Optional Name of the AWS application to use if logged into multiple.
--aws-role	none	(For AWS CLI access only) Amazon IAM role ARN or role name.
--exec	none	Execute different commands (e.g. terraform) under Teleport credentials.

Arguments:

Argument	Default	Description
command	none (optional)	AWS command and subcommands arguments that are going to be forwarded to AWS CLI.

tsh az

Access Azure API.

Usage:

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

Flags:

Flag	Default	Description
--app	none	Optional name of the Azure application to use if logged into multiple.
--azure-identity	none	(For Azure CLI access only) Azure managed identity name.

Arguments:

Argument	Default	Description
command	none (optional)	az command and subcommands arguments that are going to be forwarded to Azure CLI.

tsh clusters

List available Teleport clusters.

Usage:

tsh clusters [<flags>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
-q, --[no-]quiet	false	Quiet mode.
-v, --[no-]verbose	false	Verbose table output, shows full label output.

tsh config

Print OpenSSH configuration details.

Usage:

tsh config [<flags>]

Flags:

Flag	Default	Description
-p, --port	none	SSH port on a remote host.

tsh db config

Print database connection information. Useful when configuring GUI clients.

Usage:

tsh db config [<flags>] [<db>]

Flags:

Flag	Default	Description
-f, --format	none	Print format: "text" to print in table format (default), "cmd" to print connect command, "json" or "yaml" to print in JSON or YAML.
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').

Arguments:

Argument	Default	Description
db	none (optional)	Print information for the specified database.

tsh db connect

Connect to a database.

Usage:

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

Flags:

Flag	Default	Description
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
-n, --db-name	none	Database name to log in to.
--[no-]disable-access-request	false	Disable automatic resource Access Requests.
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
-r, --db-roles	none	List of comma separate database roles to use for auto-provisioned user.
--request-reason	none	Reason for requesting access.
-u, --db-user	none	Database user to log in as.

Arguments:

Argument	Default	Description
db	none (optional)	Database service name to connect to.

tsh db env

Print environment variables for the configured database.

Usage:

tsh db env [<flags>] [<db>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').

Arguments:

Argument	Default	Description
db	none (optional)	Print environment for the specified database.

tsh db exec

Execute database commands on target database services.

Usage:

tsh db exec [<flags>] <command>

Flags:

Flag	Default	Description
--dbs	none	List of comma separated target database services. Mutually exclusive with --search or --labels.
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
-n, --db-name	none	Database name to log in to.
--[no-]confirm	true	Confirm selected database services before executing command.
--output-dir	none	Directory to store command output per target database service. A summary is saved as "summary.json".
--parallel	1	Run commands on target databases in parallel. Defaults to 1, and maximum allowed is 10.
-r, --db-roles	none	List of comma separate database roles to use for auto-provisioned user.
--search	none	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").
-u, --db-user	none	Database user to log in as.

Arguments:

Argument	Default	Description
command	none (required)	Execute this command on target database services.

tsh db login

Retrieve credentials for a database.

Usage:

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

Flags:

Flag	Default	Description
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
-n, --db-name	none	Database name to configure as default.
--[no-]disable-access-request	false	Disable automatic resource Access Requests.
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
-r, --db-roles	none	List of comma separate database roles to use for auto-provisioned user.
--request-reason	none	Reason for requesting access.
-u, --db-user	none	Database user to configure as default.

Arguments:

Argument	Default	Description
db	none (optional)	Database to retrieve credentials for. Can be obtained from 'tsh db ls' output.

tsh db logout

Remove database credentials.

Usage:

tsh db logout [<flags>] [<db>]

Flags:

Flag	Default	Description
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').

Arguments:

Argument	Default	Description
db	none (optional)	Database to remove credentials for.

tsh db ls

List all available databases.

Usage:

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

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
-R, --[no-]all	false	List databases from all clusters and proxies.
--search	none	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").
-v, --[no-]verbose	false	Show extra database fields.

Arguments:

Argument	Default	Description
labels	none (optional)	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).

tsh device enroll

Enroll this device as a trusted device. Requires Teleport Enterprise.

Usage:

tsh device enroll [<flags>]

Flags:

Flag	Default	Description
--[no-]current-device	false	Attempts to register and enroll the current device. Requires device admin privileges.
--token	none	Device enrollment token.

tsh env

Print commands to set Teleport session environment variables.

Usage:

tsh env [<flags>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--[no-]unset	false	Print commands to clear Teleport session environment variables.

tsh gcloud

Access GCP API with the gcloud command.

Usage:

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

Flags:

Flag	Default	Description
--app	none	Optional name of the GCP application to use if logged into multiple.
--gcp-service-account	none	(For GCP CLI access only) GCP service account name.

Arguments:

Argument	Default	Description
command	none (optional)	gcloud command and subcommands arguments.

tsh git clone

Clone a Git repository.

Usage:

tsh git clone <repository> [<directory>]

Arguments:

Argument	Default	Description
directory	none (optional)	The name of a new directory to clone into.
repository	none (required)	Git URL of the repository to clone.

tsh git config

Check Teleport config on the working Git directory. Or provide an action ('update' or 'reset') to configure the Git repo.

Usage:

tsh git config [<action>]

Arguments:

Argument	Default	Description
action	none (optional)	Optional action to perform. 'update' to configure the Git repo to proxy Git commands through Teleport. 'reset' to clear Teleport configuration from the Git repo.

tsh git login

Opens a browser and retrieves your login from GitHub.

Usage:

tsh git login --github-org=GITHUB-ORG [<flags>]

Flags:

Flag	Default	Description
--github-org	none	GitHub organization.
--[no-]force	false	Force a login.

tsh git ls

List Git servers.

Usage:

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

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--search	none	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").

Arguments:

Argument	Default	Description
labels	none (optional)	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).

tsh gsutil

Access Google Cloud Storage with the gsutil command.

Usage:

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

Flags:

Flag	Default	Description
--app	none	Optional name of the GCP application to use if logged into multiple.
--gcp-service-account	none	(For GCP CLI access only) GCP service account name.

Arguments:

Argument	Default	Description
command	none (optional)	gsutil command and subcommands arguments.

tsh headless approve

Approve a headless authentication request.

Usage:

tsh headless approve [<flags>] [<request id>]

Environment variables:

Variable	Default	Description
TELEPORT_HEADLESS_SKIP_CONFIRM	false	Skip confirmation and prompt for MFA immediately.

Flags:

Flag	Default	Description
--[no-]skip-confirm	false	Skip confirmation and prompt for MFA immediately.

Arguments:

Argument	Default	Description
request id	none (optional)	Headless authentication request ID.

tsh help

Show help.

Usage:

tsh help [<command>...]

Arguments:

Argument	Default	Description
command	none (optional)	Show help on command.

tsh join

Join the active SSH or Kubernetes session.

Usage:

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

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
-m, --mode	observer	Mode of joining the session, valid modes are observer, moderator and peer.

Arguments:

Argument	Default	Description
session-id	none (required)	ID of the session to join.

tsh kube exec

Execute a command in a Kubernetes pod.

Usage:

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

Flags:

Flag	Default	Description
-c, --container	none	Container name. If omitted, use the kubectl.kubernetes.io/default-container annotation for selecting the container to be attached or the first container in the pod will be chosen.
-f, --filename	none	To use to exec into the resource.
--invite	none	A comma separated list of people to mark as invited for the session.
-n, --namespace	none	Configure the default Kubernetes namespace.
--[no-]participant-req	false	Displays a verbose list of required participants in a moderated session.
-q, --[no-]quiet	false	Only print output from the remote session.
--reason	none	The purpose of the session.
-s, --[no-]stdin	false	Pass stdin to the container.
-t, --[no-]tty	false	Stdin is a TTY.

Arguments:

Argument	Default	Description
command	none (required)	Command to execute in the container.
target	none (required)	Pod or deployment name.

tsh kube join

Join an active Kubernetes session.

Usage:

tsh kube join [<flags>] <session>

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
-m, --mode	observer	Mode of joining the session, valid modes are observer, moderator and peer.

Arguments:

Argument	Default	Description
session	none (required)	The ID of the target session.

tsh kube login

Login to a Kubernetes cluster.

Usage:

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

Flags:

Flag	Default	Description
--as	none	Configure custom Kubernetes user impersonation.
--as-groups	none	Configure custom Kubernetes group impersonation.
-c, --cluster	none	Specify the Teleport cluster to connect.
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
-n, --namespace	none	Configure the default Kubernetes namespace.
--[no-]all	false	Generate a kubeconfig with every cluster the user has access to. Mutually exclusive with --labels or --query.
--[no-]disable-access-request	false	Disable automatic resource Access Requests.
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--request-reason	none	Reason for requesting access.
--set-context-name	{{.ClusterName}}-{{.KubeName}}	Define a custom context name. To use it with --all include "{{.KubeName}}".

Arguments:

Argument	Default	Description
kube-cluster	none (optional)	Name of the Kubernetes cluster to login to. Check 'tsh kube ls' for a list of available clusters.

tsh kube ls

Get a list of Kubernetes clusters.

Usage:

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

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
-f, --format	text	Format output (text, json, yaml).
-q, --[no-]quiet	false	Quiet mode.
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
-R, --[no-]all	false	List Kubernetes clusters from all clusters and proxies.
--search	none	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").
-v, --[no-]verbose	false	Show an untruncated list of labels.

Arguments:

Argument	Default	Description
labels	none (optional)	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).

tsh kube sessions

Get a list of active Kubernetes sessions. (DEPRECATED: use tsh sessions ls --kind=kube instead.)

Usage:

tsh kube sessions [<flags>]

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
-f, --format	text	Format output (text, json, yaml).

tsh kubectl

Runs a kubectl command on a Kubernetes cluster.

Usage:

tsh kubectl [args...]

Arguments:

Argument	Default	Description
args	none (optional)	Arbitrary arguments

tsh latency ssh

Measure latency to a particular SSH host.

Usage:

tsh latency ssh [<flags>] <[user@]host>

Environment variables:

Variable	Default	Description
TELEPORT_NO_RESUME	false	Disable SSH connection resumption.

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
--[no-]no-resume	false	Disable SSH connection resumption.

Arguments:

Argument	Default	Description
[user@]host	none (required)	Remote hostname and the login to use.

tsh login

Log in to a cluster and retrieve the session certificate.

Usage:

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

Flags:

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

Arguments:

Argument	Default	Description
cluster	none (optional)	Specify the Teleport cluster to connect.

tsh logout

Delete a cluster certificate.

Usage:

tsh logout

tsh ls

List remote SSH nodes.

Usage:

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

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
-f, --format	text	Format output (text, json, yaml, names).
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
-R, --[no-]all	false	List nodes from all clusters and proxies.
--search	none	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").
-v, --[no-]verbose	false	One-line output (for text format), including node UUIDs.

Arguments:

Argument	Default	Description
labels	none (optional)	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).

tsh mcp config

Print client configuration details.

Usage:

tsh mcp config [<flags>] [<name>]

Environment variables:

Variable	Default	Description
TELEPORT_MCP_CLIENT_CONFIG	none	If specified, update the specified client config, assuming its format. "claude" for default Claude Desktop config, "cursor" for global Cursor MCP servers config, or specify a JSON file path. Can also be set with environment variable TELEPORT_MCP_CLIENT_CONFIG.
TELEPORT_MCP_CONFIG_JSON_FORMAT	auto	Format the JSON file (pretty, compact, auto, none). auto saves in compact if the file is already compact, otherwise pretty. Can also be set with environment variable TELEPORT_MCP_CONFIG_JSON_FORMAT. Default is auto.

Flags:

Flag	Default	Description
--client-config	none	If specified, update the specified client config, assuming its format. "claude" for default Claude Desktop config, "cursor" for global Cursor MCP servers config, or specify a JSON file path. Can also be set with environment variable TELEPORT_MCP_CLIENT_CONFIG.
--format	none	Format specifies the configuration format (claude, vscode, cursor). If not provided it will assume format from the configuration file, When no configuration file is provided it defaults to "claude".
-H, --header	none	Extra custom headers used for streamable HTTP MCP servers.
--json-format	auto	Format the JSON file (pretty, compact, auto, none). auto saves in compact if the file is already compact, otherwise pretty. Can also be set with environment variable TELEPORT_MCP_CONFIG_JSON_FORMAT. Default is auto.
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--[no-]auto-reconnect	false	Automatically starts a new remote MCP session when the previous remote session is interrupted by network issues or tsh session expirations. Recommended for stateless MCP sessions. Defaults to true.
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
-R, --[no-]all	false	Select all MCP servers. Mutually exclusive with --labels or --query.

Arguments:

Argument	Default	Description
name	none (optional)	Name of the MCP server.

tsh mcp db config

Print client configuration details.

Usage:

tsh mcp db config [<flags>] [<name>]

Environment variables:

Variable	Default	Description
TELEPORT_MCP_CLIENT_CONFIG	none	If specified, update the specified client config, assuming its format. "claude" for default Claude Desktop config, "cursor" for global Cursor MCP servers config, or specify a JSON file path. Can also be set with environment variable TELEPORT_MCP_CLIENT_CONFIG.
TELEPORT_MCP_CONFIG_JSON_FORMAT	auto	Format the JSON file (pretty, compact, auto, none). auto saves in compact if the file is already compact, otherwise pretty. Can also be set with environment variable TELEPORT_MCP_CONFIG_JSON_FORMAT. Default is auto.

Flags:

Flag	Default	Description
--client-config	none	If specified, update the specified client config, assuming its format. "claude" for default Claude Desktop config, "cursor" for global Cursor MCP servers config, or specify a JSON file path. Can also be set with environment variable TELEPORT_MCP_CLIENT_CONFIG.
--format	none	Format specifies the configuration format (claude, vscode, cursor). If not provided it will assume format from the configuration file, When no configuration file is provided it defaults to "claude".
--json-format	auto	Format the JSON file (pretty, compact, auto, none). auto saves in compact if the file is already compact, otherwise pretty. Can also be set with environment variable TELEPORT_MCP_CONFIG_JSON_FORMAT. Default is auto.
-n, --db-name	none	Database name to log in to.
--[no-]overwrite	false	Overwrites command and environment variable from the config file.
-u, --db-user	none	Database user to log in as.

Arguments:

Argument	Default	Description
name	none (optional)	Database service name.

tsh mcp ls

List available MCP server applications.

Usage:

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

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--search	none	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").
-v, --[no-]verbose	false	Show extra MCP server fields.

Arguments:

Argument	Default	Description
labels	none (optional)	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).

tsh mfa add

Add a new MFA device.

Usage:

tsh mfa add [<flags>]

Flags:

Flag	Default	Description
--name	none	Name of the new MFA device.
--type	none	Type of the new MFA device (TOTP, WEBAUTHN).

tsh mfa ls

Get a list of registered MFA devices.

Usage:

tsh mfa ls [<flags>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
-v, --[no-]verbose	false	Print more information about MFA devices.

tsh mfa rm

Remove a MFA device.

Usage:

tsh mfa rm <name>

Arguments:

Argument	Default	Description
name	none (required)	Name or ID of the MFA device to remove.

tsh piv agent

Start PIV key agent.

Usage:

tsh piv agent

tsh play

Replay the recorded session (SSH, Kubernetes, App, DB).

Usage:

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

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
-f, --format	pty	Format output (pty, json, yaml, text).
--[no-]skip-idle-time	false	Quickly skip over idle time, applicable when streaming SSH or Kubernetes sessions.
--speed	1x	Playback speed, applicable when streaming SSH or Kubernetes sessions.

Arguments:

Argument	Default	Description
session-id	none (required)	ID or path to session file to play.

tsh proxy app

Start local TLS proxy for app connection when using Teleport in single-port mode.

Usage:

tsh proxy app [<flags>] <app>

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
-p, --port	none	Specifies the listening port used by by the proxy app listener. Accepts an optional target port of a multi-port TCP app after a colon, e.g. "1234:5678".

Arguments:

Argument	Default	Description
app	none (required)	The name of the application to start local proxy for.

tsh proxy aws

Start local proxy for AWS access.

Usage:

tsh proxy aws [<flags>]

Flags:

Flag	Default	Description
--app	none	Optional Name of the AWS application to use if logged into multiple.
-f, --format	unix	Optional format to print the commands for setting environment variables, one of: unix, command-prompt, powershell, text. Default is unix. Or specify a service format, one of: athena-odbc, athena-jdbc.
-p, --port	none	Specifies the source port used by the proxy listener.

tsh proxy azure

Start local proxy for Azure access.

Usage:

tsh proxy azure [<flags>]

Flags:

Flag	Default	Description
--app	none	Optional Name of the Azure application to use if logged into multiple.
-f, --format	unix	Optional format to print the commands for setting environment variables, one of: unix, command-prompt, powershell, text. Default is unix.
-p, --port	none	Specifies the source port used by the proxy listener.

tsh proxy db

Start local TLS proxy for database connections when using Teleport in single-port mode.

Usage:

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

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--listen	none	Specifies the source address used by proxy db listener. Mutually exclusive with --port.
-n, --db-name	none	Database name to log in to.
--[no-]disable-access-request	false	Disable automatic resource Access Requests.
--[no-]insecure-listen-anywhere	false	Allows the local proxy to listen on any address without restrictions. WARNING: this will expose unsecured listener to anyone in the network. Only use when network access is otherwise restricted.
--[no-]tunnel	false	Open authenticated tunnel using database's client certificate so clients don't need to authenticate.
-p, --port	none	Specifies the source port used by proxy db listener.
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
-r, --db-roles	none	List of comma separate database roles to use for auto-provisioned user.
--request-reason	none	Reason for requesting access.
-u, --db-user	none	Database user to log in as.

Arguments:

Argument	Default	Description
db	none (optional)	The name of the database to start local proxy for.

tsh proxy gcloud

Start local proxy for GCP access.

Usage:

tsh proxy gcloud [<flags>]

Flags:

Flag	Default	Description
--app	none	Optional Name of the GCP application to use if logged into multiple.
-f, --format	unix	Optional format to print the commands for setting environment variables, one of: unix, command-prompt, powershell, text. Default is unix.
-p, --port	none	Specifies the source port used by the proxy listener.

tsh proxy kube

Start local proxy for Kubernetes access.

Usage:

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

Flags:

Flag	Default	Description
--as	none	Configure custom Kubernetes user impersonation.
--as-groups	none	Configure custom Kubernetes group impersonation.
-c, --cluster	none	Specify the Teleport cluster to connect.
-f, --format	unix	Optional format to print the commands for setting environment variables, one of: unix, command-prompt, powershell, text. Default is unix.
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
-n, --namespace	none	Configure the default Kubernetes namespace.
--[no-]exec	false	Run the proxy in the background and reexec into a new shell with $KUBECONFIG already pointed to our config file.
-p, --port	none	Specifies the source port used by the proxy listener.
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--set-context-name	{{.ClusterName}}-{{.KubeName}}	Define a custom context name or template.

Arguments:

Argument	Default	Description
kube-cluster	none (optional)	Name of the Kubernetes cluster to proxy. Check 'tsh kube ls' for a list of available clusters. If not specified, all clusters previously logged in through tsh kube login will be used.

tsh proxy mcp

Start local proxy for MCP access.

Usage:

tsh proxy mcp [<flags>] <app>

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
-p, --port	none	Specifies the listening port used by by the proxy app listener.

Arguments:

Argument	Default	Description
app	none (required)	The name of the MCP application to start local proxy for.

tsh proxy ssh

Start local TLS proxy for ssh connections when using Teleport in single-port mode.

Usage:

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

Environment variables:

Variable	Default	Description
TELEPORT_NO_RESUME	false	Disable SSH connection resumption.

Flags:

Flag	Default	Description
-c, --cluster	none	Specify the Teleport cluster to connect.
--[no-]no-resume	false	Disable SSH connection resumption.
--[no-]relogin	true	Permit performing an authentication attempt on a failed command.

Arguments:

Argument	Default	Description
[user@]host	none (required)	Remote hostname and the login to use.

tsh recordings export

Export recorded desktop sessions to video.

Usage:

tsh recordings export [<flags>] <session-id>

Flags:

Flag	Default	Description
--out	none	Override output file name.

Arguments:

Argument	Default	Description
session-id	none (required)	ID of the session to export.

tsh recordings ls

List recorded sessions.

Usage:

tsh recordings ls [<flags>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).. Defaults to 'text'.
--from-utc	none	Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago.
--last	none	Duration into the past from which session recordings should be listed. Format "5h30m40s".
--limit	50	Maximum number of recordings to show. Default 50.
--to-utc	none	End of time range in which recordings are listed. Format 2006-01-02. Defaults to current time.

tsh request create

Create a new Access Request.

Usage:

tsh request create [<flags>]

Flags:

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

tsh request drop

Drop one more Access Requests from current identity.

Usage:

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

Arguments:

Argument	Default	Description
request-id	* (optional)	IDs of requests to drop (default drops all requests).

tsh request ls

List Access Requests.

Usage:

tsh request ls [<flags>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--[no-]my-requests	false	Only show requests created by current user.
--[no-]reviewable	false	Only show requests reviewable by current user.
--[no-]suggested	false	Only show requests that suggest current user as reviewer.

tsh request review

Review an Access Request.

Usage:

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

Flags:

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

Arguments:

Argument	Default	Description
request-id	none (required)	ID of target request.

tsh request search

Search for resources to request access to.

Usage:

tsh request search [<flags>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--kind	none	Resource kind to search for (node, kube_cluster, kube_resource, db, app, windows_desktop, user_group, saml_idp_service_provider, aws_ic_account, aws_ic_account_assignment, git_server). Mutually exclusive with --roles.
--kube-api-group	none	Kubernetes API group to search for resources.
--kube-cluster	none	Kubernetes Cluster to search for Pods.
--kube-kind	none	Kubernetes resource kind name (plural) to search for. Required with --kind="kube_resource" Ex: pods, deployments, namespaces, etc.
--labels	none	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--namespace	default	Kubernetes Namespace to search for Pods.
--[no-]all-kube-namespaces	false	Search Pods in every namespace.
--[no-]roles	false	List requestable roles instead of searching for resources. Mutually exclusive with --kind.
--query	none	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--search	none	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").
-v, --[no-]verbose	false	Verbose table output, shows full label output.

tsh request show

Show request details.

Usage:

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

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).

Arguments:

Argument	Default	Description
request-id	none (required)	ID of the target request.

tsh resolve

Resolves an SSH host.

Usage:

tsh resolve [<flags>] <host>

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
-q, --[no-]quiet	false	Quiet mode.

Arguments:

Argument	Default	Description
host	none (required)	Remote hostname to resolve.

tsh scan keys

Scan the local machine for SSH private keys and report findings to Teleport.

Usage:

tsh scan keys [<flags>]

Flags:

Flag	Default	Description
--dirs	/Users/	Directories to scan.
--skip-paths	none	Paths to directories or files to skip. Supports for matching patterns.

tsh scopes ls

List scopes at which user has assigned privileges.

Usage:

tsh scopes ls [<flags>]

Flags:

Flag	Default	Description
-v, --[no-]verbose	false	Show table with details of per-scope privileges.

tsh scp

Transfer files to a remote SSH node.

Usage:

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

Environment variables:

Variable	Default	Description
TELEPORT_NO_RESUME	false	Disable SSH connection resumption.

Flags:

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

Arguments:

Argument	Default	Description
from, to	none (required)	Source and destination to copy, one must be a local path and one must be a remote path.

tsh sessions ls

List active sessions.

Usage:

tsh sessions ls [<flags>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--kind	ssh,k8s,db,app,desktop	Filter by session kind(s).

tsh ssh

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

Usage:

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

Environment variables:

Variable	Default	Description
TELEPORT_NO_RESUME	false	Disable SSH connection resumption.
TELEPORT_REQUEST_MODE	resource	Type of automatic Access Request to make (off, resource, role).

Flags:

Flag	Default	Description
-A, --[no-]forward-agent	false	Forward agent to target node.
-c, --cluster	none	Specify the Teleport cluster to connect.
-D, --dynamic-forward	none	Forward localhost connections to remote server using SOCKS5.
-f, --[no-]fork-after-authentication	false	Run in background after authentication is complete.
--invite	none	A comma separated list of people to mark as invited for the session.
-L, --forward	none	Forward localhost connections to remote server.
--log-dir	none	Directory to log separated command output, when executing on multiple nodes. If set, output from each node will also be labeled in the terminal.
-N, --[no-]no-remote-exec	false	Don't execute remote command, useful for port forwarding.
--[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.
-o, --option	none	OpenSSH options in the format used in the configuration file.
-p, --port	none	SSH port on a remote host.
--reason	none	The purpose of the session.
--request-mode	resource	Type of automatic Access Request to make (off, resource, role).
--request-reason	none	Reason for requesting access.
-R, --remote-forward	none	Forward remote connections to localhost.
-t, --[no-]tty	false	Allocate TTY.
--x11-untrusted-timeout	10m	Sets a timeout for untrusted X11 forwarding, after which the client will reject any forwarding requests from the server.
-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. This can make your local machine vulnerable to attacks, use with caution.

Arguments:

Argument	Default	Description
command	none (optional)	Command to execute on a remote host.
[user@]host	none (optional)	Remote hostname and the login to use, this argument is required.

tsh status

Display the list of proxy servers and retrieved certificates.

Usage:

tsh status [<flags>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
-v, --[no-]verbose	false	Show extra status information after successful login.

tsh update

Update client tools (tsh, tctl) to the latest version defined by the cluster configuration.

Usage:

tsh update [<flags>]

Flags:

Flag	Default	Description
--[no-]clear	false	Removes locally installed client tools updates from the Teleport home directory.

tsh version

Print the tsh client and Proxy server versions for the current context.

Usage:

tsh version [<flags>]

Flags:

Flag	Default	Description
-f, --format	text	Format output (text, json, yaml).
--[no-]client	false	Show the client version only (no server required).

tsh vnet

Start Teleport VNet, a virtual network for TCP application access.

Usage:

tsh vnet

tsh vnet-ssh-autoconfig

Automatically include VNet's generated OpenSSH-compatible config file in ~/.ssh/config.

Usage:

tsh vnet-ssh-autoconfig

tsh workload-identity issue-x509

Use Teleport Workload Identity to issue an X509 credential write it to a local directory.

Usage:

tsh workload-identity issue-x509 --output=OUTPUT [<flags>]

Flags:

Flag	Default	Description
--credential-ttl	1h	Sets the time to live for the credential.
--label-selector	none	A label-based selector for which workload identities to issue. Multiple labels can be provided using ','.
--name-selector	none	The name of the workload identity to issue.
--output	none	Path to the directory to write the SVID into.

Was this page helpful?

How can we improve this page?