feat: auto-generate deprecation warnings from YAML config

internal/commandsgen/code.go

@@ -237,9 +237,9 @@ func (c *Command) writeCode(w *codeWriter) error {
 		w.writeLinef("s.Command.Annotations = make(map[string]string)")
 		w.writeLinef("s.Command.Annotations[\"ignoresMissingEnv\"] = \"true\"")
 	}
-	if c.Deprecated != "" {
-		w.writeLinef("s.Command.Deprecated = %q", c.Deprecated)
-	}
+	// Note: We intentionally don't set s.Command.Deprecated here because Cobra
+	// prints deprecation warnings to stdout, which breaks JSON output. Instead,
+	// the deprecation warning is prepended to the description/help text.
 	// Add subcommands
 	for _, subCommand := range subCommands {
 		w.writeLinef("s.Command.AddCommand(&New%v(cctx, &s).Command)", subCommand.structName())

internal/commandsgen/parse.go

@@ -39,8 +39,9 @@ type (
 		Description            string `yaml:"description"`
 		DescriptionPlain       string
 		DescriptionHighlighted string
-		Deprecated             string   `yaml:"deprecated"`
-		HasInit                bool     `yaml:"has-init"`
+		Deprecated             bool   `yaml:"deprecated"`
+		DeprecationMessage     string `yaml:"deprecation-message"`
+		HasInit                bool   `yaml:"has-init"`
 		ExactArgs              int      `yaml:"exact-args"`
 		MaximumArgs            int      `yaml:"maximum-args"`
 		IgnoreMissingEnv       bool     `yaml:"ignores-missing-env"`
@@ -137,6 +138,22 @@ var markdownInlineCodeRegex = regexp.MustCompile("`([^`]+)`")
 const ansiReset = "\033[0m"
 const ansiBold = "\033[1m"
 
+const defaultDeprecationMessage = "This command is deprecated and will be removed in a later release."
+
+// generateDeprecationBox creates a formatted CAUTION box for deprecated commands.
+// If message is empty, uses the default deprecation message.
+func generateDeprecationBox(message string) string {
+	if message == "" {
+		message = defaultDeprecationMessage
+	}
+	content := "CAUTION: " + message
+	// Calculate box width (content + 2 spaces padding + 2 border chars)
+	boxWidth := len(content) + 4
+	border := "+" + strings.Repeat("-", boxWidth-2) + "+"
+	middle := "| " + content + " |"
+	return "```\n" + border + "\n" + middle + "\n" + border + "\n```\n\n"
+}
+
 func (o OptionSets) processSection() error {
 	if o.Name == "" {
 		return fmt.Errorf("missing option set name")
@@ -172,6 +189,11 @@ func (c *Command) processSection() error {
 		return fmt.Errorf("missing description for command: %s", c.FullName)
 	}
 
+	// Prepend deprecation warning box if command is deprecated
+	if c.Deprecated {
+		c.Description = generateDeprecationBox(c.DeprecationMessage) + c.Description
+	}
+
 	if len(c.NamePath) == 2 {
 		if c.Docs.Keywords == nil {
 			return fmt.Errorf("missing keywords for root command: %s", c.FullName)

internal/commandsgen/parse_test.go

@@ -0,0 +1,48 @@
+package commandsgen
+
+import "testing"
+
+func TestGenerateDeprecationBox(t *testing.T) {
+	tests := []struct {
+		name     string
+		message  string
+		expected string
+	}{
+		{
+			name:    "default message when empty",
+			message: "",
+			expected: "```\n" +
+				"+-----------------------------------------------------------------------------+\n" +
+				"| CAUTION: This command is deprecated and will be removed in a later release. |\n" +
+				"+-----------------------------------------------------------------------------+\n" +
+				"```\n\n",
+		},
+		{
+			name:    "custom message",
+			message: "Use the new API instead.",
+			expected: "```\n" +
+				"+-----------------------------------+\n" +
+				"| CAUTION: Use the new API instead. |\n" +
+				"+-----------------------------------+\n" +
+				"```\n\n",
+		},
+		{
+			name:    "short custom message",
+			message: "Removed.",
+			expected: "```\n" +
+				"+-------------------+\n" +
+				"| CAUTION: Removed. |\n" +
+				"+-------------------+\n" +
+				"```\n\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := generateDeprecationBox(tt.message)
+			if got != tt.expected {
+				t.Errorf("generateDeprecationBox(%q) =\n%q\nwant:\n%q", tt.message, got, tt.expected)
+			}
+		})
+	}
+}

internal/temporalcli/commands.gen.go

@@ -2578,9 +2578,9 @@ func NewTemporalTaskQueueVersioningCommand(cctx *CommandContext, parent *Tempora
 	s.Command.Use = "versioning"
 	s.Command.Short = "Manage Task Queue Build ID handling (Deprecated)"
 	if hasHighlighting {
-		s.Command.Long = "\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\x1b[0m\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n\x1b[1mtemporal task-queue versioning [subcommands] [options] \\\n    --task-queue YourTaskQueue\x1b[0m\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n  Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n  which are evaluated from first to last. Assignment Rules also allow for\n  gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n  Build ID. You may add at most one redirect rule for each source Build ID.\n  Redirect rules require that a target Build ID is fully compatible with\n  the source Build ID."
+		s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n\x1b[1mtemporal task-queue versioning [subcommands] [options] \\\n    --task-queue YourTaskQueue\x1b[0m\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n  Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n  which are evaluated from first to last. Assignment Rules also allow for\n  gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n  Build ID. You may add at most one redirect rule for each source Build ID.\n  Redirect rules require that a target Build ID is fully compatible with\n  the source Build ID."
 	} else {
-		s.Command.Long = "```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\n```\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n```\ntemporal task-queue versioning [subcommands] [options] \\\n    --task-queue YourTaskQueue\n```\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n  Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n  which are evaluated from first to last. Assignment Rules also allow for\n  gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n  Build ID. You may add at most one redirect rule for each source Build ID.\n  Redirect rules require that a target Build ID is fully compatible with\n  the source Build ID."
+		s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n```\ntemporal task-queue versioning [subcommands] [options] \\\n    --task-queue YourTaskQueue\n```\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n  Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n  which are evaluated from first to last. Assignment Rules also allow for\n  gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n  Build ID. You may add at most one redirect rule for each source Build ID.\n  Redirect rules require that a target Build ID is fully compatible with\n  the source Build ID."
 	}
 	s.Command.Args = cobra.NoArgs
 	s.Command.AddCommand(&NewTemporalTaskQueueVersioningAddRedirectRuleCommand(cctx, &s).Command)

internal/temporalcli/commands.yaml

@@ -2627,13 +2627,8 @@ commands:
 
   - name: temporal task-queue get-build-id-reachability
     summary: Show Build ID availability (Deprecated)
+    deprecated: true
     description: |
-      ```
-      +-----------------------------------------------------------------------------+
-      | CAUTION: This command is deprecated and will be removed in a later release. |
-      +-----------------------------------------------------------------------------+
-      ```
-
       Show if a given Build ID can be used for new, existing, or closed Workflows
       in Namespaces that support Worker versioning:
 
@@ -2674,13 +2669,8 @@ commands:
 
   - name: temporal task-queue get-build-ids
     summary: Fetch Build ID versions (Deprecated)
+    deprecated: true
     description: |
-      ```
-      +-----------------------------------------------------------------------------+
-      | CAUTION: This command is deprecated and will be removed in a later release. |
-      +-----------------------------------------------------------------------------+
-      ```
-
       Fetch sets of compatible Build IDs for specified Task Queues and display their
       information:
 
@@ -2885,13 +2875,9 @@ commands:
 
   - name: temporal task-queue versioning
     summary: Manage Task Queue Build ID handling (Deprecated)
+    deprecated: true
+    deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
-      ```
-      +---------------------------------------------------------------------+
-      | CAUTION: This API has been deprecated by Worker Deployment.         |
-      +---------------------------------------------------------------------+
-      ```
-
       Provides commands to add, list, remove, or replace Worker Build ID assignment
       and redirect rules associated with Task Queues: