Various small UX improvements (#6426)

cmd/skaffold/app/cmd/cmd.go

@@ -154,15 +154,15 @@ func NewSkaffoldCommand(out, errOut io.Writer) *cobra.Command {
 
 	groups := templates.CommandGroups{
 		{
-			Message: "End-to-end pipelines:",
+			Message: "End-to-end Pipelines:",
 			Commands: []*cobra.Command{
 				NewCmdRun(),
 				NewCmdDev(),
 				NewCmdDebug(),
 			},
 		},
 		{
-			Message: "Pipeline building blocks for CI/CD:",
+			Message: "Pipeline Building Blocks:",
 			Commands: []*cobra.Command{
 				NewCmdBuild(),
 				NewCmdTest(),
@@ -173,17 +173,17 @@ func NewSkaffoldCommand(out, errOut io.Writer) *cobra.Command {
 			},
 		},
 		{
-			Message: "Getting started with a new project:",
+			Message: "Getting Started With a New Project:",
 			Commands: []*cobra.Command{
 				NewCmdInit(),
-				NewCmdFix(),
 			},
 		},
 	}
 	groups.Add(rootCmd)
 
 	// other commands
 	rootCmd.AddCommand(NewCmdVersion())
+	rootCmd.AddCommand(NewCmdFix())
 	rootCmd.AddCommand(NewCmdCompletion())
 	rootCmd.AddCommand(NewCmdConfig())
 	rootCmd.AddCommand(NewCmdFindConfigs())
@@ -198,12 +198,12 @@ func NewSkaffoldCommand(out, errOut io.Writer) *cobra.Command {
 	rootCmd.AddCommand(NewCmdInspect())
 
 	templates.ActsAsRootCommand(rootCmd, nil, groups...)
-	rootCmd.PersistentFlags().StringVarP(&v, "verbosity", "v", constants.DefaultLogLevel.String(), "Log level (debug, info, warn, error, fatal, panic)")
+	rootCmd.PersistentFlags().StringVarP(&v, "verbosity", "v", constants.DefaultLogLevel.String(), fmt.Sprintf("Log level: one of %v", logrus.AllLevels))
 	rootCmd.PersistentFlags().IntVar(&defaultColor, "color", int(output.DefaultColorCode), "Specify the default output color in ANSI escape codes")
 	rootCmd.PersistentFlags().BoolVar(&forceColors, "force-colors", false, "Always print color codes (hidden)")
 	rootCmd.PersistentFlags().BoolVar(&interactive, "interactive", true, "Allow user prompts for more information")
 	rootCmd.PersistentFlags().BoolVar(&update.EnableCheck, "update-check", true, "Check for a more recent version of Skaffold")
-	rootCmd.PersistentFlags().BoolVar(&timestamps, "timestamps", false, "Print timestamps in logs.")
+	rootCmd.PersistentFlags().BoolVar(&timestamps, "timestamps", false, "Print timestamps in logs")
 	rootCmd.PersistentFlags().MarkHidden("force-colors")
 
 	setFlagsFromEnvVariables(rootCmd)

cmd/skaffold/app/cmd/config.go

@@ -26,7 +26,7 @@ import (
 func NewCmdConfig() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "config",
-		Short: "Interact with the global skaffold config file (defaults to `$HOME/.skaffold/config`)",
+		Short: "Interact with the global Skaffold config file (defaults to `$HOME/.skaffold/config`)",
 	}
 
 	cmd.AddCommand(NewCmdSet())

cmd/skaffold/app/cmd/credits.go

@@ -24,6 +24,7 @@ import (
 
 func NewCmdCredits() *cobra.Command {
 	return NewCmd("credits").
+		Hidden(). // internal command
 		WithDescription("Export third party notices to given path (./skaffold-credits by default)").
 		WithExample("export third party licenses to ~/skaffold-credits", "credits -d ~/skaffold-credits").
 		WithFlags([]*Flag{

cmd/skaffold/app/cmd/debug.go

@@ -33,7 +33,7 @@ var doDebug = runDebug
 // Unlike `dev`, `debug` defaults `auto-build` and `auto-deploy` to `false`.
 func NewCmdDebug() *cobra.Command {
 	return NewCmd("debug").
-		WithDescription("[beta] Run a pipeline in debug mode").
+		WithDescription("Run a pipeline in debug mode").
 		WithLongDescription("Similar to `dev`, but configures the pipeline for debugging. "+
 			"Auto-build and sync is disabled by default to prevent accidentally tearing down debug sessions.").
 		WithCommonFlags().

cmd/skaffold/app/cmd/delete.go

@@ -29,7 +29,7 @@ import (
 // NewCmdDelete describes the CLI command to delete deployed resources.
 func NewCmdDelete() *cobra.Command {
 	return NewCmd("delete").
-		WithDescription("Delete the deployed application").
+		WithDescription("Delete any resources deployed by Skaffold").
 		WithCommonFlags().
 		NoArgs(doDelete)
 }

cmd/skaffold/app/cmd/filter.go

@@ -44,7 +44,7 @@ func NewCmdFilter() *cobra.Command {
 
 	return NewCmd("filter").
 		Hidden(). // internal command
-		WithDescription("[alpha] Filter and transform a set of Kubernetes manifests from stdin").
+		WithDescription("Filter and transform a set of Kubernetes manifests from stdin").
 		WithLongDescription("Unlike `render`, this command does not build artifacts.").
 		WithCommonFlags().
 		WithFlags([]*Flag{

cmd/skaffold/app/cmd/init.go

@@ -51,7 +51,7 @@ var initEntrypoint = initializer.DoInit
 // NewCmdInit describes the CLI command to generate a Skaffold configuration.
 func NewCmdInit() *cobra.Command {
 	return NewCmd("init").
-		WithDescription("[alpha] Generate configuration for deploying an application").
+		WithDescription("Generate configuration for deploying an application").
 		WithCommonFlags().
 		WithFlags([]*Flag{
 			{Value: &skipBuild, Name: "skip-build", DefValue: false, Usage: "Skip generating build artifacts in Skaffold config", IsEnum: true},

cmd/skaffold/app/cmd/render.go

@@ -40,14 +40,14 @@ var (
 // NewCmdRender describes the CLI command to build artifacts render Kubernetes manifests.
 func NewCmdRender() *cobra.Command {
 	return NewCmd("render").
-		WithDescription("[alpha] Perform all image builds, and output rendered Kubernetes manifests").
+		WithDescription("Perform all image builds, and output rendered Kubernetes manifests").
 		WithExample("Hydrate Kubernetes manifests without building the images, using digest resolved from tag in remote registry ", "render --digest-source=remote").
 		WithCommonFlags().
 		WithFlags([]*Flag{
 			{Value: &showBuild, Name: "loud", DefValue: false, Usage: "Show the build logs and output", IsEnum: true},
 			{Value: &renderFromBuildOutputFile, Name: "build-artifacts", Shorthand: "a", Usage: "File containing build result from a previous 'skaffold build --file-output'"},
 			{Value: &offline, Name: "offline", DefValue: false, Usage: `Do not connect to Kubernetes API server for manifest creation and validation. This is helpful when no Kubernetes cluster is available (e.g. GitOps model). No metadata.namespace attribute is injected in this case - the manifest content does not get changed.`, IsEnum: true},
-			{Value: &renderOutputPath, Name: "output", Shorthand: "o", DefValue: "", Usage: "file to write rendered manifests to"},
+			{Value: &renderOutputPath, Name: "output", Shorthand: "o", DefValue: "", Usage: "File to write rendered manifests to"},
 		}).
 		NoArgs(doRender)
 }

cmd/skaffold/app/cmd/schema.go

@@ -28,7 +28,7 @@ import (
 func NewCmdSchema() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "schema",
-		Short: "List and print json schemas used to validate skaffold.yaml configuration",
+		Short: "List JSON schemas used to validate skaffold.yaml configuration",
 	}
 
 	cmd.AddCommand(NewCmdSchemaGet())
@@ -38,6 +38,7 @@ func NewCmdSchema() *cobra.Command {
 
 func NewCmdSchemaList() *cobra.Command {
 	return NewCmd("list").
+		Hidden(). // internal command
 		WithDescription("List skaffold.yaml's json schema versions").
 		WithExample("List all the versions", "schema list").
 		WithExample("List all the versions, in json format", "schema list -o json").

cmd/skaffold/app/skaffold_test.go

@@ -37,8 +37,8 @@ func TestMainHelp(t *testing.T) {
 		err := Run(&output, &errOutput)
 
 		t.CheckNoError(err)
-		t.CheckContains("End-to-end pipelines", output.String())
-		t.CheckContains("Getting started with a new project", output.String())
+		t.CheckContains("End-to-end Pipelines", output.String())
+		t.CheckContains("Getting Started With a New Project", output.String())
 		t.CheckEmpty(errOutput.String())
 	})
 }
@@ -67,8 +67,8 @@ func TestSkaffoldCmdline_MainHelp(t *testing.T) {
 		err := Run(&output, &errOutput)
 
 		t.CheckNoError(err)
-		t.CheckContains("End-to-end pipelines", output.String())
-		t.CheckContains("Getting started with a new project", output.String())
+		t.CheckContains("End-to-end Pipelines", output.String())
+		t.CheckContains("Getting Started With a New Project", output.String())
 		t.CheckEmpty(errOutput.String())
 	})
 }

docs/content/en/docs/references/cli/_index.md

@@ -66,29 +66,28 @@ To edit this file above edit index_header - the rest of the file is autogenerate
 ```
 
 
-End-to-end pipelines:
+End-to-end Pipelines:
   run               Run a pipeline
   dev               Run a pipeline in development mode
-  debug             [beta] Run a pipeline in debug mode
+  debug             Run a pipeline in debug mode
 
-Pipeline building blocks for CI/CD:
+Pipeline Building Blocks:
   build             Build the artifacts
   test              Run tests against your built application images
   deploy            Deploy pre-built artifacts
-  delete            Delete the deployed application
-  render            [alpha] Perform all image builds, and output rendered Kubernetes manifests
+  delete            Delete any resources deployed by Skaffold
+  render            Perform all image builds, and output rendered Kubernetes manifests
   apply             Apply hydrated manifests to a cluster
 
-Getting started with a new project:
-  init              [alpha] Generate configuration for deploying an application
-  fix               Update old configuration to a newer schema version
+Getting Started With a New Project:
+  init              Generate configuration for deploying an application
 
 Other Commands:
   completion        Output shell completion for the given shell (bash or zsh)
-  config            Interact with the global skaffold config file (defaults to `$HOME/.skaffold/config`)
-  credits           Export third party notices to given path (./skaffold-credits by default)
+  config            Interact with the global Skaffold config file (defaults to `$HOME/.skaffold/config`)
   diagnose          Run a diagnostic on Skaffold
-  schema            List and print json schemas used to validate skaffold.yaml configuration
+  fix               Update old configuration to a newer schema version
+  schema            List JSON schemas used to validate skaffold.yaml configuration
   survey            Opens a web browser to fill out the Skaffold survey
   version           Print the version information
 
@@ -274,7 +273,7 @@ Use "skaffold options" for a list of global command-line options (applies to all
 
 ### skaffold config
 
-Interact with the global skaffold config file (defaults to `$HOME/.skaffold/config`)
+Interact with the global Skaffold config file (defaults to `$HOME/.skaffold/config`)
 
 ```
 
@@ -374,34 +373,9 @@ Env vars:
 * `SKAFFOLD_GLOBAL` (same as `--global`)
 * `SKAFFOLD_KUBE_CONTEXT` (same as `--kube-context`)
 
-### skaffold credits
-
-Export third party notices to given path (./skaffold-credits by default)
-
-```
-
-
-Examples:
-  # export third party licenses to ~/skaffold-credits
-  skaffold credits -d ~/skaffold-credits
-
-Options:
-  -d, --dir='./skaffold-credits': destination directory to place third party licenses
-
-Usage:
-  skaffold credits [options]
-
-Use "skaffold options" for a list of global command-line options (applies to all commands).
-
-
-```
-Env vars:
-
-* `SKAFFOLD_DIR` (same as `--dir`)
-
 ### skaffold debug
 
-[beta] Run a pipeline in debug mode
+Run a pipeline in debug mode
 
 ```
 
@@ -514,7 +488,7 @@ Env vars:
 
 ### skaffold delete
 
-Delete the deployed application
+Delete any resources deployed by Skaffold
 
 ```
 
@@ -846,7 +820,7 @@ Env vars:
 
 ### skaffold init
 
-[alpha] Generate configuration for deploying an application
+Generate configuration for deploying an application
 
 ```
 
@@ -897,16 +871,16 @@ The following options can be passed to any command:
 
       --color=34: Specify the default output color in ANSI escape codes
       --interactive=true: Allow user prompts for more information
-      --timestamps=false: Print timestamps in logs.
+      --timestamps=false: Print timestamps in logs
       --update-check=true: Check for a more recent version of Skaffold
-  -v, --verbosity='warning': Log level (debug, info, warn, error, fatal, panic)
+  -v, --verbosity='warning': Log level: one of [panic fatal error warning info debug trace]
 
 
 ```
 
 ### skaffold render
 
-[alpha] Perform all image builds, and output rendered Kubernetes manifests
+Perform all image builds, and output rendered Kubernetes manifests
 
 ```
 
@@ -927,7 +901,7 @@ Options:
   -m, --module=[]: Filter Skaffold configs to only the provided named modules
   -n, --namespace='': Run deployments in the specified namespace
       --offline=false: Do not connect to Kubernetes API server for manifest creation and validation. This is helpful when no Kubernetes cluster is available (e.g. GitOps model). No metadata.namespace attribute is injected in this case - the manifest content does not get changed.
-  -o, --output='': file to write rendered manifests to
+  -o, --output='': File to write rendered manifests to
   -p, --profile=[]: Activate profiles by name (prefixed with `-` to disable a profile)
       --profile-auto-activation=true: Set to false to disable profile auto activation
       --propagate-profiles=true: Setting '--propagate-profiles=false' disables propagating profiles set by the '--profile' flag across config dependencies. This mean that only profiles defined directly in the target 'skaffold.yaml' file are activated.
@@ -1069,14 +1043,13 @@ Env vars:
 
 ### skaffold schema
 
-List and print json schemas used to validate skaffold.yaml configuration
+List JSON schemas used to validate skaffold.yaml configuration
 
 ```
 
 
 Available Commands:
   get         Print a given skaffold.yaml's json schema
-  list        List skaffold.yaml's json schema versions
 
 Use "skaffold <command> --help" for more information about a given command.
 
@@ -1102,34 +1075,6 @@ Use "skaffold options" for a list of global command-line options (applies to all
 
 ```
 
-### skaffold schema list
-
-List skaffold.yaml's json schema versions
-
-```
-
-
-Examples:
-  # List all the versions
-  skaffold schema list
-
-  # List all the versions, in json format
-  skaffold schema list -o json
-
-Options:
-  -o, --output='plain': Type of output: `plain` or `json`.
-
-Usage:
-  skaffold schema list [options]
-
-Use "skaffold options" for a list of global command-line options (applies to all commands).
-
-
-```
-Env vars:
-
-* `SKAFFOLD_OUTPUT` (same as `--output`)
-
 ### skaffold survey
 
 Opens a web browser to fill out the Skaffold survey