From 2ada44b23a471ffca5ba23dfd6bc8ae71efbdc80 Mon Sep 17 00:00:00 2001
From: "alex.stanfield" <13949480+chaptersix@users.noreply.github.com>
Date: Fri, 6 Feb 2026 16:57:49 -0600
Subject: [PATCH 1/4] feat: auto-generate deprecation warning box from YAML
 config

Add `deprecated: true` and optional `deprecation-message` fields to
command YAML config. When set, the generator auto-prepends a CAUTION
box to the command description, removing the need to manually add
deprecation warnings.
---
 internal/commandsgen/code.go         |  6 ++--
 internal/commandsgen/parse.go        | 26 +++++++++++++--
 internal/commandsgen/parse_test.go   | 48 ++++++++++++++++++++++++++++
 internal/temporalcli/commands.gen.go |  4 +--
 internal/temporalcli/commands.yaml   | 22 +++----------
 5 files changed, 81 insertions(+), 25 deletions(-)
 create mode 100644 internal/commandsgen/parse_test.go

diff --git a/internal/commandsgen/code.go b/internal/commandsgen/code.go
index fb500751b..af90e6ae1 100644
--- a/internal/commandsgen/code.go
+++ b/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())
diff --git a/internal/commandsgen/parse.go b/internal/commandsgen/parse.go
index 2083a033d..181b7cd59 100644
--- a/internal/commandsgen/parse.go
+++ b/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)
diff --git a/internal/commandsgen/parse_test.go b/internal/commandsgen/parse_test.go
new file mode 100644
index 000000000..eb77a83e1
--- /dev/null
+++ b/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)
+			}
+		})
+	}
+}
diff --git a/internal/temporalcli/commands.gen.go b/internal/temporalcli/commands.gen.go
index 8682b415b..1e7b5ec4b 100644
--- a/internal/temporalcli/commands.gen.go
+++ b/internal/temporalcli/commands.gen.go
@@ -2544,9 +2544,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)
diff --git a/internal/temporalcli/commands.yaml b/internal/temporalcli/commands.yaml
index ce311b230..8546bee3e 100644
--- a/internal/temporalcli/commands.yaml
+++ b/internal/temporalcli/commands.yaml
@@ -2603,13 +2603,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:
 
@@ -2650,13 +2645,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:
 
@@ -2861,13 +2851,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:
 

From 7538b05634b4a41b3f55e12a8d217c9d0d55e376 Mon Sep 17 00:00:00 2001
From: "alex.stanfield" <13949480+chaptersix@users.noreply.github.com>
Date: Sat, 30 May 2026 19:21:49 -0500
Subject: [PATCH 2/4] feat: print deprecation warning to stderr at runtime

Store deprecation message in command annotations and print it to stderr
in PersistentPreRunE, so users see the warning when running deprecated
commands without breaking JSON output.
---
 internal/commandsgen/code.go         | 16 +++++++++++++---
 internal/temporalcli/commands.gen.go |  6 ++++++
 internal/temporalcli/commands.go     |  5 +++++
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/internal/commandsgen/code.go b/internal/commandsgen/code.go
index af90e6ae1..84cff3bbc 100644
--- a/internal/commandsgen/code.go
+++ b/internal/commandsgen/code.go
@@ -233,13 +233,23 @@ func (c *Command) writeCode(w *codeWriter) error {
 	} else {
 		w.writeLinef("s.Command.Args = %v.NoArgs", w.importCobra())
 	}
