[DRAFT] SAA operator commands documentation by spkane31 · Pull Request #4834 · temporalio/documentation

spkane31 · 2026-07-06T23:12:55Z

What does this PR do?

Document the interactions of standalone activity pause, unpause, reset, update-options commands

Notes to reviewers

┆Attachments: EDU-6664 [DRAFT] SAA operator commands documentation

vercel · 2026-07-06T23:13:01Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Ready	Preview, Comment	Jul 7, 2026 5:55pm

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

vale

docs/encyclopedia/activities/activity-operations.mdx|540 col 49| [Temporal.terms] Use 'Task' instead of 'task' when referring to a Temporal term.
docs/encyclopedia/activities/activity-operations.mdx|560 col 45| [Temporal.terms] Use 'Timers' instead of 'timers' when referring to a Temporal term.
docs/encyclopedia/activities/activity-operations.mdx|562 col 45| [Temporal.terms] Use 'Timers' instead of 'timers' when referring to a Temporal term.
docs/encyclopedia/activities/activity-operations.mdx|565 col 42| [Temporal.terms] Use 'Timers' instead of 'timers' when referring to a Temporal term.
docs/encyclopedia/activities/activity-operations.mdx|572 col 32| [Temporal.terms] Use 'Heartbeat' instead of 'heartbeat' when referring to a Temporal term.
docs/encyclopedia/activities/activity-operations.mdx|590 col 27| [Temporal.terms] Use 'Query' instead of 'query' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:17Z

@@ -84,7 +84,8 @@ webhook, syncing data, or executing a single function reliably with built-in ret
 - Arbitrary length jobs with heartbeats for liveness and checkpointing progress
 - At-least-once execution by default with native retry policy and timeouts


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Retry Policy' instead of 'retry policy' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:17Z

 - **Pause operates on individual Activities by ID within a single Workflow.** Unlike Unpause, Reset, and Update Options,
  there's no `--query` flag. To pause multiple Activities, issue separate commands for each Activity ID.
