Merge pull request #66 from fluxcd/docs/cli-examples

Improve CLI command descriptions

.github/workflows/e2e.yaml

@@ -30,7 +30,7 @@ jobs:
       - name: Check if working tree is dirty
         run: |
           if [[ $(git diff --stat) != '' ]]; then
-            git diff --stat
+            git diff
             echo 'run make test and commit changes'
             exit 1
           fi

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",
+	Short: "Bootstrap toolkit components in a GitHub repository",
-	Long: `
+	Long: `The bootstrap github command creates the GitHub repository if it doesn't exists and
-The bootstrap 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",
+	Short: "Bootstrap toolkit components in a GitLab repository",
-	Long: `
+	Long: `The bootstrap gitlab command creates the GitLab repository if it doesn't exists and
-The bootstrap 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: `
+	Long: `The check command will perform a series of checks to validate that
-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",
+	Short:   "Create or update a Kustomization resource",
-	Long: `
+	Long:    "The kustomization source create command generates a Kustomize resource for a given GitRepository source.",
-The kustomization source command generates a kustomization.kustomize.fluxcd.io resource for a given GitRepository source.
+	Example: `  # Create a Kustomization resource from a source at a given path
-API spec: https://github.com/fluxcd/kustomize-controller/tree/master/docs/spec/v1alpha1`,
-	Example: `  # Create a kustomization 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",
+	Short:   "Export Kustomization resources in YAML format",
-	Example: `  # Export all kustomizations
+	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",
+	Short: "Export GitRepository sources in YAML format",
-	Example: `  # Export all git sources
+	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",
+	Short:   "Get Kustomization source statuses",
-	Long: `
+	Long:    "The get kustomizations command prints the statuses of the resources.",
-The get kustomizations command prints the status of the resources.`,
+	RunE:    getKsCmdRun,
-	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",
+	Short: "Get GitRepository source statuses",
-	Long: `
+	Long:  "The get sources git command prints the status of the GitRepository sources.",
-The get sources command prints the status of the git resources.`,
+	RunE:  getSourceGitCmdRun,
-	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: `
+	Long: `The install command deploys the toolkit components in the specified namespace.
-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",
+	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.",
+	Long: `The resume command marks a previously suspended Kustomization resource for reconciliation and waits for it to
-	RunE:    resumeKsCmdRun,
+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",
+	Short: "Synchronize a GitRepository source",
-	Long: `
+	Long:  `The sync source command triggers a reconciliation of a GitRepository resource and waits for it to finish.`,
-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: `
+	Long:  "The uninstall command removes the namespace, cluster roles, cluster role bindings and CRDs from the cluster.",
-The uninstall command removes the namespace, cluster roles,
-cluster role bindings and CRDs.`,
 	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,

docs/cmd/tk.md

@@ -21,16 +21,16 @@ Command line utility for assembling Kubernetes CD pipelines the GitOps way.
     --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/" \
@@ -41,22 +41,22 @@ Command line utility for assembling Kubernetes CD pipelines the GitOps way.
     --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
@@ -77,16 +77,16 @@ Command line utility for assembling Kubernetes CD pipelines the GitOps way.
 
 ### SEE ALSO
 
-* [tk bootstrap](tk_bootstrap.md)	 - Bootstrap commands
+* [tk bootstrap](tk_bootstrap.md)	 - Bootstrap toolkit components
 * [tk check](tk_check.md)	 - Check requirements and installation
 * [tk completion](tk_completion.md)	 - Generates bash completion scripts
-* [tk create](tk_create.md)	 - Create commands
+* [tk create](tk_create.md)	 - Create or update sources and resources
-* [tk delete](tk_delete.md)	 - Delete commands
+* [tk delete](tk_delete.md)	 - Delete sources and resources
-* [tk export](tk_export.md)	 - Export commands
+* [tk export](tk_export.md)	 - Export resources in YAML format
-* [tk get](tk_get.md)	 - Get commands
+* [tk get](tk_get.md)	 - Get sources and resources
 * [tk install](tk_install.md)	 - Install the toolkit components
-* [tk resume](tk_resume.md)	 - Resume commands
+* [tk resume](tk_resume.md)	 - Resume suspended resources
-* [tk suspend](tk_suspend.md)	 - Suspend commands
+* [tk suspend](tk_suspend.md)	 - Suspend resources
-* [tk sync](tk_sync.md)	 - Synchronize commands
+* [tk sync](tk_sync.md)	 - Synchronize sources and resources
 * [tk uninstall](tk_uninstall.md)	 - Uninstall the toolkit components
 

docs/cmd/tk_bootstrap.md

@@ -1,10 +1,10 @@
 ## tk bootstrap
 
-Bootstrap commands
+Bootstrap toolkit components
 
 ### Synopsis
 
-Bootstrap commands
+The bootstrap sub-commands bootstrap the toolkit components on the targeted Git provider.
 
 ### Options
 
@@ -26,6 +26,6 @@ Bootstrap commands
 ### SEE ALSO
 
 * [tk](tk.md)	 - Command line utility for assembling Kubernetes CD pipelines
-* [tk bootstrap github](tk_bootstrap_github.md)	 - Bootstrap GitHub repository
+* [tk bootstrap github](tk_bootstrap_github.md)	 - Bootstrap toolkit components in a GitHub repository
-* [tk bootstrap gitlab](tk_bootstrap_gitlab.md)	 - Bootstrap GitLab repository
+* [tk bootstrap gitlab](tk_bootstrap_gitlab.md)	 - Bootstrap toolkit components in a GitLab repository
 

docs/cmd/tk_bootstrap_github.md

@@ -1,13 +1,12 @@
 ## tk bootstrap github
 
-Bootstrap GitHub repository
+Bootstrap toolkit components in a GitHub repository
 
 ### Synopsis
 
-
+The bootstrap github command creates the GitHub repository if it doesn't exists and
-The bootstrap 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.
 
@@ -65,5 +64,5 @@ tk bootstrap github [flags]
 
 ### SEE ALSO
 
-* [tk bootstrap](tk_bootstrap.md)	 - Bootstrap commands
+* [tk bootstrap](tk_bootstrap.md)	 - Bootstrap toolkit components
 

docs/cmd/tk_bootstrap_gitlab.md

@@ -1,13 +1,12 @@
 ## tk bootstrap gitlab
 
-Bootstrap GitLab repository
+Bootstrap toolkit components in a GitLab repository
 
 ### Synopsis
 
-
+The bootstrap gitlab command creates the GitLab repository if it doesn't exists and
-The bootstrap 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.
 
@@ -61,5 +60,5 @@ tk bootstrap gitlab [flags]
 
 ### SEE ALSO
 
-* [tk bootstrap](tk_bootstrap.md)	 - Bootstrap commands
+* [tk bootstrap](tk_bootstrap.md)	 - Bootstrap toolkit components
 

docs/cmd/tk_check.md

@@ -4,7 +4,6 @@ Check requirements and installation
 
 ### Synopsis
 
-
 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.
 

docs/cmd/tk_create.md

@@ -1,15 +1,15 @@
 ## tk create
 
-Create commands
+Create or update sources and resources
 
 ### Synopsis
 
-Create commands
+The create sub-commands generate sources and resources.
 
 ### Options
 
 ```
