Update docs in CLI help and generated cmd docs (#87)

peteski22 · web-flow · commit 5119e1594595 · 2025-07-18T14:28:38.000+01:00
diff --git a/cmd/add.go b/cmd/add.go
@@ -48,8 +48,8 @@ func NewAddCmd(baseCmd *cmd.BaseCmd, opt ...cmdopts.CmdOption) (*cobra.Command,
 		Use:   "add <server-name>",
 		Short: "Adds an MCP server dependency to the project",
 		Long: "Adds an MCP server dependency to the project. " +
-			"mcpd will search the registry for the named server and attempt to return information " +
-			"on the version specified, or 'latest' if no version specified",
+			"`mcpd` will search the registry for the named server and attempt to return information " +
+			"on the version specified, or 'latest' if no version specified", // TODO: Remove 'latest' reference when we have our own registry
 		RunE: c.run,
 	}
 
@@ -71,14 +71,14 @@ func NewAddCmd(baseCmd *cmd.BaseCmd, opt ...cmdopts.CmdOption) (*cobra.Command,
 		&c.Runtime,
 		"runtime",
 		"",
-		"Optional, specify the runtime of the server package (e.g. uvx, npx)",
+		"Optional, specify the runtime of the server package (e.g. `uvx`, `npx`)",
 	)
 
 	cobraCommand.Flags().StringVar(
 		&c.Source,
 		"source",
 		"",
-		"Optional, specify the source registry of the server package (e.g. mcpm)",
+		"Optional, specify the source registry of the server package (e.g. `mcpm`)",
 	)
 
 	return cobraCommand, nil
diff --git a/cmd/config/args/clear.go b/cmd/config/args/clear.go
@@ -31,9 +31,9 @@ func NewClearCmd(baseCmd *cmd.BaseCmd, opt ...options.CmdOption) (*cobra.Command
 
 	cobraCmd := &cobra.Command{
 		Use:   "clear <server-name>",
-		Short: "Clears configured command line arguments (flags) for an MCP server",
-		Long: "Clears configured command line arguments (flags) for an MCP server, " +
-			"from the runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",
+		Short: "Clears configured command line arguments for an MCP server",
+		Long: "Clears configured command line arguments for an MCP server, " +
+			"from the runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
 		RunE: c.run,
 		Args: cobra.MinimumNArgs(1), // server-name
 	}
diff --git a/cmd/config/args/list.go b/cmd/config/args/list.go
@@ -30,9 +30,9 @@ func NewListCmd(baseCmd *cmd.BaseCmd, opt ...options.CmdOption) (*cobra.Command,
 
 	cobraCmd := &cobra.Command{
 		Use:   "list <server-name>",
-		Short: "Lists the configured command line arguments (flags) for a specific MCP server",
-		Long: "Lists the configured command line arguments (flags) for a specific MCP server, " +
-			"using the runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",
+		Short: "Lists the configured command line arguments for a specific MCP server",
+		Long: "Lists the configured command line arguments for a specific MCP server, " +
+			"using the runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
 		RunE: c.run,
 		Args: cobra.MinimumNArgs(1), // server-name
 	}
diff --git a/cmd/config/args/remove.go b/cmd/config/args/remove.go
@@ -35,9 +35,9 @@ func NewRemoveCmd(baseCmd *cmd.BaseCmd, opt ...options.CmdOption) (*cobra.Comman
 	cobraCmd := &cobra.Command{
 		Use:     "remove <server-name> -- --arg [--arg ...]",
 		Example: "remove time -- --local-timezone",
-		Short:   "Remove command line arguments (flags) for an MCP server",
-		Long: "Remove command line arguments (flags) for a specified MCP server in the " +
-			"runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",
+		Short:   "Remove command line arguments for an MCP server",
+		Long: "Remove command line arguments for a specified MCP server in the " +
+			"runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
 		RunE: c.run,
 		Args: cobra.MinimumNArgs(2), // server-name + --arg ...
 	}
diff --git a/cmd/config/args/set.go b/cmd/config/args/set.go
@@ -31,9 +31,9 @@ func NewSetCmd(baseCmd *cmd.BaseCmd, opt ...cmdopts.CmdOption) (*cobra.Command,
 
 	cobraCmd := &cobra.Command{
 		Use:   "set <server-name> -- --arg=value [--arg=value ...]",
-		Short: "Set startup command line arguments (flags) for an MCP server",
-		Long: "Set startup command line arguments (flags) for an MCP server in the " +
-			"runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",
+		Short: "Set startup command line arguments for an MCP server",
+		Long: "Set startup command line arguments for an MCP server in the " +
+			"runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
 		RunE: c.run,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if cmd.ArgsLenAtDash() < 1 || strings.TrimSpace(args[0]) == "" {
diff --git a/cmd/config/env/clear.go b/cmd/config/env/clear.go
@@ -33,7 +33,7 @@ func NewClearCmd(baseCmd *cmd.BaseCmd, opt ...options.CmdOption) (*cobra.Command
 		Use:   "clear <server-name>",
 		Short: "Clears configured environment variables for an MCP server",
 		Long: "Clears environment variables for a specified MCP server from the " +
-			"runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",
+			"runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
 		RunE: c.run,
 		Args: cobra.MinimumNArgs(1), // server-name
 	}
diff --git a/cmd/config/env/list.go b/cmd/config/env/list.go
@@ -36,7 +36,7 @@ func NewListCmd(baseCmd *cmd.BaseCmd, opt ...options.CmdOption) (*cobra.Command,
 		Use:   "list <server-name>",
 		Short: "Lists configured environment variables for a specific MCP server",
 		Long: "Lists configured environment variables for a specific MCP server, using the " +
-			"runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",
+			"runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
 		RunE: c.run,
 		Args: cobra.MinimumNArgs(1), // server-name
 	}
diff --git a/cmd/config/env/remove.go b/cmd/config/env/remove.go
@@ -36,7 +36,7 @@ func NewRemoveCmd(baseCmd *cmd.BaseCmd, opt ...options.CmdOption) (*cobra.Comman
 		Use:   "remove <server-name> KEY [KEY ...]",
 		Short: "Remove environment variables for an MCP server",
 		Long: "Remove environment variables for a specified MCP server in the " +
-			"runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",
+			"runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
 		RunE: c.run,
 		Args: cobra.MinimumNArgs(2), // server-name + KEY ...
 	}
diff --git a/cmd/config/env/set.go b/cmd/config/env/set.go
@@ -34,7 +34,7 @@ func NewSetCmd(baseCmd *cmd.BaseCmd, opt ...options.CmdOption) (*cobra.Command,
 		Use:   "set <server-name> KEY=VALUE [KEY=VALUE ...]",
 		Short: "Set or update environment variables for an MCP server",
 		Long: "Set or update environment variables for a specified MCP server in the " +
-			"runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",
+			"runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
 		RunE: c.run,
 		Args: cobra.MinimumNArgs(2), // server_name and KEY=VALUE
 	}
diff --git a/cmd/config/export/export.go b/cmd/config/export/export.go
@@ -67,22 +67,19 @@ func NewCmd(baseCmd *cmd.BaseCmd, opt ...options.CmdOption) (*cobra.Command, err
 }
 
 func (c *Cmd) longDescription() string {
-	return `Exports current configuration, generating a pair of safe and portable configuration files.
-	
-Using a project's required configuration (e.g. .mcpd.toml) and the locally configured runtime values from the execution context file (e.g. ~/.config/mcpd/secrets.dev.toml), the export command outputs two files:
-	
-Environment Contract:
-	- Lists all required and configured environment variables as secure, namespaced placeholders
-	  e.g. MCPD__{SERVER_NAME}__{ENV_VAR}
-	- Creates placeholders for command line arguments to be populated with env vars
-	  e.g. MCPD__{SERVER_NAME}__ARG_{ARG_NAME}
-	- This file is intended for the platform operator or CI/CD system
-	
-Portable Execution Context:
-	- A new secrets .toml file that defines sanitized runtime args and env sections for each server using the placeholders aligned with the environment contract
-	- These files are safe to check into version control if required.
-
-"This allows running an mcpd project in any environment, cleanly separating the configuration structure from the secret values`
+	return "Exports current configuration, generating a pair of safe and portable configuration files.\n\n" +
+		"Using a project's required configuration (e.g. `.mcpd.toml`) and the locally configured runtime values from the " +
+		"execution context file (e.g. `~/.config/mcpd/secrets.dev.toml`), the export command outputs two files:\n\n" +
+		"Environment Contract:\n\n" +
+		"Lists all required and configured environment variables as secure, namespaced placeholders:\n\n" +
+		"`MCPD__{SERVER_NAME}__{ENV_VAR}` - Creates placeholders for command line arguments to be populated with env vars\n\n" +
+		"`MCPD__{SERVER_NAME}__ARG_{ARG_NAME}` - This file is intended for the platform operator or CI/CD system\n\n" +
+		"Portable Execution Context:\n\n" +
+		"- A new secrets `.toml` file that defines sanitized runtime args and env sections for each server using the " +
+		"placeholders aligned with the environment contract\n" +
+		"- These files are safe to check into version control if required.\n\n" +
+		"This allows running an mcpd project in any environment, cleanly separating the configuration structure " +
+		"from the secret values"
 }
 
 func (c *Cmd) run(cmd *cobra.Command, args []string) error {
diff --git a/cmd/daemon.go b/cmd/daemon.go
@@ -43,8 +43,8 @@ func NewDaemonCmd(baseCmd *cmd.BaseCmd, opt ...cmdopts.CmdOption) (*cobra.Comman
 
 	cobraCommand := &cobra.Command{
 		Use:   "daemon [--dev] [--addr]",
-		Short: "Launches an mcpd daemon instance",
-		Long:  "Launches an mcpd daemon instance, which starts MCP servers and provides routing via HTTP API",
+		Short: "Launches an `mcpd` daemon instance",
+		Long:  "Launches an `mcpd` daemon instance, which starts MCP servers and provides routing via HTTP API",
 		RunE:  c.run,
 	}
 
diff --git a/cmd/init.go b/cmd/init.go
@@ -31,7 +31,7 @@ func NewInitCmd(baseCmd *cmd.BaseCmd, opt ...cmdopts.CmdOption) (*cobra.Command,
 
 	cobraCommand := &cobra.Command{
 		Use:   "init",
-		Short: "Initializes the current directory as an mcpd project",
+		Short: "Initializes the current directory as an `mcpd` project",
 		Long:  c.longDescription(),
 		RunE:  c.run,
 	}
@@ -40,14 +40,14 @@ func NewInitCmd(baseCmd *cmd.BaseCmd, opt ...cmdopts.CmdOption) (*cobra.Command,
 }
 
 func (c *InitCmd) longDescription() string {
-	return fmt.Sprintf(`Initializes the current directory as an mcpd project, creating a %s configuration file.
-
-This command sets up the basic structure required for an mcpd project.
-
-The configuration file path can be overridden using the '--%s' flag or the '%s' environment variable`,
+	return fmt.Sprintf(
+		"Initializes the current directory as an `mcpd` project, creating a %s configuration file.\n\n"+
+			"This command sets up the basic structure required for an `mcpd` project.\n\n"+
+			"The configuration file path can be overridden using the `--%s` flag or the `%s` environment variable",
 		flags.DefaultConfigFile,
 		flags.FlagNameConfigFile,
-		flags.EnvVarConfigFile)
+		flags.EnvVarConfigFile,
+	)
 }
 
 func (c *InitCmd) run(cmd *cobra.Command, _ []string) error {
diff --git a/cmd/remove.go b/cmd/remove.go
@@ -33,19 +33,13 @@ func NewRemoveCmd(baseCmd *cmd.BaseCmd, opt ...cmdopts.CmdOption) (*cobra.Comman
 	cobraCommand := &cobra.Command{
 		Use:   "remove <server-name>",
 		Short: "Removes an MCP server dependency from the project",
-		Long:  c.longDescription(),
+		Long:  "Removes an MCP server dependency from the project",
 		RunE:  c.run,
 	}
 
 	return cobraCommand, nil
 }
 
-// longDescription returns the long version of the command description.
-func (c *RemoveCmd) longDescription() string {
-	return `Removes an MCP server dependency from the project config file.
-Specify the server name to remove it`
-}
-
 // run is configured (via NewRemoveCmd) to be called by the Cobra framework when the command is executed.
 // It may return an error (or nil, when there is no error).
 func (c *RemoveCmd) run(cmd *cobra.Command, args []string) error {
diff --git a/cmd/root.go b/cmd/root.go
@@ -41,8 +41,8 @@ func Execute() error {
 func NewRootCmd(c *RootCmd) (*cobra.Command, error) {
 	rootCmd := &cobra.Command{
 		Use:   "mcpd",
-		Short: "'mcpd' CLI is the primary interface for developers to interact with mcpd",
-		Long: "The 'mcpd' CLI is the primary interface for developers to interact with the mcpd Control Plane, " +
+		Short: "`mcpd` CLI is the primary interface for developers to interact with, and configure `mcpd`",
+		Long: "The `mcpd` CLI is the primary interface for developers to interact with `mcpd` " +
 			"define their agent projects, and manage MCP server dependencies",
 		SilenceUsage:  true,
 		SilenceErrors: true,
diff --git a/cmd/search.go b/cmd/search.go
@@ -52,7 +52,7 @@ func NewSearchCmd(baseCmd *internalcmd.BaseCmd, opt ...cmdopts.CmdOption) (*cobr
 		Use:   "search [server-name]",
 		Short: "Searches all configured registries for matching MCP servers",
 		Long: fmt.Sprintf("Searches all configured registries for matching MCP servers, "+
-			"the wildcard '%s' is the default when name is not specified. "+
+			"when name is not specified, the wildcard character (`%s`) is used. "+
 			"Returns aggregated results from all configured registries", options.WildcardCharacter),
 		RunE: c.run,
 	}

Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@ func NewClearCmd(baseCmd cmd.BaseCmd, opt ...options.CmdOption) (cobra.Command`
`33`	`33`	`Use: "clear <server-name>",`
`34`	`34`	`Short: "Clears configured environment variables for an MCP server",`
`35`	`35`	`Long: "Clears environment variables for a specified MCP server from the " +`
`36`		`- "runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",`
	`36`	+ "runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
`37`	`37`	`RunE: c.run,`
`38`	`38`	`Args: cobra.MinimumNArgs(1), // server-name`
`39`	`39`	`}`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ func NewListCmd(baseCmd cmd.BaseCmd, opt ...options.CmdOption) (cobra.Command,`
`36`	`36`	`Use: "list <server-name>",`
`37`	`37`	`Short: "Lists configured environment variables for a specific MCP server",`
`38`	`38`	`Long: "Lists configured environment variables for a specific MCP server, using the " +`
`39`		`- "runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",`
	`39`	+ "runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
`40`	`40`	`RunE: c.run,`
`41`	`41`	`Args: cobra.MinimumNArgs(1), // server-name`
`42`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ func NewRemoveCmd(baseCmd cmd.BaseCmd, opt ...options.CmdOption) (cobra.Comman`
`36`	`36`	`Use: "remove <server-name> KEY [KEY ...]",`
`37`	`37`	`Short: "Remove environment variables for an MCP server",`
`38`	`38`	`Long: "Remove environment variables for a specified MCP server in the " +`
`39`		`- "runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",`
	`39`	+ "runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
`40`	`40`	`RunE: c.run,`
`41`	`41`	`Args: cobra.MinimumNArgs(2), // server-name + KEY ...`
`42`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,7 @@ func NewSetCmd(baseCmd cmd.BaseCmd, opt ...options.CmdOption) (cobra.Command,`
`34`	`34`	`Use: "set <server-name> KEY=VALUE [KEY=VALUE ...]",`
`35`	`35`	`Short: "Set or update environment variables for an MCP server",`
`36`	`36`	`Long: "Set or update environment variables for a specified MCP server in the " +`
`37`		`- "runtime context configuration file (e.g. ~/.config/mcpd/secrets.dev.toml)",`
	`37`	+ "runtime context configuration file (e.g. `~/.config/mcpd/secrets.dev.toml`)",
`38`	`38`	`RunE: c.run,`
`39`	`39`	`Args: cobra.MinimumNArgs(2), // server_name and KEY=VALUE`
`40`	`40`	`}`