tsh Reference

Report an IssueView as Markdown

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	no default	Specify the name of authentication connector to use.
--bind-addr	no default	Override host:port used when opening a browser for cluster logins.
--callback	no default	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	no default	SSH certificate format.
-d, --[no-]debug	false	Verbose logging to stdout.
-i, --identity	no default	Identity file.
-J, --jumphost	no default	SSH jumphost.
-k, --add-keys-to-agent	auto	Controls how keys are handled. Valid values are [auto no yes only].
-l, --login	no default	Remote host login.
--mfa-mode	auto (one of: auto, cross-platform, platform, otp, sso, browser)	Preferred mode for MFA and Passwordless assertions.
--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	no default	Specify a PIV slot key to use for Hardware Key support instead of the default. Ex: "9d".
--proxy	no default	Teleport proxy address.
--relay	no default	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	no default	Minutes to live for a session.
--user	no default	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	no default	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	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 (one of: auto, cross-platform, platform, otp, sso, browser)	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 (off, auto, best_effort, strict).
TELEPORT_PIV_SLOT	no default	Specify a PIV slot key to use for Hardware Key support instead of the default. Ex: "9d".
TELEPORT_PROXY	no default	Teleport proxy address.
TELEPORT_RELAY	no default	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	no default	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	no default	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	no default (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	no default	(For AWS CLI access only) Amazon IAM role ARN or role name.
--azure-identity	no default	(For Azure CLI access only) Azure managed identity name.
--gcp-service-account	no default	(For GCP CLI access only) GCP service account name.
-q, --[no-]quiet	false	Quiet mode.
--target-port	no default	Port to which connections made using this cert should be routed to. Valid only for multi-port TCP apps.

Arguments:

Argument	Default	Description
app	no default (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	no default (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 (one of: text, json, yaml)	Format output (text, json, yaml).
--query	no default	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	no default	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	no default (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	no default	Optional Name of the AWS application to use if logged into multiple.
--aws-role	no default	(For AWS CLI access only) Amazon IAM role ARN or role name.
--exec	no default	Execute different commands (e.g. terraform) under Teleport credentials.

Arguments:

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

tsh aws-profile

Generate AWS config profiles by syncing with your integrated AWS IAM Identity Center account(s). Other profiles in the config file are left untouched.

Usage:

tsh aws-profile [<flags>]

Flags:

Flag	Default	Description
--aws-sso-region	no default	AWS region for SSO. Auto-detected from cluster if not specified.
--[no-]dry-run	false	Print the configuration that will be applied without modifying the AWS config file.

tsh az

Access Azure API.

Usage:

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

Flags:

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

Arguments:

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

tsh beams add

Start a new beam, and optionally connect to it via SSH.

Usage:

tsh beams add [<flags>]

Flags:

Flag	Default	Description
-f, --format	text (one of: text, json, yaml)	Format output (text, json, yaml).
--[no-]console	true	Connect to the beam via SSH after creation.

tsh beams exec

Run a command in a beam, via SSH.

Usage:

tsh beams exec <name> <command>...

Arguments:

Argument	Default	Description
command	no default (required)	Command to execute in the instance.
name	no default (required)	ID (or UUID) of the beam to target.

tsh beams ls

List beam instances.

Usage:

tsh beams ls [<flags>]

Flags:

Flag	Default	Description
-f, --format	text (one of: text, json, yaml)	Format output (text, json, yaml).
--[no-]all	false	List all beams. By default, filters to show only beams belonging to the current user.

tsh beams publish

Publish an HTTP or TCP service running in a beam.

Usage:

tsh beams publish [<flags>] <name>

Flags:

Flag	Default	Description
-f, --format	text (one of: text, json, yaml)	Format output (text, json, yaml).
--[no-]tcp	false	Publish as a TCP app instead of an HTTP app.

Arguments:

Argument	Default	Description
name	no default (required)	ID (or UUID) of the beam to target.

tsh beams rm

Delete a beam.

Usage:

tsh beams rm <name>

Arguments:

Argument	Default	Description
name	no default (required)	ID (or UUID) of the beam to delete.

tsh beams scp

Copy files between a beam and the local filesystem.

Usage:

tsh beams scp [<flags>] <src> <dest>

Flags:

Flag	Default	Description
-f, --format	text (one of: text, json, yaml)	Format output (text, json, yaml).
-q, --[no-]quiet	false	Quiet mode.
-r, --[no-]recursive	false	Recursive copy of subdirectories.

Arguments:

Argument	Default	Description
dest	no default (required)	Destination path to copy, in the form BEAM_ID:PATH or LOCAL_PATH.
src	no default (required)	Source path to copy, in the form BEAM_ID:PATH or LOCAL_PATH.

tsh beams ssh

Start an interactive shell in a beam, via SSH.

Usage:

tsh beams ssh <name>

Arguments:

Argument	Default	Description
name	no default (required)	ID (or UUID) of the beam to connect to.

tsh beams unpublish

Unpublish a previously published service in a beam.

Usage:

tsh beams unpublish <name>

Arguments:

Argument	Default	Description
name	no default (required)	ID (or UUID) of the beam to target.

tsh clusters

List available Teleport clusters.

Usage:

tsh clusters [<flags>]

Flags:

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

Arguments:

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

Arguments:

Argument	Default	Description
db	no default (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 (one of: text, json, yaml)	Format output (text, json, yaml).
--labels	no default	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--query	no default	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').

Arguments:

Argument	Default	Description
db	no default (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	no default	List of comma separated target database services. Mutually exclusive with --search or --labels.
--labels	no default	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
-n, --db-name	no default	Database name to log in to.
--[no-]confirm	true	Confirm selected database services before executing command.
--output-dir	no default	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	no default	List of comma separate database roles to use for auto-provisioned user.
--search	no default	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").
-u, --db-user	no default	Database user to log in as.

Arguments:

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

Arguments:

Argument	Default	Description
db	no default (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	no default	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--query	no default	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').

Arguments:

Argument	Default	Description
db	no default (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 (one of: text, json, yaml)	Format output (text, json, yaml).
--query	no default	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	no default	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	no default (optional)	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).

tsh delegation create-session

Create a delegation session, allowing a bot or workload to temporarily act on your behalf.

Usage:

tsh delegation create-session [<flags>]

Flags:

Flag	Default	Description
--allow-app	no default	Allow access to an application.
--allow-db	no default	Allow access to a database.
--allow-git-server	no default	Allow access to a Git server.
--allow-kube-cluster	no default	Allow access to a Kubernetes cluster.
--allow-node	no default	Allow access to an SSH node.
--allow-windows-desktop	no default	Allow access to a Windows desktop.
--bot	no default	Name of a bot allowed to use the delegation session. Repeat to allow multiple bots.
--[no-]allow-all	false	Allow access to all resources, including destructive administrative actions. Mutually exclusive with the other --allow-* flags.
--session-ttl	no default	How long the delegation session should remain valid.

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	no default	Device enrollment token.

tsh env

Print commands to set Teleport session environment variables.

Usage:

tsh env [<flags>]

Flags:

Flag	Default	Description
-f, --format	text (one of: text, json, yaml)	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	no default	Optional name of the GCP application to use if logged into multiple.
--gcp-service-account	no default	(For GCP CLI access only) GCP service account name.

Arguments:

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

tsh git clone

Clone a Git repository.

Usage:

tsh git clone <repository> [<directory>]

Arguments:

Argument	Default	Description
directory	no default (optional)	The name of a new directory to clone into.
repository	no default (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	no default (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	no default	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 (one of: text, json, yaml)	Format output (text, json, yaml).
--query	no default	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--search	no default	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").

Arguments:

Argument	Default	Description
labels	no default (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	no default	Optional name of the GCP application to use if logged into multiple.
--gcp-service-account	no default	(For GCP CLI access only) GCP service account name.

Arguments:

Argument	Default	Description
command	no default (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	no default (optional)	Headless authentication request ID.

tsh help

Show help.

Usage:

tsh help [<command>...]

Arguments:

Argument	Default	Description
command	no default (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	no default	Specify the Teleport cluster to connect.
-m, --mode	observer (one of: observer, moderator, peer)	Mode of joining the session.

Arguments:

Argument	Default	Description
session-id	no default (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	no default	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	no default	To use to exec into the resource.
--invite	no default	A comma separated list of people to mark as invited for the session.
-n, --namespace	no default	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	no default	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	no default (required)	Command to execute in the container.
target	no default (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	no default	Specify the Teleport cluster to connect.
-m, --mode	observer (one of: observer, moderator, peer)	Mode of joining the session.

Arguments:

Argument	Default	Description
session	no default (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	no default	Configure custom Kubernetes user impersonation.
--as-groups	no default	Configure custom Kubernetes group impersonation.
-c, --cluster	no default	Specify the Teleport cluster to connect.
--labels	no default	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
-n, --namespace	no default	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	no default	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--request-reason	no default	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	no default (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	no default	Specify the Teleport cluster to connect.
-f, --format	text (one of: text, json, yaml)	Format output (text, json, yaml).
-q, --[no-]quiet	false	Quiet mode.
--query	no default	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	no default	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	no default (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	no default	Specify the Teleport cluster to connect.
-f, --format	text (one of: text, json, yaml)	Format output (text, json, yaml).

tsh kubectl

Runs a kubectl command on a Kubernetes cluster.

Usage:

tsh kubectl [args...]

Arguments:

Argument	Default	Description
args	no default (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	no default	Specify the Teleport cluster to connect.
--[no-]no-resume	false	Disable SSH connection resumption.

Arguments:

Argument	Default	Description
[user@]host	no default (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	no default	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	no default	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	no default	Identity output.
--request-id	no default	Login with the roles requested in the given request.
--request-reason	no default	Reason for requesting additional roles.
--request-reviewers	no default	Suggested reviewers for role request.
--request-roles	no default	Request one or more extra roles.
--scope	no default	Scope pins credentials to a given scope. Use "" to explicitly remove scoping.
-v, --[no-]verbose	false	Show extra status information.

Arguments:

Argument	Default	Description
cluster	no default (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	no default	Specify the Teleport cluster to connect.
-f, --format	text (one of: text, json, yaml, names)	Format output (text, json, yaml, names).
--query	no default	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	no default	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	no default (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	no default	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 (one of: pretty, compact, auto, none)	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	no default	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	no default	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	no default	Extra custom headers used for streamable HTTP MCP servers.
--json-format	auto (one of: pretty, compact, auto, none)	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	no default	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	no default	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	no default (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	no default	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 (one of: pretty, compact, auto, none)	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	no default	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	no default	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 (one of: pretty, compact, auto, none)	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	no default	Database name to log in to.
--[no-]overwrite	false	Overwrites command and environment variable from the config file.
-u, --db-user	no default	Database user to log in as.

Arguments:

Argument	Default	Description
name	no default (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 (one of: text, json, yaml)	Format output (text, json, yaml).
--query	no default	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--search	no default	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	no default (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	no default	Name of the new MFA device.
--type	no default (one of: TOTP, WEBAUTHN)	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 (one of: text, json, yaml)	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	no default (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	no default	Specify the Teleport cluster to connect.
-f, --format	pty (one of: pty, json, yaml, text)	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 (one of: 0.5x, 1x, 2x, 4x, 8x)	Playback speed, applicable when streaming SSH or Kubernetes sessions.

Arguments:

Argument	Default	Description
session-id	no default (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	no default	Specify the Teleport cluster to connect.
-p, --port	no default	Specifies the listening port used 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	no default (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	no default	Optional Name of the AWS application to use if logged into multiple.
-f, --format	unix (one of: unix, command-prompt, powershell, text, athena-odbc, athena-jdbc)	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	no default	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	no default	Optional Name of the Azure application to use if logged into multiple.
-f, --format	unix (one of: unix, command-prompt, powershell, text)	Optional format to print the commands for setting environment variables, one of: unix, command-prompt, powershell, text. Default is unix.
-p, --port	no default	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	no default	Specify the Teleport cluster to connect.
--labels	no default	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--listen	no default	Specifies the source address used by proxy db listener. Mutually exclusive with --port.
-n, --db-name	no default	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	no default	Specifies the source port used by proxy db listener.
--query	no default	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
-r, --db-roles	no default	List of comma separate database roles to use for auto-provisioned user.
--request-reason	no default	Reason for requesting access.
-u, --db-user	no default	Database user to log in as.

Arguments:

Argument	Default	Description
db	no default (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	no default	Optional Name of the GCP application to use if logged into multiple.
-f, --format	unix (one of: unix, command-prompt, powershell, text)	Optional format to print the commands for setting environment variables, one of: unix, command-prompt, powershell, text. Default is unix.
-p, --port	no default	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	no default	Configure custom Kubernetes user impersonation.
--as-groups	no default	Configure custom Kubernetes group impersonation.
-c, --cluster	no default	Specify the Teleport cluster to connect.
--exec-arg	no default	Arguments to pass to the executed command (can be specified multiple times).
--exec-cmd	no default	Command to execute when --exec is enabled. If not specified, defaults to $SHELL or /bin/bash. Implicitly enables exec mode.
-f, --format	unix (one of: unix, command-prompt, powershell, text)	Optional format to print the commands for setting environment variables, one of: unix, command-prompt, powershell, text. Default is unix.
--labels	no default	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
-n, --namespace	no default	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	no default	Specifies the source port used by the proxy listener.
--query	no default	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	no default (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	no default	Specify the Teleport cluster to connect.
-p, --port	no default	Specifies the listening port used by the proxy app listener.

Arguments:

Argument	Default	Description
app	no default (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	no default	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	no default (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	no default	Override output file name.

Arguments:

Argument	Default	Description
session-id	no default (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 (one of: text, json, yaml)	Format output (text, json, yaml).. Defaults to 'text'.
--from-utc	no default	Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago.
--last	no default	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	no default	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	no default	Sets time roles can be assumed by requestor (RFC3339 e.g 2023-12-12T23:20:50.52Z).
--max-duration	no default	How long the access should be granted for.
--[no-]nowait	false	Finish without waiting for request resolution.
--reason	no default	Reason for requesting.
--request-ttl	no default	Expiration time for the Access Request.
--resource	no default	Resource ID to be requested.
--reviewers	no default	Suggested reviewers.
--roles	no default	Roles to be requested.
--session-ttl	no default	Expiration time for the elevated certificate.

tsh request drop

Drop one or 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 (one of: text, json, yaml)	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	no default	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	no default	Review reason message.

Arguments:

Argument	Default	Description
request-id	no default (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 (one of: text, json, yaml)	Format output (text, json, yaml).
--kind	no default	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	no default	Kubernetes API group to search for resources.
--kube-cluster	no default	Kubernetes Cluster to search for Pods.
--kube-kind	no default	Kubernetes resource kind name (plural) to search for. Required with --kind="kube_resource" Ex: pods, deployments, namespaces, etc.
--labels	no default	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	no default	Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and || (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--search	no default	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 (one of: text, json, yaml)	Format output (text, json, yaml).

Arguments:

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

tsh resolve

Resolves an SSH host.

Usage:

tsh resolve [<flags>] <host>

Flags:

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

Arguments:

Argument	Default	Description
host	no default (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	no default	Directories to scan. Defaults to /home/ on Linux, /Users/ on macOS, and C:\Users\ on Windows.
--skip-paths	no default	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	no default	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	no default	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	no default (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 (one of: text, json, yaml)	Format output (text, json, yaml).
--kind	ssh,k8s,db,app,desktop (any of (repeatable): ssh, k8s, kube, 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 (one of: off, resource, role)	Type of automatic Access Request to make.

Flags:

Flag	Default	Description
-A, --[no-]forward-agent	false	Forward agent to target node.
-c, --cluster	no default	Specify the Teleport cluster to connect.
-D, --dynamic-forward	no default	Forward localhost connections to remote server using SOCKS5.
-f, --[no-]fork-after-authentication	false	Run in background after authentication is complete.
--invite	no default	A comma separated list of people to mark as invited for the session.
-L, --forward	no default	Forward localhost connections to remote server.
--log-dir	no default	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	no default	OpenSSH options in the format used in the configuration file.
-p, --port	no default	SSH port on a remote host.
--reason	no default	The purpose of the session.
--request-mode	resource (one of: off, resource, role)	Type of automatic Access Request to make.
--request-reason	no default	Reason for requesting access.
-R, --remote-forward	no default	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	no default (optional)	Command to execute on a remote host.
[user@]host	no default (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 (one of: text, json, yaml)	Format output (text, json, yaml).
--[no-]client	false	Show client information only (no server required).
-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 (one of: text, json, yaml)	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 and 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	no default	A label-based selector for which workload identities to issue. Multiple labels can be provided using ','.
--name-selector	no default	The name of the workload identity to issue.
--output	no default	Path to the directory to write the SVID into.

Was this page helpful?

How can we improve this page?