diff --git a/cmd/registry/cmd/apply/apply.go b/cmd/registry/cmd/apply/apply.go index 2a7822791..dd9ee4ed7 100644 --- a/cmd/registry/cmd/apply/apply.go +++ b/cmd/registry/cmd/apply/apply.go @@ -33,10 +33,12 @@ func Command() *cobra.Command { cmd := &cobra.Command{ Use: "apply (-f FILE | -f -)", Short: "Apply YAML to the API Registry", - Long: "Apply YAML to the API Registry by files / folder names or stdin. " + - "Resources will be created if they don't exist yet. " + - "Multiple files may be specified by repeating the -f flag." + - "\n\nMore info and example usage at https://github.com/apigee/registry/wiki/registry-apply", + Long: `Apply YAML to the API Registry by files / folder names or stdin. + +Resources will be created if they don't exist yet. +Multiple files may be specified by repeating the -f flag. + +More info and example usage at https://github.com/apigee/registry/wiki/registry-apply.`, Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, args []string) error { if len(files) > 1 { diff --git a/cmd/registry/cmd/auth/auth.go b/cmd/registry/cmd/auth/auth.go index c819d0bf2..8fd3e2846 100644 --- a/cmd/registry/cmd/auth/auth.go +++ b/cmd/registry/cmd/auth/auth.go @@ -24,14 +24,21 @@ import ( func Command() *cobra.Command { cmd := &cobra.Command{ Use: "auth", - Short: "Manage authentication to the API Registry", - Long: "Authentication to the registry is via tokens. These tokens can be provided " + - "directly by using '--registry.token' in any command, or can be generated as needed " + - "by setting the token-source property in a configuration. The token-source can be set " + - "to any executable command that prints a registry token by using the 'config set token-source'. " + - "Once set, the command will be executed before a registry command is run and the output used " + - "as the token passed to the registry. The output can be verified by 'auth print-token'.", - Example: "config set token-source 'gcloud auth print-access-token email@example.com'", + Short: "Manage client authentication to the API Registry", + Long: `Manage client authentication to the API Registry. + +Authentication to the registry is via tokens. These tokens can be provided +directly by using '--registry.token' in any command, or can be generated as +needed by setting the token-source property in a configuration. + +The token-source can be set to any executable command that prints a registry +token by using 'registry config set token-source'. Once set, the command will +be executed before a registry command is run and the output used as the token +passed to the registry. + +Output of the token-source setting can be verified by 'auth print-token'.`, + Example: `registry config set token-source 'gcloud auth print-access-token email@example.com +registry auth print-token`, } cmd.AddCommand(printTokenCommand()) diff --git a/cmd/registry/cmd/config/config.go b/cmd/registry/cmd/config/config.go index 520314c31..e251e19e4 100644 --- a/cmd/registry/cmd/config/config.go +++ b/cmd/registry/cmd/config/config.go @@ -23,10 +23,21 @@ func Command() *cobra.Command { cmd := &cobra.Command{ Use: "config", Short: "Maintain properties in the active configuration", - Long: "Configurations manage sets of properties used when connecting to the registry. " + - "These commands manipulate the property values in the active configuration. " + - "See `config configurations --help` for information on how to manage configurations. " + - "See `config set --help` for the list of properties available.", + Long: `Maintain properties in the active configuration. + +Configurations manage sets of properties used when a client connects to the +API Registry. These commands display manipulate the property values in the +active configuration. + +The following are valid configuration properties: + - address + - insecure + - location + - project + - token-source + +See 'config configurations --help' for information on how to manage configurations. +See 'config set --help' for the list of properties available.`, } cmd.AddCommand(configurations.Command()) diff --git a/cmd/registry/cmd/config/configurations/activate.go b/cmd/registry/cmd/config/configurations/activate.go index 45062b363..3c55aee23 100644 --- a/cmd/registry/cmd/config/configurations/activate.go +++ b/cmd/registry/cmd/config/configurations/activate.go @@ -23,9 +23,10 @@ import ( func activateCommand() *cobra.Command { cmd := &cobra.Command{ - Use: "activate CONFIGURATION", - Short: "Activates an existing named configuration", - Args: cobra.ExactArgs(1), + Use: "activate CONFIGURATION", + Short: "Activates an existing named configuration", + Example: `registry config configurations activate local`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { name := args[0] if err := config.ValidateName(name); err != nil { diff --git a/cmd/registry/cmd/config/configurations/configurations.go b/cmd/registry/cmd/config/configurations/configurations.go index 2a9371377..9f9a17834 100644 --- a/cmd/registry/cmd/config/configurations/configurations.go +++ b/cmd/registry/cmd/config/configurations/configurations.go @@ -22,11 +22,17 @@ func Command() *cobra.Command { cmd := &cobra.Command{ Use: "configurations", Short: "Maintain named configurations of properties", - Long: "Configurations manage sets of properties used when connecting to the registry. " + - "These commands manipulate named sets of these properties, called 'configurations'. " + - "When a configuration is 'active', it's properties are automatically loaded and used " + - "by registry commands. See `registry config` for manipulating the properties themselves. " + - "Configuration files are stored in the $HOME/.config/registry folder.", + Long: `Maintain named configurations of properties. + +Configurations are sets of properties used by a client when connecting to +the API Registry. These commands manipulate these named sets of properties +stored in the '$HOME/.config/registry folder. + +When a configuration is 'active', its properties are automatically loaded +and used, although they can be overridden by flags and environment variables. + +See 'registry config' for commands to manipulate the properties within a +configuration.`, } cmd.AddCommand(activateCommand()) diff --git a/cmd/registry/cmd/config/configurations/create.go b/cmd/registry/cmd/config/configurations/create.go index 18fad23a1..893017264 100644 --- a/cmd/registry/cmd/config/configurations/create.go +++ b/cmd/registry/cmd/config/configurations/create.go @@ -30,10 +30,13 @@ func createCommand() *cobra.Command { cmd := &cobra.Command{ Use: "create CONFIGURATION", Short: "Creates and activates a new named configuration", - Long: "Creates and activates a new named configuration. Values will be populated from active " + - "configuration (if any) and any passed property flags (unless using --gcloud).", - Example: "registry config configurations create localhost --registry.address='locahost:8080'\n" + - "registry config configurations create hosted --gcloud", + Long: `Creates and activates a new named configuration. + +Values in the new configuration will default to the currently active +configuration (if any) but can be overridden by setting property flags +(unless using --gcloud).`, + Example: `registry config configurations create localhost --registry.address='locahost:8080' +registry config configurations create hosted --gcloud`, Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { name := args[0] diff --git a/cmd/registry/cmd/config/configurations/delete.go b/cmd/registry/cmd/config/configurations/delete.go index aa682caba..f57d2e672 100644 --- a/cmd/registry/cmd/config/configurations/delete.go +++ b/cmd/registry/cmd/config/configurations/delete.go @@ -24,9 +24,10 @@ import ( func deleteCommand() *cobra.Command { cmd := &cobra.Command{ - Use: "delete CONFIGURATION_1 ... CONFIGURATION_N", - Short: "Deletes a named configuration", - Args: cobra.MinimumNArgs(1), + Use: "delete CONFIGURATION_1 ... CONFIGURATION_N", + Short: "Deletes a named configuration", + Example: `registry config configurations delete local`, + Args: cobra.MinimumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { for _, name := range args { if err := config.ValidateName(name); err != nil { diff --git a/cmd/registry/cmd/config/configurations/describe.go b/cmd/registry/cmd/config/configurations/describe.go index 7ccc1d1d4..9dd67ccba 100644 --- a/cmd/registry/cmd/config/configurations/describe.go +++ b/cmd/registry/cmd/config/configurations/describe.go @@ -24,9 +24,10 @@ import ( func describeCommand() *cobra.Command { cmd := &cobra.Command{ - Use: "describe CONFIGURATION", - Short: "Describes a named configuration by listing its properties", - Args: cobra.ExactArgs(1), + Use: "describe CONFIGURATION", + Short: "Describes a named configuration by listing its properties", + Example: `registry config configurations describe localhost`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { name := args[0] s, err := config.Read(name) diff --git a/cmd/registry/cmd/config/configurations/list.go b/cmd/registry/cmd/config/configurations/list.go index eed578722..bfd03301a 100644 --- a/cmd/registry/cmd/config/configurations/list.go +++ b/cmd/registry/cmd/config/configurations/list.go @@ -27,9 +27,10 @@ import ( func listCommand() *cobra.Command { cmd := &cobra.Command{ - Use: "list", - Short: "Lists existing named configs", - Args: cobra.NoArgs, + Use: "list", + Short: "Lists existing named configurations", + Example: `registry config configurations list`, + Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { configs, err := config.Configurations() if errors.Is(err, fs.ErrNotExist) || len(configs) == 0 { diff --git a/cmd/registry/cmd/config/get.go b/cmd/registry/cmd/config/get.go index 9311fec61..9a03913f2 100644 --- a/cmd/registry/cmd/config/get.go +++ b/cmd/registry/cmd/config/get.go @@ -23,9 +23,18 @@ import ( func getCommand() *cobra.Command { cmd := &cobra.Command{ - Use: "get PROPERTY", - Short: "Print a property value in the active configuration", - Args: cobra.ExactArgs(1), + Use: "get PROPERTY", + Short: "Print a property value in the active configuration", + Example: `registry config get address`, + Long: `Print a property value in the active configuration. + +The following are valid configuration properties: + - address + - insecure + - location + - project + - token-source`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { _, c, err := config.ActiveRaw() if err != nil { diff --git a/cmd/registry/cmd/config/list.go b/cmd/registry/cmd/config/list.go index 9f5aabb45..cb6627cf2 100644 --- a/cmd/registry/cmd/config/list.go +++ b/cmd/registry/cmd/config/list.go @@ -23,9 +23,10 @@ import ( func listCommand() *cobra.Command { cmd := &cobra.Command{ - Use: "list", - Short: "List properties in the active configuration", - Args: cobra.NoArgs, + Use: "list", + Short: "List properties in the active configuration", + Example: `registry config list`, + Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { target, c, err := config.ActiveRaw() if err != nil { diff --git a/cmd/registry/cmd/config/set.go b/cmd/registry/cmd/config/set.go index d7b48db78..0ea8eb9be 100644 --- a/cmd/registry/cmd/config/set.go +++ b/cmd/registry/cmd/config/set.go @@ -25,14 +25,16 @@ func setCommand() *cobra.Command { cmd := &cobra.Command{ Use: "set PROPERTY VALUE", Short: "Set a property value in the active configuration", - Long: "Set a property value in the active configuration. The following are valid properties:\n" + - " - registry.address\n" + - " - registry.insecure\n" + - " - registry.location\n" + - " - registry.project\n" + - " - token-source", - Example: "registry config set registry.address localhost:8080\n" + - "registry config set token-source 'gcloud auth print-access-token email@example.com'", + Long: `Set a property value in the active configuration. + +The following are valid configuration properties: + - address + - insecure + - location + - project + - token-source`, + Example: `registry config set address localhost:8080 +registry config set token-source 'gcloud auth print-access-token email@example.com'`, Args: cobra.ExactArgs(2), RunE: func(cmd *cobra.Command, args []string) error { target, c, err := config.ActiveRaw()