-      --export              export in yaml format to stdout
+      --export              export in YAML format to stdout
   -h, --help                help for create
       --interval duration   source sync interval (default 1m0s)
 ```
@@ -27,6 +27,6 @@ Create commands
 ### SEE ALSO
 
 * [tk](tk.md)	 - Command line utility for assembling Kubernetes CD pipelines
-* [tk create kustomization](tk_create_kustomization.md)	 - Create or update a kustomization resource
+* [tk create kustomization](tk_create_kustomization.md)	 - Create or update a Kustomization resource
-* [tk create source](tk_create_source.md)	 - Create source commands
+* [tk create source](tk_create_source.md)	 - Create or update sources
 

docs/cmd/tk_create_kustomization.md

@@ -1,12 +1,10 @@
 ## tk create kustomization
 
-Create or update a kustomization resource
+Create or update a Kustomization resource
 
 ### Synopsis
 
-
+The kustomization source create command generates a Kustomize resource for a given GitRepository source.
-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
 
 ```
 tk create kustomization [name] [flags]
@@ -15,7 +13,7 @@ tk create kustomization [name] [flags]
 ### Examples
 
 ```
-  # Create a kustomization from a source at a given path
+  # Create a Kustomization resource from a source at a given path
   create kustomization contour \
     --source=contour \
     --path="./examples/contour/" \
@@ -26,7 +24,7 @@ tk create kustomization [name] [flags]
     --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 \
@@ -35,7 +33,7 @@ tk create kustomization [name] [flags]
     --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" \
@@ -50,11 +48,11 @@ tk create kustomization [name] [flags]
 ### Options
 
 ```
