Update kv and pg help text based on feedback from docs team (#504)

Updates help text for all pg and kv commands based on feedback from docs team.

GROW-2707

GitOrigin-RevId: 8936f4b65a20f6b8043f12101a3200fbf9e688d4

Author: davidharting

cmd/kv.go

@@ -5,8 +5,8 @@ import "github.com/spf13/cobra"
 func newKVCmd(children ...*cobra.Command) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "kv",
-		Aliases: []string{"keyvalue"},
-		Short:   "Manage Key Value store instances (early access)",
+		Aliases: []string{"keyvalues", "keyvalue"},
+		Short:   "Manage Render Key Value instances (early access)",
 	}
 	cmd.AddCommand(children...)
 	return cmd

cmd/kvcreate.go

@@ -17,17 +17,15 @@ import (
 func newKVCreateCmd(deps *dependencies.Dependencies) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
-		Short: "Create a new Key Value store instance",
+		Short: "Create a new Render Key Value instance",
 		Args:  cobra.NoArgs,
-		Long: `Create a new Key Value store instance on Render.
+		Long: `Create a new Render Key Value instance.
 
 In interactive mode, a prompt guides you through each option one at a time.
 In non-interactive mode (--output text/json/yaml), flags use defaults if not supplied.
 Use --confirm to skip all prompts (including final confirmation) and create immediately.
-Output will be human-readable; use --output json/yaml/text for machine-readable output.
-
-Examples:
-  # Interactive wizard (guided prompts for each option)
+Output will be human-readable; use --output json/yaml/text for machine-readable output.`,
+		Example: `  # Interactive wizard (guided prompts for each option)
   render ea kv create
 
   # Specify all options; wizard still asks for confirmation before creating
@@ -45,27 +43,25 @@ Examples:
     --ip-allow-list "cidr=10.0.0.0/8,description=internal"`,
 	}
 
-	cmd.Flags().String("name", "", "Key Value instance name (generated if not provided)")
-	cmd.Flags().String("workspace", "", "Workspace ID or name. Defaults to the active workspace (set via 'render workspace set').")
-	cmd.Flags().String("project", "", "Project ID or name (optional). Scopes environment lookup; if the project has exactly one environment it is used automatically.")
-	cmd.Flags().String("environment", "", "Environment ID or name (optional). Example: Production or evm-abc123def456")
+	cmd.Flags().String("name", "", "Set the Key Value instance name (generated if not provided)")
+	cmd.Flags().String("workspace", "", "Set the workspace to create the Key Value in (ID or name). Defaults to the active workspace (set via 'render workspace set').")
+	cmd.Flags().String("project", "", "Scope environment lookup to a project (ID or name, optional); if the project has exactly one environment it is used automatically.")
+	cmd.Flags().String("environment", "", "Set the environment to create the Key Value in (ID or name, optional). Example: Production or evm-abc123def456")
 
 	cmd.Flags().String("plan", "",
-		"Plan name. Examples: free | starter | standard | pro | pro_plus. Account-specific plan names are accepted.")
+		"Set the plan to one of: free | starter | standard | pro | pro_plus. Custom enterprise plan names are also accepted.")
 
 	regionFlag := command.NewEnumInput(types.RegionValues(), false)
-	cmd.Flags().Var(regionFlag, "region", "Region: frankfurt | ohio | oregon | singapore | virginia")
+	cmd.Flags().Var(regionFlag, "region", "Set the region: frankfurt | ohio | oregon | singapore | virginia")
 
 	maxmemFlag := command.NewEnumInput(kvtypes.MemoryPolicyInputValues(), false)
 	cmd.Flags().Var(maxmemFlag, "memory-policy",
-		"Controls what the instance does when it runs out of memory to store new data.\n"+
-			"Shortcuts: cache (sets allkeys_lru, recommended for caching) | queue (sets noeviction, recommended for job queues).\n"+
-			"Technical values: noeviction | allkeys_lru | allkeys_lfu | allkeys_random | volatile_lru | volatile_lfu | volatile_random | volatile_ttl")
+		"Set the eviction policy used when the instance runs out of memory.\n"+
+			"Accepts a friendly alias — cache (= allkeys_lru, for caching) or queue (= noeviction, for job queues) —\n"+
+			"or any raw policy: noeviction | allkeys_lru | allkeys_lfu | allkeys_random | volatile_lru | volatile_lfu | volatile_random | volatile_ttl")
 
 	cmd.Flags().StringArray("ip-allow-list", nil,
-		"Restrict inbound traffic to specific IP ranges. Repeat the flag for multiple entries.\n"+
-			"Format: cidr=<range>,description=<label>\n"+
-			"Example: --ip-allow-list \"cidr=203.0.113.5/32,description=office\"")
+		"Restrict inbound traffic to specific IP ranges (format: cidr=<range>,description=<label>). Repeat the flag for multiple entries.")
 
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		var input kvtypes.KeyValueCreateInput
@@ -123,7 +119,7 @@ func runKVCreateAndPrint(cmd *cobra.Command, deps *dependencies.Dependencies, in
 
 func kvCreateSuccessMessage(kv *keyvalue.KeyValueOut) string {
 	return fmt.Sprintf(
-		"Created Key Value store\n\n%s\n",
+		"Created Render Key Value\n\n%s\n",
 		text.KeyValueDetail(kv),
 	)
 }

cmd/kvcreate_test.go

@@ -430,7 +430,7 @@ func TestKVCreate_InvalidRegion(t *testing.T) {
 	assert.Contains(t, result.Stderr, `"oregon"`)
 	assert.Contains(t, result.Stderr, `"virginia"`)
 	assert.Contains(t, result.Stdout, "Usage:")
-	assert.Contains(t, result.Stdout, "Region: frankfurt | ohio | oregon | singapore | virginia")
+	assert.Contains(t, result.Stdout, "Set the region: frankfurt | ohio | oregon | singapore | virginia")
 	assert.Empty(t, server.KV.Instances)
 }
 
@@ -446,8 +446,8 @@ func TestKVCreate_InvalidMemoryPolicy(t *testing.T) {
 	assert.Contains(t, result.Stderr, `"queue"`)
 	assert.Contains(t, result.Stderr, `"noeviction"`)
 	assert.Contains(t, result.Stdout, "Usage:")
-	assert.Contains(t, result.Stdout, "Shortcuts: cache")
-	assert.Contains(t, result.Stdout, "Technical values: noeviction")
+	assert.Contains(t, result.Stdout, "Accepts a friendly alias — cache")
+	assert.Contains(t, result.Stdout, "or any raw policy: noeviction")
 	assert.Empty(t, server.KV.Instances)
 }
 

cmd/kvdelete.go

@@ -13,10 +13,10 @@ import (
 func newKVDeleteCmd(deps *dependencies.Dependencies) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:          "delete <keyValueID|keyValueName>",
-		Short:        "Delete a Key Value store instance",
+		Short:        "Delete a Render Key Value instance",
 		Args:         cobra.ExactArgs(1),
 		SilenceUsage: true,
-		Long: `Delete a Key Value store instance on Render.
+		Long: `Delete a Render Key Value instance.
 
 Without --confirm, this command previews what would be deleted and makes no
 changes. Pass --confirm to actually delete the instance.
@@ -45,7 +45,7 @@ Key Value ID instead (which works across workspaces).`,
 	}
 
 	cmd.Flags().String("environment", "",
-		"Environment ID or name (optional). Narrows name lookup when the same Key Value name exists in multiple environments.")
+		"Narrow lookup to an environment (ID or name, optional) when the same Key Value name exists in multiple environments.")
 
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		// No interactive flow yet; collapse --output interactive (the default in a TTY)

