Add experimental warning around activity batch operations (#966)

## What was changed
Add experimental warning around pause/update-options/unpause/reset
activity by type or use of --query flag with activity operations.

## Why?
These have been experimental commands and should have been marked
experimental from the beginning.

## Checklist
1. Closes NA

2. How was this tested: manually built and verified

3. Any docs updates needed?

Author: spkane31

internal/temporalcli/commands.activity.go

@@ -156,6 +156,8 @@ func (c *TemporalActivityUpdateOptionsCommand) run(cctx *CommandContext, args []
 		updatePath = append(updatePath, "retry_policy.maximum_attempts")
 	}
 
+	// workflowExecOrBatch is defined on SingleWorkflowOrBatchOptions; bridge via
+	// manual copy from the embedded SingleActivityOrBatchOptions fields.
 	opts := SingleWorkflowOrBatchOptions{
 		WorkflowId: c.WorkflowId,
 		RunId:      c.RunId,
@@ -271,6 +273,8 @@ func (c *TemporalActivityUnpauseCommand) run(cctx *CommandContext, args []string
 	}
 	defer cl.Close()
 
+	// workflowExecOrBatch is defined on SingleWorkflowOrBatchOptions; bridge via
+	// manual copy from the embedded SingleActivityOrBatchOptions fields.
 	opts := SingleWorkflowOrBatchOptions{
 		WorkflowId: c.WorkflowId,
 		RunId:      c.RunId,
@@ -344,6 +348,8 @@ func (c *TemporalActivityResetCommand) run(cctx *CommandContext, args []string)
 	}
 	defer cl.Close()
 
+	// workflowExecOrBatch is defined on SingleWorkflowOrBatchOptions; bridge via
+	// manual copy from the embedded SingleActivityOrBatchOptions fields.
 	opts := SingleWorkflowOrBatchOptions{
 		WorkflowId: c.WorkflowId,
 		RunId:      c.RunId,

internal/temporalcli/commands.gen.go

@@ -151,6 +151,28 @@ func (v *DeploymentReferenceOptions) BuildFlags(f *pflag.FlagSet) {
 	_ = cobra.MarkFlagRequired(f, "build-id")
 }
 
+type SingleActivityOrBatchOptions struct {
+	WorkflowId string
+	Query      string
+	RunId      string
+	Reason     string
+	Yes        bool
+	Rps        float32
+	Headers    []string
+	FlagSet    *pflag.FlagSet
+}
+
+func (v *SingleActivityOrBatchOptions) BuildFlags(f *pflag.FlagSet) {
+	v.FlagSet = f
+	f.StringVarP(&v.WorkflowId, "workflow-id", "w", "", "Workflow ID. You must set either --workflow-id or --query.")
+	f.StringVarP(&v.Query, "query", "q", "", "Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query. Note: Using --query for batch activity operations is an experimental feature and may change in the future.")
+	f.StringVarP(&v.RunId, "run-id", "r", "", "Run ID. Only use with --workflow-id. Cannot use with --query.")
+	f.StringVar(&v.Reason, "reason", "", "Reason for batch operation. Only use with --query. Defaults to user name.")
+	f.BoolVarP(&v.Yes, "yes", "y", false, "Don't prompt to confirm signaling. Only allowed when --query is present.")
+	f.Float32Var(&v.Rps, "rps", 0, "Limit batch's requests per second. Only allowed if query is present.")
+	f.StringArrayVar(&v.Headers, "headers", nil, "Temporal workflow headers in 'KEY=VALUE' format. Keys must be identifiers, and values must be JSON values. May be passed multiple times to set multiple Temporal headers. Note: These are workflow headers, not gRPC headers.")
+}
+
 type SingleWorkflowOrBatchOptions struct {
 	WorkflowId string
 	Query      string
@@ -508,7 +530,7 @@ func NewTemporalActivityPauseCommand(cctx *CommandContext, parent *TemporalActiv
 type TemporalActivityResetCommand struct {
 	Parent  *TemporalActivityCommand
 	Command cobra.Command
-	SingleWorkflowOrBatchOptions
+	SingleActivityOrBatchOptions
 	ActivityId             string
 	ActivityType           string
 	KeepPaused             bool
@@ -532,15 +554,15 @@ func NewTemporalActivityResetCommand(cctx *CommandContext, parent *TemporalActiv
 	}
 	s.Command.Args = cobra.NoArgs
 	s.Command.Flags().StringVarP(&s.ActivityId, "activity-id", "a", "", "The Activity ID to reset.  Mutually exclusive with `--query`, `--match-all`, and `--activity-type`. Requires `--workflow-id` to be specified.")
-	s.Command.Flags().StringVar(&s.ActivityType, "activity-type", "", "Activities of this Type will be reset. Mutually exclusive with `--match-all` and `activity-id`.")
+	s.Command.Flags().StringVar(&s.ActivityType, "activity-type", "", "Activities of this Type will be reset. Mutually exclusive with `--match-all` and `activity-id`. Note: Resetting Activity by Type is an experimental feature and may change in the future.")
 	s.Command.Flags().BoolVar(&s.KeepPaused, "keep-paused", false, "If the activity was paused, it will stay paused.")
 	s.Command.Flags().BoolVar(&s.ResetAttempts, "reset-attempts", false, "Reset the activity attempts.")
 	s.Command.Flags().BoolVar(&s.ResetHeartbeats, "reset-heartbeats", false, "Reset the Activity's heartbeats. Only works with --reset-attempts.")
-	s.Command.Flags().BoolVar(&s.MatchAll, "match-all", false, "Every activity should be reset. Every activity should be updated. Mutually exclusive with `--activity-id` and `--activity-type`.")
+	s.Command.Flags().BoolVar(&s.MatchAll, "match-all", false, "Every activity should be reset. Every activity should be updated. Mutually exclusive with `--activity-id` and `--activity-type`. Note: This is an experimental feature and may change in the future.")
 	s.Jitter = 0
 	s.Command.Flags().Var(&s.Jitter, "jitter", "The activity will reset at random a time within the specified duration. Can only be used with --query.")
 	s.Command.Flags().BoolVar(&s.RestoreOriginalOptions, "restore-original-options", false, "Restore the original options of the activity.")
-	s.SingleWorkflowOrBatchOptions.BuildFlags(s.Command.Flags())
+	s.SingleActivityOrBatchOptions.BuildFlags(s.Command.Flags())
 	s.Command.Run = func(c *cobra.Command, args []string) {
 		if err := s.run(cctx, args); err != nil {
 			cctx.Options.Fail(err)
@@ -552,7 +574,7 @@ func NewTemporalActivityResetCommand(cctx *CommandContext, parent *TemporalActiv
 type TemporalActivityUnpauseCommand struct {
 	Parent  *TemporalActivityCommand
 	Command cobra.Command
-	SingleWorkflowOrBatchOptions
+	SingleActivityOrBatchOptions
 	ActivityId      string
 	ActivityType    string
 	ResetAttempts   bool
@@ -574,13 +596,13 @@ func NewTemporalActivityUnpauseCommand(cctx *CommandContext, parent *TemporalAct
 	}
 	s.Command.Args = cobra.NoArgs
 	s.Command.Flags().StringVarP(&s.ActivityId, "activity-id", "a", "", "The Activity ID to unpause.  Mutually exclusive with `--query`, `--match-all`, and `--activity-type`. Requires `--workflow-id` to be specified.")
-	s.Command.Flags().StringVar(&s.ActivityType, "activity-type", "", "Activities of this Type will unpause. Can only be used without --match-all. Either `activity-id` or `activity-type` must be provided, but not both.")
+	s.Command.Flags().StringVar(&s.ActivityType, "activity-type", "", "Activities of this Type will unpause. Can only be used without --match-all. Either `activity-id` or `activity-type` must be provided, but not both. Note: Unpausing Activity by Type is an experimental feature and may change in the future.")
 	s.Command.Flags().BoolVar(&s.ResetAttempts, "reset-attempts", false, "Reset the activity attempts.")
 	s.Command.Flags().BoolVar(&s.ResetHeartbeats, "reset-heartbeats", false, "Reset the Activity's heartbeats. Only works with --reset-attempts.")
-	s.Command.Flags().BoolVar(&s.MatchAll, "match-all", false, "Every paused activity should be unpaused. This flag is ignored if activity-type is provided.")
+	s.Command.Flags().BoolVar(&s.MatchAll, "match-all", false, "Every paused activity should be unpaused. This flag is ignored if activity-type is provided. Note: This is an experimental feature and may change in the future.")
 	s.Jitter = 0
 	s.Command.Flags().Var(&s.Jitter, "jitter", "The activity will start at random a time within the specified duration. Can only be used with --query.")
-	s.SingleWorkflowOrBatchOptions.BuildFlags(s.Command.Flags())
+	s.SingleActivityOrBatchOptions.BuildFlags(s.Command.Flags())
 	s.Command.Run = func(c *cobra.Command, args []string) {
 		if err := s.run(cctx, args); err != nil {
 			cctx.Options.Fail(err)
@@ -592,7 +614,7 @@ func NewTemporalActivityUnpauseCommand(cctx *CommandContext, parent *TemporalAct
 type TemporalActivityUpdateOptionsCommand struct {
 	Parent  *TemporalActivityCommand
 	Command cobra.Command
-	SingleWorkflowOrBatchOptions
+	SingleActivityOrBatchOptions
 	ActivityId              string
 	ActivityType            string
 	MatchAll                bool
@@ -621,8 +643,8 @@ func NewTemporalActivityUpdateOptionsCommand(cctx *CommandContext, parent *Tempo
 	}
 	s.Command.Args = cobra.NoArgs
 	s.Command.Flags().StringVarP(&s.ActivityId, "activity-id", "a", "", "The Activity ID to update options. Mutually exclusive with `--query`, `--match-all`, and `--activity-type`. Requires `--workflow-id` to be specified.")
-	s.Command.Flags().StringVar(&s.ActivityType, "activity-type", "", "Activities of this Type will be updated. Mutually exclusive with `--match-all` and `activity-id`.")
-	s.Command.Flags().BoolVar(&s.MatchAll, "match-all", false, "Every activity should be updated. Mutually exclusive with `--activity-id` and `--activity-type`.")
+	s.Command.Flags().StringVar(&s.ActivityType, "activity-type", "", "Activities of this Type will be updated. Mutually exclusive with `--match-all` and `activity-id`. Note: Updating Activity options by Type is an experimental feature and may change in the future.")
+	s.Command.Flags().BoolVar(&s.MatchAll, "match-all", false, "Every activity should be updated. Mutually exclusive with `--activity-id` and `--activity-type`. Note: This is an experimental feature and may change in the future.")
 	s.Command.Flags().StringVar(&s.TaskQueue, "task-queue", "", "Name of the task queue for the Activity.")
 	s.ScheduleToCloseTimeout = 0
 	s.Command.Flags().Var(&s.ScheduleToCloseTimeout, "schedule-to-close-timeout", "Indicates how long the caller is willing to wait for an activity completion. Limits how long retries will be attempted.")
@@ -639,7 +661,7 @@ func NewTemporalActivityUpdateOptionsCommand(cctx *CommandContext, parent *Tempo
 	s.Command.Flags().Float32Var(&s.RetryBackoffCoefficient, "retry-backoff-coefficient", 0, "Coefficient used to calculate the next retry interval. The next retry interval is previous interval multiplied by the backoff coefficient. Must be 1 or larger.")
 	s.Command.Flags().IntVar(&s.RetryMaximumAttempts, "retry-maximum-attempts", 0, "Maximum number of attempts. When exceeded the retries stop even if not expired yet. Setting this value to 1 disables retries. Setting this value to 0 means unlimited attempts(up to the timeouts).")
 	s.Command.Flags().BoolVar(&s.RestoreOriginalOptions, "restore-original-options", false, "Restore the original options of the activity.")
-	s.SingleWorkflowOrBatchOptions.BuildFlags(s.Command.Flags())
+	s.SingleActivityOrBatchOptions.BuildFlags(s.Command.Flags())
 	s.Command.Run = func(c *cobra.Command, args []string) {
 		if err := s.run(cctx, args); err != nil {
 			cctx.Options.Fail(err)

internal/temporalcli/commands.yaml

@@ -278,10 +278,12 @@ commands:
         type: string
         description: |
           Activities of this Type will be updated. Mutually exclusive with `--match-all` and `activity-id`.
+          Note: Updating Activity options by Type is an experimental feature and may change in the future.
       - name: match-all
         type: bool
         description: |
           Every activity should be updated. Mutually exclusive with `--activity-id` and `--activity-type`.
+          Note: This is an experimental feature and may change in the future.
       - name: task-queue
         type: string
         description: Name of the task queue for the Activity.
@@ -338,7 +340,7 @@ commands:
         type: bool
         description: Restore the original options of the activity.
     option-sets:
-      - single-workflow-or-batch
+      - single-activity-or-batch
 
   - name: temporal activity pause
     summary: Pause an Activity
@@ -429,6 +431,7 @@ commands:
         type: string
         description: |
           Activities of this Type will unpause. Can only be used without --match-all. Either `activity-id` or `activity-type` must be provided, but not both.
+          Note: Unpausing Activity by Type is an experimental feature and may change in the future.
       - name: reset-attempts
         type: bool
         description: Reset the activity attempts.
@@ -440,13 +443,14 @@ commands:
         type: bool
         description: |
           Every paused activity should be unpaused. This flag is ignored if activity-type is provided.
+          Note: This is an experimental feature and may change in the future.
       - name: jitter
         type: duration
         description: |
           The activity will start at random a time within the specified duration.
           Can only be used with --query.
     option-sets:
-      - single-workflow-or-batch
+      - single-activity-or-batch
 
   - name: temporal activity reset
     summary: Reset an Activity
@@ -506,7 +510,9 @@ commands:
         description: The Activity ID to reset.  Mutually exclusive with `--query`, `--match-all`, and `--activity-type`. Requires `--workflow-id` to be specified.
       - name: activity-type
         type: string
-        description: Activities of this Type will be reset. Mutually exclusive with `--match-all` and `activity-id`.
+        description: |
+          Activities of this Type will be reset. Mutually exclusive with `--match-all` and `activity-id`.
+          Note: Resetting Activity by Type is an experimental feature and may change in the future.
       - name: keep-paused
         type: bool
         description: If the activity was paused, it will stay paused.
@@ -521,6 +527,7 @@ commands:
         type: bool
         description: |
           Every activity should be reset. Every activity should be updated. Mutually exclusive with `--activity-id` and `--activity-type`.
+          Note: This is an experimental feature and may change in the future.
       - name: jitter
         type: duration
         description: |
@@ -531,7 +538,7 @@ commands:
         description: |
           Restore the original options of the activity.
     option-sets:
-      - single-workflow-or-batch
+      - single-activity-or-batch
 
   - name: temporal batch
     summary: Manage running batch jobs
@@ -4441,6 +4448,56 @@ option-sets:
         description: Build ID for a Worker Deployment.
         required: true
 
+  # Duplicate of single-workflow-or-batch with an experimental note on --query.
+  # Cannot extend the shared option set because workflow commands that also use
+  # it (workflow cancel, workflow count, etc.) are not experimental.
+  - name: single-activity-or-batch
+    options:
+      - name: workflow-id
+        type: string
+        short: w
+        description: |
+          Workflow ID.
+          You must set either --workflow-id or --query.
+      - name: query
+        type: string
+        short: q
+        description: |
+          Content for an SQL-like `QUERY` List Filter.
+          You must set either --workflow-id or --query.
+          Note: Using --query for batch activity operations is an experimental feature and may change in the future.
+      - name: run-id
+        type: string
+        short: r
+        description: |
+          Run ID.
+          Only use with --workflow-id.
+          Cannot use with --query.
+      - name: reason
+        type: string
+        description: |
+          Reason for batch operation.
+          Only use with --query.
+          Defaults to user name.
+      - name: yes
+        type: bool
+        short: y
+        description: |
+          Don't prompt to confirm signaling.
+          Only allowed when --query is present.
+      - name: rps
+        type: float
+        description: |
+          Limit batch's requests per second.
+          Only allowed if query is present.
+      - name: headers
+        type: string[]
+        description: |
+          Temporal workflow headers in 'KEY=VALUE' format.
+          Keys must be identifiers, and values must be JSON values.
+          May be passed multiple times to set multiple Temporal headers.
+          Note: These are workflow headers, not gRPC headers.
+
   - name: single-workflow-or-batch
     options:
       - name: workflow-id