-      --depends-on stringArray          kustomization that must be ready before this kustomization can be applied
+      --depends-on stringArray          Kustomization that must be ready before this Kustomization can be applied
       --health-check stringArray        workload to be included in the health assessment, in the format '<kind>/<name>.<namespace>'
       --health-check-timeout duration   timeout of health checking operations (default 2m0s)
   -h, --help                            help for kustomization
-      --path string                     path to the directory containing the kustomization file (default "./")
+      --path string                     path to the directory containing the Kustomization file (default "./")
       --prune                           enable garbage collection
       --sa-name string                  service account name
       --sa-namespace string             service account namespace
@@ -66,7 +64,7 @@ tk create kustomization [name] [flags]
 
 ```
       --components strings   list of components, accepts comma-separated values (default [source-controller,kustomize-controller])
-      --export               export in yaml format to stdout
+      --export               export in YAML format to stdout
       --interval duration    source sync interval (default 1m0s)
       --kubeconfig string    path to the kubeconfig file (default "~/.kube/config")
       --namespace string     the namespace scope for this operation (default "gitops-system")
@@ -76,5 +74,5 @@ tk create kustomization [name] [flags]
 
 ### SEE ALSO
 
-* [tk create](tk_create.md)	 - Create commands
+* [tk create](tk_create.md)	 - Create or update sources and resources
 

docs/cmd/tk_create_source.md

@@ -1,10 +1,10 @@
 ## tk create source
 
-Create source commands
+Create or update sources
 
 ### Synopsis
 
-Create source commands
+The create source sub-commands generate sources.
 
 ### Options
 
@@ -16,7 +16,7 @@ Create source commands
 
 ```
       --components strings   list of components, accepts comma-separated values (default [source-controller,kustomize-controller])
-      --export               export in yaml format to stdout
+      --export               export in YAML format to stdout
       --interval duration    source sync interval (default 1m0s)
       --kubeconfig string    path to the kubeconfig file (default "~/.kube/config")
       --namespace string     the namespace scope for this operation (default "gitops-system")
@@ -26,6 +26,6 @@ Create source commands
 
 ### SEE ALSO
 
-* [tk create](tk_create.md)	 - Create commands
+* [tk create](tk_create.md)	 - Create or update sources and resources
-* [tk create source git](tk_create_source_git.md)	 - Create or update a git source
+* [tk create source git](tk_create_source_git.md)	 - Create or update a GitRepository source
 

docs/cmd/tk_create_source_git.md

@@ -1,11 +1,11 @@
 ## tk create source git
 
-Create or update a git source
+Create or update a GitRepository source
 
 ### Synopsis
 
 
-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.
 