-	if c.IgnoreMissingEnv {
+	if c.IgnoreMissingEnv || c.Deprecated {
 		w.writeLinef("s.Command.Annotations = make(map[string]string)")
-		w.writeLinef("s.Command.Annotations[\"ignoresMissingEnv\"] = \"true\"")
+		if c.IgnoreMissingEnv {
+			w.writeLinef("s.Command.Annotations[\"ignoresMissingEnv\"] = \"true\"")
+		}
 	}
 	// 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.
+	// the deprecation warning is prepended to the description/help text and
+	// printed to stderr via the annotation below.
+	if c.Deprecated {
+		msg := c.DeprecationMessage
+		if msg == "" {
+			msg = defaultDeprecationMessage
+		}
+		w.writeLinef("s.Command.Annotations[\"deprecationWarning\"] = %q", msg)
+	}
 	// Add subcommands
 	for _, subCommand := range subCommands {
 		w.writeLinef("s.Command.AddCommand(&New%v(cctx, &s).Command)", subCommand.structName())
diff --git a/internal/temporalcli/commands.gen.go b/internal/temporalcli/commands.gen.go
index 15f62f81f..1af1eca92 100644
--- a/internal/temporalcli/commands.gen.go
+++ b/internal/temporalcli/commands.gen.go
@@ -2644,6 +2644,8 @@ func NewTemporalTaskQueueGetBuildIdReachabilityCommand(cctx *CommandContext, par
 		s.Command.Long = "```\n+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n```\n\nShow if a given Build ID can be used for new, existing, or closed Workflows\nin Namespaces that support Worker versioning:\n\n```\ntemporal task-queue get-build-id-reachability \\\n    --task-queue YourTaskQueue \\\n    --build-id \"YourBuildId\"\n```\n\nYou can specify the `--build-id` and `--task-queue` flags multiple times. If\n`--task-queue` is omitted, the command checks Build ID reachability against\nall Task Queues."
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This command is deprecated and will be removed in a later release."
 	s.Command.Flags().StringArrayVar(&s.BuildId, "build-id", nil, "One or more Build ID strings. Can be passed multiple times.")
 	s.ReachabilityType = cliext.NewFlagStringEnum([]string{"open", "closed", "existing"}, "existing")
 	s.Command.Flags().Var(&s.ReachabilityType, "reachability-type", "Reachability filter. `open`: reachable by one or more open workflows. `closed`: reachable by one or more closed workflows. `existing`: reachable by either. New Workflow Executions reachable by a Build ID are always reported. Accepted values: open, closed, existing.")
@@ -2675,6 +2677,8 @@ func NewTemporalTaskQueueGetBuildIdsCommand(cctx *CommandContext, parent *Tempor
 		s.Command.Long = "```\n+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n```\n\nFetch sets of compatible Build IDs for specified Task Queues and display their\ninformation:\n\n```\ntemporal task-queue get-build-ids \\\n    --task-queue YourTaskQueue\n```\n\nThis command is limited to Namespaces that support Worker versioning."
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This command is deprecated and will be removed in a later release."
 	s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task Queue name. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "task-queue")
 	s.Command.Flags().IntVar(&s.MaxSets, "max-sets", 0, "Max return count. Use 1 for default major version. Use 0 for all sets.")
@@ -2883,6 +2887,8 @@ func NewTemporalTaskQueueVersioningCommand(cctx *CommandContext, parent *Tempora
 		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.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This API has been deprecated by Worker Deployment."
 	s.Command.AddCommand(&NewTemporalTaskQueueVersioningAddRedirectRuleCommand(cctx, &s).Command)
 	s.Command.AddCommand(&NewTemporalTaskQueueVersioningCommitBuildIdCommand(cctx, &s).Command)
 	s.Command.AddCommand(&NewTemporalTaskQueueVersioningDeleteAssignmentRuleCommand(cctx, &s).Command)
diff --git a/internal/temporalcli/commands.go b/internal/temporalcli/commands.go
index 116de4800..cde13615d 100644
--- a/internal/temporalcli/commands.go
+++ b/internal/temporalcli/commands.go
@@ -497,6 +497,11 @@ func (c *TemporalCommand) initCommand(cctx *CommandContext) {
 		}
 		cctx.ActuallyRanCommand = true
 
+		// Print deprecation warning to stderr so it doesn't break JSON output
+		if msg, ok := cmd.Annotations["deprecationWarning"]; ok {
+			fmt.Fprintf(cctx.Options.Stderr, "WARNING: %s\n", msg)
+		}
+
 		if cctx.Options.DeprecatedEnvConfig.EnvConfigName != "default" {
 			if _, ok := cctx.DeprecatedEnvConfigValues[cctx.Options.DeprecatedEnvConfig.EnvConfigName]; !ok {
 				if _, ok := cmd.Annotations["ignoresMissingEnv"]; !ok {

From bf5ee468aedff7368f4a7aff9aa67345d5f00db4 Mon Sep 17 00:00:00 2001
From: "alex.stanfield" <13949480+chaptersix@users.noreply.github.com>
Date: Sat, 30 May 2026 19:27:22 -0500
Subject: [PATCH 3/4] refactor: migrate old-style deprecation commands to YAML
 deprecated flag

Migrate all remaining commands with manual CAUTION boxes to use the
`deprecated: true` YAML field. Auto-append "(Deprecated)" to the summary
in code gen so authors don't need to add it manually.
---
 internal/commandsgen/parse.go        |   4 +-
 internal/temporalcli/commands.gen.go |  56 +++++++++----
 internal/temporalcli/commands.yaml   | 121 ++++++++-------------------
 3 files changed, 78 insertions(+), 103 deletions(-)

diff --git a/internal/commandsgen/parse.go b/internal/commandsgen/parse.go
index 181b7cd59..831b86902 100644
--- a/internal/commandsgen/parse.go
+++ b/internal/commandsgen/parse.go
@@ -189,9 +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
+	// Auto-handle deprecation: prepend warning box to description and append
+	// "(Deprecated)" to summary.
 	if c.Deprecated {
 		c.Description = generateDeprecationBox(c.DeprecationMessage) + c.Description
+		c.Summary += " (Deprecated)"
 	}
 
 	if len(c.NamePath) == 2 {
diff --git a/internal/temporalcli/commands.gen.go b/internal/temporalcli/commands.gen.go
index 1af1eca92..647ddb092 100644
--- a/internal/temporalcli/commands.gen.go
+++ b/internal/temporalcli/commands.gen.go
@@ -2734,6 +2734,8 @@ func NewTemporalTaskQueueUpdateBuildIdsCommand(cctx *CommandContext, parent *Tem
 		s.Command.Long = "```\n+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n```\n\nAdd or change a Task Queue's compatible Build IDs for Namespaces using Worker\nversioning:\n\n```\ntemporal task-queue update-build-ids [subcommands] [options] \\\n    --task-queue YourTaskQueue\n```"
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This command is deprecated and will be removed in a later release."
 	s.Command.AddCommand(&NewTemporalTaskQueueUpdateBuildIdsAddNewCompatibleCommand(cctx, &s).Command)
 	s.Command.AddCommand(&NewTemporalTaskQueueUpdateBuildIdsAddNewDefaultCommand(cctx, &s).Command)
 	s.Command.AddCommand(&NewTemporalTaskQueueUpdateBuildIdsPromoteIdInSetCommand(cctx, &s).Command)
@@ -2796,6 +2798,8 @@ func NewTemporalTaskQueueUpdateBuildIdsAddNewDefaultCommand(cctx *CommandContext
 		s.Command.Long = "```\n+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n```\n\nCreate a new Task Queue Build ID set, add a Build ID to it, and make it the\noverall Task Queue default. The new set will be incompatible with previous\nsets and versions.\n\n```\ntemporal task-queue update-build-ids add-new-default \\\n    --task-queue YourTaskQueue \\\n    --build-id \"YourNewBuildId\"\n```\n\n```\n+------------------------------------------------------------------------+\n| NOTICE: This command is limited to Namespaces that support Worker      |\n| versioning. Worker versioning is experimental. Versioning commands are |\n| subject to change.                                                     |\n+------------------------------------------------------------------------+\n```"
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This command is deprecated and will be removed in a later release."
 	s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Build ID to be added. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id")
 	s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task Queue name. Required.")
@@ -2827,6 +2831,8 @@ func NewTemporalTaskQueueUpdateBuildIdsPromoteIdInSetCommand(cctx *CommandContex
 		s.Command.Long = "```\n+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n```\n\nEstablish an existing Build ID as the default in its Task Queue set. New tasks\ncompatible with this set will now be dispatched to this ID:\n\n```\ntemporal task-queue update-build-ids promote-id-in-set \\\n    --task-queue YourTaskQueue \\\n    --build-id \"YourBuildId\"\n```\n\n```\n+------------------------------------------------------------------------+\n| NOTICE: This command is limited to Namespaces that support Worker      |\n| versioning. Worker versioning is experimental. Versioning commands are |\n| subject to change.                                                     |\n+------------------------------------------------------------------------+\n```"
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This command is deprecated and will be removed in a later release."
 	s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Build ID to set as default. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id")
 	s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task Queue name. Required.")
@@ -2858,6 +2864,8 @@ func NewTemporalTaskQueueUpdateBuildIdsPromoteSetCommand(cctx *CommandContext, p
 		s.Command.Long = "```\n+-----------------------------------------------------------------------------+\n| CAUTION: This command is deprecated and will be removed in a later release. |\n+-----------------------------------------------------------------------------+\n```\n\nPromote a Build ID set to be the default on a Task Queue. Identify the set by\nproviding a Build ID within it. If the set is already the default, this\ncommand has no effect:\n\n```\ntemporal task-queue update-build-ids promote-set \\\n    --task-queue YourTaskQueue \\\n    --build-id \"YourBuildId\"\n```\n\n```\n+------------------------------------------------------------------------+\n| NOTICE: This command is limited to Namespaces that support Worker      |\n| versioning. Worker versioning is experimental. Versioning commands are |\n| subject to change.                                                     |\n+------------------------------------------------------------------------+\n```"
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This command is deprecated and will be removed in a later release."
 	s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Build ID within the promoted set. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id")
 	s.Command.Flags().StringVarP(&s.TaskQueue, "task-queue", "t", "", "Task Queue name. Required.")
@@ -2917,11 +2925,13 @@ func NewTemporalTaskQueueVersioningAddRedirectRuleCommand(cctx *CommandContext,
 	s.Command.Use = "add-redirect-rule [flags]"
 	s.Command.Short = "Add Task Queue redirect rules (Deprecated)"
 	if hasHighlighting {
-		s.Command.Long = "Add a new redirect rule for a given Task Queue. You may add at most one\nredirect rule for each distinct source build ID:\n\n\x1b[1mtemporal task-queue versioning add-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id \"YourSourceBuildID\" \\\n    --target-build-id \"YourTargetBuildID\"\x1b[0m\n\n\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\x1b[0m"
+		s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nAdd a new redirect rule for a given Task Queue. You may add at most one\nredirect rule for each distinct source build ID:\n\n\x1b[1mtemporal task-queue versioning add-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id \"YourSourceBuildID\" \\\n    --target-build-id \"YourTargetBuildID\"\x1b[0m"
 	} else {
-		s.Command.Long = "Add a new redirect rule for a given Task Queue. You may add at most one\nredirect rule for each distinct source build ID:\n\n```\ntemporal task-queue versioning add-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id \"YourSourceBuildID\" \\\n    --target-build-id \"YourTargetBuildID\"\n```\n\n```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\n```"
+		s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nAdd a new redirect rule for a given Task Queue. You may add at most one\nredirect rule for each distinct source build ID:\n\n```\ntemporal task-queue versioning add-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id \"YourSourceBuildID\" \\\n    --target-build-id \"YourTargetBuildID\"\n```"
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This API has been deprecated by Worker Deployment."
 	s.Command.Flags().StringVar(&s.SourceBuildId, "source-build-id", "", "Source build ID. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "source-build-id")
 	s.Command.Flags().StringVar(&s.TargetBuildId, "target-build-id", "", "Target build ID. Required.")
@@ -2950,11 +2960,13 @@ func NewTemporalTaskQueueVersioningCommitBuildIdCommand(cctx *CommandContext, pa
 	s.Command.Use = "commit-build-id [flags]"
 	s.Command.Short = "Complete Build ID rollout (Deprecated)"
 	if hasHighlighting {
-		s.Command.Long = "Complete a Build ID's rollout and clean up unnecessary rules that might have\nbeen created during a gradual rollout:\n\n\x1b[1mtemporal task-queue versioning commit-build-id \\\n    --task-queue YourTaskQueue\n    --build-id \"YourBuildId\"\x1b[0m\n\nThis command automatically applies the following atomic changes:\n\n- Adds an unconditional assignment rule for the target Build ID at the\n  end of the list.\n- Removes all previously added assignment rules to the given target\n  Build ID.\n- Removes any unconditional assignment rules for other Build IDs.\n\nRejects requests when there have been no recent pollers for this Build ID.\nThis prevents committing invalid Build IDs. Use the \x1b[1m--force\x1b[0m option to\noverride this validation.\n\n\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\x1b[0m"
+		s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nComplete a Build ID's rollout and clean up unnecessary rules that might have\nbeen created during a gradual rollout:\n\n\x1b[1mtemporal task-queue versioning commit-build-id \\\n    --task-queue YourTaskQueue\n    --build-id \"YourBuildId\"\x1b[0m\n\nThis command automatically applies the following atomic changes:\n\n- Adds an unconditional assignment rule for the target Build ID at the\n  end of the list.\n- Removes all previously added assignment rules to the given target\n  Build ID.\n- Removes any unconditional assignment rules for other Build IDs.\n\nRejects requests when there have been no recent pollers for this Build ID.\nThis prevents committing invalid Build IDs. Use the \x1b[1m--force\x1b[0m option to\noverride this validation."
 	} else {
-		s.Command.Long = "Complete a Build ID's rollout and clean up unnecessary rules that might have\nbeen created during a gradual rollout:\n\n```\ntemporal task-queue versioning commit-build-id \\\n    --task-queue YourTaskQueue\n    --build-id \"YourBuildId\"\n```\n\nThis command automatically applies the following atomic changes:\n\n- Adds an unconditional assignment rule for the target Build ID at the\n  end of the list.\n- Removes all previously added assignment rules to the given target\n  Build ID.\n- Removes any unconditional assignment rules for other Build IDs.\n\nRejects requests when there have been no recent pollers for this Build ID.\nThis prevents committing invalid Build IDs. Use the `--force` option to\noverride this validation.\n\n```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\n```"
+		s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nComplete a Build ID's rollout and clean up unnecessary rules that might have\nbeen created during a gradual rollout:\n\n```\ntemporal task-queue versioning commit-build-id \\\n    --task-queue YourTaskQueue\n    --build-id \"YourBuildId\"\n```\n\nThis command automatically applies the following atomic changes:\n\n- Adds an unconditional assignment rule for the target Build ID at the\n  end of the list.\n- Removes all previously added assignment rules to the given target\n  Build ID.\n- Removes any unconditional assignment rules for other Build IDs.\n\nRejects requests when there have been no recent pollers for this Build ID.\nThis prevents committing invalid Build IDs. Use the `--force` option to\noverride this validation."
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This API has been deprecated by Worker Deployment."
 	s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Target build ID. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id")
 	s.Command.Flags().BoolVar(&s.Force, "force", false, "Bypass recent-poller validation.")
@@ -2982,11 +2994,13 @@ func NewTemporalTaskQueueVersioningDeleteAssignmentRuleCommand(cctx *CommandCont
 	s.Command.Use = "delete-assignment-rule [flags]"
 	s.Command.Short = "Removes a Task Queue assignment rule (Deprecated)"
 	if hasHighlighting {
-		s.Command.Long = "Deletes a rule identified by its index in the Task Queue's list of assignment\nrules.\n\n\x1b[1mtemporal task-queue versioning delete-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index YourIntegerRuleIndex\x1b[0m\n\nBy default, the Task Queue must retain one unconditional rule, such as \"no\nhint filter\" or \"percentage\". Otherwise, the delete operation is rejected.\nUse the \x1b[1m--force\x1b[0m option to override this validation.\n\n\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\x1b[0m"
+		s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nDeletes a rule identified by its index in the Task Queue's list of assignment\nrules.\n\n\x1b[1mtemporal task-queue versioning delete-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index YourIntegerRuleIndex\x1b[0m\n\nBy default, the Task Queue must retain one unconditional rule, such as \"no\nhint filter\" or \"percentage\". Otherwise, the delete operation is rejected.\nUse the \x1b[1m--force\x1b[0m option to override this validation."
 	} else {
-		s.Command.Long = "Deletes a rule identified by its index in the Task Queue's list of assignment\nrules.\n\n```\ntemporal task-queue versioning delete-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index YourIntegerRuleIndex\n```\n\nBy default, the Task Queue must retain one unconditional rule, such as \"no\nhint filter\" or \"percentage\". Otherwise, the delete operation is rejected.\nUse the `--force` option to override this validation.\n\n```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\n```"
+		s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nDeletes a rule identified by its index in the Task Queue's list of assignment\nrules.\n\n```\ntemporal task-queue versioning delete-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index YourIntegerRuleIndex\n```\n\nBy default, the Task Queue must retain one unconditional rule, such as \"no\nhint filter\" or \"percentage\". Otherwise, the delete operation is rejected.\nUse the `--force` option to override this validation."
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This API has been deprecated by Worker Deployment."
 	s.Command.Flags().IntVarP(&s.RuleIndex, "rule-index", "i", 0, "Position of the assignment rule to be replaced. Requests for invalid indices will fail. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "rule-index")
 	s.Command.Flags().BoolVar(&s.Force, "force", false, "Bypass one-unconditional-rule validation.")
@@ -3013,11 +3027,13 @@ func NewTemporalTaskQueueVersioningDeleteRedirectRuleCommand(cctx *CommandContex
 	s.Command.Use = "delete-redirect-rule [flags]"
 	s.Command.Short = "Removes Build-ID routing rule (Deprecated)"
 	if hasHighlighting {
-		s.Command.Long = "Deletes the routing rule for the given source Build ID.\n\n\x1b[1mtemporal task-queue versioning delete-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id \"YourBuildId\"\x1b[0m\n\n\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\x1b[0m"
+		s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nDeletes the routing rule for the given source Build ID.\n\n\x1b[1mtemporal task-queue versioning delete-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id \"YourBuildId\"\x1b[0m"
 	} else {
-		s.Command.Long = "Deletes the routing rule for the given source Build ID.\n\n```\ntemporal task-queue versioning delete-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id \"YourBuildId\"\n```\n\n```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\n```"
+		s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nDeletes the routing rule for the given source Build ID.\n\n```\ntemporal task-queue versioning delete-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id \"YourBuildId\"\n```"
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This API has been deprecated by Worker Deployment."
 	s.Command.Flags().StringVar(&s.SourceBuildId, "source-build-id", "", "Source Build ID. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "source-build-id")
 	s.Command.Flags().BoolVarP(&s.Yes, "yes", "y", false, "Don't prompt to confirm.")
@@ -3041,11 +3057,13 @@ func NewTemporalTaskQueueVersioningGetRulesCommand(cctx *CommandContext, parent
 	s.Command.Use = "get-rules [flags]"
 	s.Command.Short = "Fetch Worker Build ID assignments and redirect rules (Deprecated)"
 	if hasHighlighting {
-		s.Command.Long = "Retrieve all the Worker Build ID assignments and redirect rules associated\nwith a Task Queue:\n\n\x1b[1mtemporal task-queue versioning get-rules \\\n    --task-queue YourTaskQueue\x1b[0m\n\nTask Queues support the following versioning rules:\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.\n\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\x1b[0m"
+		s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nRetrieve all the Worker Build ID assignments and redirect rules associated\nwith a Task Queue:\n\n\x1b[1mtemporal task-queue versioning get-rules \\\n    --task-queue YourTaskQueue\x1b[0m\n\nTask Queues support the following versioning rules:\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 = "Retrieve all the Worker Build ID assignments and redirect rules associated\nwith a Task Queue:\n\n```\ntemporal task-queue versioning get-rules \\\n    --task-queue YourTaskQueue\n```\n\nTask Queues support the following versioning rules:\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.\n```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\n```"
+		s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nRetrieve all the Worker Build ID assignments and redirect rules associated\nwith a Task Queue:\n\n```\ntemporal task-queue versioning get-rules \\\n    --task-queue YourTaskQueue\n```\n\nTask Queues support the following versioning rules:\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.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This API has been deprecated by Worker Deployment."
 	s.Command.Run = func(c *cobra.Command, args []string) {
 		if err := s.run(cctx, args); err != nil {
 			cctx.Options.Fail(err)
@@ -3070,11 +3088,13 @@ func NewTemporalTaskQueueVersioningInsertAssignmentRuleCommand(cctx *CommandCont
 	s.Command.Use = "insert-assignment-rule [flags]"
 	s.Command.Short = "Add an assignment rule at a index (Deprecated)"
 	if hasHighlighting {
-		s.Command.Long = "Inserts a new assignment rule for this Task Queue. Rules are evaluated in\norder, starting from index 0. The first applicable rule is applied, and the\nrest ignored:\n\n\x1b[1mtemporal task-queue versioning insert-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --build-id \"YourBuildId\"\x1b[0m\n\nIf you do not specify a \x1b[1m--rule-index\x1b[0m, this command inserts at index 0.\n\n\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\x1b[0m"
+		s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nInserts a new assignment rule for this Task Queue. Rules are evaluated in\norder, starting from index 0. The first applicable rule is applied, and the\nrest ignored:\n\n\x1b[1mtemporal task-queue versioning insert-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --build-id \"YourBuildId\"\x1b[0m\n\nIf you do not specify a \x1b[1m--rule-index\x1b[0m, this command inserts at index 0."
 	} else {
-		s.Command.Long = "Inserts a new assignment rule for this Task Queue. Rules are evaluated in\norder, starting from index 0. The first applicable rule is applied, and the\nrest ignored:\n\n```\ntemporal task-queue versioning insert-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --build-id \"YourBuildId\"\n```\n\nIf you do not specify a `--rule-index`, this command inserts at index 0.\n\n```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\n```"
+		s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nInserts a new assignment rule for this Task Queue. Rules are evaluated in\norder, starting from index 0. The first applicable rule is applied, and the\nrest ignored:\n\n```\ntemporal task-queue versioning insert-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --build-id \"YourBuildId\"\n```\n\nIf you do not specify a `--rule-index`, this command inserts at index 0."
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This API has been deprecated by Worker Deployment."
 	s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Target Build ID. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id")
 	s.Command.Flags().IntVarP(&s.RuleIndex, "rule-index", "i", 0, "Insertion position. Ranges from 0 (insert at start) to count (append). Any number greater than the count is treated as \"append\".")
@@ -3105,11 +3125,13 @@ func NewTemporalTaskQueueVersioningReplaceAssignmentRuleCommand(cctx *CommandCon
 	s.Command.Use = "replace-assignment-rule [flags]"
 	s.Command.Short = "Update assignment rule at index (Deprecated)"
 	if hasHighlighting {
-		s.Command.Long = "Change an assignment rule for this Task Queue. By default, this enforces one\nunconditional rule (no hint filter or percentage). Otherwise, the operation\nwill be rejected. Set \x1b[1mforce\x1b[0m to true to bypass this validation.\n\n\x1b[1mtemporal task-queue versioning replace-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index AnIntegerIndex \\\n    --build-id \"YourBuildId\"\x1b[0m\n\nTo assign multiple assignment rules to a single Build ID, use\n'insert-assignment-rule'.\n\nTo update the percent:\n\n\x1b[1mtemporal task-queue versioning replace-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index AnIntegerIndex \\\n    --build-id \"YourBuildId\" \\\n    --percentage AnIntegerPercent\x1b[0m\n\nPercent may vary between 0 and 100 (default).\n\n\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\x1b[0m"
+		s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nChange an assignment rule for this Task Queue. By default, this enforces one\nunconditional rule (no hint filter or percentage). Otherwise, the operation\nwill be rejected. Set \x1b[1mforce\x1b[0m to true to bypass this validation.\n\n\x1b[1mtemporal task-queue versioning replace-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index AnIntegerIndex \\\n    --build-id \"YourBuildId\"\x1b[0m\n\nTo assign multiple assignment rules to a single Build ID, use\n'insert-assignment-rule'.\n\nTo update the percent:\n\n\x1b[1mtemporal task-queue versioning replace-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index AnIntegerIndex \\\n    --build-id \"YourBuildId\" \\\n    --percentage AnIntegerPercent\x1b[0m\n\nPercent may vary between 0 and 100 (default)."
 	} else {
-		s.Command.Long = "Change an assignment rule for this Task Queue. By default, this enforces one\nunconditional rule (no hint filter or percentage). Otherwise, the operation\nwill be rejected. Set `force` to true to bypass this validation.\n\n```\ntemporal task-queue versioning replace-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index AnIntegerIndex \\\n    --build-id \"YourBuildId\"\n```\n\nTo assign multiple assignment rules to a single Build ID, use\n'insert-assignment-rule'.\n\nTo update the percent:\n\n```\ntemporal task-queue versioning replace-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index AnIntegerIndex \\\n    --build-id \"YourBuildId\" \\\n    --percentage AnIntegerPercent\n```\n\nPercent may vary between 0 and 100 (default).\n\n```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\n```"
+		s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nChange an assignment rule for this Task Queue. By default, this enforces one\nunconditional rule (no hint filter or percentage). Otherwise, the operation\nwill be rejected. Set `force` to true to bypass this validation.\n\n```\ntemporal task-queue versioning replace-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index AnIntegerIndex \\\n    --build-id \"YourBuildId\"\n```\n\nTo assign multiple assignment rules to a single Build ID, use\n'insert-assignment-rule'.\n\nTo update the percent:\n\n```\ntemporal task-queue versioning replace-assignment-rule \\\n    --task-queue YourTaskQueue \\\n    --rule-index AnIntegerIndex \\\n    --build-id \"YourBuildId\" \\\n    --percentage AnIntegerPercent\n```\n\nPercent may vary between 0 and 100 (default)."
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This API has been deprecated by Worker Deployment."
 	s.Command.Flags().StringVar(&s.BuildId, "build-id", "", "Target Build ID. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "build-id")
 	s.Command.Flags().IntVarP(&s.RuleIndex, "rule-index", "i", 0, "Position of the assignment rule to be replaced. Requests for invalid indices will fail. Required.")
@@ -3140,11 +3162,13 @@ func NewTemporalTaskQueueVersioningReplaceRedirectRuleCommand(cctx *CommandConte
 	s.Command.Use = "replace-redirect-rule [flags]"
 	s.Command.Short = "Change the target for a Build ID's redirect (Deprecated)"
 	if hasHighlighting {
-		s.Command.Long = "Updates a Build ID's redirect rule on a Task Queue by replacing its target\nBuild ID:\n\n\x1b[1mtemporal task-queue versioning replace-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id YourSourceBuildId \\\n    --target-build-id YourNewTargetBuildId\x1b[0m\n\n\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\x1b[0m"
+		s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nUpdates a Build ID's redirect rule on a Task Queue by replacing its target\nBuild ID:\n\n\x1b[1mtemporal task-queue versioning replace-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id YourSourceBuildId \\\n    --target-build-id YourNewTargetBuildId\x1b[0m"
 	} else {
-		s.Command.Long = "Updates a Build ID's redirect rule on a Task Queue by replacing its target\nBuild ID:\n\n```\ntemporal task-queue versioning replace-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id YourSourceBuildId \\\n    --target-build-id YourNewTargetBuildId\n```\n\n```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment.         |\n+---------------------------------------------------------------------+\n```"
+		s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nUpdates a Build ID's redirect rule on a Task Queue by replacing its target\nBuild ID:\n\n```\ntemporal task-queue versioning replace-redirect-rule \\\n    --task-queue YourTaskQueue \\\n    --source-build-id YourSourceBuildId \\\n    --target-build-id YourNewTargetBuildId\n```"
 	}
 	s.Command.Args = cobra.NoArgs
+	s.Command.Annotations = make(map[string]string)
+	s.Command.Annotations["deprecationWarning"] = "This API has been deprecated by Worker Deployment."
 	s.Command.Flags().StringVar(&s.SourceBuildId, "source-build-id", "", "Source Build ID. Required.")
 	_ = cobra.MarkFlagRequired(s.Command.Flags(), "source-build-id")
 	s.Command.Flags().StringVar(&s.TargetBuildId, "target-build-id", "", "Target Build ID. Required.")
diff --git a/internal/temporalcli/commands.yaml b/internal/temporalcli/commands.yaml
index fc0a6b086..97b708d6d 100644
--- a/internal/temporalcli/commands.yaml
+++ b/internal/temporalcli/commands.yaml
@@ -2839,7 +2839,7 @@ commands:
           configuration for the task queue.
 
   - name: temporal task-queue get-build-id-reachability
-    summary: Show Build ID availability (Deprecated)
+    summary: Show Build ID availability
     deprecated: true
     description: |
       Show if a given Build ID can be used for new, existing, or closed Workflows
@@ -2881,7 +2881,7 @@ commands:
           Can be passed multiple times.
 
   - name: temporal task-queue get-build-ids
-    summary: Fetch Build ID versions (Deprecated)
+    summary: Fetch Build ID versions
     deprecated: true
     description: |
       Fetch sets of compatible Build IDs for specified Task Queues and display their
@@ -2925,14 +2925,9 @@ commands:
         short: t
 
   - name: temporal task-queue update-build-ids
-    summary: Manage Build IDs (Deprecated)
+    summary: Manage Build IDs
+    deprecated: true
     description: |
-      ```
-      +-----------------------------------------------------------------------------+
-      | CAUTION: This command is deprecated and will be removed in a later release. |
-      +-----------------------------------------------------------------------------+
-      ```
-
       Add or change a Task Queue's compatible Build IDs for Namespaces using Worker
       versioning:
 
@@ -2977,14 +2972,9 @@ commands:
         description: Set the expanded Build ID set as the Task Queue default.
 
   - name: temporal task-queue update-build-ids add-new-default
-    summary: Set new default Build ID set (Deprecated)
+    summary: Set new default Build ID set
+    deprecated: true
     description: |
-      ```
-      +-----------------------------------------------------------------------------+
-      | CAUTION: This command is deprecated and will be removed in a later release. |
-      +-----------------------------------------------------------------------------+
-      ```
-
       Create a new Task Queue Build ID set, add a Build ID to it, and make it the
       overall Task Queue default. The new set will be incompatible with previous
       sets and versions.
@@ -3014,14 +3004,9 @@ commands:
         short: t
 
   - name: temporal task-queue update-build-ids promote-id-in-set
-    summary: Set Build ID as set default (Deprecated)
+    summary: Set Build ID as set default
+    deprecated: true
     description: |
-      ```
-      +-----------------------------------------------------------------------------+
-      | CAUTION: This command is deprecated and will be removed in a later release. |
-      +-----------------------------------------------------------------------------+
-      ```
-
       Establish an existing Build ID as the default in its Task Queue set. New tasks
       compatible with this set will now be dispatched to this ID:
 
@@ -3050,14 +3035,9 @@ commands:
         short: t
 
   - name: temporal task-queue update-build-ids promote-set
-    summary: Promote Build ID set (Deprecated)
+    summary: Promote Build ID set
+    deprecated: true
     description: |
-      ```
-      +-----------------------------------------------------------------------------+
-      | CAUTION: This command is deprecated and will be removed in a later release. |
-      +-----------------------------------------------------------------------------+
-      ```
-
       Promote a Build ID set to be the default on a Task Queue. Identify the set by
       providing a Build ID within it. If the set is already the default, this
       command has no effect:
@@ -3087,7 +3067,7 @@ commands:
         short: t
 
   - name: temporal task-queue versioning
-    summary: Manage Task Queue Build ID handling (Deprecated)
+    summary: Manage Task Queue Build ID handling
     deprecated: true
     deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
@@ -3117,7 +3097,9 @@ commands:
         required: true
 
   - name: temporal task-queue versioning add-redirect-rule
-    summary: Add Task Queue redirect rules (Deprecated)
+    summary: Add Task Queue redirect rules
+    deprecated: true
+    deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
       Add a new redirect rule for a given Task Queue. You may add at most one
       redirect rule for each distinct source build ID:
@@ -3128,12 +3110,6 @@ commands:
           --source-build-id "YourSourceBuildID" \
           --target-build-id "YourTargetBuildID"
       ```
-
-      ```
-      +---------------------------------------------------------------------+
-      | CAUTION: This API has been deprecated by Worker Deployment.         |
-      +---------------------------------------------------------------------+
-      ```
     options:
       - name: source-build-id
         type: string
@@ -3149,7 +3125,9 @@ commands:
         description: Don't prompt to confirm.
 
   - name: temporal task-queue versioning commit-build-id
-    summary: Complete Build ID rollout (Deprecated)
+    summary: Complete Build ID rollout
+    deprecated: true
+    deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
       Complete a Build ID's rollout and clean up unnecessary rules that might have
       been created during a gradual rollout:
@@ -3171,12 +3149,6 @@ commands:
       Rejects requests when there have been no recent pollers for this Build ID.
       This prevents committing invalid Build IDs. Use the `--force` option to
       override this validation.
-
-      ```
-      +---------------------------------------------------------------------+
-      | CAUTION: This API has been deprecated by Worker Deployment.         |
-      +---------------------------------------------------------------------+
-      ```
     options:
       - name: build-id
         type: string
@@ -3191,7 +3163,9 @@ commands:
         description: Don't prompt to confirm.
 
   - name: temporal task-queue versioning delete-assignment-rule
-    summary: Removes a Task Queue assignment rule (Deprecated)
+    summary: Removes a Task Queue assignment rule
+    deprecated: true
+    deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
       Deletes a rule identified by its index in the Task Queue's list of assignment
       rules.
@@ -3205,12 +3179,6 @@ commands:
       By default, the Task Queue must retain one unconditional rule, such as "no
       hint filter" or "percentage". Otherwise, the delete operation is rejected.
       Use the `--force` option to override this validation.
-
-      ```
-      +---------------------------------------------------------------------+
-      | CAUTION: This API has been deprecated by Worker Deployment.         |
-      +---------------------------------------------------------------------+
-      ```
     options:
       - name: rule-index
         type: int
@@ -3228,7 +3196,9 @@ commands:
         description: Don't prompt to confirm.
 
   - name: temporal task-queue versioning delete-redirect-rule
-    summary: Removes Build-ID routing rule (Deprecated)
+    summary: Removes Build-ID routing rule
+    deprecated: true
+    deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
       Deletes the routing rule for the given source Build ID.
 
@@ -3237,12 +3207,6 @@ commands:
           --task-queue YourTaskQueue \
           --source-build-id "YourBuildId"
       ```
-
-      ```
-      +---------------------------------------------------------------------+
-      | CAUTION: This API has been deprecated by Worker Deployment.         |
-      +---------------------------------------------------------------------+
-      ```
     options:
       - name: source-build-id
         type: string
@@ -3254,7 +3218,9 @@ commands:
         description: Don't prompt to confirm.
 
   - name: temporal task-queue versioning get-rules
-    summary: Fetch Worker Build ID assignments and redirect rules (Deprecated)
+    summary: Fetch Worker Build ID assignments and redirect rules
+    deprecated: true
+    deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
       Retrieve all the Worker Build ID assignments and redirect rules associated
       with a Task Queue:
@@ -3274,14 +3240,11 @@ commands:
         Build ID. You may add at most one redirect rule for each source Build ID.
         Redirect rules require that a target Build ID is fully compatible with
         the source Build ID.
-      ```
-      +---------------------------------------------------------------------+
-      | CAUTION: This API has been deprecated by Worker Deployment.         |
-      +---------------------------------------------------------------------+
-      ```
 
   - name: temporal task-queue versioning insert-assignment-rule
-    summary: Add an assignment rule at a index (Deprecated)
+    summary: Add an assignment rule at a index
+    deprecated: true
+    deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
       Inserts a new assignment rule for this Task Queue. Rules are evaluated in
       order, starting from index 0. The first applicable rule is applied, and the
@@ -3294,12 +3257,6 @@ commands:
       ```
 
       If you do not specify a `--rule-index`, this command inserts at index 0.
-
-      ```
-      +---------------------------------------------------------------------+
-      | CAUTION: This API has been deprecated by Worker Deployment.         |
-      +---------------------------------------------------------------------+
-      ```
     options:
       - name: build-id
         type: string
@@ -3324,7 +3281,9 @@ commands:
         description: Don't prompt to confirm.
 
   - name: temporal task-queue versioning replace-assignment-rule
-    summary: Update assignment rule at index (Deprecated)
+    summary: Update assignment rule at index
+    deprecated: true
+    deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
       Change an assignment rule for this Task Queue. By default, this enforces one
       unconditional rule (no hint filter or percentage). Otherwise, the operation
@@ -3351,12 +3310,6 @@ commands:
       ```
 
       Percent may vary between 0 and 100 (default).
-
-      ```
-      +---------------------------------------------------------------------+
-      | CAUTION: This API has been deprecated by Worker Deployment.         |
-      +---------------------------------------------------------------------+
-      ```
     options:
       - name: build-id
         type: string
@@ -3383,7 +3336,9 @@ commands:
         description: Bypass the validation that one unconditional rule remains.
 
   - name: temporal task-queue versioning replace-redirect-rule
-    summary: Change the target for a Build ID's redirect (Deprecated)
+    summary: Change the target for a Build ID's redirect
+    deprecated: true
+    deprecation-message: This API has been deprecated by Worker Deployment.
     description: |
       Updates a Build ID's redirect rule on a Task Queue by replacing its target
       Build ID:
@@ -3394,12 +3349,6 @@ commands:
           --source-build-id YourSourceBuildId \
           --target-build-id YourNewTargetBuildId
       ```
-
-      ```
-      +---------------------------------------------------------------------+
-      | CAUTION: This API has been deprecated by Worker Deployment.         |
-      +---------------------------------------------------------------------+
-      ```
     options:
       - name: source-build-id
         type: string

From fb7033a7294fe2cc0a5b441978b374f138c6f4d4 Mon Sep 17 00:00:00 2001
From: "alex.stanfield" <13949480+chaptersix@users.noreply.github.com>
Date: Sat, 30 May 2026 19:35:44 -0500
Subject: [PATCH 4/4] fix: lowercase deprecation stderr warning and add tests

Follow PR template convention: stderr messages are lowercase with no
trailing punctuation. CAUTION box in help text retains original casing.
Add functional tests for stderr deprecation warnings in both text and
JSON output modes.
---
 internal/temporalcli/commands.go              |  2 +-
 .../commands.taskqueue_build_id_test.go       | 42 +++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/internal/temporalcli/commands.go b/internal/temporalcli/commands.go
index cde13615d..ecb52515d 100644
--- a/internal/temporalcli/commands.go
+++ b/internal/temporalcli/commands.go
@@ -499,7 +499,7 @@ func (c *TemporalCommand) initCommand(cctx *CommandContext) {
 
 		// Print deprecation warning to stderr so it doesn't break JSON output
 		if msg, ok := cmd.Annotations["deprecationWarning"]; ok {
-			fmt.Fprintf(cctx.Options.Stderr, "WARNING: %s\n", msg)
+			fmt.Fprintf(cctx.Options.Stderr, "warning: %s\n", strings.ToLower(strings.TrimRight(msg, ".")))
 		}
 
 		if cctx.Options.DeprecatedEnvConfig.EnvConfigName != "default" {
diff --git a/internal/temporalcli/commands.taskqueue_build_id_test.go b/internal/temporalcli/commands.taskqueue_build_id_test.go
index 365bf9e1b..fb137ac28 100644
--- a/internal/temporalcli/commands.taskqueue_build_id_test.go
+++ b/internal/temporalcli/commands.taskqueue_build_id_test.go
@@ -180,3 +180,45 @@ func (s *SharedServerSuite) TestTaskQueue_BuildId() {
 		},
 	}, jsonReachOut)
 }
+
+func (s *SharedServerSuite) TestDeprecatedCommand_WarnsOnStderr() {
+	taskQueue := uuid.NewString()
+
+	// Run a deprecated command
+	res := s.Execute(
+		"task-queue", "update-build-ids", "add-new-default",
+		"--address", s.Address(),
+		"--task-queue", taskQueue,
+		"--build-id", "1.0",
+	)
+	s.NoError(res.Err)
+
+	// Deprecation warning must appear on stderr
+	stderr := res.Stderr.String()
+	s.Contains(stderr, "warning:")
+	s.Contains(stderr, "deprecated")
+
+	// Warning must not appear on stdout (would break JSON consumers)
+	s.NotContains(res.Stdout.String(), "warning:")
+}
+
+func (s *SharedServerSuite) TestDeprecatedCommand_WarnsOnStderr_JSON() {
+	taskQueue := uuid.NewString()
+
+	// Run a deprecated command with JSON output
+	res := s.Execute(
+		"task-queue", "get-build-ids",
+		"-o", "json",
+		"--address", s.Address(),
+		"--task-queue", taskQueue,
+	)
+	s.NoError(res.Err)
+
+	// Deprecation warning must appear on stderr even with JSON output
+	stderr := res.Stderr.String()
+	s.Contains(stderr, "warning:")
+	s.Contains(stderr, "deprecated")
+
+	// Stdout must be valid JSON, not polluted by warnings
+	s.NotContains(res.Stdout.String(), "warning:")
+}