Add descriptions to all CLI commands

cmd/tk/bootstrap.go

@@ -40,7 +40,8 @@ import (
 
 var bootstrapCmd = &cobra.Command{
 	Use:   "bootstrap",
-	Short: "Bootstrap commands",
+	Short: "Bootstrap toolkit components",
+	Long:  "The bootstrap sub-commands bootstrap the toolkit components on the targeted Git provider.",
 }
 
 var (

cmd/tk/bootstrap_github.go

@@ -32,11 +32,10 @@ import (
 
 var bootstrapGitHubCmd = &cobra.Command{
 	Use:   "github",
-	Short: "Bootstrap GitHub repository",
-	Long: `
-The bootstrap command creates the GitHub repository if it doesn't exists and
+	Short: "Bootstrap toolkit components in a GitHub repository",
+	Long: `The bootstrap github command creates the GitHub repository if it doesn't exists and
 commits the toolkit components manifests to the master branch.
-Then it configure the target cluster to synchronize with the repository.
+Then it configures the target cluster to synchronize with the repository.
 If the toolkit components are present on the cluster,
 the bootstrap command will perform an upgrade if needed.`,
 	Example: `  # Create a GitHub personal access token and export it as an env var

cmd/tk/bootstrap_gitlab.go

@@ -32,11 +32,10 @@ import (
 
 var bootstrapGitLabCmd = &cobra.Command{
 	Use:   "gitlab",
-	Short: "Bootstrap GitLab repository",
-	Long: `
-The bootstrap command creates the GitLab repository if it doesn't exists and
+	Short: "Bootstrap toolkit components in a GitLab repository",
+	Long: `The bootstrap gitlab command creates the GitLab repository if it doesn't exists and
 commits the toolkit components manifests to the master branch.
-Then it configure the target cluster to synchronize with the repository.
+Then it configures the target cluster to synchronize with the repository.
 If the toolkit components are present on the cluster,
 the bootstrap command will perform an upgrade if needed.`,
 	Example: `  # Create a GitLab API token and export it as an env var

cmd/tk/check.go

@@ -32,8 +32,7 @@ import (
 var checkCmd = &cobra.Command{
 	Use:   "check",
 	Short: "Check requirements and installation",
-	Long: `
-The check command will perform a series of checks to validate that
+	Long: `The check command will perform a series of checks to validate that
 the local environment is configured correctly and if the installed components are healthy.`,
 	Example: `  # Run pre-installation checks
   check --pre

cmd/tk/create.go

@@ -24,7 +24,8 @@ import (
 
 var createCmd = &cobra.Command{
 	Use:   "create",
-	Short: "Create commands",
+	Short: "Create or update sources and resources",
+	Long:  "The create sub-commands generate sources and resources.",
 }
 
 var (
@@ -34,6 +35,6 @@ var (
 
 func init() {
 	createCmd.PersistentFlags().DurationVarP(&interval, "interval", "", time.Minute, "source sync interval")
-	createCmd.PersistentFlags().BoolVar(&export, "export", false, "export in yaml format to stdout")
+	createCmd.PersistentFlags().BoolVar(&export, "export", false, "export in YAML format to stdout")
 	rootCmd.AddCommand(createCmd)
 }

cmd/tk/create_kustomization.go

@@ -37,11 +37,9 @@ import (
 var createKsCmd = &cobra.Command{
 	Use:     "kustomization [name]",
 	Aliases: []string{"ks"},
-	Short:   "Create or update a kustomization resource",
-	Long: `
-The kustomization source command generates a kustomization.kustomize.fluxcd.io resource for a given GitRepository source.
-API spec: https://github.com/fluxcd/kustomize-controller/tree/master/docs/spec/v1alpha1`,
-	Example: `  # Create a kustomization from a source at a given path
+	Short:   "Create or update a Kustomization resource",
+	Long:    "The kustomization source create command generates a Kustomize resource for a given GitRepository source.",
+	Example: `  # Create a Kustomization resource from a source at a given path
   create kustomization contour \
     --source=contour \
     --path="./examples/contour/" \
@@ -52,7 +50,7 @@ API spec: https://github.com/fluxcd/kustomize-controller/tree/master/docs/spec/v
     --health-check="DaemonSet/envoy.projectcontour" \
     --health-check-timeout=3m
 
-  # Create a kustomization that depends on the previous one
+  # Create a Kustomization resource that depends on the previous one
   create kustomization webapp \
     --depends-on=contour \
     --source=webapp \
@@ -61,7 +59,7 @@ API spec: https://github.com/fluxcd/kustomize-controller/tree/master/docs/spec/v
     --interval=5m \
     --validate=client
 
-  # Create a kustomization that runs under a service account
+  # Create a Kustomization resource that runs under a service account
   create kustomization webapp \
     --source=webapp \
     --path="./deploy/overlays/staging" \
@@ -88,12 +86,12 @@ var (
 
 func init() {
 	createKsCmd.Flags().StringVar(&ksSource, "source", "", "GitRepository name")
-	createKsCmd.Flags().StringVar(&ksPath, "path", "./", "path to the directory containing the kustomization file")
+	createKsCmd.Flags().StringVar(&ksPath, "path", "./", "path to the directory containing the Kustomization file")
 	createKsCmd.Flags().BoolVar(&ksPrune, "prune", false, "enable garbage collection")
 	createKsCmd.Flags().StringArrayVar(&ksHealthCheck, "health-check", nil, "workload to be included in the health assessment, in the format '<kind>/<name>.<namespace>'")
 	createKsCmd.Flags().DurationVar(&ksHealthTimeout, "health-check-timeout", 2*time.Minute, "timeout of health checking operations")
 	createKsCmd.Flags().StringVar(&ksValidate, "validate", "", "validate the manifests before applying them on the cluster, can be 'client' or 'server'")
-	createKsCmd.Flags().StringArrayVar(&ksDependsOn, "depends-on", nil, "kustomization that must be ready before this kustomization can be applied")
+	createKsCmd.Flags().StringArrayVar(&ksDependsOn, "depends-on", nil, "Kustomization that must be ready before this Kustomization can be applied")
 	createKsCmd.Flags().StringVar(&ksSAName, "sa-name", "", "service account name")
 	createKsCmd.Flags().StringVar(&ksSANamespace, "sa-namespace", "", "service account namespace")
 	createCmd.AddCommand(createKsCmd)

cmd/tk/create_source.go

@@ -22,7 +22,8 @@ import (
 
 var createSourceCmd = &cobra.Command{
 	Use:   "source",
-	Short: "Create source commands",
+	Short: "Create or update sources",
+	Long:  "The create source sub-commands generate sources.",
 }
 
 func init() {

cmd/tk/create_source_git.go

@@ -40,9 +40,9 @@ import (
 
 var createSourceGitCmd = &cobra.Command{
 	Use:   "git [name]",
-	Short: "Create or update a git source",
+	Short: "Create or update a GitRepository source",
 	Long: `
-The create source command generates a GitRepository resource and waits for it to sync.
+The create source git command generates a GitRepository resource and waits for it to sync.
 For Git over SSH, host and SSH keys are automatically generated and stored in a Kubernetes secret.
 For private Git repositories, the basic authentication credentials are stored in a Kubernetes secret.`,
 	Example: `  # Create a source from a public Git repository master branch

cmd/tk/delete.go

@@ -22,7 +22,8 @@ import (
 
 var deleteCmd = &cobra.Command{
 	Use:   "delete",
-	Short: "Delete commands",
+	Short: "Delete sources and resources",
+	Long:  "The delete sub-commands delete sources and resources.",
 }
 
 var (

cmd/tk/delete_kustomization.go

@@ -29,7 +29,8 @@ import (
 var deleteKsCmd = &cobra.Command{
 	Use:     "kustomization [name]",
 	Aliases: []string{"ks"},
-	Short:   "Delete kustomization",
+	Short:   "Delete a Kustomization resource",
+	Long:    "The delete kustomization command deletes the given Kustomization from the cluster.",
 	RunE:    deleteKsCmdRun,
 }
 

cmd/tk/delete_source.go

@@ -22,7 +22,8 @@ import (
 
 var deleteSourceCmd = &cobra.Command{
 	Use:   "source",
-	Short: "Delete sources commands",
+	Short: "Delete sources",
+	Long:  "The delete source sub-commands delete sources.",
 }
 
 func init() {

cmd/tk/delete_source_git.go

@@ -28,7 +28,8 @@ import (
 
 var deleteSourceGitCmd = &cobra.Command{
 	Use:   "git [name]",
-	Short: "Delete git source",
+	Short: "Delete a GitRepository source",
+	Long:  "The delete source git command deletes the given GitRepository from the cluster.",
 	RunE:  deleteSourceGitCmdRun,
 }
 

cmd/tk/export.go

@@ -22,7 +22,8 @@ import (
 
 var exportCmd = &cobra.Command{
 	Use:   "export",
-	Short: "Export commands",
+	Short: "Export resources in YAML format",
+	Long:  "The export sub-commands export resources in YAML format.",
 }
 
 var (

cmd/tk/export_kustomization.go

@@ -31,11 +31,12 @@ import (
 var exportKsCmd = &cobra.Command{
 	Use:     "kustomization [name]",
 	Aliases: []string{"ks"},
-	Short:   "Export kustomization in YAML format",
-	Example: `  # Export all kustomizations
+	Short:   "Export Kustomization resources in YAML format",
+	Long:    "The export kustomization command exports one or all Kustomization resources in YAML format.",
+	Example: `  # Export all Kustomization resources
   export kustomization --all > kustomizations.yaml
 
-  # Export a kustomization
+  # Export a Kustomization
   export kustomization my-app > kustomization.yaml
 `,
 	RunE: exportKsCmdRun,

cmd/tk/export_source.go

@@ -22,7 +22,8 @@ import (
 
 var exportSourceCmd = &cobra.Command{
 	Use:   "source",
-	Short: "Export source commands",
+	Short: "Export sources",
+	Long:  "The export source sub-commands export sources in YAML format.",
 }
 
 var (

cmd/tk/export_source_git.go

@@ -31,11 +31,12 @@ import (
 
 var exportSourceGitCmd = &cobra.Command{
 	Use:   "git [name]",
-	Short: "Export git sources in YAML format",
-	Example: `  # Export all git sources
+	Short: "Export GitRepository sources in YAML format",
+	Long:  "The export source git command exports on or all GitRepository sources in YAML format.",
+	Example: `  # Export all GitRepository sources
   export source git --all > sources.yaml
 
-  # Export a git source including the SSH keys or basic auth credentials
+  # Export a GitRepository source including the SSH key pair or basic auth credentials
   export source git my-private-repo --with-credentials > source.yaml
 `,
 	RunE: exportSourceGitCmdRun,

cmd/tk/get.go

@@ -22,7 +22,8 @@ import (
 
 var getCmd = &cobra.Command{
 	Use:   "get",
-	Short: "Get commands",
+	Short: "Get sources and resources",
+	Long:  "The get sub-commands print the statuses of sources and resources.",
 }
 
 func init() {

cmd/tk/get_kustomization.go

@@ -28,10 +28,9 @@ import (
 var getKsCmd = &cobra.Command{
 	Use:     "kustomizations",
 	Aliases: []string{"ks"},
-	Short:   "Get kustomizations status",
-	Long: `
-The get kustomizations command prints the status of the resources.`,
-	RunE: getKsCmdRun,
+	Short:   "Get Kustomization source statuses",
+	Long:    "The get kustomizations command prints the statuses of the resources.",
+	RunE:    getKsCmdRun,
 }
 
 func init() {

cmd/tk/get_source.go

@@ -22,7 +22,8 @@ import (
 
 var getSourceCmd = &cobra.Command{
 	Use:   "sources",
-	Short: "Get sources commands",
+	Short: "Get source statuses",
+	Long:  "The get source sub-commands print the statuses of the sources.",
 }
 
 func init() {

cmd/tk/get_source_git.go

@@ -27,10 +27,9 @@ import (
 
 var getSourceGitCmd = &cobra.Command{
 	Use:   "git",
-	Short: "Get git sources status",
-	Long: `
-The get sources command prints the status of the git resources.`,
-	RunE: getSourceGitCmdRun,
+	Short: "Get GitRepository source statuses",
+	Long:  "The get sources git command prints the status of the GitRepository sources.",
+	RunE:  getSourceGitCmdRun,
 }
 
 func init() {

cmd/tk/install.go

@@ -33,8 +33,7 @@ import (
 var installCmd = &cobra.Command{
 	Use:   "install",
 	Short: "Install the toolkit components",
-	Long: `
-The install command deploys the toolkit components in the specified namespace.
+	Long: `The install command deploys the toolkit components in the specified namespace.
 If a previous version is installed, then an in-place upgrade will be performed.`,
 	Example: `  # Install the latest version in the gitops-systems namespace
   install --version=master --namespace=gitops-systems

cmd/tk/main.go

@@ -48,16 +48,16 @@ var rootCmd = &cobra.Command{
     --branch=master \
     --interval=3m
 
-  # List git sources and their status
+  # List GitRepository sources and their status
   tk get sources git
 
-  # Trigger a git sync
+  # Trigger a GitRepository source sync
   tk sync source git webapp-latest
 
-  # Export git sources in YAML format
+  # Export GitRepository sources in YAML format
   tk export source git --all > sources.yaml
 
-  # Create a kustomization for deploying a series of microservices
+  # Create a Kustomization for deploying a series of microservices
   tk create kustomization webapp-dev \
     --source=webapp-latest \
     --path="./deploy/webapp/" \
@@ -68,22 +68,22 @@ var rootCmd = &cobra.Command{
     --health-check="Deployment/frontend.webapp" \
     --health-check-timeout=2m
 
-  # Trigger a git sync and apply changes if any
+  # Trigger a git sync of the Kustomization's source and apply changes
   tk sync kustomization webapp-dev --with-source
 
-  # Suspend a kustomization reconciliation
+  # Suspend a Kustomization reconciliation
   tk suspend kustomization webapp-dev
 
-  # Export kustomizations in YAML format
+  # Export Kustomizations in YAML format
   tk export kustomization --all > kustomizations.yaml
 
-  # Resume a kustomization reconciliation
+  # Resume a Kustomization reconciliation
   tk resume kustomization webapp-dev
 
-  # Delete a kustomization
+  # Delete a Kustomization
   tk delete kustomization webapp-dev
 
-  # Delete a git source
+  # Delete a GitRepository source
   tk delete source git webapp-latest
 
   # Uninstall the toolkit and delete CRDs

cmd/tk/resume.go

@@ -22,7 +22,8 @@ import (
 
 var resumeCmd = &cobra.Command{
 	Use:   "resume",
-	Short: "Resume commands",
+	Short: "Resume suspended resources",
+	Long:  "The resume sub-commands resume a suspended resource.",
 }
 
 func init() {

cmd/tk/resume_kustomization.go

@@ -32,9 +32,10 @@ import (
 var resumeKsCmd = &cobra.Command{
 	Use:     "kustomization [name]",
 	Aliases: []string{"ks"},
-	Short:   "Resume kustomization",
-	Long:    "The resume command marks a previously suspended Kustomization resource for reconciliation and waits for it to finish the apply.",
-	RunE:    resumeKsCmdRun,
+	Short:   "Resume a suspended Kustomization",
+	Long: `The resume command marks a previously suspended Kustomization resource for reconciliation and waits for it to
+finish the apply.`,
+	RunE: resumeKsCmdRun,
 }
 
 func init() {

cmd/tk/suspend.go

@@ -22,7 +22,8 @@ import (
 
 var suspendCmd = &cobra.Command{
 	Use:   "suspend",
-	Short: "Suspend commands",
+	Short: "Suspend resources",
+	Long:  "The suspend sub-commands suspend the reconciliation of a resource.",
 }
 
 func init() {

cmd/tk/suspend_kustomization.go

@@ -27,7 +27,7 @@ import (
 var suspendKsCmd = &cobra.Command{
 	Use:     "kustomization [name]",
 	Aliases: []string{"ks"},
-	Short:   "Suspend kustomization",
+	Short:   "Suspend reconciliation of Kustomization",
 	Long:    "The suspend command disables the reconciliation of a Kustomization resource.",
 	RunE:    suspendKsCmdRun,
 }

cmd/tk/sync.go

@@ -22,7 +22,8 @@ import (
 
 var syncCmd = &cobra.Command{
 	Use:   "sync",
-	Short: "Synchronize commands",
+	Short: "Synchronize sources and resources",
+	Long:  "The sync sub-commands trigger a reconciliation of sources and resources.",
 }
 
 func init() {

cmd/tk/sync_kustomization.go

@@ -30,13 +30,13 @@ import (
 var syncKsCmd = &cobra.Command{
 	Use:     "kustomization [name]",
 	Aliases: []string{"ks"},
-	Short:   "Synchronize kustomization",
+	Short:   "Synchronize a Kustomization resource",
 	Long: `
 The sync kustomization command triggers a reconciliation of a Kustomization resource and waits for it to finish.`,
-	Example: `  # Trigger a kustomization apply outside of the reconciliation interval
+	Example: `  # Trigger a Kustomization apply outside of the reconciliation interval
   sync kustomization podinfo
 
-  # Trigger a git sync of the kustomization source and apply changes
+  # Trigger a sync of the Kustomization's source and apply changes
   sync kustomization podinfo --with-source
 `,
 	RunE: syncKsCmdRun,

cmd/tk/sync_source.go

@@ -22,7 +22,8 @@ import (
 
 var syncSourceCmd = &cobra.Command{
 	Use:   "source",
-	Short: "Synchronize source commands",
+	Short: "Synchronize sources",
+	Long:  "The sync source sub-commands trigger a reconciliation of sources.",
 }
 
 func init() {

cmd/tk/sync_source_git.go

@@ -28,9 +28,8 @@ import (
 
 var syncSourceGitCmd = &cobra.Command{
 	Use:   "git [name]",
-	Short: "Synchronize git source",
-	Long: `
-The sync source command triggers a reconciliation of a GitRepository resource and waits for it to finish.`,
+	Short: "Synchronize a GitRepository source",
+	Long:  `The sync source command triggers a reconciliation of a GitRepository resource and waits for it to finish.`,
 	Example: `  # Trigger a git pull for an existing source
   sync source git podinfo
 `,

cmd/tk/uninstall.go

@@ -28,9 +28,7 @@ import (
 var uninstallCmd = &cobra.Command{
 	Use:   "uninstall",
 	Short: "Uninstall the toolkit components",
-	Long: `
-The uninstall command removes the namespace, cluster roles,
-cluster role bindings and CRDs.`,
+	Long:  "The uninstall command removes the namespace, cluster roles, cluster role bindings and CRDs from the cluster.",
 	Example: `  # Dry-run uninstall of all components
    uninstall --dry-run --namespace=gitops-system
 
@@ -49,7 +47,7 @@ var (
 
 func init() {
 	uninstallCmd.Flags().BoolVarP(&uninstallKustomizations, "kustomizations", "", false,
-		"removes all kustomizations previously installed")
+		"removes all Kustomizations previously installed")
 	uninstallCmd.Flags().BoolVarP(&uninstallCRDs, "crds", "", false,
 		"removes all CRDs previously installed")
 	uninstallCmd.Flags().BoolVarP(&uninstallDryRun, "dry-run", "", false,