cmd/kvget.go

@@ -13,10 +13,10 @@ import (
 func newKVGetCmd(deps *dependencies.Dependencies) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:          "get <keyValueID|keyValueName>",
-		Short:        "Get details of a Key Value store instance",
+		Short:        "Get details of a Render Key Value instance",
 		Args:         cobra.ExactArgs(1),
 		SilenceUsage: true,
-		Long: `Get details and connection info for a Key Value store instance on Render.
+		Long: `Get details and connection info for a Render Key Value instance.
 
 The positional argument accepts either a Key Value ID (red-...) or a name.
 If the name matches more than one instance, narrow the search with
@@ -46,9 +46,9 @@ Key Value ID instead (which works across workspaces).`,
 	}
 
 	cmd.Flags().String("project", "",
-		"Project ID or name (optional). Narrows name lookup within the active workspace.")
+		"Narrow lookup to a project (ID or name, optional) within the active workspace.")
 	cmd.Flags().String("environment", "",
-		"Environment ID or name (optional). Narrows name lookup when the same Key Value name exists in multiple environments.")
+		"Narrow lookup to an environment (ID or name, optional) when the same Key Value name exists in multiple environments.")
 	cmd.Flags().Bool("include-sensitive-connection-info", false,
 		"Include connection strings and credentials in the output")
 

cmd/kvlist.go

@@ -17,10 +17,10 @@ import (
 func newKVListCmd(deps *dependencies.Dependencies) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:          "list",
-		Short:        "List Key Value store instances",
+		Short:        "List Render Key Value instances",
 		Args:         cobra.NoArgs,
 		SilenceUsage: true,
-		Long: `List Key Value store instances in the active workspace.
+		Long: `List Render Key Value instances in the active workspace.
 
 Use --project to narrow results to a single project, --environment to narrow
 to a single environment, or both — when both are supplied, the environment is
@@ -42,9 +42,9 @@ resolved within that project.`,
 	}
 
 	cmd.Flags().String("project", "",
-		"Project ID or name (optional). Narrows results to environments in this project.")
+		"Narrow results to environments in a project (ID or name, optional).")
 	cmd.Flags().String("environment", "",
-		"Environment ID or name (optional). Narrows results to this environment.")
+		"Narrow results to a single environment (ID or name, optional).")
 
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		command.DefaultFormatNonInteractive(cmd)