@@ -71,7 +71,7 @@ tk create source git [name] [flags]
 
 ```
       --components strings   list of components, accepts comma-separated values (default [source-controller,kustomize-controller])
-      --export               export in yaml format to stdout
+      --export               export in YAML format to stdout
       --interval duration    source sync interval (default 1m0s)
       --kubeconfig string    path to the kubeconfig file (default "~/.kube/config")
       --namespace string     the namespace scope for this operation (default "gitops-system")
@@ -81,5 +81,5 @@ tk create source git [name] [flags]
 
 ### SEE ALSO
 
-* [tk create source](tk_create_source.md)	 - Create source commands
+* [tk create source](tk_create_source.md)	 - Create or update sources
 

docs/cmd/tk_delete.md

@@ -1,10 +1,10 @@
 ## tk delete
 
-Delete commands
+Delete sources and resources
 
 ### Synopsis
 
-Delete commands
+The delete sub-commands delete sources and resources.
 
 ### Options
 
@@ -26,6 +26,6 @@ Delete commands
 ### SEE ALSO
 
 * [tk](tk.md)	 - Command line utility for assembling Kubernetes CD pipelines
-* [tk delete kustomization](tk_delete_kustomization.md)	 - Delete kustomization
+* [tk delete kustomization](tk_delete_kustomization.md)	 - Delete a Kustomization resource
-* [tk delete source](tk_delete_source.md)	 - Delete sources commands
+* [tk delete source](tk_delete_source.md)	 - Delete sources
 

docs/cmd/tk_delete_kustomization.md

@@ -1,10 +1,10 @@
 ## tk delete kustomization
 
-Delete kustomization
+Delete a Kustomization resource
 
 ### Synopsis
 
-Delete kustomization
+The delete kustomization command deletes the given Kustomization from the cluster.
 
 ```
 tk delete kustomization [name] [flags]
@@ -29,5 +29,5 @@ tk delete kustomization [name] [flags]
 
 ### SEE ALSO
 
-* [tk delete](tk_delete.md)	 - Delete commands
+* [tk delete](tk_delete.md)	 - Delete sources and resources
 

docs/cmd/tk_delete_source.md

@@ -1,10 +1,10 @@
 ## tk delete source
 
-Delete sources commands
+Delete sources
 
 ### Synopsis
 
-Delete sources commands
+The delete source sub-commands delete sources.
 
 ### Options
 
@@ -25,6 +25,6 @@ Delete sources commands
 
 ### SEE ALSO
 
-* [tk delete](tk_delete.md)	 - Delete commands
+* [tk delete](tk_delete.md)	 - Delete sources and resources
-* [tk delete source git](tk_delete_source_git.md)	 - Delete git source
+* [tk delete source git](tk_delete_source_git.md)	 - Delete a GitRepository source
 

docs/cmd/tk_delete_source_git.md

@@ -1,10 +1,10 @@
 ## tk delete source git
 
-Delete git source
+Delete a GitRepository source
 
 ### Synopsis
 
-Delete git source
+The delete source git command deletes the given GitRepository from the cluster.
 
 ```
 tk delete source git [name] [flags]
@@ -29,5 +29,5 @@ tk delete source git [name] [flags]
 
 ### SEE ALSO
 
-* [tk delete source](tk_delete_source.md)	 - Delete sources commands
+* [tk delete source](tk_delete_source.md)	 - Delete sources
 

docs/cmd/tk_export.md

@@ -1,10 +1,10 @@
 ## tk export
 
-Export commands
+Export resources in YAML format
 
 ### Synopsis
 
-Export commands
+The export sub-commands export resources in YAML format.
 
 ### Options
 
@@ -26,6 +26,6 @@ Export commands
 ### SEE ALSO
 
 * [tk](tk.md)	 - Command line utility for assembling Kubernetes CD pipelines
-* [tk export kustomization](tk_export_kustomization.md)	 - Export kustomization in YAML format
+* [tk export kustomization](tk_export_kustomization.md)	 - Export Kustomization resources in YAML format
-* [tk export source](tk_export_source.md)	 - Export source commands
+* [tk export source](tk_export_source.md)	 - Export sources
 

docs/cmd/tk_export_kustomization.md

@@ -1,10 +1,10 @@
 ## tk export kustomization
 
-Export kustomization in YAML format
+Export Kustomization resources in YAML format
 
 ### Synopsis
 
-Export kustomization in YAML format
+The export kustomization command exports one or all Kustomization resources in YAML format.
 
 ```
 tk export kustomization [name] [flags]
