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

@@ -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"
   ]
 }

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:

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).
-
-

lib/utils/docenvdefaults/tsh.yaml

@@ -18,11 +18,6 @@ TELEPORT_LOGIN_BIND_ADDR:
   default: "none"
   type: "string"
 
-TELEPORT_LOGIN_BROWSER:
-  description: "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."
-  default: "none"
-  type: "string"
-
 TELEPORT_PROXY:
   description: "Address of the Teleport proxy server"
   default: "none"
@@ -71,4 +66,4 @@ TELEPORT_MFA_MODE:
 TELEPORT_IDENTITY_FILE:
   description: "File path to identity file"
   default: "none"
-  type: "string"
+  type: "string"

lib/utils/docs-usage.md.tmpl

@@ -59,6 +59,7 @@ tags:
   - reference
   - {{if eq .App.Name "tbot"}}mwi{{else}}platform-wide{{end}}
 ---
+{/*vale messaging = NO*/}
 
 This guide provides a comprehensive list of commands, arguments, and flags for
 {{.App.Name}}: {{ if .App.Help -}}

tool/tsh/common/kube.go

@@ -1228,7 +1228,7 @@ func newKubeLoginCommand(parent *kingpin.CmdClause) *kubeLoginCommand {
 		Default(kubeconfig.ContextName("{{.ClusterName}}", "{{.KubeName}}")).
 		StringVar(&c.overrideContextName)
 	c.Flag("request-reason", "Reason for requesting access.").StringVar(&c.requestReason)
-	c.Flag("disable-access-request", "Disable automatic resource access requests.").BoolVar(&c.disableAccessRequest)
+	c.Flag("disable-access-request", "Disable automatic resource Access Requests.").BoolVar(&c.disableAccessRequest)
 
 	return c
 }

tool/tsh/common/tsh.go

@@ -971,8 +971,8 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 	ssh.Flag("reason", "The purpose of the session.").StringVar(&cf.Reason)
 	ssh.Flag("participant-req", "Displays a verbose list of required participants in a moderated session.").BoolVar(&cf.displayParticipantRequirements)
 	ssh.Flag("request-reason", "Reason for requesting access.").StringVar(&cf.RequestReason)
-	ssh.Flag("request-mode", fmt.Sprintf("Type of automatic access request to make (%s).", strings.Join(accessRequestModes, ", "))).Envar(requestModeEnvVar).Default(accessRequestModeResource).EnumVar(&cf.RequestMode, accessRequestModes...)
-	ssh.Flag("disable-access-request", "Disable automatic resource access requests (DEPRECATED: use --request-mode=off).").BoolVar(&cf.disableAccessRequest)
+	ssh.Flag("request-mode", fmt.Sprintf("Type of automatic Access Request to make (%s).", strings.Join(accessRequestModes, ", "))).Envar(requestModeEnvVar).Default(accessRequestModeResource).EnumVar(&cf.RequestMode, accessRequestModes...)
+	ssh.Flag("disable-access-request", "Disable automatic resource Access Requests (DEPRECATED: use --request-mode=off).").BoolVar(&cf.disableAccessRequest)
 	ssh.Flag("log-dir", "Directory to log separated command output, when executing on multiple nodes. If set, output from each node will also be labeled in the terminal.").StringVar(&cf.SSHLogDir)
 	ssh.Flag("no-resume", "Disable SSH connection resumption.").Envar(noResumeEnvVar).BoolVar(&cf.DisableSSHResumption)
 	ssh.Flag("relogin", "Permit performing an authentication attempt on a failed command.").Default("true").BoolVar(&cf.Relogin)
@@ -1089,7 +1089,7 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 	proxyDB.Flag("labels", labelHelp).StringVar(&cf.Labels)
 	proxyDB.Flag("query", queryHelp).StringVar(&cf.PredicateExpression)
 	proxyDB.Flag("request-reason", "Reason for requesting access.").StringVar(&cf.RequestReason)
-	proxyDB.Flag("disable-access-request", "Disable automatic resource access requests.").BoolVar(&cf.disableAccessRequest)
+	proxyDB.Flag("disable-access-request", "Disable automatic resource Access Requests.").BoolVar(&cf.disableAccessRequest)
 
 	proxyApp := proxy.Command("app", "Start local TLS proxy for app connection when using Teleport in single-port mode.")
 	proxyApp.Arg("app", "The name of the application to start local proxy for.").Required().StringVar(&cf.AppName)
@@ -1141,7 +1141,7 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 	dbLogin.Flag("db-name", "Database name to configure as default.").Short('n').StringVar(&cf.DatabaseName)
 	dbLogin.Flag("db-roles", "List of comma separate database roles to use for auto-provisioned user.").Short('r').StringVar(&cf.DatabaseRoles)
 	dbLogin.Flag("request-reason", "Reason for requesting access.").StringVar(&cf.RequestReason)
-	dbLogin.Flag("disable-access-request", "Disable automatic resource access requests.").BoolVar(&cf.disableAccessRequest)
+	dbLogin.Flag("disable-access-request", "Disable automatic resource Access Requests.").BoolVar(&cf.disableAccessRequest)
 	dbLogout := db.Command("logout", "Remove database credentials.")
 	dbLogout.Arg("db", "Database to remove credentials for.").StringVar(&cf.DatabaseService)
 	dbLogout.Flag("labels", labelHelp).StringVar(&cf.Labels)
