Fix and polish CLI help (#1226)

1. Adds the `mdx.format: md` hint to the generated markdown front matter for Docusarus to avoid issues with the MDX renderer failing on placeholders like "<path>" like we saw on v0.2.1

2. Polishes several of the longer CLI command synopses so they render more consistently on both the CLI help output and in the rendered Markdown. There are minor changes to indentation / line breaks in the CLI output to accommodate markdown rendering (like converting "real" tabs into code blocks) but I don't think it hurts the CLI experience at all. See screenshots below.

3. Stared polishing some of the help text for more consistent language.

Author: danbarr

cmd/help/main.go

@@ -22,6 +22,8 @@ description: %s
 last_update:
   author: autogenerated
 slug: %s
+mdx:
+  format: md
 ---
 
 `

cmd/thv/app/client.go

@@ -34,7 +34,8 @@ var clientRegisterCmd = &cobra.Command{
 	Use:   "register [client]",
 	Short: "Register a client for MCP server configuration",
 	Long: `Register a client for MCP server configuration.
-Valid clients are:
+
+Valid clients:
   - claude-code: Claude Code CLI
   - cline: Cline extension for VS Code
   - cursor: Cursor editor
@@ -51,7 +52,8 @@ var clientRemoveCmd = &cobra.Command{
 	Use:   "remove [client]",
 	Short: "Remove a client from MCP server configuration",
 	Long: `Remove a client from MCP server configuration.
-Valid clients are:
+
+Valid clients:
   - claude-code: Claude Code CLI
   - cline: Cline extension for VS Code
   - cursor: Cursor editor

cmd/thv/app/export.go

@@ -16,10 +16,11 @@ func newExportCmd() *cobra.Command {
 		Short: "Export a workload's run configuration to a file",
 		Long: `Export a workload's run configuration to a file for sharing or backup.
 
-	The exported configuration can be used with 'thv run --from-config <path>' to recreate
-	the same workload with identical settings.
+The exported configuration can be used with 'thv run --from-config <path>' to recreate
+the same workload with identical settings.
+
+Examples:
 
-	Examples:
 	# Export a workload configuration to a file
 	thv export my-server ./my-server-config.json
 

cmd/thv/app/otel.go

@@ -21,10 +21,12 @@ var setOtelEndpointCmd = &cobra.Command{
 	Use:   "set-endpoint <endpoint>",
 	Short: "Set the OpenTelemetry endpoint URL",
 	Long: `Set the OpenTelemetry OTLP endpoint URL for tracing and metrics.
+
 This endpoint will be used by default when running MCP servers unless overridden by the --otel-endpoint flag.
 
 Example:
-  thv config otel set-endpoint https://api.honeycomb.io`,
+
+	thv config otel set-endpoint https://api.honeycomb.io`,
 	Args: cobra.ExactArgs(1),
 	RunE: setOtelEndpointCmdFunc,
 }
@@ -47,10 +49,12 @@ var setOtelSamplingRateCmd = &cobra.Command{
 	Use:   "set-sampling-rate <rate>",
 	Short: "Set the OpenTelemetry sampling rate",
 	Long: `Set the OpenTelemetry trace sampling rate (between 0.0 and 1.0).
+
 This sampling rate will be used by default when running MCP servers unless overridden by the --otel-sampling-rate flag.
 
 Example:
-  thv config otel set-sampling-rate 0.1`,
+
+	thv config otel set-sampling-rate 0.1`,
 	Args: cobra.ExactArgs(1),
 	RunE: setOtelSamplingRateCmdFunc,
 }
@@ -73,10 +77,12 @@ var setOtelEnvVarsCmd = &cobra.Command{
 	Use:   "set-env-vars <var1,var2,...>",
 	Short: "Set the OpenTelemetry environment variables",
 	Long: `Set the list of environment variable names to include in OpenTelemetry spans.
+
 These environment variables will be used by default when running MCP servers unless overridden by the --otel-env-vars flag.
 
 Example:
-  thv config otel set-env-vars USER,HOME,PATH`,
+
+	thv config otel set-env-vars USER,HOME,PATH`,
 	Args: cobra.ExactArgs(1),
 	RunE: setOtelEnvVarsCmdFunc,
 }

cmd/thv/app/proxy.go

@@ -28,46 +28,55 @@ var proxyCmd = &cobra.Command{
 	Use:   "proxy [flags] SERVER_NAME",
 	Short: "Create a transparent proxy for an MCP server with authentication support",
 	Long: `Create a transparent HTTP proxy that forwards requests to an MCP server endpoint.
+
 This command starts a standalone proxy without creating a workload, providing:
 
-• Transparent request forwarding to the target MCP server
-• Optional OAuth/OIDC authentication to remote MCP servers
-• Automatic authentication detection via WWW-Authenticate headers
-• OIDC-based access control for incoming proxy requests
-• Secure credential handling via files or environment variables
+- Transparent request forwarding to the target MCP server
+- Optional OAuth/OIDC authentication to remote MCP servers
+- Automatic authentication detection via WWW-Authenticate headers
+- OIDC-based access control for incoming proxy requests
+- Secure credential handling via files or environment variables
+
+#### Authentication modes
 
-AUTHENTICATION MODES:
 The proxy supports multiple authentication scenarios:
 
 1. No Authentication: Simple transparent forwarding
 2. Outgoing Authentication: Authenticate to remote MCP servers using OAuth/OIDC
 3. Incoming Authentication: Protect the proxy endpoint with OIDC validation
 4. Bidirectional: Both incoming and outgoing authentication
 
-OAUTH CLIENT SECRET SOURCES:
+#### OAuth client secret sources
+
 OAuth client secrets can be provided via (in order of precedence):
+
 1. --remote-auth-client-secret flag (not recommended for production)
 2. --remote-auth-client-secret-file flag (secure file-based approach)
 3. ` + envOAuthClientSecret + ` environment variable
 
-EXAMPLES:
-  # Basic transparent proxy
-  thv proxy my-server --target-uri http://localhost:8080
+#### Examples
+
+Basic transparent proxy:
+
+	thv proxy my-server --target-uri http://localhost:8080
+
+Proxy with OAuth authentication to remote server:
+
+	thv proxy my-server --target-uri https://api.example.com \
+	  --remote-auth --remote-auth-issuer https://auth.example.com \
+	  --remote-auth-client-id my-client-id \
+	  --remote-auth-client-secret-file /path/to/secret
+
+Proxy with OIDC protection for incoming requests:
 
-  # Proxy with OAuth authentication to remote server
-  thv proxy my-server --target-uri https://api.example.com \
-    --remote-auth --remote-auth-issuer https://auth.example.com \
-    --remote-auth-client-id my-client-id \
-    --remote-auth-client-secret-file /path/to/secret
+	thv proxy my-server --target-uri http://localhost:8080 \
+	  --oidc-issuer https://auth.example.com \
+	  --oidc-audience my-audience
 
-  # Proxy with OIDC protection for incoming requests
-  thv proxy my-server --target-uri http://localhost:8080 \
-    --oidc-issuer https://auth.example.com \
-    --oidc-audience my-audience
+Auto-detect authentication requirements:
 
-  # Auto-detect authentication requirements
-  thv proxy my-server --target-uri https://protected-api.com \
-    --remote-auth-client-id my-client-id`,
+	thv proxy my-server --target-uri https://protected-api.com \
+	  --remote-auth-client-id my-client-id`,
 	Args: cobra.ExactArgs(1),
 	RunE: proxyCmdFunc,
 }

cmd/thv/app/run.go

@@ -27,26 +27,34 @@ var runCmd = &cobra.Command{
 ToolHive supports four ways to run an MCP server:
 
 1. From the registry:
-   $ thv run server-name [-- args...]
+
+	   $ thv run server-name [-- args...]
+
    Looks up the server in the registry and uses its predefined settings
    (transport, permissions, environment variables, etc.)
 
 2. From a container image:
-   $ thv run ghcr.io/example/mcp-server:latest [-- args...]
+
+	   $ thv run ghcr.io/example/mcp-server:latest [-- args...]
+
    Runs the specified container image directly with the provided arguments
 
 3. Using a protocol scheme:
-   $ thv run uvx://package-name [-- args...]
-   $ thv run npx://package-name [-- args...]
-   $ thv run go://package-name [-- args...]
-   $ thv run go://./local-path [-- args...]
+
+	   $ thv run uvx://package-name [-- args...]
+	   $ thv run npx://package-name [-- args...]
+	   $ thv run go://package-name [-- args...]
+	   $ thv run go://./local-path [-- args...]
+
    Automatically generates a container that runs the specified package
    using either uvx (Python with uv package manager), npx (Node.js),
    or go (Golang). For Go, you can also specify local paths starting
    with './' or '../' to build and run local Go projects.
 
 4. From an exported configuration:
-   $ thv run --from-config <path>
+
+	   $ thv run --from-config <path>
+
    Runs an MCP server using a previously exported configuration file.
 
 The container will be started with the specified transport mode and

cmd/thv/app/secret.go

@@ -19,7 +19,11 @@ func newSecretCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "secret",
 		Short: "Manage secrets",
-		Long:  "The secret command provides subcommands to set, get, delete, and list secrets.",
+		Long: `Manage secrets using the configured secrets provider.
+
+The secret command provides subcommands to configure, store, retrieve, and manage secrets securely.
+
+Run "thv secret setup" first to configure a secrets provider before using any secret operations.`,
 	}
 
 	cmd.AddCommand(
@@ -38,12 +42,18 @@ func newSecretCommand() *cobra.Command {
 func newSecretProviderCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:   "provider <name>",
-		Short: "Configure the secrets provider directly",
-		Long: `For most users, it is recommended to use "thv secret setup" instead.
-Configure the secrets provider.
-Valid secrets providers are:
-  - encrypted: Full read-write secrets provider
-  - 1password: Read-only secrets provider`,
+		Short: "Set the secrets provider directly",
+		Long: `Configure the secrets provider directly.
+
+Note: The "thv secret setup" command is recommended for interactive configuration.
+
+Use this command to set the secrets provider directly without interactive prompts,
+making it suitable for scripted deployments and automation.
+
+Valid secrets providers:
+  - encrypted: Full read-write secrets provider using AES-256-GCM encryption
+  - 1password: Read-only secrets provider (requires OP_SERVICE_ACCOUNT_TOKEN)
+  - none: Disables secrets functionality`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(_ *cobra.Command, args []string) error {
 			provider := args[0]
@@ -57,15 +67,17 @@ func newSecretSetupCommand() *cobra.Command {
 		Use:   "setup",
 		Short: "Set up secrets provider",
 		Long: fmt.Sprintf(`Interactive setup for configuring a secrets provider.
-This command will guide you through selecting and configuring
-a secrets provider for storing and retrieving secrets.
+
+This command guides you through selecting and configuring a secrets provider
+for storing and retrieving secrets. The setup process validates your
+configuration and ensures the selected provider initializes properly.
 
 Available providers:
-  - %s: Stores secrets in an encrypted file using AES-256-GCM using the OS Keyring
-  - %s: Read-only access to 1Password secrets (requires OP_SERVICE_ACCOUNT_TOKEN)
+  - %s: Stores secrets in an encrypted file using AES-256-GCM using the OS keyring
+  - %s: Read-only access to 1Password secrets (requires OP_SERVICE_ACCOUNT_TOKEN environment variable)
   - %s: Disables secrets functionality
 
-You must run this command before using any other secrets functionality.`,
+Run this command before using any other secrets functionality.`,
 			string(secrets.EncryptedType), string(secrets.OnePasswordType), string(secrets.NoneType)), //nolint:gofmt,gci
 		Args: cobra.NoArgs,
 		RunE: runSecretsSetup,
@@ -76,21 +88,29 @@ func newSecretSetCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:   "set <name>",
 		Short: "Set a secret",
-		Long: `Set a secret with the given name.
-
-Input Methods:
-		- Piped Input: If data is piped to the command, the secret value will be read from stdin.
-		  Examples:
-		    echo "my-secret-value" | thv secret set my-secret
-		    cat secret-file.txt | thv secret set my-secret
-		
-		- Interactive Input: If no data is piped, you will be prompted to enter the secret value securely
-		  (input will be hidden).
-		  Example:
-		    thv secret set my-secret
-		    Enter secret value (input will be hidden): _
-
-The secret will be stored securely using the configured secrets provider.`,
+		Long: `Create or update a secret with the specified name.
+
+This command supports two input methods for maximum flexibility:
+
+Piped input:
+
+When you pipe data to the command, it reads the secret value from stdin.
+Examples:
+
+	$ echo "my-secret-value" | thv secret set my-secret
+	$ cat secret-file.txt | thv secret set my-secret
+
+Interactive input:
+
+When you don't pipe data, the command prompts you to enter the secret value securely.
+The input remains hidden for security.
+Example:
+
+	$ thv secret set my-secret
+	Enter secret value (input will be hidden): _
+
+The command stores the secret securely using your configured secrets provider.
+Note that some providers (like 1Password) are read-only and do not support setting secrets.`,
 		Args: cobra.ExactArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
 			name := args[0]
@@ -166,7 +186,14 @@ func newSecretGetCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:   "get <name>",
 		Short: "Get a secret",
-		Args:  cobra.ExactArgs(1),
+		Long: `Retrieve and display the value of a secret by name.
+
+This command fetches the specified secret from your configured secrets provider
+and displays its value. The secret value prints to stdout, making it
+suitable for use in scripts or command substitution.
+
+The secret must exist in your configured secrets provider, otherwise the command returns an error.`,
+		Args: cobra.ExactArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
 			ctx := cmd.Context()
 			name := args[0]
@@ -197,7 +224,14 @@ func newSecretDeleteCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:   "delete <name>",
 		Short: "Delete a secret",
-		Args:  cobra.ExactArgs(1),
+		Long: `Remove a secret from the configured secrets provider.
+
+This command permanently deletes the specified secret from your secrets provider.
+Once you delete a secret, you cannot recover it unless you have a backup.
+
+Note that some secrets providers may not support deletion operations.
+If your provider is read-only or doesn't support deletion, this command returns an error.`,
+		Args: cobra.ExactArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
 			ctx := cmd.Context()
 			name := args[0]
@@ -235,7 +269,11 @@ func newSecretListCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:   "list",
 		Short: "List all available secrets",
-		Args:  cobra.NoArgs,
+		Long: `Display all secrets available in the configured secrets provider.
+
+This command shows the names of all secrets stored in your secrets provider.
+If descriptions exist for the secrets, the command displays them alongside the names.`,
+		Args: cobra.NoArgs,
 		Run: func(cmd *cobra.Command, _ []string) {
 			ctx := cmd.Context()
 			manager, err := getSecretsManager()
@@ -278,8 +316,23 @@ func newSecretListCommand() *cobra.Command {
 func newSecretResetKeyringCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:   "reset-keyring",
-		Short: "Reset the keyring secret",
-		Args:  cobra.NoArgs,
+		Short: "Reset the keyring password",
+		Long: `Reset the keyring password used to encrypt secrets.
+
+This command resets the master password stored in your OS keyring that
+encrypts and decrypts secrets when using the 'encrypted' secrets provider.
+
+Use this command if:
+  - You've forgotten your keyring password
+  - You want to change your encryption password
+  - Your keyring has become corrupted
+
+Warning: Resetting the keyring password makes any existing encrypted secrets
+inaccessible unless you remember the previous password. You will need to set up
+your secrets again after resetting.
+
+This command only works with the 'encrypted' secrets provider.`,
+		Args: cobra.NoArgs,
 		Run: func(_ *cobra.Command, _ []string) {
 			if err := secrets.ResetKeyringSecret(); err != nil {
 				fmt.Fprintf(os.Stderr, "Failed to reset keyring secret: %v\n", err)