@@ -13,10 +13,10 @@ tk export kustomization [name] [flags]
 ### Examples
 
 ```
-  # Export all kustomizations
+  # Export all Kustomization resources
   export kustomization --all > kustomizations.yaml
 
-  # Export a kustomization
+  # Export a Kustomization
   export kustomization my-app > kustomization.yaml
 
 ```
@@ -40,5 +40,5 @@ tk export kustomization [name] [flags]
 
 ### SEE ALSO
 
-* [tk export](tk_export.md)	 - Export commands
+* [tk export](tk_export.md)	 - Export resources in YAML format
 

docs/cmd/tk_export_source.md

@@ -1,10 +1,10 @@
 ## tk export source
 
-Export source commands
+Export sources
 
 ### Synopsis
 
-Export source commands
+The export source sub-commands export sources in YAML format.
 
 ### Options
 
@@ -26,6 +26,6 @@ Export source commands
 
 ### SEE ALSO
 
-* [tk export](tk_export.md)	 - Export commands
+* [tk export](tk_export.md)	 - Export resources in YAML format
-* [tk export source git](tk_export_source_git.md)	 - Export git sources in YAML format
+* [tk export source git](tk_export_source_git.md)	 - Export GitRepository sources in YAML format
 

docs/cmd/tk_export_source_git.md

@@ -1,10 +1,10 @@
 ## tk export source git
 
-Export git sources in YAML format
+Export GitRepository sources in YAML format
 
 ### Synopsis
 
-Export git sources in YAML format
+The export source git command exports on or all GitRepository sources in YAML format.
 
 ```
 tk export source git [name] [flags]
@@ -13,10 +13,10 @@ tk export source git [name] [flags]
 ### Examples
 
 ```
-  # Export all git sources
+  # 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
 
 ```
@@ -41,5 +41,5 @@ tk export source git [name] [flags]
 
 ### SEE ALSO
 
-* [tk export source](tk_export_source.md)	 - Export source commands
+* [tk export source](tk_export_source.md)	 - Export sources
 

docs/cmd/tk_get.md

@@ -1,10 +1,10 @@
 ## tk get
 
-Get commands
+Get sources and resources
 
 ### Synopsis
 
-Get commands
+The get sub-commands print the statuses of sources and resources.
 
 ### Options
 
@@ -25,6 +25,6 @@ Get commands
 ### SEE ALSO
 
 * [tk](tk.md)	 - Command line utility for assembling Kubernetes CD pipelines
-* [tk get kustomizations](tk_get_kustomizations.md)	 - Get kustomizations status
+* [tk get kustomizations](tk_get_kustomizations.md)	 - Get Kustomization source statuses
-* [tk get sources](tk_get_sources.md)	 - Get sources commands
+* [tk get sources](tk_get_sources.md)	 - Get source statuses
 

docs/cmd/tk_get_kustomizations.md

@@ -1,11 +1,10 @@
 ## tk get kustomizations
 
-Get kustomizations status
+Get Kustomization source statuses
 
 ### Synopsis
 
-
+The get kustomizations command prints the statuses of the resources.
-The get kustomizations command prints the status of the resources.
 
 ```
 tk get kustomizations [flags]
@@ -29,5 +28,5 @@ tk get kustomizations [flags]
 
 ### SEE ALSO
 
