Add documentation for new activity commands - pause/unpause/reset/update

docs/cli/activity.mdx

@@ -9,6 +9,10 @@ keywords:
   - activity complete
   - activity execution
   - activity fail
+  - activity update-options
+  - activity pause
+  - activity unpause
+  - activity reset
   - cli reference
   - cli-feature
   - command-line-interface-cli
@@ -18,6 +22,8 @@ tags:
   - Temporal CLI
 ---
 
+# Activity commands
+
 Activity commands operate on [Activity Executions](/activities#activity-execution).
 
 Activity commands follow this syntax:
@@ -118,3 +124,188 @@ Use the following options to change the behavior of this command.
 - [--tls-server-name](/cli/cmd-options#tls-server-name)
 
 - [--workflow-id](/cli/cmd-options#workflow-id)
+
+## update-options
+
+The `temporal activity update-options` command lets you fix running activities by updating the options that were passed in by the activity's parent workflow.
+
+The Activity must already be running on a valid [Workflow](/workflows).
+Updates are incremental, only changing the specified options. Either activity id or activity type must be provided.
+If activity type is provided, and there are multiple pending activities of the provided type - all of them will be updated.
+The command will return the new activity options for an [Activity Execution](/activities#activity-execution)..
+
+Use the following options to change the behavior of this command.
+
+Routing options:
+- [--activity-id](/cli/cmd-options#activity-id)
+- [--activity-type](/cli/cmd-options#activity-type)
+- [--workflow-id](/cli/cmd-options#workflow-id)
+- [--run-id](/cli/cmd-options#run-id)
+- [--namespace](/cli/cmd-options#namespace)
+
+
+You can update the following Activity options:
+
+- [--task-queue](/cli/cmd-options#task-queue)
+- [--schedule-to-close-timeout](/cli/cmd-options#schedule-to-close-timeout)
+- [--schedule-to-start-timeout](/cli/cmd-options#schedule-to-start-timeout)
+- [--start-to-close-timeout](/cli/cmd-options#start-to-close-timeout)
+- [--heartbeat-timeout](/cli/cmd-options#heartbeat-timeout)
+- [--retry-initial-interval](/cli/cmd-options#retry-initial-interval)
+- [--retry-maximum-interval](/cli/cmd-options#retry-maximum-interval)
+- [--retry-backoff-coefficient](/cli/cmd-options#retry-backoff-coefficient)
+- [--retry-maximum-attempts](/cli/cmd-options#retry-maximum-attempts)
+
+Other options:
+- [--identity](/cli/cmd-options#identity)
+- [--tls](/cli/cmd-options#tls)
+- [--tls-ca-path](/cli/cmd-options#tls-ca-path)
+- [--tls-cert-path](/cli/cmd-options#tls-cert-path)
+- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification)
+- [--tls-key-path](/cli/cmd-options#tls-key-path)
+- [--tls-server-name](/cli/cmd-options#tls-server-name)
+- [--address](/cli/cmd-options#address)
+- [--codec-auth](/cli/cmd-options#codec-auth)
+- [--codec-endpoint](/cli/cmd-options#codec-endpoint)
+- [--color](/cli/cmd-options#color)
+- [--command-timeout](/cli/cmd-options#command-timeout)
+- [--detail](/cli/cmd-options#detail)
+- [--env](/cli/cmd-options#env)
+- [--grpc-meta](/cli/cmd-options#grpc-meta)
+
+## pause
+
+The `temporal activity pause` command pauses an [Activity Execution](/activities#activity-execution) specified by its ID or type.
+Pausing the activity can be undone by using the `temporal activity unpause` command.
+
+Pausing an activity means:
+* If the activity is currently waiting for a retry or is running and subsequently fails, it will not be rescheduled until it is unpaused.
+* If the activity is already paused, calling this method will have no effect.
+* If the activity is running and finishes successfully, the activity will be completed.
+* If the activity is running and finishes with failure:
+  * if there is no retry left - the activity will be completed.
+  * if there are more retries left - the activity will be paused.
+
+If activity type is provided, and there are multiple pending activities of the provided type - all of them will be paused.
+
+For long-running activities, activities in paused state will send a cancellation with "activity_paused" set to 'true' as a part of [Activity Heartbeat](/encyclopedia/detecting-activity-failures#activity-heartbeat) response.
+### activity-typeYou can choose how you'd like to handle this case in your activity.
+
+This command returns a `NotFound` error if there is no pending activity with the provided ID or type.
+Use the following options to change the behavior of this command.
+
+Routing options:
+- [--activity-id](/cli/cmd-options#activity-id)
+- [--activity-type](/cli/cmd-options#activity-type)
+- [--workflow-id](/cli/cmd-options#workflow-id)
+- [--run-id](/cli/cmd-options#run-id)
+- [--namespace](/cli/cmd-options#namespace)
+
+Other options:
+  - [--identity](/cli/cmd-options#identity)
+  - [--tls](/cli/cmd-options#tls)
+  - [--tls-ca-path](/cli/cmd-options#tls-ca-path)
+  - [--tls-cert-path](/cli/cmd-options#tls-cert-path)
+  - [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification)
+  - [--tls-key-path](/cli/cmd-options#tls-key-path)
+  - [--tls-server-name](/cli/cmd-options#tls-server-name)
+  - [--address](/cli/cmd-options#address)
+  - [--codec-auth](/cli/cmd-options#codec-auth)
+  - [--codec-endpoint](/cli/cmd-options#codec-endpoint)
+  - [--color](/cli/cmd-options#color)
+  - [--command-timeout](/cli/cmd-options#command-timeout)
+  - [--detail](/cli/cmd-options#detail)
+  - [--env](/cli/cmd-options#env)
+  - [--grpc-meta](/cli/cmd-options#grpc-meta)
+
+## unpause
+
+The `temporal activity unpause` command unpauses an [Activity Execution](/activities#activity-execution) specified by its ID or type.
+If there are multiple pending activities of the provided type - all of them will be unpaused.
+If activity is not paused, this call will have no effect.
+If the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).
+Once the activity is unpaused, all timeout timers will be regenerated.
+
+Command will fail with a `NotFound` error if there is no pending activity with the provided ID or type.
+
+Activities can be unpaused in bulk via a visibility Query list filter:
+
+```
+temporal activity unpause --query YourQuery \
+    --reason YourReasonForUnpause
+```
+
+
+Routing options:
+- [--activity-id](/cli/cmd-options#activity-id)
+- [--activity-type](/cli/cmd-options#activity-type)
+- [--workflow-id](/cli/cmd-options#workflow-id)
+- [--run-id](/cli/cmd-options#run-id)
+- [--namespace](/cli/cmd-options#namespace)
+
+Unpause specific options:
+- [--match-all](/cli/cmd-options#match-all)
+- [--reset-attempts](/cli/cmd-options#reset-attempts)
+- [--reset-heartbeat](/cli/cmd-options#reset-heartbeat)
+- [--jitter](/cli/cmd-options#activity-jitter)
+
+Other options:
+  - [--identity](/cli/cmd-options#identity)
+  - [--tls](/cli/cmd-options#tls)
+  - [--tls-ca-path](/cli/cmd-options#tls-ca-path)
+  - [--tls-cert-path](/cli/cmd-options#tls-cert-path)
+  - [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification)
+  - [--tls-key-path](/cli/cmd-options#tls-key-path)
+  - [--tls-server-name](/cli/cmd-options#tls-server-name)
+  - [--address](/cli/cmd-options#address)
+  - [--codec-auth](/cli/cmd-options#codec-auth)
+  - [--codec-endpoint](/cli/cmd-options#codec-endpoint)
+  - [--color](/cli/cmd-options#color)
+  - [--command-timeout](/cli/cmd-options#command-timeout)
+  - [--detail](/cli/cmd-options#detail)
+  - [--env](/cli/cmd-options#env)
+  - [--grpc-meta](/cli/cmd-options#grpc-meta)
+
+## reset
+
+The `temporal activity reset` command restarts a running [Activity Execution](/activities#activity-execution) specified by its ID or type.
+If there are multiple pending activities of the provided type - all of them will be reset.
+Resetting an activity means:
+* number of attempts will be reset to 0;
+* activity timeouts will be reset;
+* if the activity is waiting for retry, it will be scheduled immediately (* see 'jitter' flag);
+* if the activity is currently executing, it will be reset once/if it completes with failure;
+* if the activity is paused, it will be unpaused. If you want it to stay paused, you can pass --keep-paused flag;
+
+Command will fail with a `NotFound` error if there is no pending activity with the provided ID or type.
+This may happen if the activity has already completed.
+
+Routing options:
+- [--activity-id](/cli/cmd-options#activity-id)
+- [--activity-type](/cli/cmd-options#activity-type)
+- [--workflow-id](/cli/cmd-options#workflow-id)
+- [--run-id](/cli/cmd-options#run-id)
+- [--namespace](/cli/cmd-options#namespace)
+
+Reset specific options:
+- [--keep-paused](/cli/cmd-options#keep-paused)
+- [--reset-heartbeat](/cli/cmd-options#reset-heartbeat)
+- [--jitter](/cli/cmd-options#activity-jitter)
+
+Other options:
+  - [--identity](/cli/cmd-options#identity)
+  - [--tls](/cli/cmd-options#tls)
+  - [--tls-ca-path](/cli/cmd-options#tls-ca-path)
+  - [--tls-cert-path](/cli/cmd-options#tls-cert-path)
+  - [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification)
+  - [--tls-key-path](/cli/cmd-options#tls-key-path)
+  - [--tls-server-name](/cli/cmd-options#tls-server-name)
+  - [--address](/cli/cmd-options#address)
+  - [--codec-auth](/cli/cmd-options#codec-auth)
+  - [--codec-endpoint](/cli/cmd-options#codec-endpoint)
+  - [--color](/cli/cmd-options#color)
+  - [--command-timeout](/cli/cmd-options#command-timeout)
+  - [--detail](/cli/cmd-options#detail)
+  - [--env](/cli/cmd-options#env)
+  - [--grpc-meta](/cli/cmd-options#grpc-meta)
+

docs/cli/cmd-options.mdx

@@ -700,3 +700,72 @@ Workflow type name.
 ## yes
 
 Confirm all prompts.
+
+## activity-type
+
+Command is applied to the all running activities with of this type.
+
+## task-queue
+
+If specified, activity will be assigned to this task-queue.
+
+## schedule-to-close-timeout
+
+Indicates how long the caller is willing to wait for an activity completion.
+Limits how long retries will be attempted.
+
+## schedule-to-start-timeout
+
+Limits time an activity task can stay in a task queue before a worker picks it up.
+This timeout is always non retryable, as all a retry would achieve is to put it back into the same queue.
+Defaults to `schedule_to_close_timeout` or workflow execution timeout if not specified.
+
+## start-to-close-timeout
+
+Maximum time an activity is allowed to execute after being picked up by a worker.
+This timeout is always retryable.
+
+## heartbeat-timeout
+
+Maximum permitted time between successful worker heartbeats.
+
+## retry-initial-interval
+
+Interval of the first retry. If retryBackoffCoefficient is 1.0 then it is used for all retries.
+
+## retry-maximum-interval
+
+Maximum interval between retries. Exponential backoff leads to interval increase.
+This value is the cap of the increase. Default is 100x of the initial interval.
+
+## retry-backoff-coefficient
+
+Coefficient used to calculate the next retry interval.
+The next retry interval is previous interval multiplied by the coefficient.
+Must be 1 or larger.
+
+## retry-maximum-attempts
+
+Maximum number of attempts. When exceeded the retries stop even if not expired yet.
+1 disables retries. 0 means unlimited (up to the timeouts).
+
+## match-all
+
+If set, all currently running activities will be unpaused.
+
+## reset-attempts
+
+Providing this flag will reset the number of attempts.
+
+## reset-heartbeat
+
+Providing this flag will reset the heartbeat details.
+
+## activity-jitter
+
+If set, the activity will start at a random time within the specified jitter duration.
+
+## keep-paused
+
+If this flag is provided and activity was paused, it will stay paused after reset.
+