@@ -1169,7 +1169,7 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 	dbConnect.Flag("labels", labelHelp).StringVar(&cf.Labels)
 	dbConnect.Flag("query", queryHelp).StringVar(&cf.PredicateExpression)
 	dbConnect.Flag("request-reason", "Reason for requesting access.").StringVar(&cf.RequestReason)
-	dbConnect.Flag("disable-access-request", "Disable automatic resource access requests.").BoolVar(&cf.disableAccessRequest)
+	dbConnect.Flag("disable-access-request", "Disable automatic resource Access Requests.").BoolVar(&cf.disableAccessRequest)
 	dbConnect.Flag("tunnel", "Open authenticated tunnel using database's client certificate so clients don't need to authenticate.").Hidden().BoolVar(&cf.LocalProxyTunnel)
 	dbExec := db.Command("exec", "Execute database commands on target database services.")
 	dbExec.Flag("db-user", "Database user to log in as.").Short('u').StringVar(&cf.DatabaseUser)
@@ -1336,9 +1336,9 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 	environment.Flag("format", defaults.FormatFlagDescription(defaults.DefaultFormats...)).Short('f').Default(teleport.Text).EnumVar(&cf.Format, defaults.DefaultFormats...)
 	environment.Flag("unset", "Print commands to clear Teleport session environment variables.").BoolVar(&cf.unsetEnvironment)
 
-	req := app.Command("request", "Manage access requests.").Alias("requests")
+	req := app.Command("request", "Manage Access Requests.").Alias("requests")
 
-	reqList := req.Command("ls", "List access requests.").Alias("list")
+	reqList := req.Command("ls", "List Access Requests.").Alias("list")
 	reqList.Flag("format", defaults.FormatFlagDescription(defaults.DefaultFormats...)).Short('f').Default(teleport.Text).EnumVar(&cf.Format, defaults.DefaultFormats...)
 	reqList.Flag("reviewable", "Only show requests reviewable by current user.").BoolVar(&cf.ReviewableRequests)
 	reqList.Flag("suggested", "Only show requests that suggest current user as reviewer.").BoolVar(&cf.SuggestedRequests)
@@ -1351,18 +1351,18 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 	// Note: The "tsh request new" subcommand should not be used anymore. It
 	// will be kept around for users that built automation around it, but all
 	// public facing documentation should now refer to "tsh request create".
-	reqCreate := req.Command("create", "Create a new access request.").Alias("new")
+	reqCreate := req.Command("create", "Create a new Access Request.").Alias("new")
 	reqCreate.Flag("roles", "Roles to be requested.").StringVar(&cf.DesiredRoles)
 	reqCreate.Flag("reason", "Reason for requesting.").StringVar(&cf.RequestReason)
 	reqCreate.Flag("reviewers", "Suggested reviewers.").StringVar(&cf.SuggestedReviewers)
 	reqCreate.Flag("nowait", "Finish without waiting for request resolution.").BoolVar(&cf.NoWait)
 	reqCreate.Flag("resource", "Resource ID to be requested.").StringsVar(&cf.RequestedResourceIDs)
-	reqCreate.Flag("request-ttl", "Expiration time for the access request.").DurationVar(&cf.RequestTTL)
+	reqCreate.Flag("request-ttl", "Expiration time for the Access Request.").DurationVar(&cf.RequestTTL)
 	reqCreate.Flag("session-ttl", "Expiration time for the elevated certificate.").DurationVar(&cf.SessionTTL)
 	reqCreate.Flag("max-duration", "How long the access should be granted for.").DurationVar(&cf.MaxDuration)
 	reqCreate.Flag("assume-start-time", "Sets time roles can be assumed by requestor (RFC3339 e.g 2023-12-12T23:20:50.52Z).").StringVar(&cf.AssumeStartTimeRaw)
 
-	reqReview := req.Command("review", "Review an access request.")
+	reqReview := req.Command("review", "Review an Access Request.")
 	reqReview.Arg("request-id", "ID of target request.").Required().StringVar(&cf.RequestID)
 	reqReview.Flag("approve", "Review proposes approval.").BoolVar(&cf.Approve)
 	reqReview.Flag("deny", "Review proposes denial.").BoolVar(&cf.Deny)
@@ -1440,7 +1440,7 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 	headlessApprove.Arg("request id", "Headless authentication request ID.").StringVar(&cf.HeadlessAuthenticationID)
 	headlessApprove.Flag("skip-confirm", "Skip confirmation and prompt for MFA immediately.").Envar(headlessSkipConfirmEnvVar).BoolVar(&cf.headlessSkipConfirm)
 
-	reqDrop := req.Command("drop", "Drop one more access requests from current identity.")
+	reqDrop := req.Command("drop", "Drop one more Access Requests from current identity.")
 	reqDrop.Arg("request-id", "IDs of requests to drop (default drops all requests).").Default("*").StringsVar(&cf.RequestIDs)
 	kubectl := app.Command("kubectl", "Runs a kubectl command on a Kubernetes cluster.").Interspersed(false)
 	// This hack is required in order to accept any args for tsh kubectl.