-* [tk get](tk_get.md)	 - Get commands
+* [tk get](tk_get.md)	 - Get sources and resources
 

docs/cmd/tk_get_sources.md

@@ -1,10 +1,10 @@
 ## tk get sources
 
-Get sources commands
+Get source statuses
 
 ### Synopsis
 
-Get sources commands
+The get source sub-commands print the statuses of the sources.
 
 ### Options
 
@@ -24,6 +24,6 @@ Get sources commands
 
 ### SEE ALSO
 
-* [tk get](tk_get.md)	 - Get commands
+* [tk get](tk_get.md)	 - Get sources and resources
-* [tk get sources git](tk_get_sources_git.md)	 - Get git sources status
+* [tk get sources git](tk_get_sources_git.md)	 - Get GitRepository source statuses
 

docs/cmd/tk_get_sources_git.md

@@ -1,11 +1,10 @@
 ## tk get sources git
 
-Get git sources status
+Get GitRepository source statuses
 
 ### Synopsis
 
-
+The get sources git command prints the status of the GitRepository sources.
-The get sources command prints the status of the git resources.
 
 ```
 tk get sources git [flags]
@@ -29,5 +28,5 @@ tk get sources git [flags]
 
 ### SEE ALSO
 
-* [tk get sources](tk_get_sources.md)	 - Get sources commands
+* [tk get sources](tk_get_sources.md)	 - Get source statuses
 

docs/cmd/tk_install.md

@@ -4,7 +4,6 @@ Install the toolkit components
 
 ### Synopsis
 
-
 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.
 

docs/cmd/tk_resume.md

@@ -1,10 +1,10 @@
 ## tk resume
 
-Resume commands
+Resume suspended resources
 
 ### Synopsis
 
-Resume commands
+The resume sub-commands resume a suspended resource.
 
 ### Options
 
@@ -25,5 +25,5 @@ Resume commands
 ### SEE ALSO
 
 * [tk](tk.md)	 - Command line utility for assembling Kubernetes CD pipelines
-* [tk resume kustomization](tk_resume_kustomization.md)	 - Resume kustomization
+* [tk resume kustomization](tk_resume_kustomization.md)	 - Resume a suspended Kustomization
 

docs/cmd/tk_resume_kustomization.md

@@ -1,10 +1,11 @@
 ## tk resume kustomization
 
-Resume kustomization
+Resume a suspended Kustomization
 
 ### Synopsis
 
-The resume command marks a previously suspended Kustomization resource for reconciliation and waits for it to finish the apply.
+The resume command marks a previously suspended Kustomization resource for reconciliation and waits for it to
+finish the apply.
 
 ```
 tk resume kustomization [name] [flags]
@@ -28,5 +29,5 @@ tk resume kustomization [name] [flags]
 
 ### SEE ALSO
 
-* [tk resume](tk_resume.md)	 - Resume commands
+* [tk resume](tk_resume.md)	 - Resume suspended resources
 

docs/cmd/tk_suspend.md

@@ -1,10 +1,10 @@
 ## tk suspend
 
-Suspend commands
+Suspend resources
 
 ### Synopsis
 
-Suspend commands
+The suspend sub-commands suspend the reconciliation of a resource.
 
 ### Options
 
@@ -25,5 +25,5 @@ Suspend commands
 ### SEE ALSO
 
 * [tk](tk.md)	 - Command line utility for assembling Kubernetes CD pipelines
-* [tk suspend kustomization](tk_suspend_kustomization.md)	 - Suspend kustomization
+* [tk suspend kustomization](tk_suspend_kustomization.md)	 - Suspend reconciliation of Kustomization
 

docs/cmd/tk_suspend_kustomization.md

@@ -1,6 +1,6 @@
 ## tk suspend kustomization
 
-Suspend kustomization
+Suspend reconciliation of Kustomization
 
 ### Synopsis
 
