# tsh CLI reference

`tsh` is a CLI client used by Teleport users. It allows users to interact with current and past sessions on the cluster, copy files to and from nodes, and list information about the cluster.

## tsh environment variables

Environment variables configure your tsh client and can help you avoid using flags repetitively.

| Environment Variable             | Description                                                                                                                                                                                        | Example Value                            |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| TELEPORT\_AUTH                   | Any defined [authentication connector](https://goteleport.com/docs/ver/17.x/reference/access-controls/authentication.md), including `passwordless` and `local` (i.e., no authentication connector) | okta                                     |
| TELEPORT\_CLUSTER                | Name of a Teleport root or leaf cluster                                                                                                                                                            | cluster.example.com                      |
| TELEPORT\_LOGIN                  | Login name to be used by default on the remote host                                                                                                                                                | root                                     |
| TELEPORT\_LOGIN\_BIND\_ADDR      | Address in the form of host:port to bind to for login command webhook                                                                                                                              | host:port                                |
| TELEPORT\_LOGIN\_BROWSER         | Set to `none` to stop the system default browser from opening for SSO logins. If the value is not `none`, `tsh` will open the system default browser.                                              | none                                     |
| TELEPORT\_PROXY                  | Address of the Teleport proxy server                                                                                                                                                               | cluster.example.com:3080                 |
| TELEPORT\_HEADLESS               | Use headless authentication                                                                                                                                                                        | true, false, 1, 0                        |
| TELEPORT\_HOME                   | Home location for tsh configuration and data                                                                                                                                                       | /directory                               |
| TELEPORT\_USER                   | A Teleport user name                                                                                                                                                                               | alice                                    |
| TELEPORT\_ADD\_KEYS\_TO\_AGENT   | Specifies if the user certificate should be stored on the running SSH agent                                                                                                                        | yes, no, auto, only                      |
| TELEPORT\_USE\_LOCAL\_SSH\_AGENT | Disable or enable local SSH agent integration                                                                                                                                                      | true, false                              |
| TELEPORT\_GLOBAL\_TSH\_CONFIG    | Override location of global `tsh` config file from default `/etc/tsh.yaml`                                                                                                                         | /opt/teleport/tsh.yaml                   |
| TELEPORT\_MFA\_MODE              | Preferred mode for MFA and Passwordless assertions                                                                                                                                                 | auto, cross-platform, platform, otp, sso |
| TELEPORT\_IDENTITY\_FILE         | File path to identity file                                                                                                                                                                         | /opt/identity                            |

## tsh global flags

| Name                   | Default Value(s) | Allowed Value(s)                                                                                                                                                                                   | Description                                                                                                                                                                               |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-l, --login`          | none             | an identity name                                                                                                                                                                                   | The login identity that the Teleport user will use                                                                                                                                        |
| `--proxy`              | none             | `host:https_port[,ssh_proxy_port]`                                                                                                                                                                 | Teleport Proxy Service address                                                                                                                                                            |
| `--user`               | `$USER`          | none                                                                                                                                                                                               | The Teleport username                                                                                                                                                                     |
| `--ttl`                | `720` (12 hours) | integer                                                                                                                                                                                            | Number of minutes a certificate issued for the `tsh` user will be valid for                                                                                                               |
| `-i, --identity`       | none             | **string** filepath                                                                                                                                                                                | Identity file                                                                                                                                                                             |
| `--cert-format`        | `standard`       | `standard` or `oldssh`                                                                                                                                                                             | SSH certificate format. `oldssh` supports older versions of OpenSSH servers that do not allow for custom metadata, which is how Teleport encodes a user's roles in their SSH certificate. |
| `--insecure`           | none             | none                                                                                                                                                                                               | Do not verify the server's certificate and host name. Use only in test environments.                                                                                                      |
| `--auth`               | `local`          | Any defined [authentication connector](https://goteleport.com/docs/ver/17.x/reference/access-controls/authentication.md), including `passwordless` and `local` (i.e., no authentication connector) | Specify the type of authentication connector to use.                                                                                                                                      |
| `--mfa-mode`           | auto             | `auto`, `cross-platform`, `platform`, `otp`, or `sso`                                                                                                                                              | Preferred mode for MFA and Passwordless assertions.                                                                                                                                       |
| `--skip-version-check` | none             | none                                                                                                                                                                                               | Skip version checking between server and client.                                                                                                                                          |
| `-d, --debug`          | none             | none                                                                                                                                                                                               | Verbose logging to stdout                                                                                                                                                                 |
| `-J, --jumphost`       | none             | A jump host                                                                                                                                                                                        | SSH jumphost                                                                                                                                                                              |
| `--headless`           | none             | none                                                                                                                                                                                               | Use Headless Authentication                                                                                                                                                               |
| `--mlock`              | `auto`           | `auto`, `off`, `best_effort`, `strict`                                                                                                                                                             | Lock process memory to protect client secrets stored in memory from being swapped to disk.                                                                                                |

## tsh apps ls

List all available applications:

```
$ tsh apps ls
```

## tsh clusters

```
$ tsh clusters [<flags>]
```

### Flags

| Name          | Default Value(s) | Allowed Value(s) | Description          |
| ------------- | ---------------- | ---------------- | -------------------- |
| `-q, --quiet` | none             | none             | no headers in output |

### Global flags

These flags are available for all commands `--login`, `--proxy`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

```
$ tsh clusters

Cluster Name Status
------------ ------
staging          online
production       offline

$ tsh clusters --quiet

staging online
production offline
```

## tsh config

Print OpenSSH configuration details to allow using an SSH client with credentials managed by Teleport to connect to hosts in your cluster.

```
$ tsh config
```

### Flags

| Name           | Default Value(s) | Allowed Value(s) | Description                                                                  |
| -------------- | ---------------- | ---------------- | ---------------------------------------------------------------------------- |
| `-l, --login`  | none             | Linux username   | Default Linux username to use. Will translate to SSH config's `User` option. |
| `-p`, `--port` | 3022             | port             | Default SSH port to use. Will translate to SSH config's `Port` option.       |

### Examples

```
Print OpenSSH config file to console
$ tsh config

Append Teleport configuration to ssh config
$ tsh config >> ~/.ssh/config
```

## tsh device enroll

Enroll the current device as a trusted device.

Requires a device enrollment token created via `tctl devices enroll`.

```
$ tsh device enroll --token=TOKEN
```

### Flags

| Name      | Default Value(s) | Allowed Value(s) | Description             |
| --------- | ---------------- | ---------------- | ----------------------- |
| `--token` | none             | String           | Device enrollment token |

### Examples

```
$ tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example
Device "C00AA0AAAA0A"/macOS enrolled
```

## tsh gcloud

Proxy `gcloud` CLI commands through the Teleport Application Service. `gcloud` is a tool for interacting with Google Cloud. A user must already be authenticated to a Google Cloud application in Teleport before they can execute `tsh gcloud` commands.

```
$ tsh gcloud [--app] [<command>]
```

### Arguments

`command`: A `gcloud` command to run, including arguments and flags.

### Flags

| Name    | Default Value(s)                             | Allowed Value(s)                                                    | Description                                                                                                  |
| ------- | -------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `--app` | Currently logged in Google Cloud application | The name of a Google Cloud application as listed via `tsh apps ls`. | The Google Cloud application to run the command against, if logged in to multiple Google Cloud applications. |

### Global flags

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

```
$ tsh gcloud compute instances list
```

## tsh gsutil

Proxy `gsutil` CLI commands through the Teleport Application Service. `gsutil` is a tool for interacting with Google Cloud Storage. A user must already be authenticated to a Google Cloud application in Teleport before they can execute `tsh gsutil` commands.

```
$ tsh gsutil [--app] [<command>]
```

### Arguments

`command`: A `gsutil` command to run, including arguments and flags.

### Flags

| Name    | Default Value(s)                             | Allowed Value(s)                                                    | Description                                                                                                  |
| ------- | -------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `--app` | Currently logged in Google Cloud application | The name of a Google Cloud application as listed via `tsh apps ls`. | The Google Cloud application to run the command against, if logged in to multiple Google Cloud applications. |

### Global flags

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

```
$ tsh gsutil ls
```

## tsh help

Prints help:

```
$ tsh help
```

## tsh join

Joins an active session:

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

### Arguments

`<session-id>`

- `session-id` The UUID of an active Teleport Session obtained by `teleport status` within the session.

### Flags

| Name        | Default Value(s) | Allowed Value(s) | Description                    |
| ----------- | ---------------- | ---------------- | ------------------------------ |
| `--cluster` | none             | a cluster\_name  | Specify the cluster to connect |

### Global flags

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

```
join session using teleport user joe as ec2-user
$ tsh --user=joe --login=ec2-user join <session-id>
```

## tsh kube login

Log into a Kubernetes cluster. Discover connected clusters by using [`tsh kube ls`](#tsh-kube-ls).

```
$ tsh kube login <kube-cluster>
```

```
tsh kube login to k8s cluster (gke_bens-demos_us-central1-c_gks-demo)
$ tsh kube login gke_bens-demos_us-central1-c_gks-demo
Logged into kubernetes cluster "gke_bens-demos_us-central1-c_gks-demo". Try 'kubectl version' to test the connection.

On login, kubeconfig is pointed at the first cluster (alphabetically)
$ kubectl config current-context
aws-gke_bens-demos_us-central1-c_gks-demo

But all clusters are populated as contexts
$ kubectl config get-contexts

CURRENT   NAME                                        CLUSTER                       AUTHINFO                                    NAMESPACE
*         aws-gke_bens-demos_us-central1-c_gks-demo   aws                           aws-gke_bens-demos_us-central1-c_gks-demo
aws-microk8s                                aws                           aws-microk8s
```

### Flags

| Name                     | Default Value(s) | Allowed Value(s) | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------ | ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--all`                  | false            | Boolean          | Whether to generate a kubeconfig for every Kubernetes cluster the current Teleport user has access to. If this is false, `tsh` will only generate a kubeconfig for the cluster specified in the `tsh kube login` command.                                                                                                                                                                                                                                                          |
| `--as`                   | none             | string           | The Kubernetes user that the current Teleport user will log in as when they authenticate to the specified Kubernetes cluster.<br /><br />This uses [Kubernetes impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation), so the Teleport user's Kubernetes user must have permissions to impersonate the target user.                                                                                                            |
| `--as-groups`            | none             | string           | A Kubernetes group that the current Teleport user will log in as when they authenticate to the specified Kubernetes cluster.<br /><br />This uses [Kubernetes impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation), so the Teleport user's Kubernetes user must have permissions to impersonate the target group.<br /><br />You can include this flag multiple times to enable impersonation of multiple Kubernetes groups. |
| `--cluster`              | none             | string           | Name of the Teleport cluster to log into in order to connect to the given Kubernetes cluster.                                                                                                                                                                                                                                                                                                                                                                                      |
| `-n`, `--kube-namespace` | none             | string           | The name of the Kubernetes namespace to configure as the default within the cluster the user is logging into.                                                                                                                                                                                                                                                                                                                                                                      |

## tsh kube ls

List Kubernetes clusters:

```
$ tsh kube ls
```

### Examples

```
$ tsh kube ls

Kube Cluster Name                     Selected
------------------------------------- --------
gke_bens-demos_us-central1-c_gks-demo *
microk8s
```

## tsh login

Logs in to the cluster. When `tsh` logs in, the auto-expiring key is stored in `~/.tsh` and is valid for 12 hours by default unless you specify another interval via `--ttl` flag (capped by the server-side configuration).

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

### Arguments

- `<cluster>` - the name of the cluster, see [Trusted Cluster](https://goteleport.com/docs/ver/17.x/zero-trust-access/management/admin/trustedclusters.md) for more information.

### Flags

| Name                       | Default Value(s) | Allowed Value(s)                  | Description                                                                                                                                                                                                                                       |
| -------------------------- | ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bind-addr`              | none             | host:port                         | Address in the form of host:port to bind to for login command webhook                                                                                                                                                                             |
| `--callback`               | none             | host:port                         | Override the base URL (host:port) of the link shown when opening a browser for cluster logins. Must be used with --bind-addr.                                                                                                                     |
| `-o, --out`                | none             | filepath                          | Identity output filepath                                                                                                                                                                                                                          |
| `--format`                 | `file`           | `file`, `openssh` or `kubernetes` | Identity format: file, openssh (for OpenSSH compatibility) or kubernetes (for kubeconfig)                                                                                                                                                         |
| `--browser`                | none             | `none`                            | Set to 'none' to suppress opening system default browser for `tsh login` commands                                                                                                                                                                 |
| `--request-roles`          | none             |                                   | Request one or more extra roles                                                                                                                                                                                                                   |
| `--request-reason`         | none             |                                   | Reason for requesting additional roles                                                                                                                                                                                                            |
| `--request-nowait`         | none             |                                   | Finish without waiting for request resolution                                                                                                                                                                                                     |
| `--request-id`             | none             |                                   | Login with the roles requested in the given request                                                                                                                                                                                               |
| `--no-use-local-ssh-agent` |                  |                                   | Do not load generated SSH certificates into the local ssh-agent (specified via `$SSH_AUTH_SOCK`). Useful when using `gpg-agent` or Yubikeys. You can also set the `TELEPORT_USE_LOCAL_SSH_AGENT` environment variable to `false` (default `true`) |

### Global flags

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

*The proxy endpoint can take a https and ssh port in this format `host:https_port[,ssh_proxy_port]`*

```
Try both ports 443 and 3080 for https
$ tsh --proxy=proxy.example.com login

Use ports 8080 and 8023 for https and SSH proxy:
$ tsh --proxy=proxy.example.com:8080,8023 login

Use port 8080 and 3023 (default) for SSH proxy:
$ tsh --proxy=proxy.example.com:8080 login

Use port 23 as custom SSH port, keep HTTPS proxy port as default
$ tsh --proxy=work.example.com:,23 login

Login and select cluster "two":
$ tsh --proxy=proxy.example.com login two

Select cluster "two" using existing credentials and proxy:
$ tsh login two

Login to the  cluster with a very short-lived certificate
$ tsh --ttl=1 login

Login using the local Teleport 'admin' user:
$ tsh --proxy=proxy.example.com --auth=local --user=admin login

Login using GitHub as an SSO provider, assuming the GitHub connector is called "github"
$ tsh --proxy=proxy.example.com --auth=github login

Suppress the opening of the system default browser for external provider logins
$ tsh --proxy=proxy.example.com --browser=none

Login to cluster and output a local kubeconfig
$ tsh login --proxy=proxy.example.com --format=kubernetes -o kubeconfig

Request access to a cluster.
$ tsh login --proxy=proxy.example.com --request-reason="I need to run a debug script on production"
```

## tsh logout

Deletes the client's cluster certificate:

```
$ tsh logout
```

## tsh ls

List cluster nodes:

```
$ tsh ls [<flags>] [<label>]
```

Not seeing Nodes?

When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to display Nodes in the Web UI or via `tsh ls`), it only returns the Nodes that the current user is authorized to view.

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

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

If you are not seeing Nodes when expected, make sure that your user's roles include the appropriate `allow` and `deny` rules as documented in the [Access Controls Reference](https://goteleport.com/docs/ver/17.x/reference/access-controls/roles.md).

### Arguments

- `<labels>` - comma-separated list of `key=value` labels to filter nodes by, e.g., `env=dev,host=foo`.

### Flags

| Name            | Default Value(s) | Allowed Value(s) | Description        |
| --------------- | ---------------- | ---------------- | ------------------ |
| `-v, --verbose` | none             | none             | also print Node ID |

### Global flags

These flags are available for all commands `--login`, `--proxy`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

```
$ tsh ls

Node Name Address            Labels
--------- ------------------ ------
grav-00   10.164.0.0:3022    os:linux
grav-01   10.156.0.2:3022    os:linux
grav-02   10.156.0.7:3022    os:osx

$ tsh ls -v

Node Name Node ID                              Address            Labels
--------- ------------------------------------ ------------------ ------
grav-00   52e3e46a-372f-494b-bdd9-a1d25b9d6dec 10.164.0.0:3022    os:linux
grav-01   73d86fc7-7c4b-42e3-9a5f-c46e177a29e8 10.156.0.2:3022    os:linux
grav-02  24503590-e8ae-4a0a-ad7a-dd1865c04e30 10.156.0.7:3022     os:osx

Only show nodes with os label set to 'osx':
$ tsh ls os=osx

Node Name Address            Labels
--------- ------------------ ------
grav-02   10.156.0.7:3022    os:osx
```

## tsh mfa add

Register a new Multi-Factor Authentication (MFA) device:

```
$ tsh mfa add
```

### Examples

```
$ tsh mfa add

Choose device type [TOTP, WEBAUTHN]: webauthn
Enter device name: desktop yubikey
Tap any *registered* security key
Tap your *new* security key
MFA device "desktop yubikey" added.
```

```
$ tsh mfa add

Choose device type [TOTP, WEBAUTHN]: totp
Enter device name: android
Tap any *registered* security key
Open your TOTP app and create a new manual entry with these fields:
Name: awly@example.com:3080
Issuer: Teleport
Algorithm: SHA1
Number of digits: 6
Period: 30s
Secret: 6DHDR7GWA7ZKLLWEWRIF55WXJKZ52UVJ

Once created, enter an OTP code generated by the app: 123456
MFA device "android" added.
```

## tsh mfa ls

List all registered Multi-Factor Authentication (MFA) devices:

```
$ tsh mfa ls
```

## tsh mfa rm

Remove a registered Multi-Factor Authentication (MFA) device. You can view your registered devices using [`tsh mfa ls`](#tsh-mfa-ls).

```
$ tsh mfa rm <device-name>
```

## tsh play

Plays back a prior session:

```
$ tsh play [<flags>] <id-or-file>
```

### Arguments

`<id-or-file>`

- `id-or-file` The UUID of a past Teleport session, or the path to a local recording file.

### Flags

| Name               | Default Value(s) | Allowed Value(s)               | Description                    |
| ------------------ | ---------------- | ------------------------------ | ------------------------------ |
| `--cluster`        | none             | a cluster\_name                | Specify the cluster to connect |
| `--format`         | `pty`            | `json`, `yaml`, `pty`, `text`  | Format for playback            |
| `--speed`          | `1x`             | `0.5x`, `1x`, `2x`, `4x`, `8x` | Playback speed                 |
| `--skip-idle-time` | `false`          | `true, `false\`                | Skip idle time during playback |

### Global flags

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

```
$ tsh --proxy proxy.example.com play <session-id>

Playing back a session streamed from the server.
$ tsh play 1fe153d1-ce8b-4ef4-9908-6539457ba4ad

Playing back a local session in JSON format using jq to filter on events
$ tsh play --format=json ~/play/0c0b81ed-91a9-4a2a-8d7c-7495891a6ca0.tar | jq '.event

Playing back a session at 2x speed while also skipping idle time
$ tsh play --speed=2x --skip-idle-time 1fe153d1-ce8b-4ef4-9908-6539457ba4ad

Dump an SSH session recording to standard out, without respecting timing data.
$ tsh play --format=text 1fe153d1-ce8b-4ef4-9908-6539457ba4ad
```

## tsh proxy app

Starts a local TLS proxy for Application Service connections. You can use this proxy to connect to an application repeatedly after a single login to your Teleport cluster, which is especially useful for interacting with an application via a CLI.

```
$ tsh proxy app [<flags>] <app>
```

### Arguments

`<app>`

- `app` The name of the application to start the local proxy for. To see a list of available applications, run `tsh apps ls`.

### Flags

| Name         | Default Value(s) | Allowed Value(s)       | Description                                                                                                                              |
| ------------ | ---------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `-p, --port` | none             | port number, port pair | Specify the listening port for the local proxy. Accepts an optional target port of a multi-port TCP app after a colon, e.g. "1234:5678". |

### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

### Examples

```
$ tsh proxy app <app>

Proxy a connection to grafana on local port 10700
$ tsh proxy --port 10700 app grafana &
Proxying connections to grafana on 127.0.0.1:10700
$ curl http://127.0.0.1:10700/api/users
```

## tsh proxy aws

Start a local proxy for AWS access. The user must already be logged in to at least one AWS application via Teleport before the proxy can start.

```
$ tsh proxy aws [<flags>]
```

### Flags

| Name                   | Default Value(s)            | Allowed Value(s)                                  | Description                                                                                                      |
| ---------------------- | --------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--app`                | Currently logged in AWS app | string                                            | Optional name of the AWS application (as shown in `tsh apps ls`) to use if logged in to multiple                 |
| `-p`, `--port`         | none                        | port number                                       | Specify the source port for the local proxy                                                                      |
| `-e`, `--endpoint-url` | HTTP Proxy                  | Endpoint URL                                      | Run the local proxy to serve as an AWS endpoint URL. If not specified, the local proxy serves as an HTTPS proxy. |
| `-f`, `--format`       | unix                        | `text`, `unix`, `command-prompt`, or `powershell` | Optional format for printing environment variables for the AWS proxy                                             |

### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

### Examples

```
Proxy a connection to AWS with the default settings
$ tsh apps login awsapp
$ tsh proxy aws
Set env variables from output
$ aws s3 ls

Proxying connections to AWS on 127.0.0.1:10700 to app awsapp2
$ tsh apps logins awsapp2
$ tsh proxy aws --port=10700 --app=awsapp2
Set env variables from output
$ aws s3 ls
```

## tsh proxy azure

Starts a local proxy server that provides secure access to an Azure managed service identity endpoint. This is useful for managing access to Azure from custom client applications. The local proxy forwards traffic to the Teleport Application Service, which uses an Azure managed identity to fetch an authentication token from Azure.

```
$ tsh proxy azure [<flags>]
```

The command will print the address of the local proxy server along with `export` commands for environment variables required to connect:

```
Started Azure proxy on http://127.0.0.1:54321.
To avoid port randomization, you can choose the listening port using the --port flag.

Use the following credentials and HTTPS proxy setting to connect to the proxy:

  export AZURE_CONFIG_DIR=/Users/myuser/.tsh/azure/my.teleport.cluster/azure
  export HTTPS_PROXY=http://127.0.0.1:54321
  export HTTP_PROXY=http://127.0.0.1:54321
  export MSI_ENDPOINT=https://azure-msi.teleport.dev/123456789abcdef01234
  export REQUESTS_CA_BUNDLE=/Users/myuser/.tsh/keys/teleport.example.com/myuser-app/teleport.example.com/azure-cli-localca.pem

```

---

TIP

`tsh proxy azure` runs the local proxy in the foreground, so don't interrupt the process or exit the terminal where you ran the command until you're ready to close the local proxy.

---

Copy the `export` commands and paste them into a second terminal.

To run the local proxy server, one of the user's roles must include the `spec.allow.azure_identities` field with one of the identities used by the Application Service. To learn how to set up secure access to Azure via Teleport, read [Protect the Azure CLI with Teleport Application Access](https://goteleport.com/docs/ver/17.x/enroll-resources/application-access/cloud-apis/azure.md).

### Arguments

This command does not accept any arguments.

### Flags

| Name       | Default Value(s)                             | Allowed Value(s)                                  | Description                                                                                                                                                        |
| ---------- | -------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--app`    | none                                         | string                                            | Name of the Teleport application representing Azure (i.e., based on `tsh apps ls`). Use this flag if your Teleport user has access to multiple Azure applications. |
| `--port`   | none                                         | port number                                       | The port on `localhost` where the local proxy will listen for connections.                                                                                         |
| `--format` | `powershell` if on Windows, `unix` otherwise | `text`, `unix`, `command-prompt`, or `powershell` | The format to use for listing environment variables for Azure client applications connecting to the local proxy.                                                   |

### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

## tsh proxy db

Start a local TLS proxy for database connections when using Teleport with TLS Routing enabled. Clients can connect to a Teleport-registered database through the local proxy.

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

### Flags

| Name        | Default Value(s) | Allowed Value(s) | Description                                                                                               |
| ----------- | ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `--cluster` | none             | string           | The name of the Teleport cluster to connect to.                                                           |
| `--db-name` | see below        | string           | The database name to log in to.                                                                           |
| `--db-user` | see below        | string           | The database user to log in as.                                                                           |
| `--port`    | none             | string           | Source port used by the local proxy.                                                                      |
| `--tunnel`  | none             | Boolean          | Open an authenticated tunnel using a database's client certificate so clients don't need to authenticate. |

If `--db-user` or `--db-name` are required, then default settings are chosen from either an active database certificate obtained via a prior use of `tsh db login` or from the user's allowed `db_users` or `db_names`.

The database user is always required. The database name is required for PostgreSQL, MongoDB, and Oracle databases.

### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

### Examples

Proxy a DB connection to a named database

```
$ tsh proxy db <db>
```

Proxy a connection to mysql db on local port 10700:

```
$ tsh proxy db --port 10700  mysql-db
Started DB proxy on 127.0.0.1:10700

Use following credentials to connect to the mysql-db proxy:
ca_file=/Users/jeff/.tsh/keys/teleport.example.com/cas/teleport.example.com.pem
cert_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff-db/tele1c/mysql-db-x509.pem
key_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff
```

Proxy a connection to mysql db with no credentials required:

```
$ tsh proxy db --tunnel mysql-db
Started authenticated tunnel for the MySQL database "mysql-db" in cluster "teleport.example.com" on 127.0.0.1:49415.

Use the following command to connect to the database:
  $ mysql --port 49415 --host localhost --protocol TCP
```

## tsh proxy gcloud

Start a local proxy for Google Cloud API access. The user must already be logged in to at least one Google Cloud application via Teleport before the proxy can start.

```
$ tsh proxy gcloud [<flags>]
```

### Flags

| Name                   | Default Value(s)                     | Allowed Value(s)                                  | Description                                                                                                              |
| ---------------------- | ------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--app`                | Currently logged in Google Cloud app | string                                            | Optional name of the Google Cloud application (as shown in `tsh apps ls`) to use if logged in to multiple                |
| `-p`, `--port`         | none                                 | port number                                       | Specify the source port for the local proxy                                                                              |
| `-e`, `--endpoint-url` | HTTP Proxy                           | Endpoint URL                                      | Run the local proxy to serve as a Google Cloud endpoint URL. If not specified, the local proxy serves as an HTTPS proxy. |
| `-f`, `--format`       | unix                                 | `text`, `unix`, `command-prompt`, or `powershell` | Optional format for printing environment variables for the Google Cloud proxy                                            |

### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

### Examples

```
$ tsh apps login google-cloud-app
$ tsh proxy gcloud
Set env variables from output
$ gcloud compute instances list
$ gsutil ls
```

## tsh proxy kube

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

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

### Flags

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

### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

### Examples

Proxy requests to a Kubernetes cluster

```
$ tsh proxy kube test-cluster
Preparing the following Teleport Kubernetes clusters:
Teleport Cluster Name Kube Cluster Name Context Name
--------------------- ----------------- -----------------
teleport-test             test-cluster           teleport-test-test-cluster

Started local proxy for Kubernetes on 127.0.0.1:49487
To avoid port randomization, you can choose the listening port using the --port flag.

Use the following config for your Kubernetes applications. For example:
export KUBECONFIG="/home/alice/.tsh/keys/proxy.example.com/alice-kube/teleport-test/localproxy-49487-kubeconfig"
kubectl version
```

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

```
$ tsh proxy kube test-cluster --exec
Preparing the following Teleport Kubernetes clusters:
Teleport Cluster Name Kube Cluster Name Context Name
--------------------- ----------------- -----------------
teleport-test             test-cluster           teleport-test-test-cluster

Started local proxy for Kubernetes Access in the background.

Warning! Teleport will initiate a new shell configured with kubectl for local proxy access.
To conclude the session, simply use the "exit" command. Upon exiting, your original shell will be restored,
the local proxy will be closed, and future access through this headless session won't be possible.


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

## tsh proxy ssh

Start a local TLS proxy for `ssh` connections when using Teleport in TLS Routing mode. This is typically used as part of the SSH client configuration to use `ssh` as a client through Teleport. See the [OpenSSH Guide](https://goteleport.com/docs/ver/17.x/enroll-resources/server-access/openssh/openssh-agentless.md) guide on configuring OpenSSH servers and clients. The `tsh config` output will include `tsh proxy ssh` within a `ProxyCommand` directive.

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

### Arguments

- `<[user@]host>` Remote hostname and the login to use

### Flags

| Name        | Default Value(s) | Allowed Value(s) | Description                                     |
| ----------- | ---------------- | ---------------- | ----------------------------------------------- |
| `--cluster` | none             | Teleport Cluster | The name of the Teleport cluster to connect to. |

### [Global Flags](#tsh-global-flags)

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)

### Examples

Run the following command to generate an OpenSSH client configuration:

```
$ tsh config
```

This command produces the following configuration:

```
# Common flags for all example.com hosts
Host *.example.com example.com
    UserKnownHostsFile "/Users/jeff/.tsh/known_hosts"
    IdentityFile "/Users/jeff/.tsh/keys/enterprise.teleportdemo.com/jeff"
    CertificateFile "/Users/jeff/.tsh/keys/example.com/jeff-ssh/example.com-cert.pub"
    PubkeyAcceptedKeyTypes +ssh-rsa-cert-v01@openssh.com
    HostKeyAlgorithms ssh-rsa-cert-v01@openssh.com

# Flags for all example.com hosts except the proxy
Host *.example.com !example.com
    Port 3022
    ProxyCommand "/usr/local/bin/tsh" proxy ssh --cluster=example.com --proxy=example.com %r@%h:%p

```

This output should be placed into the default SSH Config for environment, `~/.ssh/config` for Mac/Linux or `.ssh\config` in the Windows User home directory. You can use this as a standalone SSH config file too.

When you run an `ssh` command against a host with a subdomain of your Proxy Service's domain, this SSH configuration will use the `ProxyCommand` to run `tsh proxy ssh`:

```
$ ssh myuser@node1.example.com
```

## tsh puttyconfig

Adds a PuTTY saved session to the Windows registry for the currently logged in Windows user.

```
$ tsh puttyconfig [--leaf <leaf-cluster-name>] [login@]hostname

```

### Flags

| Name           | Default Value(s) | Allowed Value(s)  | Description                                                                  |
| -------------- | ---------------- | ----------------- | ---------------------------------------------------------------------------- |
| `-l, --login`  | none             | Linux username    | Default Linux username to use. Will translate to SSH config's `User` option. |
| `-p`, `--port` | 3022             | port              | Default SSH port to use. Will translate to SSH config's `Port` option.       |
| `--leaf`       | none             | Leaf cluster name | Leaf cluster name to add to the saved session.                               |

### Examples

```
Add a saved PuTTY session on 'node' for the user 'ec2-user'
$ tsh puttyconfig ec2-user@node

Add a saved PuTTY session for the Teleport-registered OpenSSH node 'openssh' for the user 'ubuntu'
$ tsh puttyconfig --port 22 ubuntu@openssh

Add a saved PuTTY session on leaf-node for the user 'ec2-user' on the leaf cluster 'example.teleport.sh'
$ tsh puttyconfig --leaf example.teleport.sh ec2-user@leaf-node
```

See [full docs on `tsh puttyconfig` here](https://goteleport.com/docs/ver/17.x/connect-your-client/putty-winscp.md).

## tsh recordings ls

List recorded sessions.

```
$ tsh recordings ls [<flags>]
```

### Flags

| Name         | Default Value(s) | Allowed Value(s) | Description                                                                                      |
| ------------ | ---------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| `--from-utc` | 24 hours ago     | date             | Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago. |
| `--to-utc`   | current          | date             | Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago. |
| `--limit`    | 50               | number           | Maximum number of recordings to show.                                                            |
| `--last`     | none             | duration         | Duration into the past from which session recordings should be listed. Format 5h30m40s           |

### Global flags

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

```
get the recorded sessions from the last 24 hours
$ tsh --proxy proxy.example.com recordings ls
ID                                   Type Participants Hostname Timestamp
------------------------------------ ---- ------------ -------- -------------------
b0a04442-70dc-4be8-9308-7b7901d2d600 ssh  jeff         dev       Nov 26 16:36:16 UTC
c0a02222-70dc-4be8-9308-7b7901d2d600 kube alice                  Nov 26 20:36:16 UTC
d0a04442-70dc-4be8-9308-7b7901d2d600 ssh  navin        test      Nov 26 16:36:16 UTC

The session can be played with tsh play
$ tsh play c0a02222-70dc-4be8-9308-7b7901d2d60

List recorded sessions that occurred between Nov 1, 2022 to Nov 3, 2022
$ tsh recordings ls --from-utc=2022-11-01 --to-utc=2022-11-3

Retrieve recorded sessions in the last 6 hours
$ tsh recordings ls --last=6h0m0s
```

---

RECORDED SESSIONS AVAILABILITY

Recorded sessions are linked from the audit events to session recordings files in their [storage backend](https://goteleport.com/docs/ver/17.x/reference/backends.md). The following error can occur if a session recording file is not available or when employing multiple auth servers with directory storage backend for recorded sessions. When using a directory storage backend for audit logs and recorded sessions, only the Auth Service with that recorded session can retrieve it.

```
$ tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b
ERROR: Recording for session c8e1b2c5-322a-4095-89e3-391edfd2da9b not found.
```

Using a Security Information and Event Management (SIEM) service that combines the audit logs will help consolidate the list of available recordings.

Downloaded recorded session are directly playable as a file.

```
$ tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b.tar
```

---

## tsh request create

Create a new Access Request.

```
$ tsh request create [<flags>]
```

### Flags

| Name                  | Default Value(s)             | Allowed Value(s)                                            | Description                                                                                                                                    |
| --------------------- | ---------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--roles`             | none                         | Comma-separated strings                                     | List of Teleport roles to request                                                                                                              |
| `--resource`          | none                         | String (flag can be repeated to request multiple resources) | Resource ID to be requested                                                                                                                    |
| `--reason`            | none                         | String                                                      | Reason for making the request (optional)                                                                                                       |
| `--reviewers`         | none                         | Comma-separated strings                                     | Suggested reviewers for the request (optional)                                                                                                 |
| `--nowait`            | `false`                      | `true` or `false`                                           | Finish without waiting for request resolution                                                                                                  |
| `--request-ttl`       | 1 hour                       | Relative duration like `5s`, `2m`, or `3h`,                 | Defines how long the Access Request will be in a `PENDING` state before becoming invalid                                                       |
| `--session-ttl`       | Time left on current session | Relative duration like `5s`, `2m`, or `3h`                  | Defines how long the elevated session will be valid for                                                                                        |
| `--max-duration`      | none                         | Relative duration like `5s`, `2m`, `3h`, or `7d`            | Defines the maximum duration of the elevated session up to 7 days. The assigned role also must have `max_duration` option specified (optional) |
| `--assume-start-time` | none                         | String                                                      | Sets time roles can be assumed by requestor (RFC3339)                                                                                          |

---

NOTE

The `--request-ttl` and `--session-ttl` values can not be greater than the following:

- Maximum certificate lifetime.
- Time left on an existing session (certificate).
- Maximum session duration defined by the user's roles.

Use `--max-duration` to request access for longer than the maximum certificate lifetime.

---

## tsh request drop

Drop one or more Access Requests from current identity

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

### Arguments

- `<request-id>` - IDs of requests to "drop" from the current identity so that your certificate will lose elevated roles and/or resource restrictions. If no request ID is given, the default is to drop all Access Requests.

## tsh request ls

List Access Requests

```
$ tsh request ls
```

### Flags

| Name            | Default Value(s) | Allowed Value(s)          | Description                                              |
| --------------- | ---------------- | ------------------------- | -------------------------------------------------------- |
| `--format`      | `text`           | `text`, `json`, or `yaml` | Format output                                            |
| `--reviewable`  | `false`          | `true` or `false`         | Only show requests reviewable by current user            |
| `--suggested`   | `false`          | `true` or `false`         | Only show requests that suggest current user as reviewer |
| `--my-requests` | `false`          | `true` or `false`         | Only show requests created by current user               |

## tsh request review

Review an Access Request

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

### Flags

| Name                  | Default Value(s) | Allowed Value(s)  | Description                                           |
| --------------------- | ---------------- | ----------------- | ----------------------------------------------------- |
| `--approve`           | `false`          | `true` or `false` | Review proposes approval                              |
| `--deny`              | `false`          | `true` or `false` | Review proposes denial                                |
| `--reason`            | none             | String            | Review reason message                                 |
| `--assume-start-time` | none             | String            | Sets time roles can be assumed by requestor (RFC3339) |

### Arguments

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

## tsh request search

Search for resources to request access to

```
$ tsh request search [<flags>]
```

### Flags

| Name       | Default Value(s) | Allowed Value(s)                                             | Description                                                                                                                                      |
| ---------- | ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--kind`   | none             | `node`, `kubernetes_cluster`, `db`, `app`, `windows_desktop` | Resource kind to search for (required)                                                                                                           |
| `--search` | none             | Comma-separated strings                                      | List of comma-separated search keywords or phrases enclosed in single quotes                                                                     |
| `--query`  | none             | String                                                       | Query by [predicate language](https://goteleport.com/docs/ver/17.x/reference/predicate-language.md#resource-filtering) enclosed in single quotes |
| `--labels` | none             | Comma-separated strings                                      | List of comma-separated labels to filter by labels (e.g. `key=value1,key2=value2`)                                                               |

## tsh request show

Show Access Request details

```
$ tsh request show <request-id>
```

### Flags

| Name       | Default Value(s) | Allowed Value(s)          | Description   |
| ---------- | ---------------- | ------------------------- | ------------- |
| `--format` | text             | `text`, `json`, or `yaml` | Format output |

### Arguments

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

## tsh scp

Copies files from source to dest:

```
$ tsh scp [<flags>] <source>... <dest>
```

### Arguments

- `<source>` - filepath to copy
- `<dest>` - target destination

### Flags

| Name              | Default Value(s) | Allowed Value(s) | Description                           |
| ----------------- | ---------------- | ---------------- | ------------------------------------- |
| `--cluster`       | none             | a cluster\_name  | Specify the cluster to connect        |
| `-r, --recursive` | none             | none             | Recursive copy of subdirectories      |
| `-P, --port`      | none             | port number      | Port to connect to on the remote host |
| `-q, --quiet`     | none             | none             | Quiet mode                            |

### Global flags

These flags are available for all commands `--login`, `--proxy`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

```
$ tsh --proxy=proxy.example.com scp example.txt user@host:/destination/dir
```

---

NOTE

`tsh scp` will not work from the CLI if the user requires session moderation. You can transfer files in a moderated session by joining the SSH session from the Web UI and requesting the file transfer there. Both the session initiator and moderators must be present in the Web UI in order to approve the file transfer request.

---

## tsh ssh

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

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

### Arguments

`<[user@]host> [<command>...]`

- `user` The login identity to use on the remote host. If `[user]` is not specified the user defaults to `$USER` or can be set with `--user`. If the flag `--user` and positional argument `[user]` are specified the arg `[user]` takes precedence.
- `host` The `nodename` of a cluster Node or a label specification like `env=aws` to run on all matching hosts.
- `command` The command to execute on a remote host.

### Flags

| Name                        | Default Value(s) | Allowed Value(s) | Description                                                                                                                                                                                                                                       |
| --------------------------- | ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p, --port`                | none             | port             | SSH port on a remote host                                                                                                                                                                                                                         |
| `-A, --forward-agent`       | none             | none             | Forward agent to target node like `ssh -A`                                                                                                                                                                                                        |
| `-L, --forward`             | none             | none             | Forward localhost connections to remote server                                                                                                                                                                                                    |
| `-D, --dynamic-forward`     | none             | none             | Forward localhost connections to remote server using SOCKS5                                                                                                                                                                                       |
| `-R, --remote-forward`      | none             | none             | Forward remote connections to localhost                                                                                                                                                                                                           |
| `-N, -no-remote-exec`       | none             | none             | Don't execute remote command, useful for port forwarding                                                                                                                                                                                          |
| `--local`                   | none             |                  | Execute command on localhost after connecting to SSH node                                                                                                                                                                                         |
| `-t, --tty`                 | `file`           |                  | Allocate TTY                                                                                                                                                                                                                                      |
| `--cluster`                 | none             |                  | Specify the cluster to connect                                                                                                                                                                                                                    |
| `-o, --option`              | `local`          |                  | OpenSSH options in the format used in the configuration file                                                                                                                                                                                      |
| `--enable-escape-sequences` |                  |                  | Enable support for SSH escape sequences. Type `~?` during an SSH session to list supported sequences.                                                                                                                                             |
| `--no-use-local-ssh-agent`  |                  |                  | Do not load generated SSH certificates into the local ssh-agent (specified via `$SSH_AUTH_SOCK`). Useful when using `gpg-agent` or Yubikeys. You can also set the `TELEPORT_USE_LOCAL_SSH_AGENT` environment variable to `false` (default `true`) |
| `-X, --x11-untrusted`       | none             | none             | Requests untrusted (secure) X11 forwarding for this session.                                                                                                                                                                                      |
| `-Y, --x11-trusted`         | none             | none             | Requests trusted (insecure) X11 forwarding for this session. This can make your local machine vulnerable to attacks, use with caution.                                                                                                            |
| `--x11-untrusted-timeout`   | 10m              | duration         | Sets a timeout for untrusted X11 forwarding, after which the client will reject any forwarding requests from the server.                                                                                                                          |

### Global flags

These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`. Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).

### Examples

```
Log in to node `grav-00` as OS User `root` with Teleport User `teleport`
$ tsh ssh --proxy proxy.example.com --user teleport -d root@grav-00
`tsh ssh` takes the same arguments as OpenSSH client:
$ tsh ssh -o ForwardAgent=yes root@grav-00
$ tsh ssh -o AddKeysToAgent=yes root@grav-00
Run `hostname` on all nodes with the `env: aws` label
$ tsh ssh root@env=aws hostname
```

## tsh sessions ls

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

```
$ tsh sessions ls
```

### Flags

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

### Examples

```
list all active sessions
$ tsh sessions ls

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

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

## tsh status

Display the list of proxy servers and retrieved certificates:

```
$ tsh status
```

### Examples

```
$ tsh status

> Profile URL:  https://proxy.example.com:3080
Logged in as:       benarent
Cluster:            aws
Roles:              access, editor, auditor
Logins:             benarent, root, ec2-user, ubuntu
Kubernetes:         enabled
Kubernetes cluster: "gke_bens-demos_us-central1-c_gks-demo"
Kubernetes groups:  system:masters
Valid until:        2020-11-21 01:50:23 -0800 PST [valid for 11h52m0s]
Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty
```

## tsh version

Prints the version of your `tsh` binary and the Teleport Proxy Service in the current `tsh` profile

```
$ tsh version [<flags>]
```

| Name           | Default Value(s) | Allowed Value(s) | Description                                        |
| -------------- | ---------------- | ---------------- | -------------------------------------------------- |
| `-f, --format` | `text`           | text, json, yaml | Format for version output                          |
| `--client`     | none             | none             | Show the client version only (no server required). |

### Examples

```
$ tsh version
Teleport v17.7.20 git: go1.25.9
Proxy version: 17.7.20
Proxy: teleport.example.com:443
```

Display in JSON format:

```
$ tsh version --format=json
```

```
{
  "version": "17.7.20",
  "gitref": "",
  "runtime": "go1.25.9",
  "proxyVersion": "17.7.20",
  "proxyPublicAddress": "teleport.example.com:443"
}

```

Only display the `tsh` binary version:

```
$ tsh version --client
Teleport v17.7.20 git: go1.25.9
```