cmd/kvresume.go

@@ -13,10 +13,10 @@ import (
 func newKVResumeCmd(deps *dependencies.Dependencies) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:          "resume <keyValueID|keyValueName>",
-		Short:        "Resume a suspended Key Value store instance",
+		Short:        "Resume a suspended Render Key Value instance",
 		Args:         cobra.ExactArgs(1),
 		SilenceUsage: true,
-		Long: `Resume a suspended Key Value store instance on Render.
+		Long: `Resume a suspended Render Key Value instance.
 
 The positional argument accepts either a Key Value ID (red-...) or a name.
 If the name matches more than one instance, narrow the search with
@@ -39,7 +39,7 @@ Key Value ID instead (which works across workspaces).`,
 	}
 
 	cmd.Flags().String("environment", "",
-		"Environment ID or name (optional). Narrows name lookup when the same Key Value name exists in multiple environments.")
+		"Narrow lookup to an environment (ID or name, optional) when the same Key Value name exists in multiple environments.")
 
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		command.DefaultFormatNonInteractive(cmd)

cmd/kvsuspend.go

@@ -13,10 +13,10 @@ import (
 func newKVSuspendCmd(deps *dependencies.Dependencies) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:          "suspend <keyValueID|keyValueName>",
-		Short:        "Suspend a Key Value store instance",
+		Short:        "Suspend a Render Key Value instance",
 		Args:         cobra.ExactArgs(1),
 		SilenceUsage: true,
-		Long: `Suspend a Key Value store instance on Render.
+		Long: `Suspend a Render Key Value instance.
 
 Without --confirm, this command previews what would be suspended and makes no
 changes. Pass --confirm to actually suspend the instance.
@@ -45,7 +45,7 @@ Key Value ID instead (which works across workspaces).`,
 	}
 
 	cmd.Flags().String("environment", "",
-		"Environment ID or name (optional). Narrows name lookup when the same Key Value name exists in multiple environments.")
+		"Narrow lookup to an environment (ID or name, optional) when the same Key Value name exists in multiple environments.")
 
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		command.DefaultFormatNonInteractive(cmd)