@@ -28,5 +28,5 @@ tk suspend kustomization [name] [flags]
 
 ### SEE ALSO
 
-* [tk suspend](tk_suspend.md)	 - Suspend commands
+* [tk suspend](tk_suspend.md)	 - Suspend resources
 

docs/cmd/tk_sync.md

@@ -1,10 +1,10 @@
 ## tk sync
 
-Synchronize commands
+Synchronize sources and resources
 
 ### Synopsis
 
-Synchronize commands
+The sync sub-commands trigger a reconciliation of sources and resources.
 
 ### Options
 
@@ -25,6 +25,6 @@ Synchronize commands
 ### SEE ALSO
 
 * [tk](tk.md)	 - Command line utility for assembling Kubernetes CD pipelines
-* [tk sync kustomization](tk_sync_kustomization.md)	 - Synchronize kustomization
+* [tk sync kustomization](tk_sync_kustomization.md)	 - Synchronize a Kustomization resource
-* [tk sync source](tk_sync_source.md)	 - Synchronize source commands
+* [tk sync source](tk_sync_source.md)	 - Synchronize sources
 

docs/cmd/tk_sync_kustomization.md

@@ -1,6 +1,6 @@
 ## tk sync kustomization
 
-Synchronize kustomization
+Synchronize a Kustomization resource
 
 ### Synopsis
 
@@ -14,10 +14,10 @@ tk sync kustomization [name] [flags]
 ### Examples
 
 ```
-  # Trigger a kustomization apply outside of the reconciliation interval
+  # 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
 
 ```
@@ -41,5 +41,5 @@ tk sync kustomization [name] [flags]
 
 ### SEE ALSO
 
-* [tk sync](tk_sync.md)	 - Synchronize commands
+* [tk sync](tk_sync.md)	 - Synchronize sources and resources
 

docs/cmd/tk_sync_source.md

@@ -1,10 +1,10 @@
 ## tk sync source
 
-Synchronize source commands
+Synchronize sources
 
 ### Synopsis
 
-Synchronize source commands
+The sync source sub-commands trigger a reconciliation of sources.
 
 ### Options
 
@@ -24,6 +24,6 @@ Synchronize source commands
 
 ### SEE ALSO
 
-* [tk sync](tk_sync.md)	 - Synchronize commands
+* [tk sync](tk_sync.md)	 - Synchronize sources and resources
-* [tk sync source git](tk_sync_source_git.md)	 - Synchronize git source
+* [tk sync source git](tk_sync_source_git.md)	 - Synchronize a GitRepository source
 

docs/cmd/tk_sync_source_git.md

@@ -1,10 +1,9 @@
 ## tk sync source git
 
-Synchronize git source
+Synchronize a GitRepository source
 
 ### Synopsis
 
-
 The sync source command triggers a reconciliation of a GitRepository resource and waits for it to finish.
 
 ```
@@ -37,5 +36,5 @@ tk sync source git [name] [flags]
 
 ### SEE ALSO
 
-* [tk sync source](tk_sync_source.md)	 - Synchronize source commands
+* [tk sync source](tk_sync_source.md)	 - Synchronize sources
 

docs/cmd/tk_uninstall.md

@@ -4,9 +4,7 @@ Uninstall the toolkit components
 
 ### Synopsis
 
-
+The uninstall command removes the namespace, cluster roles, cluster role bindings and CRDs from the cluster.
-The uninstall command removes the namespace, cluster roles,
-cluster role bindings and CRDs.
 
 ```
 tk uninstall [flags]
@@ -29,7 +27,7 @@ tk uninstall [flags]
       --crds             removes all CRDs previously installed
       --dry-run          only print the object that would be deleted
   -h, --help             help for uninstall
-      --kustomizations   removes all kustomizations previously installed
+      --kustomizations   removes all Kustomizations previously installed
   -s, --silent           delete components without asking for confirmation
 ```