feat: add Long descriptions and Examples to all CLI commands (#494)

Add detailed Long descriptions and usage Examples to every Cobra command definition. This improves the built-in help output and provides the source material for auto-generated CLI reference documentation.

Author: reubeno

internal/app/azldev/app.go

@@ -106,9 +106,15 @@ func NewApp(fsFactory opctx.FileSystemFactory, osEnvFactory opctx.OSEnvFactory)
 
 	// Define the top-level command for the CLI.
 	app.cmd = cobra.Command{
-		Use:     "azldev",
-		Short:   usageInfo,
-		Long:    usageInfo,
+		Use:   "azldev",
+		Short: usageInfo,
+		Long: `Azure Linux Dev Tool (azldev) manages Azure Linux projects, components,
+images, and builds. It provides a unified CLI for the full development
+workflow: creating projects, importing and building RPM packages,
+customizing images, and more.
+
+Run azldev from the root of an Azure Linux project (where azldev.toml
+lives), or use -C to point to one.`,
 		Version: displayVersion,
 		PersistentPreRunE: func(command *cobra.Command, _ []string) error {
 			slog.Debug("Command annotations", "annotations", command.Annotations)

internal/app/azldev/cmds/advanced/advanced.go

@@ -14,7 +14,12 @@ func OnAppInit(app *azldev.App) {
 		Use:     "advanced",
 		Aliases: []string{"adv"},
 		Short:   "Advanced operations",
-		Hidden:  true,
+		Long: `Advanced operations for power users and automation.
+
+These commands provide low-level access to mock, MCP server mode,
+and direct file downloads. They are hidden from the default help
+output but fully supported.`,
+		Hidden: true,
 	}
 
 	app.AddTopLevelCommand(cmd)

internal/app/azldev/cmds/advanced/mcp.go

@@ -21,6 +21,13 @@ func NewMCPCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "mcp",
 		Short: "Run in MCP server mode",
+		Long: `Start azldev as a Model Context Protocol (MCP) server.
+
+In this mode, azldev communicates over stdin/stdout using the MCP protocol,
+exposing selected commands as tools that can be invoked by AI coding agents
+and other MCP clients.`,
+		Example: `  # Start the MCP server
+  azldev advanced mcp`,
 		RunE: (func(cmd *cobra.Command, args []string) error {
 			env, err := azldev.GetEnvFromCommand(cmd)
 			if err != nil {

internal/app/azldev/cmds/advanced/mock.go

@@ -23,6 +23,10 @@ func NewMockCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "mock",
 		Short: "Run RPM mock tool",
+		Long: `Run RPM mock tool commands directly.
+
+Provides low-level access to mock for building RPMs from SRPMs and
+starting interactive shell sessions in mock chroot environments.`,
 	}
 
 	cmd.AddCommand(NewBuildRPMCmd())
@@ -58,6 +62,16 @@ func NewBuildRPMCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "build-rpms",
 		Short: "Use mock to build an RPM",
+		Long: `Build binary RPMs from a source RPM using mock.
+
+This is a low-level command that invokes mock directly with the given
+SRPM and configuration. For most use cases, prefer 'azldev component build'
+which handles source preparation and overlay application automatically.`,
+		Example: `  # Build from an SRPM
+  azldev advanced mock build-rpms --srpm ./my-package.src.rpm -o ./rpms/
+
+  # Build with a custom mock config
+  azldev advanced mock build-rpms -c my-mock.cfg --srpm ./my-package.src.rpm -o ./rpms/`,
 		RunE: azldev.RunFuncWithoutRequiredConfig(func(env *azldev.Env) (results interface{}, err error) {
 			return BuildRPMS(env, options)
 		}),
@@ -94,6 +108,22 @@ func NewShellCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "shell",
 		Short: "Enter mock shell",
+		Long: `Start an interactive shell inside a mock chroot environment.
+
+This is useful for inspecting built RPMs, debugging package issues, or
+running smoke tests. Packages can be pre-installed into the chroot using
+--add-package. Extra arguments after -- are passed to the shell command.`,
+		Example: `  # Open a mock shell
+  azldev advanced mock shell
+
+  # Open a shell with packages pre-installed
+  azldev advanced mock shell --add-package /path/to/my-package.rpm
+
+  # Open a shell with network access
+  azldev advanced mock shell --enable-network
+
+  # Run a command inside the mock shell
+  azldev advanced mock shell -- rpm -qa`,
 		RunE: azldev.RunFuncWithoutRequiredConfigWithExtraArgs(
 			func(env *azldev.Env, extraArgs []string) (results interface{}, err error) {
 				return true, RunShell(env, options, extraArgs)

internal/app/azldev/cmds/advanced/wget.go

@@ -29,6 +29,12 @@ func NewWgetCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "wget URI",
 		Short: "Download files via https",
+		Long: `Download a file from an HTTPS URI to a local path.
+
+This is a simple download utility that respects azldev's network retry
+configuration. It is primarily used internally but can be invoked directly.`,
+		Example: `  # Download a file
+  azldev advanced wget --uri https://example.com/file.tar.gz -o ./file.tar.gz`,
 		RunE: azldev.RunFuncWithoutRequiredConfig(func(env *azldev.Env) (results interface{}, err error) {
 			return true, Download(env, options)
 		}),

internal/app/azldev/cmds/component/add.go

@@ -32,6 +32,16 @@ func NewComponentAddCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "add",
 		Short: "Add component(s) to this project",
+		Long: `Add one or more components to the project configuration.
+
+Each component name is added as a bare entry in the root config file,
+inheriting defaults from the distro configuration. If a component with
+the same name already exists, the command returns an error.`,
+		Example: `  # Add a single component
+  azldev component add curl
+
+  # Add multiple components at once
+  azldev component add curl wget bash`,
 		RunE: azldev.RunFuncWithExtraArgs(func(env *azldev.Env, args []string) (interface{}, error) {
 			return true, AddComponentsToConfig(env.FS(), env.Config(), options, args)
 		}),

internal/app/azldev/cmds/component/build.go

@@ -62,6 +62,26 @@ func NewBuildCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "build",
 		Short: "Build packages for components",
+		Long: `Build RPM packages for one or more components using mock.
+
+This command fetches upstream sources (applying any configured overlays),
+creates an SRPM, and invokes mock to produce binary RPMs. Built packages
+are placed in the project's output directory.
+
+Use --local-repo-with-publish to build a chain of dependent components:
+each component's RPMs are published to a local repository that subsequent
+builds can consume.`,
+		Example: `  # Build a single component
+  azldev component build -p curl
+
+  # Build all components, continuing past failures
+  azldev component build -a -k
+
+  # Build SRPM only (skip binary RPM build)
+  azldev component build -p curl --srpm-only
+
+  # Chain-build dependent components with a local repo
+  azldev component build --local-repo-with-publish ./base/out -p liba -p libb`,
 		RunE: azldev.RunFuncWithExtraArgs(func(env *azldev.Env, args []string) (interface{}, error) {
 			options.ComponentFilter.ComponentNamePatterns = append(options.ComponentFilter.ComponentNamePatterns, args...)
 

internal/app/azldev/cmds/component/component.go

@@ -14,6 +14,12 @@ func OnAppInit(app *azldev.App) {
 		Use:     "component",
 		Aliases: []string{"comp"},
 		Short:   "Manage components",
+		Long: `Manage components in an Azure Linux project.
+
+Components are the primary unit of packaging — each corresponds to exactly one
+RPM spec file. Building a component results in producing one or more RPM packages.
+Use subcommands to add, list, query, build, and prepare sources for
+components defined in the project configuration.`,
 	}
 
 	app.AddTopLevelCommand(cmd)

internal/app/azldev/cmds/component/list.go

@@ -30,6 +30,21 @@ func NewComponentListCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List components in this project",
+		Long: `List components defined in the project configuration.
+
+By default only matching components are shown. Use -a to list all components.
+Component name patterns support glob syntax (*, ?, []).`,
+		Example: `  # List all components
+  azldev component list -a
+
+  # List a specific component
+  azldev component list -p curl
+
+  # List components matching a pattern
+  azldev component list -p "azure*"
+
+  # Output as JSON for scripting
+  azldev component list -a -q -O json`,
 		RunE: azldev.RunFuncWithExtraArgs(func(env *azldev.Env, args []string) (interface{}, error) {
 			options.ComponentFilter.ComponentNamePatterns = append(args, options.ComponentFilter.ComponentNamePatterns...)
 

internal/app/azldev/cmds/component/preparesources.go

@@ -34,6 +34,19 @@ func NewPrepareSourcesCmd() *cobra.Command {
 		Use:     "prepare-sources",
 		Aliases: []string{"prep-sources"},
 		Short:   "Prepare buildable sources for components",
+		Long: `Prepare buildable sources for a component by fetching the upstream spec and
+source files, then applying any configured overlays.
+
+The result is a directory containing the spec file and all sources, ready
+for inspection or manual building. This is useful for verifying that
+overlays apply cleanly before running a full build.
+
+Only one component may be selected at a time.`,
+		Example: `  # Prepare sources for a component
+  azldev component prep-sources -p curl -o ./build/work/scratch/curl --force
+
+  # Prepare without applying overlays (raw upstream sources)
+  azldev component prep-sources -p curl -o ./build/work/scratch/curl --skip-overlays --force`,
 		RunE: azldev.RunFuncWithExtraArgs(func(env *azldev.Env, args []string) (interface{}, error) {
 			options.ComponentFilter.ComponentNamePatterns = append(args, options.ComponentFilter.ComponentNamePatterns...)