updated/standardize command descriptions (#313)

* initial desc formatting/updates
* fixed typos
* updated commands base on feedback
* more updates based on feedback

---------

Signed-off-by: Zack Brady <zackbrady123@gmail.com>

cmd/hauler/cli/completion.go

@@ -10,8 +10,7 @@ import (
 func addCompletion(parent *cobra.Command) {
 	cmd := &cobra.Command{
 		Use:   "completion",
-		Short: "Generates completion scripts for various shells",
-		Long:  `The completion sub-command generates completion scripts for various shells.`,
+		Short: "Generate auto-completion scripts for various shells",
 	}
 
 	cmd.AddCommand(
@@ -27,8 +26,7 @@ func addCompletion(parent *cobra.Command) {
 func addCompletionZsh() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "zsh",
-		Short: "Generates zsh completion scripts",
-		Long:  `The completion sub-command generates completion scripts for zsh.`,
+		Short: "Generates auto-completion scripts for zsh",
 		Example: `To load completion run
 
 	. <(hauler completion zsh)
@@ -57,8 +55,7 @@ func addCompletionZsh() *cobra.Command {
 func addCompletionBash() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "bash",
-		Short: "Generates bash completion scripts",
-		Long:  `The completion sub-command generates completion scripts for bash.`,
+		Short: "Generates auto-completion scripts for bash",
 		Example: `To load completion run
 
 	. <(hauler completion bash)
@@ -77,8 +74,7 @@ func addCompletionBash() *cobra.Command {
 func addCompletionFish() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "fish",
-		Short: "Generates fish completion scripts",
-		Long:  `The completion sub-command generates completion scripts for fish.`,
+		Short: "Generates auto-completion scripts for fish",
 		Example: `To configure your fish shell to load completions for each session write this script to your completions dir:
 
 	hauler completion fish > ~/.config/fish/completions/hauler.fish
@@ -94,8 +90,7 @@ func addCompletionFish() *cobra.Command {
 func addCompletionPowershell() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "powershell",
-		Short: "Generates powershell completion scripts",
-		Long:  `The completion sub-command generates completion scripts for powershell.`,
+		Short: "Generates auto-completion scripts for powershell",
 		Example: `To load completion run
 
 	. <(hauler completion powershell)

cmd/hauler/cli/login.go

@@ -18,12 +18,11 @@ func addLogin(parent *cobra.Command) {
 	o := &flags.LoginOpts{}
 
 	cmd := &cobra.Command{
-		Use:   "login",
-		Short: "Log in to a registry",
-		Example: `
-# Log in to reg.example.com
-hauler login reg.example.com -u bob -p haulin`,
-		Args: cobra.ExactArgs(1),
+		Use:     "login",
+		Short:   "Login to a registry",
+		Long:    "Login to an OCI Compliant Registry (stored at ~/.docker/config.json)",
+		Example: "# login to registry.example.com\nhauler login registry.example.com -u bob -p haulin",
+		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, arg []string) error {
 			ctx := cmd.Context()
 

cmd/hauler/cli/store.go

@@ -16,7 +16,7 @@ func addStore(parent *cobra.Command) {
 	cmd := &cobra.Command{
 		Use:     "store",
 		Aliases: []string{"s"},
-		Short:   "Interact with hauler's embedded content store",
+		Short:   "Interact with the content store",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return cmd.Help()
 		},
@@ -31,8 +31,6 @@ func addStore(parent *cobra.Command) {
 		addStoreServe(),
 		addStoreInfo(),
 		addStoreCopy(),
-
-		// TODO: Remove this in favor of sync?
 		addStoreAdd(),
 	)
 
@@ -44,7 +42,7 @@ func addStoreExtract() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "extract",
-		Short:   "Extract content from the store to disk",
+		Short:   "Extract artifacts from the content store to disk",
 		Aliases: []string{"x"},
 		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -68,7 +66,7 @@ func addStoreSync() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "sync",
-		Short: "Sync content to the embedded content store",
+		Short: "Sync content to the content store",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
@@ -112,7 +110,7 @@ func addStoreLoad() *cobra.Command {
 func addStoreServe() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "serve",
-		Short: "Expose the content of a local store through an OCI compliant registry or file server",
+		Short: "Serve the content store via an OCI Compliant Registry or Fileserver",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return cmd.Help()
 		},
@@ -125,12 +123,12 @@ func addStoreServe() *cobra.Command {
 	return cmd
 }
 
-// RegistryCmd serves the embedded registry
+// RegistryCmd serves the registry
 func addStoreServeRegistry() *cobra.Command {
 	o := &flags.ServeRegistryOpts{StoreRootOpts: rootStoreOpts}
 	cmd := &cobra.Command{
 		Use:   "registry",
-		Short: "Serve the embedded registry",
+		Short: "Serve the OCI Compliant Registry",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
@@ -153,7 +151,7 @@ func addStoreServeFiles() *cobra.Command {
 	o := &flags.ServeFilesOpts{StoreRootOpts: rootStoreOpts}
 	cmd := &cobra.Command{
 		Use:   "fileserver",
-		Short: "Serve the file server",
+		Short: "Serve the Fileserver",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
@@ -231,7 +229,7 @@ func addStoreCopy() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "copy",
-		Short: "Copy all store contents to another OCI registry",
+		Short: "Copy all store content to another location",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
@@ -252,7 +250,7 @@ func addStoreCopy() *cobra.Command {
 func addStoreAdd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "add",
-		Short: "Add content to store",
+		Short: "Add content to the store",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return cmd.Help()
 		},
@@ -272,8 +270,16 @@ func addStoreAddFile() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "file",
-		Short: "Add a file to the content store",
-		Args:  cobra.ExactArgs(1),
+		Short: "Add a file to the store",
+		Example: `# fetch local file
+hauler store add file file.txt
+
+# fetch remote file
+hauler store add file https://get.rke2.io/install.sh
+
+# fetch remote file and assign new name
+hauler store add file https://get.hauler.dev --name hauler-install.sh`,
+		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
@@ -295,8 +301,22 @@ func addStoreAddImage() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "image",
-		Short: "Add an image to the content store",
-		Args:  cobra.ExactArgs(1),
+		Short: "Add a image to the store",
+		Example: `# fetch image
+hauler store add image busybox
+
+# fetch image with repository and tag
+hauler store add image library/busybox:stable
+
+# fetch image with full image reference and specific platform
+hauler store add image ghcr.io/hauler-dev/hauler-debug:v1.0.7 --platform linux/amd64
+
+# fetch image with full image reference via digest
+hauler store add image gcr.io/distroless/base@sha256:7fa7445dfbebae4f4b7ab0e6ef99276e96075ae42584af6286ba080750d6dfe5
+
+# fetch image with full image reference, specific platform, and signature verification
+hauler store add image rgcrprod.azurecr.us/hauler/rke2-manifest.yaml:v1.28.12-rke2r1 --platform linux/amd64 --key carbide-key.pub`,
+		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
@@ -321,20 +341,24 @@ func addStoreAddChart() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "chart",
-		Short: "Add a local or remote chart to the content store",
-		Example: `
-# add a local chart
-hauler store add chart path/to/chart/directory
+		Short: "Add a helm chart to the store",
+		Example: `# fetch local helm chart
+hauler store add chart path/to/chart/directory --repo .
+
+# fetch local compressed helm chart
+hauler store add chart path/to/chart.tar.gz --repo .
+
+# fetch remote oci helm chart
+hauler store add chart hauler-helm --repo oci://ghcr.io/hauler-dev
 
-# add a local compressed chart
-hauler store add chart path/to/chart.tar.gz
+# fetch remote oci helm chart with version
+hauler store add chart hauler-helm --repo oci://ghcr.io/hauler-dev --version 1.0.6
 
-# add a remote chart
-hauler store add chart longhorn --repo "https://charts.longhorn.io"
+# fetch remote helm chart
+hauler store add chart rancher --repo https://releases.rancher.com/server-charts/stable
 
-# add a specific version of a chart
-hauler store add chart rancher --repo "https://releases.rancher.com/server-charts/latest" --version "2.6.2"
-`,
+# fetch remote helm chart with specific version
+hauler store add chart rancher --repo https://releases.rancher.com/server-charts/latest --version 2.9.1`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

internal/flags/add.go

@@ -14,8 +14,8 @@ type AddImageOpts struct {
 
 func (o *AddImageOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
-	f.StringVarP(&o.Key, "key", "k", "", "(Optional) Path to the key for digital signature verification")
-	f.StringVarP(&o.Platform, "platform", "p", "", "(Optional) Specific platform to save. i.e. linux/amd64. Defaults to all if flag is omitted.")
+	f.StringVarP(&o.Key, "key", "k", "", "(Optional) Location of public key to use for signature verification")
+	f.StringVarP(&o.Platform, "platform", "p", "", "(Optional) Specifiy the platform of the image... i.e. linux/amd64 (defaults to all)")
 }
 
 type AddFileOpts struct {
@@ -25,7 +25,7 @@ type AddFileOpts struct {
 
 func (o *AddFileOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
-	f.StringVarP(&o.Name, "name", "n", "", "(Optional) Name to assign to file in store")
+	f.StringVarP(&o.Name, "name", "n", "", "(Optional) Rewrite the name of the file")
 }
 
 type AddChartOpts struct {
@@ -37,13 +37,13 @@ type AddChartOpts struct {
 func (o *AddChartOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
 
-	f.StringVar(&o.ChartOpts.RepoURL, "repo", "", "chart repository url where to locate the requested chart")
-	f.StringVar(&o.ChartOpts.Version, "version", "", "specify a version constraint for the chart version to use. This constraint can be a specific tag (e.g. 1.1.1) or it may reference a valid range (e.g. ^2.0.0). If this is not specified, the latest version is used")
-	f.BoolVar(&o.ChartOpts.Verify, "verify", false, "verify the package before using it")
-	f.StringVar(&o.ChartOpts.Username, "username", "", "chart repository username where to locate the requested chart")
-	f.StringVar(&o.ChartOpts.Password, "password", "", "chart repository password where to locate the requested chart")
-	f.StringVar(&o.ChartOpts.CertFile, "cert-file", "", "identify HTTPS client using this SSL certificate file")
-	f.StringVar(&o.ChartOpts.KeyFile, "key-file", "", "identify HTTPS client using this SSL key file")
-	f.BoolVar(&o.ChartOpts.InsecureSkipTLSverify, "insecure-skip-tls-verify", false, "skip tls certificate checks for the chart download")
-	f.StringVar(&o.ChartOpts.CaFile, "ca-file", "", "verify certificates of HTTPS-enabled servers using this CA bundle")
+	f.StringVar(&o.ChartOpts.RepoURL, "repo", "", "Location of the chart (https:// | http:// | oci://)")
+	f.StringVar(&o.ChartOpts.Version, "version", "", "(Optional) Specifiy the version of the chart (v1.0.0 | 2.0.0 | ^2.0.0)")
+	f.BoolVar(&o.ChartOpts.Verify, "verify", false, "(Optional) Verify the chart before fetching it")
+	f.StringVar(&o.ChartOpts.Username, "username", "", "(Optional) Username to use for authentication")
+	f.StringVar(&o.ChartOpts.Password, "password", "", "(Optional) Password to use for authentication")
+	f.StringVar(&o.ChartOpts.CertFile, "cert-file", "", "(Optional) Location of the TLS Certificate to use for client authenication")
+	f.StringVar(&o.ChartOpts.KeyFile, "key-file", "", "(Optional) Location of the TLS Key to use for client authenication")
+	f.BoolVar(&o.ChartOpts.InsecureSkipTLSverify, "insecure-skip-tls-verify", false, "(Optional) Skip TLS certificate verification")
+	f.StringVar(&o.ChartOpts.CaFile, "ca-file", "", "(Optional) Location of CA Bundle to enable certification verification")
 }

internal/flags/copy.go

@@ -14,8 +14,8 @@ type CopyOpts struct {
 func (o *CopyOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
 
-	f.StringVarP(&o.Username, "username", "u", "", "Username when copying to an authenticated remote registry")
-	f.StringVarP(&o.Password, "password", "p", "", "Password when copying to an authenticated remote registry")
-	f.BoolVar(&o.Insecure, "insecure", false, "Toggle allowing insecure connections when copying to a remote registry")
-	f.BoolVar(&o.PlainHTTP, "plain-http", false, "Toggle allowing plain http connections when copying to a remote registry")
+	f.StringVarP(&o.Username, "username", "u", "", "(Optional) Username to use for authentication")
+	f.StringVarP(&o.Password, "password", "p", "", "(Optional) Password to use for authentication")
+	f.BoolVar(&o.Insecure, "insecure", false, "(Optional) Allow insecure connections")
+	f.BoolVar(&o.PlainHTTP, "plain-http", false, "(Optional) Allow plain HTTP connections")
 }

internal/flags/extract.go

@@ -10,5 +10,5 @@ type ExtractOpts struct {
 func (o *ExtractOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
 
-	f.StringVarP(&o.DestinationDir, "output", "o", "", "Directory to save contents to (defaults to current directory)")
+	f.StringVarP(&o.DestinationDir, "output", "o", "", "(Optional) Specify the directory to output (defaults to current directory)")
 }

internal/flags/info.go

@@ -14,9 +14,7 @@ type InfoOpts struct {
 func (o *InfoOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
 
-	f.StringVarP(&o.OutputFormat, "output", "o", "table", "Output format (table, json)")
-	f.StringVarP(&o.TypeFilter, "type", "t", "all", "Filter on type (image, chart, file, sigs, atts, sbom)")
-	f.BoolVar(&o.ListRepos, "list-repos", false, "List all repository names")
-
-	// TODO: Regex/globbing
+	f.StringVarP(&o.OutputFormat, "output", "o", "table", "(Optional) Specify the output format (table | json)")
+	f.StringVarP(&o.TypeFilter, "type", "t", "all", "(Optional) Filter on content type (image | chart | file | sigs | atts | sbom)")
+	f.BoolVar(&o.ListRepos, "list-repos", false, "(Optional) List all repository names")
 }

internal/flags/load.go

@@ -14,5 +14,5 @@ func (o *LoadOpts) AddFlags(cmd *cobra.Command) {
 	// On Windows, the default is GetTempPath, returning the first non-empty
 	// value from %TMP%, %TEMP%, %USERPROFILE%, or the Windows directory.
 	// On Plan 9, the default is /tmp.
-	f.StringVarP(&o.TempOverride, "tempdir", "t", "", "overrides the default directory for temporary files, as returned by your OS.")
+	f.StringVarP(&o.TempOverride, "tempdir", "t", "", "(Optional) Override the default temporary directiory determined by the OS")
 }

internal/flags/login.go

@@ -10,7 +10,7 @@ type LoginOpts struct {
 
 func (o *LoginOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
-	f.StringVarP(&o.Username, "username", "u", "", "Username to use for authentication")
-	f.StringVarP(&o.Password, "password", "p", "", "Password to use for authentication")
-	f.BoolVar(&o.PasswordStdin, "password-stdin", false, "Password to use for authentication (from stdin)")
+	f.StringVarP(&o.Username, "username", "u", "", "(Optional) Username to use for authentication")
+	f.StringVarP(&o.Password, "password", "p", "", "(Optional) Password to use for authentication")
+	f.BoolVar(&o.PasswordStdin, "password-stdin", false, "(Optional) Password to use for authentication (from stdin)")
 }

internal/flags/save.go

@@ -10,5 +10,5 @@ type SaveOpts struct {
 func (o *SaveOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
 
-	f.StringVarP(&o.FileName, "filename", "f", "haul.tar.zst", "Name of archive")
+	f.StringVarP(&o.FileName, "filename", "f", "haul.tar.zst", "(Optional) Specify the name of outputted archive")
 }

internal/flags/serve.go

@@ -23,13 +23,13 @@ type ServeRegistryOpts struct {
 func (o *ServeRegistryOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
 
-	f.IntVarP(&o.Port, "port", "p", 5000, "Port used to accept incoming connections")
-	f.StringVar(&o.RootDir, "directory", "registry", "Directory to use for backend. Defaults to $PWD/registry")
-	f.StringVarP(&o.ConfigFile, "config", "c", "", "Path to config file, overrides all other flags")
-	f.BoolVar(&o.ReadOnly, "readonly", true, "Run the registry as readonly")
+	f.IntVarP(&o.Port, "port", "p", 5000, "(Optional) Specify the port to use for incoming connections")
+	f.StringVar(&o.RootDir, "directory", "registry", "(Optional) Directory to use for backend. Defaults to $PWD/registry")
+	f.StringVarP(&o.ConfigFile, "config", "c", "", "(Optional) Location of config file (overrides all flags)")
+	f.BoolVar(&o.ReadOnly, "readonly", true, "(Optional) Run the registry as readonly")
 
-	f.StringVar(&o.TLSCert, "tls-cert", "", "Location of the TLS Certificate")
-	f.StringVar(&o.TLSKey, "tls-key", "", "Location of the TLS Key")
+	f.StringVar(&o.TLSCert, "tls-cert", "", "(Optional) Location of the TLS Certificate to use for server authenication")
+	f.StringVar(&o.TLSKey, "tls-key", "", "(Optional) Location of the TLS Key to use for server authenication")
 
 	cmd.MarkFlagsRequiredTogether("tls-cert", "tls-key")
 }
@@ -76,12 +76,12 @@ type ServeFilesOpts struct {
 func (o *ServeFilesOpts) AddFlags(cmd *cobra.Command) {
 	f := cmd.Flags()
 
-	f.IntVarP(&o.Port, "port", "p", 8080, "Port used to accept incoming connections")
-	f.IntVarP(&o.Timeout, "timeout", "t", 60, "Timeout duration for HTTP Requests in seconds for both reads/writes")
-	f.StringVar(&o.RootDir, "directory", "fileserver", "Directory to use for backend. Defaults to $PWD/fileserver")
+	f.IntVarP(&o.Port, "port", "p", 8080, "(Optional) Specify the port to use for incoming connections")
+	f.IntVarP(&o.Timeout, "timeout", "t", 60, "(Optional) Timeout duration for HTTP Requests in seconds for both reads/writes")
+	f.StringVar(&o.RootDir, "directory", "fileserver", "(Optional) Directory to use for backend. Defaults to $PWD/fileserver")
 
-	f.StringVar(&o.TLSCert, "tls-cert", "", "Location of the TLS Certificate")
-	f.StringVar(&o.TLSKey, "tls-key", "", "Location of the TLS Key")
+	f.StringVar(&o.TLSCert, "tls-cert", "", "(Optional) Location of the TLS Certificate to use for server authenication")
+	f.StringVar(&o.TLSKey, "tls-key", "", "(Optional) Location of the TLS Key to use for server authenication")
 
 	cmd.MarkFlagsRequiredTogether("tls-cert", "tls-key")
 }

internal/flags/store.go

@@ -19,7 +19,7 @@ type StoreRootOpts struct {
 
 func (o *StoreRootOpts) AddFlags(cmd *cobra.Command) {
 	pf := cmd.PersistentFlags()
-	pf.StringVarP(&o.StoreDir, "store", "s", consts.DefaultStoreName, "Location to create store at")
+	pf.StringVarP(&o.StoreDir, "store", "s", consts.DefaultStoreName, "(Optional) Specify the directory to use for the content store")
 	pf.StringVar(&o.CacheDir, "cache", "", "(deprecated flag and currently not used)")
 }