cmd/kvupdate.go

@@ -16,23 +16,24 @@ import (
 func newKVUpdateCmd(deps *dependencies.Dependencies) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:          "update <keyValueID|keyValueName>",
-		Short:        "Update a Key Value store instance",
+		Short:        "Update a Render Key Value instance",
 		Args:         cobra.ExactArgs(1),
 		SilenceUsage: true,
-		Long: `Update an existing Key Value store instance on Render.
+		Long: `Update an existing Render Key Value instance.
 
 The positional argument is the target Key Value (ID red-... or name). At least
 one mutating flag must be supplied. Use --name to rename the instance; the
 positional argument always identifies the target and is never the new name.
 
+Environment, project, workspace, and region are immutable. A Key Value instance
+cannot be moved between them; the --environment flag is for name disambiguation
+only.
+
 Name lookup is scoped to your active workspace. If a name isn't found, switch
 workspaces with 'render workspace set <name|ID>' and try again, or pass the
 Key Value ID instead (which works across workspaces). If a name matches more
 than one instance, narrow the search with --environment <id|name>.
 
-Environment, project, workspace, and region are immutable. A KV cannot be
-moved between them; the --environment flag is for name disambiguation only.
-
 The --ip-allow-list flag replaces the server-side list; pass it once per entry.
 To remove all allow-list entries, pass --clear-ip-allow-list. The two flags are
 mutually exclusive.`,
@@ -57,20 +58,18 @@ mutually exclusive.`,
   render ea kv update red-abc123def456ghi789jkl0 --plan pro --output json`,
 	}
 
-	memoryPolicyDesc := `Controls what the instance does when it runs out of memory to store new data.
-Shortcuts: cache (sets allkeys_lru, recommended for caching) | queue (sets noeviction, recommended for job queues).
-Technical values: noeviction | allkeys_lru | allkeys_lfu | allkeys_random | volatile_lru | volatile_lfu | volatile_random | volatile_ttl`
+	memoryPolicyDesc := `Set the eviction policy used when the instance runs out of memory.
+Accepts a friendly alias — cache (= allkeys_lru, for caching) or queue (= noeviction, for job queues) —
+or any raw policy: noeviction | allkeys_lru | allkeys_lfu | allkeys_random | volatile_lru | volatile_lfu | volatile_random | volatile_ttl`
 
-	ipAllowListDesc := `Replace the IP allow-list with the supplied entries. Repeat the flag for multiple entries.
-Format: cidr=<range>,description=<label>
-Example: --ip-allow-list "cidr=203.0.113.5/32,description=office"`
+	ipAllowListDesc := `Replace the IP allow-list with the supplied entries (format: cidr=<range>,description=<label>). Repeat the flag for multiple entries.`
 
 	cmd.Flags().String("environment", "",
-		"Environment ID or name (optional). Narrows name lookup when the same Key Value name exists in multiple environments")
+		"Narrow lookup to an environment (ID or name, optional) when the same Key Value name exists in multiple environments")
 
 	cmd.Flags().String("name", "", "Rename the Key Value instance")
 	cmd.Flags().String("plan", "",
-		"Plan name. Examples: free | starter | standard | pro | pro_plus. Account-specific plan names are accepted")
+		"Set the plan to one of: free | starter | standard | pro | pro_plus. Custom enterprise plan names are also accepted.")
 
 	maxmemFlag := command.NewEnumInput(kvtypes.MemoryPolicyInputValues(), false)
 	cmd.Flags().Var(maxmemFlag, "memory-policy", memoryPolicyDesc)

cmd/pg.go

@@ -6,8 +6,8 @@ func newPgCmd(children ...*cobra.Command) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "pg",
 		Aliases: []string{"postgres"},
-		Short:   "Manage Postgres databases",
-		Long: `Manage Postgres databases.
+		Short:   "Manage Render Postgres databases",
+		Long: `Manage Render Postgres databases.
 
 Lives under 'ea' while the command surface stabilizes. Postgres itself is
 generally available, but the flag set and output format for these commands may