From 9d214bf98bcbdbaedef7fff243abaf2c239709d4 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Mon, 12 Jan 2026 11:52:15 -0500 Subject: [PATCH] Generate the tsh CLI reference (#56205) Closes #47358 Run the docs generator introduced in #54394 for the `tsh` CLI reference. Also remove the environment variable override for `TELEPORT_LOGIN_BROWSER`, which is a hidden flag. Note that the following hidden global environment variables are present in the manually maintained guide but, because they are hidden, absent in the generated guide: - TELEPORT_LOGIN_BROWSER - TELEPORT_USE_LOCAL_SSH_AGENT The guide is also missing the `tsh puttyconfig` command, which is only present when we build `tsh` for Windows. However, since VNET for SSH fulfills much of the use case for `tsh puttyconfig`, and generating the docs adds entries for around 33 more `tsh` commands, this is an acceptable tradeoff. Edit some help text to conform to the standards of the documentation. --- docs/cspell.json | 1 + .../teleport-clients/teleport-connect.mdx | 2 +- .../third-party/putty-winscp.mdx | 4 - docs/pages/reference/cli/tsh.mdx | 2201 ++++++++++------- lib/utils/docenvdefaults/tsh.yaml | 7 +- lib/utils/docs-usage.md.tmpl | 1 + tool/tsh/common/kube.go | 2 +- tool/tsh/common/tsh.go | 22 +- 8 files changed, 1306 insertions(+), 934 deletions(-) diff --git a/docs/cspell.json b/docs/cspell.json index 579dfd12e62..1eb8d0336d2 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -1146,6 +1146,7 @@ "**/reference/infrastructure-as-code/operator-resources/**", "**/reference/infrastructure-as-code/teleport-resources/**", "**/reference/infrastructure-as-code/terraform-provider/**", + "pages/reference/cli/**", "../CHANGELOG.md" ] } diff --git a/docs/pages/connect-your-client/teleport-clients/teleport-connect.mdx b/docs/pages/connect-your-client/teleport-clients/teleport-connect.mdx index cad0e6ad61c..146528820f0 100644 --- a/docs/pages/connect-your-client/teleport-clients/teleport-connect.mdx +++ b/docs/pages/connect-your-client/teleport-clients/teleport-connect.mdx @@ -694,7 +694,7 @@ Available key codes: ### `tsh ssh` environment variables Under the hood, Teleport Connect uses `tsh ssh` to connect to SSH servers. As a result, -Teleport Connect will respect many [tsh environment variables](../../reference/cli/tsh.mdx#tsh-environment-variables) +Teleport Connect will respect many [tsh environment variables](../../reference/cli/tsh.mdx) related to `tsh ssh`. This can make it easier to share common settings between `tsh` and Teleport Connect. Below is a list of environment variables supported by Teleport Connect for SSH connections: diff --git a/docs/pages/connect-your-client/third-party/putty-winscp.mdx b/docs/pages/connect-your-client/third-party/putty-winscp.mdx index dffcf04a726..4b530f55976 100644 --- a/docs/pages/connect-your-client/third-party/putty-winscp.mdx +++ b/docs/pages/connect-your-client/third-party/putty-winscp.mdx @@ -368,7 +368,3 @@ If this error appears during normal day-to-day operation, this is a bug and shou To remove `tsh` and associated user data see [Uninstalling Teleport](../../installation/uninstall-teleport.mdx). -## Further reading -- [CLI Reference](../../reference/cli/tsh.mdx#tsh-puttyconfig). - - diff --git a/docs/pages/reference/cli/tsh.mdx b/docs/pages/reference/cli/tsh.mdx index 77a45b212a0..21f4e2e0739 100644 --- a/docs/pages/reference/cli/tsh.mdx +++ b/docs/pages/reference/cli/tsh.mdx @@ -1,390 +1,856 @@ --- -title: tsh CLI reference +title: tsh Reference +description: Provides a comprehensive list of commands, arguments, and flags for tsh. sidebar_label: tsh -description: Comprehensive reference of subcommands, flags, and arguments for the tsh CLI tool. tags: - - reference - - platform-wide + - reference + - platform-wide --- +{/*vale messaging = NO*/} -`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. +This guide provides a comprehensive list of commands, arguments, and flags for +tsh: Teleport Command Line Client. -## tsh environment variables +```code +$ tsh [] [ ...] +``` -Environment variables configure your tsh client and can help you avoid using flags repetitively. +Global flags: -| Environment Variable | Description | Example Value | -| - | - | - | -| TELEPORT_AUTH | Any defined [authentication connector](../access-controls/authentication.mdx), 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_RELAY | Address of the Teleport relay server to use, "none" to disable the use of a relay, or "default" to use the default address specified by the control plane at login time. Defaults to port 443. | relay.example.com | -| 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 | +|Flag|Default|Description| +|---|---|---| +|`--auth`|none|Specify the name of authentication connector to use.| +|`--bind-addr`|none|Override host:port used when opening a browser for cluster logins.| +|`--callback`|none|Override the base URL (host:port) of the link shown when opening a browser for cluster logins. Must be used with --bind-addr.| +|`--cert-format`|none|SSH certificate format.| +|`-d`, `--[no-]debug`|`false`|Verbose logging to stdout.| +|`-i`, `--identity`|none|Identity file.| +|`-J`, `--jumphost`|none|SSH jumphost.| +|`-k`, `--add-keys-to-agent`|`auto`|Controls how keys are handled. Valid values are \[auto no yes only\].| +|`-l`, `--login`|none|Remote host login.| +|`--mfa-mode`|`auto`|Preferred mode for MFA and Passwordless assertions (auto, cross-platform, platform, otp, sso).| +|`--mlock`|`auto`|Determines whether process memory will be locked and whether failure to do so will be accepted (off, auto, best_effort, strict).| +|`--[no-]enable-escape-sequences`|`true`|Enable support for SSH escape sequences. Type '~?' during an SSH session to list supported sequences. Default is enabled.| +|`--[no-]headless`|`false`|Use headless login. Shorthand for --auth=headless.| +|`--[no-]insecure`|`false`|Do not verify server's certificate and host name. Use only in test environments.| +|`--[no-]os-log`|`false`|Verbose logging to the unified logging system. This flag implies --debug. Also available through the TELEPORT_OS_LOG env var. More details see https://goteleport.com/docs/connect-your-client/tsh/#debug-logs.| +|`--[no-]skip-version-check`|`false`|Skip version checking between server and client.| +|`--piv-slot`|none|Specify a PIV slot key to use for Hardware Key support instead of the default. Ex: "9d".| +|`--proxy`|none|Teleport proxy address.| +|`--relay`|none|Teleport relay address, "none" to explicitly disable the use of a relay, or "default" to use the cluster-provided address even if a different address was specified at login time.| +|`--ttl`|none|Minutes to live for a session.| +|`--user`|none|Teleport user, defaults to current local user.| -## tsh global flags +Global environment variables: -| 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 | -| `--relay` | none | `host[:port]|none|default` | Address of the Teleport relay server to use, "none" to disable the use of a relay, or "default" to use the default address specified by the control plane at login time. Defaults to port 443. | -| `--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](../access-controls/authentication.mdx), 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. | +|Variable|Default|Description| +|---|---|---| +|`TELEPORT_ADD_KEYS_TO_AGENT`|`auto`|Controls how keys are handled. Valid values are [auto no yes only].| +|`TELEPORT_AUTH`|none|Specify the name of authentication connector to use.| +|`TELEPORT_CLUSTER`|`none`|Name of a Teleport root or leaf cluster| +|`TELEPORT_GLOBAL_TSH_CONFIG`|`none`|Override location of global `tsh` config file from default `/etc/tsh.yaml`| +|`TELEPORT_HEADLESS`|`false`|Use headless login. Shorthand for --auth=headless.| +|`TELEPORT_HOME`|`none`|Home location for tsh configuration and data| +|`TELEPORT_IDENTITY_FILE`|none|Identity file.| +|`TELEPORT_LOGIN`|none|Remote host login.| +|`TELEPORT_LOGIN_BIND_ADDR`|none|Override host:port used when opening a browser for cluster logins.| +|`TELEPORT_MFA_MODE`|`auto`|Preferred mode for MFA and Passwordless assertions (auto, cross-platform, platform, otp, sso).| +|`TELEPORT_MLOCK_MODE`|`auto`|Determines whether process memory will be locked and whether failure to do so will be accepted (off, auto, best_effort, strict).| +|`TELEPORT_PIV_SLOT`|none|Specify a PIV slot key to use for Hardware Key support instead of the default. Ex: "9d".| +|`TELEPORT_PROXY`|none|Teleport proxy address.| +|`TELEPORT_RELAY`|none|Teleport relay address, "none" to explicitly disable the use of a relay, or "default" to use the cluster-provided address even if a different address was specified at login time.| +|`TELEPORT_USER`|none|Teleport user, defaults to current local user.| + +## tsh apps config + +Print app connection information. + +Usage: + +```code +$ tsh apps config [] [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-f`, `--format`|none|Optional print format, one of: "uri" to print app address, "ca" to print CA cert path, "cert" to print cert path, "key" print key path, "curl" to print example curl command, "json" or "yaml" to print everything as JSON or YAML.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|app|none (optional)|App to print information for. Required when logged into multiple apps.| + +## tsh apps login + +Retrieve short-lived certificate for an app. + +Usage: + +```code +$ tsh apps login [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`--aws-role`|none|(For AWS CLI access only) Amazon IAM role ARN or role name.| +|`--azure-identity`|none|(For Azure CLI access only) Azure managed identity name.| +|`--gcp-service-account`|none|(For GCP CLI access only) GCP service account name.| +|`-q`, `--[no-]quiet`|`false`|Quiet mode.| +|`--target-port`|none|Port to which connections made using this cert should be routed to. Valid only for multi-port TCP apps.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|app|none (required)|App name to retrieve credentials for. Can be obtained from `tsh apps ls` output.| + +## tsh apps logout + +Remove app certificate. + +Usage: + +```code +$ tsh apps logout [] +``` + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|app|none (optional)|App to remove credentials for.| ## tsh apps ls -List all available applications: +List available applications. + +Usage: ```code -$ tsh apps ls +$ tsh apps ls [] [] ``` +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-f`, `--format`|`text`|Format output (text, json, yaml).| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| +|`-R`, `--[no-]all`|`false`|List apps from all clusters and proxies.| +|`--search`|none|List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").| +|`-v`, `--[no-]verbose`|`false`|Show extra application fields.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|labels|none (optional)|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| + +## tsh aws + +Access AWS API. + +Usage: + +```code +$ tsh aws [] [...] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`--app`|none|Optional Name of the AWS application to use if logged into multiple.| +|`--aws-role`|none|(For AWS CLI access only) Amazon IAM role ARN or role name.| +|`--exec`|none|Execute different commands (e.g. terraform) under Teleport credentials.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|command|none (optional)|AWS command and subcommands arguments that are going to be forwarded to AWS CLI.| + +## tsh az + +Access Azure API. + +Usage: + +```code +$ tsh az [] [...] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`--app`|none|Optional name of the Azure application to use if logged into multiple.| +|`--azure-identity`|none|(For Azure CLI access only) Azure managed identity name.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|command|none (optional)|`az` command and subcommands arguments that are going to be forwarded to Azure CLI.| + ## tsh clusters +List available Teleport clusters. + +Usage: + ```code $ 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`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -### Examples - -```code -$ tsh clusters - -# Cluster Name Status -# ------------ ------ -# staging online -# production offline - -$ tsh clusters --quiet - -# staging online -# production offline -``` +|Flag|Default|Description| +|---|---|---| +|`-f`, `--format`|`text`|Format output (text, json, yaml).| +|`-q`, `--[no-]quiet`|`false`|Quiet mode.| +|`-v`, `--[no-]verbose`|`false`|Verbose table output, shows full label output.| ## tsh config -Print OpenSSH configuration details to allow using an SSH -client with credentials managed by Teleport to connect to -hosts in your cluster. +Print OpenSSH configuration details. + +Usage: ```code -$ tsh config +$ tsh config [] ``` -### Flags +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. | +|Flag|Default|Description| +|---|---|---| +|`-p`, `--port`|none|SSH port on a remote host.| +## tsh db config -### Examples +Print database connection information. Useful when configuring GUI clients. + +Usage: ```code -# Print OpenSSH config file to console -$ tsh config - -# Append Teleport configuration to ssh config -$ tsh config >> ~/.ssh/config +$ tsh db config [] [] ``` +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-f`, `--format`|none|Print format: "text" to print in table format (default), "cmd" to print connect command, "json" or "yaml" to print in JSON or YAML.| +|`--labels`|none|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|db|none (optional)|Print information for the specified database.| + +## tsh db connect + +Connect to a database. + +Usage: + +```code +$ tsh db connect [] [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`--labels`|none|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| +|`-n`, `--db-name`|none|Database name to log in to.| +|`--[no-]disable-access-request`|`false`|Disable automatic resource Access Requests.| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| +|`-r`, `--db-roles`|none|List of comma separate database roles to use for auto-provisioned user.| +|`--request-reason`|none|Reason for requesting access.| +|`-u`, `--db-user`|none|Database user to log in as.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|db|none (optional)|Database service name to connect to.| + +## tsh db env + +Print environment variables for the configured database. + +Usage: + +```code +$ tsh db env [] [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-f`, `--format`|`text`|Format output (text, json, yaml).| +|`--labels`|none|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|db|none (optional)|Print environment for the specified database.| + +## tsh db exec + +Execute database commands on target database services. + +Usage: + +```code +$ tsh db exec [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`--dbs`|none|List of comma separated target database services. Mutually exclusive with --search or --labels.| +|`--labels`|none|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| +|`-n`, `--db-name`|none|Database name to log in to.| +|`--[no-]confirm`|`true`|Confirm selected database services before executing command.| +|`--output-dir`|none|Directory to store command output per target database service. A summary is saved as "summary.json".| +|`--parallel`|`1`|Run commands on target databases in parallel. Defaults to 1, and maximum allowed is 10.| +|`-r`, `--db-roles`|none|List of comma separate database roles to use for auto-provisioned user.| +|`--search`|none|List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").| +|`-u`, `--db-user`|none|Database user to log in as.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|command|none (required)|Execute this command on target database services.| + +## tsh db login + +Retrieve credentials for a database. + +Usage: + +```code +$ tsh db login [] [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`--labels`|none|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| +|`-n`, `--db-name`|none|Database name to configure as default.| +|`--[no-]disable-access-request`|`false`|Disable automatic resource Access Requests.| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| +|`-r`, `--db-roles`|none|List of comma separate database roles to use for auto-provisioned user.| +|`--request-reason`|none|Reason for requesting access.| +|`-u`, `--db-user`|none|Database user to configure as default.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|db|none (optional)|Database to retrieve credentials for. Can be obtained from 'tsh db ls' output.| + +## tsh db logout + +Remove database credentials. + +Usage: + +```code +$ tsh db logout [] [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`--labels`|none|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|db|none (optional)|Database to remove credentials for.| + +## tsh db ls + +List all available databases. + +Usage: + +```code +$ tsh db ls [] [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-f`, `--format`|`text`|Format output (text, json, yaml).| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| +|`-R`, `--[no-]all`|`false`|List databases from all clusters and proxies.| +|`--search`|none|List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").| +|`-v`, `--[no-]verbose`|`false`|Show extra database fields.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|labels|none (optional)|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| + ## tsh device enroll -Enroll the current device as a trusted device. +Enroll this device as a trusted device. Requires Teleport Enterprise. -Requires a device enrollment token created via `tctl devices enroll`. +Usage: ```code -$ tsh device enroll --token=TOKEN +$ tsh device enroll [] ``` -### Flags +Flags: -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--token` | none | String | Device enrollment token | +|Flag|Default|Description| +|---|---|---| +|`--[no-]current-device`|`false`|Attempts to register and enroll the current device. Requires device admin privileges.| +|`--token`|none|Device enrollment token.| -### Examples +## tsh env + +Print commands to set Teleport session environment variables. + +Usage: ```code -$ tsh device enroll --token=(=devicetrust.enroll_token=) -Device "(=devicetrust.asset_tag=)"/macOS enrolled +$ tsh env [] ``` +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-f`, `--format`|`text`|Format output (text, json, yaml).| +|`--[no-]unset`|`false`|Print commands to clear Teleport session environment variables.| + ## tsh gcloud -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. +Access GCP API with the gcloud command. + +Usage: ```code -$ tsh gcloud [--app] [] +$ tsh gcloud [] [...] ``` -### Arguments +Flags: -`command`: A `gcloud` command to run, including arguments and flags. +|Flag|Default|Description| +|---|---|---| +|`--app`|none|Optional name of the GCP application to use if logged into multiple.| +|`--gcp-service-account`|none|(For GCP CLI access only) GCP service account name.| -### Flags +Arguments: -| 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. | +|Argument|Default|Description| +|---|---|---| +|command|none (optional)|`gcloud` command and subcommands arguments.| -### Global flags +## tsh git clone -These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). +Clone a Git repository. -### Examples +Usage: ```code -$ tsh gcloud compute instances list +$ tsh git clone [] ``` +Arguments: + +|Argument|Default|Description| +|---|---|---| +|directory|none (optional)|The name of a new directory to clone into.| +|repository|none (required)|Git URL of the repository to clone.| + +## tsh git config + +Check Teleport config on the working Git directory. Or provide an action +('update' or 'reset') to configure the Git repo. + +Usage: + +```code +$ tsh git config [] +``` + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|action|none (optional)|Optional action to perform. 'update' to configure the Git repo to proxy Git commands through Teleport. 'reset' to clear Teleport configuration from the Git repo.| + +## tsh git login + +Opens a browser and retrieves your login from GitHub. + +Usage: + +```code +$ tsh git login --github-org=GITHUB-ORG [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`--github-org`|none|GitHub organization.| +|`--[no-]force`|`false`|Force a login.| + +## tsh git ls + +List Git servers. + +Usage: + +```code +$ tsh git ls [] [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-f`, `--format`|`text`|Format output (text, json, yaml).| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| +|`--search`|none|List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|labels|none (optional)|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| + ## tsh gsutil -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. +Access Google Cloud Storage with the gsutil command. + +Usage: ```code -$ tsh gsutil [--app] [] +$ tsh gsutil [] [...] ``` -### Arguments +Flags: -`command`: A `gsutil` command to run, including arguments and flags. +|Flag|Default|Description| +|---|---|---| +|`--app`|none|Optional name of the GCP application to use if logged into multiple.| +|`--gcp-service-account`|none|(For GCP CLI access only) GCP service account name.| -### Flags +Arguments: -| 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. | +|Argument|Default|Description| +|---|---|---| +|command|none (optional)|`gsutil` command and subcommands arguments.| -### Global flags +## tsh headless approve -These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). +Approve a headless authentication request. -### Examples +Usage: ```code -$ tsh gsutil ls +$ tsh headless approve [] [] ``` +Environment variables: + +|Variable|Default|Description| +|---|---|---| +|`TELEPORT_HEADLESS_SKIP_CONFIRM`|`false`|Skip confirmation and prompt for MFA immediately.| + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`--[no-]skip-confirm`|`false`|Skip confirmation and prompt for MFA immediately.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|request id|none (optional)|Headless authentication request ID.| + ## tsh help -Prints help: +Show help. + +Usage: ```code -$ tsh help +$ tsh help [...] ``` +Arguments: + +|Argument|Default|Description| +|---|---|---| +|command|none (optional)|Show help on command.| + ## tsh join -Joins an active session: +Join the active SSH or Kubernetes session. + +Usage: ```code $ tsh join [] ``` -### Arguments +Flags: -`` +|Flag|Default|Description| +|---|---|---| +|`-c`, `--cluster`|none|Specify the Teleport cluster to connect.| +|`-m`, `--mode`|`observer`|Mode of joining the session, valid modes are observer, moderator and peer.| -- `session-id` The UUID of an active Teleport Session obtained by `teleport status` within - the session. +Arguments: -### Flags +|Argument|Default|Description| +|---|---|---| +|session-id|none (required)|ID of the session to join.| -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--cluster` | none | a cluster_name | Specify the cluster to connect | +## tsh kube exec -### Global flags +Execute a command in a Kubernetes pod. -These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -### Examples +Usage: ```code -# join session using teleport user joe as ec2-user -$ tsh --user=joe --login=ec2-user join +$ tsh kube exec [] ... ``` +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-c`, `--container`|none|Container name. If omitted, use the kubectl.kubernetes.io/default-container annotation for selecting the container to be attached or the first container in the pod will be chosen.| +|`-f`, `--filename`|none|To use to exec into the resource.| +|`--invite`|none|A comma separated list of people to mark as invited for the session.| +|`-n`, `--namespace`|none|Configure the default Kubernetes namespace.| +|`--[no-]participant-req`|`false`|Displays a verbose list of required participants in a moderated session.| +|`-q`, `--[no-]quiet`|`false`|Only print output from the remote session.| +|`--reason`|none|The purpose of the session.| +|`-s`, `--[no-]stdin`|`false`|Pass stdin to the container.| +|`-t`, `--[no-]tty`|`false`|Stdin is a TTY.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|command|none (required)|Command to execute in the container.| +|target|none (required)|Pod or deployment name.| + +## tsh kube join + +Join an active Kubernetes session. + +Usage: + +```code +$ tsh kube join [] +``` + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-c`, `--cluster`|none|Specify the Teleport cluster to connect.| +|`-m`, `--mode`|`observer`|Mode of joining the session, valid modes are observer, moderator and peer.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|session|none (required)|The ID of the target session.| + ## tsh kube login -Log into a Kubernetes cluster. Discover connected clusters by using [`tsh kube ls`](#tsh-kube-ls). +Login to a Kubernetes cluster. + +Usage: ```code -$ tsh kube login +$ tsh kube login [] [] ``` -```code -# 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. +Flags: -# On login, kubeconfig is pointed at the first cluster (alphabetically) -$ kubectl config current-context -# aws-gke_bens-demos_us-central1-c_gks-demo +|Flag|Default|Description| +|---|---|---| +|`--as`|none|Configure custom Kubernetes user impersonation.| +|`--as-groups`|none|Configure custom Kubernetes group impersonation.| +|`-c`, `--cluster`|none|Specify the Teleport cluster to connect.| +|`--labels`|none|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| +|`-n`, `--namespace`|none|Configure the default Kubernetes namespace.| +|`--[no-]all`|`false`|Generate a kubeconfig with every cluster the user has access to. Mutually exclusive with --labels or --query.| +|`--[no-]disable-access-request`|`false`|Disable automatic resource Access Requests.| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| +|`--request-reason`|none|Reason for requesting access.| +|`--set-context-name`|`{{.ClusterName}}-{{.KubeName}}`|Define a custom context name. To use it with --all include "\{\{.KubeName\}\}".| -# But all clusters are populated as contexts -$ kubectl config get-contexts +Arguments: -# 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.

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.

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.

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. | +|Argument|Default|Description| +|---|---|---| +|kube-cluster|none (optional)|Name of the Kubernetes cluster to login to. Check 'tsh kube ls' for a list of available clusters.| ## tsh kube ls -List Kubernetes clusters: +Get a list of Kubernetes clusters. + +Usage: ```code -$ tsh kube ls +$ tsh kube ls [] [] ``` -### Examples +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-c`, `--cluster`|none|Specify the Teleport cluster to connect.| +|`-f`, `--format`|`text`|Format output (text, json, yaml).| +|`-q`, `--[no-]quiet`|`false`|Quiet mode.| +|`--query`|none|Query by predicate language enclosed in single quotes. Supports ==, !=, &&, and \|\| (e.g. --query='labels\["key1"\] == "value1" && labels\["key2"\] != "value2"').| +|`-R`, `--[no-]all`|`false`|List Kubernetes clusters from all clusters and proxies.| +|`--search`|none|List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").| +|`-v`, `--[no-]verbose`|`false`|Show an untruncated list of labels.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|labels|none (optional)|List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).| + +## tsh kube sessions + +Get a list of active Kubernetes sessions. (DEPRECATED: use tsh sessions ls +--kind=kube instead.) + +Usage: ```code -$ tsh kube ls - -# Kube Cluster Name Selected -# ------------------------------------- -------- -# gke_bens-demos_us-central1-c_gks-demo * -# microk8s +$ tsh kube sessions [] ``` +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-c`, `--cluster`|none|Specify the Teleport cluster to connect.| +|`-f`, `--format`|`text`|Format output (text, json, yaml).| + +## tsh kubectl + +Runs a kubectl command on a Kubernetes cluster. + +Usage: + +```code +$ tsh kubectl [args...] +``` + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|args|none (optional)|Arbitrary arguments| + +## tsh latency ssh + +Measure latency to a particular SSH host. + +Usage: + +```code +$ tsh latency ssh [] <[user@]host> +``` + +Environment variables: + +|Variable|Default|Description| +|---|---|---| +|`TELEPORT_NO_RESUME`|`false`|Disable SSH connection resumption.| + +Flags: + +|Flag|Default|Description| +|---|---|---| +|`-c`, `--cluster`|none|Specify the Teleport cluster to connect.| +|`--[no-]no-resume`|`false`|Disable SSH connection resumption.| + +Arguments: + +|Argument|Default|Description| +|---|---|---| +|[user@]host|none (required)|Remote hostname and the login to use.| + ## tsh login -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). +Log in to a cluster and retrieve the session certificate. + +Usage: ```code $ tsh login [] [] ``` -### Arguments +Flags: -- `` - the name of the cluster, see [Trusted Cluster](../../zero-trust-access/deploy-a-cluster/trustedclusters.mdx) for more information. +|Flag|Default|Description| +|---|---|---| +|`--browser`|none|Set to 'none' to suppress browser opening on login.| +|`-f`, `--format`|`file`|Identity format: file, openssh (for OpenSSH compatibility) or kubernetes (for kubeconfig).| +|`--kube-cluster`|none|Name of the Kubernetes cluster to login to.| +|`--[no-]overwrite`|`false`|Whether to overwrite the existing identity file.| +|`--[no-]request-nowait`|`false`|Finish without waiting for request resolution.| +|`-o`, `--out`|none|Identity output.| +|`--request-id`|none|Login with the roles requested in the given request.| +|`--request-reason`|none|Reason for requesting additional roles.| +|`--request-reviewers`|none|Suggested reviewers for role request.| +|`--request-roles`|none|Request one or more extra roles.| +|`--scope`|none|Scope pins credentials to a given scope.| +|`-v`, `--[no-]verbose`|`false`|Show extra status information.| -### Flags +Arguments: -| 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`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -A relay address specified (or explicitly disabled with the "none" value) at login time will be stored in the `tsh` configuration directory for the specified proxy; if unspecified, the relay address may fall back to a default value specified by the Teleport control plane. Use of a Relay requires `tsh` v18.3.0 or later. - -### Examples - -*The proxy endpoint can take a https and ssh port in this format `host:https_port[,ssh_proxy_port]`* - -```code -# 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" -``` +|Argument|Default|Description| +|---|---|---| +|cluster|none (optional)|Specify the Teleport cluster to connect.| ## tsh logout -Deletes the client's cluster certificate: +Delete a cluster certificate. + +Usage: ```code $ tsh logout @@ -392,918 +858,831 @@ $ tsh logout ## tsh ls -List cluster nodes: +List remote SSH nodes. + +Usage: ```code -$ tsh ls [] [