- **No Namespace-wide query for Paused Activities.** You must know the Workflow Id. See [Observability](#observability).
+- **No Namespace-wide query for Paused Activities.** You must know the Workflow ID. See [Observability](#observability).


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Query' instead of 'query' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:17Z


 - **Update Options is CLI and gRPC only.** It's not available in the UI.

+## Standalone Activity operator commands {/* #standalone-activity-operator-commands */}


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Activity' instead of 'activity' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:17Z

+- If the Activity has a Start Delay, the first dispatch can't happen before `ScheduleTime + StartDelay`.
+- Start Delay also affects the Schedule-To-Close and Schedule-To-Start deadlines for the first dispatch.
+- Start Delay stops affecting dispatch after the first Worker has picked up the Activity.
+- If an operation reissues a dispatch task, the task is scheduled at the later of the operation time, any remaining


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Task' instead of 'task' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:17Z

+- If the Activity has a Start Delay, the first dispatch can't happen before `ScheduleTime + StartDelay`.
+- Start Delay also affects the Schedule-To-Close and Schedule-To-Start deadlines for the first dispatch.
+- Start Delay stops affecting dispatch after the first Worker has picked up the Activity.
+- If an operation reissues a dispatch task, the task is scheduled at the later of the operation time, any remaining


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Task' instead of 'task' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:18Z

+  - `restore_original` restores Start Delay only if the Activity has not started its first attempt.
+- Updated timeout values are validated and normalized after the update.
+- If Schedule-To-Close Timeout is updated:
+  - Update Options reissues the Schedule-To-Close timeout task at the new deadline.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Task' instead of 'task' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:18Z

+  - Extending Schedule-To-Close Timeout can allow future retries that would otherwise be blocked by the Activity
+    deadline.
+- If Start-To-Close Timeout or Heartbeat Timeout is updated for a running attempt:
+  - Update Options reissues the Start-To-Close timeout task for that attempt.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Task' instead of 'task' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:18Z

+    deadline.
+- If Start-To-Close Timeout or Heartbeat Timeout is updated for a running attempt:
+  - Update Options reissues the Start-To-Close timeout task for that attempt.
+  - Update Options reissues the Heartbeat timeout task for that attempt.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Task' instead of 'task' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:18Z

+- If Start-To-Close Timeout or Heartbeat Timeout is updated for a running attempt:
+  - Update Options reissues the Start-To-Close timeout task for that attempt.
+  - Update Options reissues the Heartbeat timeout task for that attempt.
+  - Updated running-attempt timers are anchored to the current attempt's start time or last heartbeat time.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Timers' instead of 'timers' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:18Z

+- If Start-To-Close Timeout or Heartbeat Timeout is updated for a running attempt:
+  - Update Options reissues the Start-To-Close timeout task for that attempt.
+  - Update Options reissues the Heartbeat timeout task for that attempt.
+  - Updated running-attempt timers are anchored to the current attempt's start time or last heartbeat time.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Heartbeat' instead of 'heartbeat' when referring to a Temporal term.

github-actions · 2026-07-06T23:13:25Z

📖 Docs PR preview links

github-actions · 2026-07-07T16:31:09Z

-| [Unpause](#unpause)               | Resumes a Paused Activity. The next execution starts immediately.                | [`temporal activity unpause`](/cli/command-reference/activity#unpause)               |
-| [Reset](#reset)                   | Clears retry state (attempts, backoff) and schedules a new execution.            | [`temporal activity reset`](/cli/command-reference/activity#reset)                   |
-| [Update Options](#update-options) | Changes timeouts, Retry Policy, or Task Queue without restarting the Activity.   | [`temporal activity update-options`](/cli/command-reference/activity#update-options) |
+| [Unpause](#unpause)               | Resumes a Paused Activity. The next execution starts after any remaining retry backoff or start delay.                | [`temporal activity unpause`](/cli/command-reference/activity#unpause)               |


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Start Delay' instead of 'start delay' when referring to a Temporal term.

github-actions · 2026-07-07T16:31:09Z

-Pause stops the Temporal Service from scheduling new retries of an [Activity Execution](/activity-execution).
+Pause stops the Temporal Service scheduling new retries of an [Activity Execution](/activity-execution).

 ### When to Pause


📝 [vale] _{reported by reviewdog 🐶}
[Temporal.Headings] 'When to Pause' should use sentence-style capitalization.

github-actions · 2026-07-07T16:31:09Z

- **Attempt count and Heartbeat data are preserved by default.** The Activity resumes from where it left off. Use
-  `--reset-attempts` or `--reset-heartbeats` on the CLI to clear these, or use [Reset](#reset) to restart from
-  attempt 1.
+- **The Activity is rescheduled for its next attempt.** The next attempt wait for the end of any remaining retry backoff (or start delay) before starting.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Start Delay' instead of 'start delay' when referring to a Temporal term.

github-actions · 2026-07-07T16:31:09Z

 Unpause is idempotent. Unpausing an Activity that isn't Paused has no effect. Unpausing an Activity that has already
-completed returns an error.
+completed returns an error. Use [Reset](#reset) with `--keep-paused` to reset the attempt counter to 1 and optionally
+clear the heartbeat data .


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Heartbeat' instead of 'heartbeat' when referring to a Temporal term.

github-actions · 2026-07-07T16:31:09Z

-Reset clears an Activity's retry state and schedules a fresh execution.
+Reset clears an Activity's retry state and schedules it to start again from attempt 1.

 ### When to Reset


📝 [vale] _{reported by reviewdog 🐶}
[Temporal.Headings] 'When to Reset' should use sentence-style capitalization.

github-actions · 2026-07-07T16:31:09Z

+  - Update Options stores the new options but doesn't dispatch the Activity.
+  - Updated Retry Policy values can affect when the Activity dispatches after Unpause.
+- If the Activity is PAUSE_REQUESTED:
+  - Update Options reissues running-attempt timers so Start-To-Close and Heartbeat timeouts continue to be enforced.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Timers' instead of 'timers' when referring to a Temporal term.

github-actions · 2026-07-07T16:31:09Z

+- If the Activity is PAUSE_REQUESTED:
+  - Update Options reissues running-attempt timers so Start-To-Close and Heartbeat timeouts continue to be enforced.
+- If the Activity is RESET_REQUESTED:
+  - Update Options reissues running-attempt timers so Start-To-Close and Heartbeat timeouts continue to be enforced.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Timers' instead of 'timers' when referring to a Temporal term.

github-actions · 2026-07-07T16:31:09Z

+  - Update Options reissues running-attempt timers so Start-To-Close and Heartbeat timeouts continue to be enforced.
+- If cancellation is pending:
+  - Update Options is still allowed.
+  - Updated Start-To-Close and Heartbeat timers can still affect the running attempt.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Timers' instead of 'timers' when referring to a Temporal term.

github-actions · 2026-07-07T16:31:09Z

+  - Start Delay can't be updated after a Worker has picked up the first attempt.
+  - A nonzero Start Delay update requires Start Delay to be enabled for the Namespace.
+- Update Options doesn't reset attempts.
+- Update Options doesn't clear heartbeat details.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Heartbeat' instead of 'heartbeat' when referring to a Temporal term.

github-actions · 2026-07-07T16:31:09Z

 The `TemporalPauseInfo` [Search Attribute](/search-attribute) is filterable within a Workflow.

-There's no Namespace-wide query to find all Paused Activities across Workflows. You must know the Workflow Id.
+There's no Namespace-wide query to find all Paused Activities across Workflows. You must know the Workflow ID.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Query' instead of 'query' when referring to a Temporal term.

…aa-operator

github-actions · 2026-07-07T17:54:33Z

@@ -236,8 +236,7 @@ Use the following options to change the behavior of this command. You can also u
 Reset an activity. Not supported for Standalone Activities.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Activity' instead of 'activity' when referring to a Temporal term.

github-actions · 2026-07-07T17:54:33Z

@@ -236,8 +236,7 @@ Use the following options to change the behavior of this command. You can also u
 Reset an activity. Not supported for Standalone Activities.
 This restarts the activity as if it were first being


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Activity' instead of 'activity' when referring to a Temporal term.

github-actions · 2026-07-07T17:54:33Z

 scheduled. That is, it will reset both the number of attempts and the
-activity timeout, as well as, optionally, the
-[heartbeat details](#reset-heartbeats).
+activity timeout, as well as the [heartbeat details](#reset-heartbeats).


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Activity' instead of 'activity' when referring to a Temporal term.

github-actions · 2026-07-07T17:54:33Z

 scheduled. That is, it will reset both the number of attempts and the
-activity timeout, as well as, optionally, the
-[heartbeat details](#reset-heartbeats).
+activity timeout, as well as the [heartbeat details](#reset-heartbeats).


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Heartbeat' instead of 'heartbeat' when referring to a Temporal term.

github-actions · 2026-07-07T17:54:33Z

-[heartbeat details](#reset-heartbeats).
+activity timeout, as well as the [heartbeat details](#reset-heartbeats).

 If the activity may be executing (i.e. it has not yet timed out), the


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Activity' instead of 'activity' when referring to a Temporal term.

github-actions · 2026-07-07T17:54:33Z

@@ -291,7 +289,6 @@ Use the following options to change the behavior of this command. You can also u
 | `--query`, `-q` | No | **string** 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. |
 | `--reason` | No | **string** Reason for batch operation. Only use with --query. Defaults to user name. |
 | `--reset-attempts` | No | **bool** Reset the activity attempts. |


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Activity' instead of 'activity' when referring to a Temporal term.

github-actions · 2026-07-07T17:54:33Z

 | `--reason` | No | **string** Reason for batch operation. Only use with --query. Defaults to user name. |
 | `--reset-attempts` | No | **bool** Reset the activity attempts. |
-| `--reset-heartbeats` | No | **bool** Reset the Activity's heartbeats. |
 | `--restore-original-options` | No | **bool** Restore the original options of the activity. |


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Activity' instead of 'activity' when referring to a Temporal term.

github-actions · 2026-07-07T17:54:33Z

 | `--reset-attempts` | No | **bool** Reset the activity attempts. |
-| `--reset-heartbeats` | No | **bool** Reset the Activity's heartbeats. |
 | `--restore-original-options` | No | **bool** Restore the original options of the activity. |
 | `--rps` | No | **float** Limit batch's requests per second. Only allowed if query is present. |


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Query' instead of 'query' when referring to a Temporal term.

github-actions · 2026-07-07T17:54:33Z

+- After a reset dispatches a new attempt, the attempt's scheduled time reports the reset attempt's dispatch time, not
+  the original first-attempt dispatch time.
+- Reset discards retry backoff, but it still respects any remaining Start Delay before the first Worker pickup.
+- Reset clears stored heartbeat time and heartbeat details.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Heartbeat' instead of 'heartbeat' when referring to a Temporal term.

github-actions · 2026-07-07T17:54:33Z

+- After a reset dispatches a new attempt, the attempt's scheduled time reports the reset attempt's dispatch time, not
+  the original first-attempt dispatch time.
+- Reset discards retry backoff, but it still respects any remaining Start Delay before the first Worker pickup.
+- Reset clears stored heartbeat time and heartbeat details.


⚠️ [vale] _{reported by reviewdog 🐶}
[Temporal.terms] Use 'Heartbeat' instead of 'heartbeat' when referring to a Temporal term.

vercel Bot deployed to Preview July 6, 2026 23:13 View deployment

github-actions Bot reviewed Jul 6, 2026

View reviewed changes

github-actions Bot reviewed Jul 7, 2026

View reviewed changes

vercel Bot deployed to Preview July 7, 2026 16:31 View deployment

spkane31 and others added 4 commits July 7, 2026 11:31

[DRAFT] SAA operator commands documentation

61f2e4a

Edit existing docs

35c009f

additional documentation for reset heartbeats

4caf949

Merge branch 'main' of github.com:temporalio/documentation into spk/s…

65f091f

…aa-operator

spkane31 force-pushed the spk/saa-operator branch from 3e186aa to 65f091f Compare July 7, 2026 17:54

github-actions Bot reviewed Jul 7, 2026

View reviewed changes

vercel Bot deployed to Preview July 7, 2026 17:55 View deployment

		@@ -84,7 +84,8 @@ webhook, syncing data, or executing a single function reliably with built-in ret
		- Arbitrary length jobs with heartbeats for liveness and checkpointing progress
		- At-least-once execution by default with native retry policy and timeouts


		- Update Options is CLI and gRPC only. It's not available in the UI.

		## Standalone Activity operator commands {/* #standalone-activity-operator-commands */}

		@@ -236,8 +236,7 @@ Use the following options to change the behavior of this command. You can also u
		Reset an activity. Not supported for Standalone Activities.

		@@ -236,8 +236,7 @@ Use the following options to change the behavior of this command. You can also u
		Reset an activity. Not supported for Standalone Activities.
		This restarts the activity as if it were first being

Uh oh!

Conversation

spkane31 commented Jul 6, 2026 • edited by sync-by-unito Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Notes to reviewers

Uh oh!

vercel Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📖 Docs PR preview links

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

spkane31 commented Jul 6, 2026 •

edited by sync-by-unito Bot

Loading

vercel Bot commented Jul 6, 2026 •

edited

Loading

github-actions Bot commented Jul 6, 2026 •

edited

Loading