feat: update kusion cli descriptions (#1103)

hack/gen-docs/main.go

@@ -17,7 +17,8 @@ const defaultCmdDocsDir = "docs/cmd/"
 
 var docsMatrix = map[string]string{
 	i18n.LangEnUS: i18n.LangValueEnUS,
-	i18n.LangZhCN: i18n.LangValueZhCN,
+	// TODO: optimize the multi-language support.
+	// i18n.LangZhCN: i18n.LangValueZhCN,
 }
 
 func main() {

pkg/cmd/apply/apply.go

@@ -174,6 +174,13 @@ func (o *ApplyOptions) Run() error {
 		pterm.DisableStyling()
 	}
 
+	// build parameters
+	parameters := make(map[string]string)
+	for _, value := range o.PreviewOptions.Values {
+		parts := strings.SplitN(value, "=", 2)
+		parameters[parts[0]] = parts[1]
+	}
+
 	// Generate Spec
 	spec, err := generate.GenerateSpecWithSpinner(o.RefProject, o.RefStack, o.RefWorkspace, nil, o.UI, o.NoStyle)
 	if err != nil {

pkg/cmd/cmd.go

@@ -58,20 +58,23 @@ func NewDefaultKusionctlCommandWithArgs(o KusionctlOptions) *cobra.Command {
 }
 
 func NewKusionctlCmd(o KusionctlOptions) *cobra.Command {
+	// TODO: optimize the multi-language support.
 	// Sending in 'nil' for the getLanguageFn() results in using LANGUAGE, LC_ALL,
 	// LC_MESSAGES, or LANG environment variable in sequence.
-	_ = i18n.LoadTranslations(i18n.DomainKusion, nil)
+	// _ = i18n.LoadTranslations(i18n.DomainKusion, nil)
 
 	// Parent command to which all subcommands are added.
 	rootCmd := &cobra.Command{
-		Use:   "kusion",
-		Short: i18n.T(`Kusion is the Platform Orchestrator of Internal Developer Platform`),
-		Long: templates.LongDesc(`
-      As a Platform Orchestrator, Kusion delivers user intentions to Kubernetes, Clouds and On-Premise resources.
-      Also enables asynchronous cooperation between the development and the platform team and drives separation of concerns.
-
-      Find more information at:
-            https://www.kusionstack.io/docs/user_docs/reference/cli/kusion/`),
+		Use: "kusion",
+		Short: i18n.T(`Kusion is the Platform Orchestrator of Internal Developer Platform
+		
+Find more information at: https://www.kusionstack.io`),
+		// 	Long: templates.LongDesc(`
+		//   As a Platform Orchestrator, Kusion delivers user intentions to Kubernetes, Clouds and On-Premise infrastructures.
+		//   It also enables asynchronous cooperation between the developer and the platform team, and drives separation of concerns.
+
+		//   Find more information at:
+		//   		https://www.kusionstack.io/docs/`),
 		SilenceErrors: true,
 		Run:           runHelp,
 		// Hook before and after Run initialize and write profiles to disk,
@@ -96,9 +99,14 @@ func NewKusionctlCmd(o KusionctlOptions) *cobra.Command {
 
 	groups := templates.CommandGroups{
 		{
-			Message: "Configuration Commands:",
+			Message: "Initialization Commands:",
 			Commands: []*cobra.Command{
 				cmdinit.NewCmd(),
+			},
+		},
+		{
+			Message: "Configuration Management Commands:",
+			Commands: []*cobra.Command{
 				config.NewCmd(),
 				workspace.NewCmd(),
 				project.NewCmd(),
@@ -107,7 +115,7 @@ func NewKusionctlCmd(o KusionctlOptions) *cobra.Command {
 			},
 		},
 		{
-			Message: "Runtime Commands:",
+			Message: "Operational Commands:",
 			Commands: []*cobra.Command{
 				preview.NewCmdPreview(o.UI, o.IOStreams),
 				apply.NewCmdApply(o.UI, o.IOStreams),
@@ -128,6 +136,7 @@ func NewKusionctlCmd(o KusionctlOptions) *cobra.Command {
 	templates.ActsAsRootCommand(rootCmd, filters, groups...)
 	rootCmd.AddCommand(version.NewCmdVersion())
 	rootCmd.AddCommand(options.NewCmdOptions(o.IOStreams.Out))
+	rootCmd.CompletionOptions.DisableDefaultCmd = true
 
 	return rootCmd
 }

pkg/cmd/generate/generate.go

@@ -25,6 +25,7 @@ import (
 	"github.com/spf13/cobra"
 	yamlv3 "gopkg.in/yaml.v3"
 	"k8s.io/cli-runtime/pkg/genericiooptions"
+	"k8s.io/kubectl/pkg/util/templates"
 
 	v1 "kusionstack.io/kusion/pkg/apis/api.kusion.io/v1"
 	"kusionstack.io/kusion/pkg/cmd/meta"
@@ -46,7 +47,10 @@ var (
 		kusion generate -o /tmp/spec.yaml
 
 		# Generate spec with custom workspace
-		kusion generate -o /tmp/spec.yaml --workspace dev`)
+		kusion generate -o /tmp/spec.yaml --workspace dev
+		
+		# Generate spec with specified arguments
+		kusion generate -D name=test -D age=18`)
 )
 
 // GenerateFlags directly reflect the information that CLI is gathering via flags. They will be converted to
@@ -94,8 +98,8 @@ func NewCmdGenerate(ui *terminal.UI, ioStreams genericiooptions.IOStreams) *cobr
 	cmd := &cobra.Command{
 		Use:     "generate",
 		Short:   "Generate and print the resulting Spec resources of target Stack",
-		Long:    generateLong,
-		Example: generateExample,
+		Long:    templates.LongDesc(generateLong),
+		Example: templates.Examples(generateExample),
 		RunE: func(cmd *cobra.Command, args []string) (err error) {
 			o, err := flags.ToOptions()
 			defer cmdutil.RecoverErr(&err)
@@ -117,7 +121,7 @@ func (flags *GenerateFlags) AddFlags(cmd *cobra.Command) {
 	flags.MetaFlags.AddFlags(cmd)
 
 	cmd.Flags().StringVarP(&flags.Output, "output", "o", flags.Output, i18n.T("File to write generated Spec resources to"))
-	cmd.Flags().StringArrayVar(&flags.Values, "set", []string{}, i18n.T("Set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)"))
+	cmd.Flags().StringArrayVarP(&flags.Values, "argument", "D", []string{}, i18n.T("Specify arguments on the command line"))
 	cmd.Flags().BoolVarP(&flags.NoStyle, "no-style", "", false, i18n.T("no-style sets to RawOutput mode and disables all of styling"))
 }
 

pkg/cmd/mod/mod.go

@@ -3,6 +3,7 @@ package mod
 import (
 	"github.com/spf13/cobra"
 	"k8s.io/cli-runtime/pkg/genericclioptions"
+	"k8s.io/kubectl/pkg/util/templates"
 
 	cmdutil "kusionstack.io/kusion/pkg/cmd/util"
 	"kusionstack.io/kusion/pkg/util/i18n"
@@ -19,7 +20,7 @@ func NewCmdMod(streams genericclioptions.IOStreams) *cobra.Command {
 		Use:                   "mod",
 		DisableFlagsInUseLine: true,
 		Short:                 "Manage Kusion modules",
-		Long:                  modLong,
+		Long:                  templates.LongDesc(modLong),
 		Run:                   cmdutil.DefaultSubCommandRun(streams.ErrOut),
 	}
 

pkg/cmd/mod/mod_push.go

@@ -16,6 +16,7 @@ import (
 	v1 "github.com/google/go-containerregistry/pkg/v1"
 	"github.com/spf13/cobra"
 	"k8s.io/cli-runtime/pkg/genericiooptions"
+	"k8s.io/kubectl/pkg/util/templates"
 	"kcl-lang.io/kpm/pkg/api"
 
 	cmdutil "kusionstack.io/kusion/pkg/cmd/util"
@@ -112,8 +113,8 @@ func NewCmdPush(ioStreams genericiooptions.IOStreams) *cobra.Command {
 		Use:                   "push [MODULE PATH] [OCI REPOSITORY URL]",
 		DisableFlagsInUseLine: true,
 		Short:                 "Push a module to OCI registry",
-		Long:                  pushLong,
-		Example:               pushExample,
+		Long:                  templates.LongDesc(pushLong),
+		Example:               templates.Examples(pushExample),
 		RunE: func(cmd *cobra.Command, args []string) (err error) {
 			o, err := flags.ToOptions(args, flags.IOStreams)
 			defer cmdutil.RecoverErr(&err)

pkg/cmd/preview/preview.go

@@ -17,6 +17,7 @@ package preview
 import (
 	"encoding/json"
 	"fmt"
+	"strings"
 
 	"github.com/pterm/pterm"
 	"github.com/spf13/cobra"
@@ -53,7 +54,7 @@ var (
 		kusion preview -D name=test -D age=18
 
 		# Preview with ignored fields
-		kusion preview --ignore-fields="metadata.generation,metadata.managedFields
+		kusion preview --ignore-fields="metadata.generation,metadata.managedFields"
 		
 		# Preview with json format result
 		kusion preview -o json
@@ -77,6 +78,7 @@ type PreviewFlags struct {
 	NoStyle      bool
 	Output       string
 	IgnoreFields []string
+	Values       []string
 
 	UI *terminal.UI
 
@@ -93,6 +95,7 @@ type PreviewOptions struct {
 	NoStyle      bool
 	Output       string
 	IgnoreFields []string
+	Values       []string
 
 	UI *terminal.UI
 
@@ -143,6 +146,7 @@ func (f *PreviewFlags) AddFlags(cmd *cobra.Command) {
 	cmd.Flags().BoolVarP(&f.NoStyle, "no-style", "", false, i18n.T("no-style sets to RawOutput mode and disables all of styling"))
 	cmd.Flags().StringSliceVarP(&f.IgnoreFields, "ignore-fields", "", f.IgnoreFields, i18n.T("Ignore differences of target fields"))
 	cmd.Flags().StringVarP(&f.Output, "output", "o", f.Output, i18n.T("Specify the output format"))
+	cmd.Flags().StringArrayVarP(&f.Values, "argument", "D", []string{}, i18n.T("Specify arguments on the command line"))
 }
 
 // ToOptions converts from CLI inputs to runtime inputs.
@@ -163,6 +167,7 @@ func (f *PreviewFlags) ToOptions() (*PreviewOptions, error) {
 		IgnoreFields: f.IgnoreFields,
 		UI:           f.UI,
 		IOStreams:    f.IOStreams,
+		Values:       f.Values,
 	}
 
 	return o, nil
@@ -184,8 +189,15 @@ func (o *PreviewOptions) Run() error {
 		pterm.DisableStyling()
 	}
 
+	// build parameters
+	parameters := make(map[string]string)
+	for _, value := range o.Values {
+		parts := strings.SplitN(value, "=", 2)
+		parameters[parts[0]] = parts[1]
+	}
+
 	// Generate spec
-	spec, err := generate.GenerateSpecWithSpinner(o.RefProject, o.RefStack, o.RefWorkspace, nil, o.UI, o.NoStyle)
+	spec, err := generate.GenerateSpecWithSpinner(o.RefProject, o.RefStack, o.RefWorkspace, parameters, o.UI, o.NoStyle)
 	if err != nil {
 		return err
 	}