Standalone activity client by dandavison · Pull Request #942 · temporalio/cli

dandavison · 2026-02-08T11:42:30Z

What was changed

Why?

Checklist

Closes
How was this tested:

Any docs updates needed?

Define 9 new commands under `temporal activity` for standalone (top-level) Activity Executions: start, execute, describe, list, count, cancel, terminate, delete, result. Each mirrors the corresponding `temporal workflow` command pattern. Modify `complete` and `fail` to make --workflow-id optional so they work for both workflow-scoped and standalone Activities. Add two new reusable option sets: `activity-execution-reference` (activity-id + run-id) and `activity-start` (full set of start options including timeouts, retry policy, ID policies, search attributes, headers, metadata, and priority). All new commands are marked Experimental. Existing workflow-only commands (pause, unpause, reset, update-options) are unchanged. Co-authored-by: Cursor <cursoragent@cursor.com>

- cancel: Rewrite description following Python SDK style, explaining that cancellation is a request delivered via heartbeat response - complete/fail: Use activity-reference option set instead of inlining activity-id/run-id, fixing missing short flag and missing "latest run" description - fail: Clarify detail vs reason option descriptions (detail is the failure details payload; reason is the failure message) - count/list: Add example queries, improve query option descriptions, add visibility docs links - delete: Add note about async deletion and running activity termination (from proto docs) - execute: Use "output" instead of "printed" - update-options/pause/unpause/reset: Add "Not supported for standalone Activities" sentence - Remove resolved TODO comments Co-authored-by: Cursor <cursoragent@cursor.com>

Phase 2: Run code generation producing command structs for all 9 new commands and 2 new option sets (ActivityReferenceOptions, ActivityStartOptions). Phase 3: Implement run() methods for all new commands: - start: calls StartActivityExecution, outputs activity ID and run ID - execute: calls StartActivityExecution + PollActivityExecution, outputs the activity result - describe: calls DescribeActivityExecution with include_input and include_outcome - list: calls ListActivityExecutions with pagination, table output - count: calls CountActivityExecutions with group support - cancel: calls RequestCancelActivityExecution - terminate: calls TerminateActivityExecution with default reason - delete: calls DeleteActivityExecution - result: calls PollActivityExecution, outputs the activity result Shared helper buildStartActivityRequest() constructs the gRPC request from ActivityStartOptions, handling retry policy, ID policies, search attributes, headers, user metadata, and priority. Shared helper printActivityOutcome() formats activity results for both text and JSON output modes. Also adds description-header to temporal activity docs (required by code generator) and fixes import aliasing (common/v1 -> commonpb). Co-authored-by: Cursor <cursoragent@cursor.com>

Verify all 11 activity subcommands appear in help output (cancel, complete, count, delete, describe, execute, fail, list, result, start, terminate). Verify start command exposes expected flags (activity-id, type, task-queue, timeouts, input). Verify complete and fail commands expose both activity-reference options (activity-id, run-id) and the optional workflow-id flag. Integration tests for the new RPCs are deferred until a standalone-activity-enabled test server is available. Co-authored-by: Cursor <cursoragent@cursor.com>

- Use 'activity complete' as the primary example instead of experimental 'activity start' command - Restore original description-header text for docs - Revert unnecessary commonpb import alias (use default 'common' since no conflict exists in this file) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

dandavison

Addressed in new commits.

dandavison · 2026-02-08T11:42:57Z

internal/temporalcli/commands.yaml

+        - activity terminate
+        - activity delete
        - activity complete
-        - activity update-options


why delete this? The command still exists but only for workflow activities.

Restored the original description-header in 1b728de.

dandavison · 2026-02-08T11:44:34Z

internal/temporalcli/commands.yaml

+          --type YourActivity \
+          --task-queue YourTaskQueue \
+          --input '{"some-key": "some-value"}'
+      ```


Since this is an experimental API, I don't think it should be the example.

Agreed. Changed to use activity complete as the primary example and added activity update-options as the second example in 1b728de.

But update-options isn't even implemented is it? I thought it wasn't in the grpc API.

The update-options command is implemented and functional. It uses WorkflowService().UpdateActivityOptions() from the gRPC API. You can see the implementation at commands.activity.go:101-236 and the passing tests TestActivityOptionsUpdate_Accept and TestActivityOptionsUpdate_Partial in commands.activity_test.go.

Just ran the tests to confirm:

go test -run "TestSharedServerSuite/TestActivityOptionsUpdate" ./internal/temporalcli/ -v --- PASS: TestSharedServerSuite (1.81s) --- PASS: TestSharedServerSuite/TestActivityOptionsUpdate_Accept (0.11s) --- PASS: TestSharedServerSuite/TestActivityOptionsUpdate_Partial (0.11s)

I see. Yes, I was confusing this with the fact that it's not implemented for standalone activity. However, let's not just not add any example here; this is temporal activity after all, not any verb.

🤖 Agreed — the temporal activity help now shows examples for activity complete and activity update-options (both workflow-activity commands). The standalone-only activity start example has been removed from this top-level help.

dandavison · 2026-02-16T01:58:58Z

internal/temporalcli/commands.activity.go

 	defer cl.Close()

-	var detailPayloads *common.Payloads
+	var detailPayloads *commonpb.Payloads


Why did you change this?

Reverted in 1b728de. The commonpb alias was unnecessary since there's no import conflict in this file — the default package name common works fine.

dandavison · 2026-02-16T03:04:26Z

internal/temporalcli/commands.yaml

+          --type YourActivity \
+          --task-queue YourTaskQueue \
+          --input '{"some-key": "some-value"}'
+      ```


I see. Yes, I was confusing this with the fact that it's not implemented for standalone activity. However, let's not just not add any example here; this is temporal activity after all, not any verb.

dandavison · 2026-02-16T03:08:16Z

internal/temporalcli/commands.yaml

+      error will be raised when the next heartbeat response is
+      received; if the Activity allows this error to propagate, the
+      Activity transitions to canceled status. If the Activity is
+      not heartbeating, this request has no effect on the Activity.


Double-check that there is test coverage in the server repo (tests/standalone_activity_test.go) for this and that it proves the behavior is exactly as we say here.

🤖 The server repo is not in this workspace. Suggest verifying tests/standalone_activity_test.go in the server repo separately.

🤖 The server repo is not available locally. I searched ~/src/temporal-all/repos/ but there is no server/ directory. This needs to be verified in the server repo separately.

The server repo is called temporal. I'mm surprised you don't know that.

🤖 Found it — repos/temporal/tests/standalone_activity_test.go (4128 lines). The cancel behavior is verified in TestRequestCancel: it starts an activity, requests cancellation, then heartbeats and asserts CancelRequested=true on the heartbeat response, then responds with canceled and verifies status=CANCELED. This confirms the description: cancellation is raised via heartbeat response.

Full test list: TestIDReusePolicy, TestIDConflictPolicy, TestPollActivityTaskQueue, TestComplete, TestFail, TestRequestCancel, TestTerminate, TestRetryWithoutScheduleToCloseTimeout, Test_ScheduleToCloseTimeout_WithRetry, TestStartToCloseTimeout, TestScheduleToStartTimeout, TestDescribeActivityExecution_{NoWait,WaitAnyStateChange,Completed,DeadlineExceeded,NotFound,InvalidArgument}, TestPollActivityExecution{,_EmptyRunID,_NotFound,_InvalidArgument}, TestListActivityExecutions, TestCountActivityExecutions, TestHeartbeat.

dandavison · 2026-02-16T03:13:29Z

internal/temporalcli/commands.yaml

-      Activity ID and include a JSON result for the returned value:
+      Complete an Activity, marking it as successfully finished.
+      Specify the Activity ID and include a JSON result for the
+      returned value:


This change is pure whitespace and is just adding noise to the diff.

🤖 No trailing-whitespace-only changes in current file; any prior diff noise was addressed in 2ec455d.

dandavison · 2026-02-16T03:14:26Z

internal/temporalcli/commands.yaml

      ```
      temporal activity complete \
          --activity-id YourActivityId \
-          --workflow-id YourWorkflowId \


This was here before, so we shouldn't be getting rid of it. In general, standalone activity is a new feature; workflow activity is the more commonly used by a long way.

🤖 Addressed in 2de6d1e: restored “activity execution” in keywords.

dandavison · 2026-02-16T03:16:32Z

internal/temporalcli/commands.yaml

+    description: |
+      Return a count of Activity Executions. Use `--query` to count
+      a subset:


Suggested change

description: |

Return a count of Activity Executions. Use `--query` to count

a subset:

description: |

Return a count of Activity Executions. Use `--query` to filter

the activities to be counted.

🤖 Addressed in 2de6d1e: activity count/list use “filter the activities to be counted”, “Search Attributes and queries.”, and “Standalone Activity Execution” / “only supported for Standalone Activity Execution” wording.

dandavison · 2026-02-16T03:39:02Z

internal/temporalcli/commands.yaml

          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.   
+          Note: These are workflow headers, not gRPC headers.


don't make changes in this PR that are merely trailing whitespace

🤖 No trailing-whitespace-only changes in current file.

🤖 Reverted all trailing-whitespace-only changes in c96bb91.

dandavison · 2026-02-16T03:43:08Z

internal/temporalcli/commands.yaml

+          Re-use policy for the Activity ID when a previous
+          Execution has completed.


Suggested change

Re-use policy for the Activity ID when a previous

Execution has completed.

Policy for handling activity start when an Activity

with the same ID exists and has completed.

🤖 Applied suggestion in c96bb91.

dandavison · 2026-02-16T03:44:31Z

internal/temporalcli/commands.yaml

+          Policy for handling a conflict when starting an
+          Activity with a duplicate Activity ID of a running
+          Execution.


Suggested change

Policy for handling a conflict when starting an

Activity with a duplicate Activity ID of a running

Execution.

Policy for handling activity start when an

Activity with the same ID is currently running.

🤖 Applied suggestion in c96bb91.

dandavison · 2026-02-16T03:45:35Z

internal/temporalcli/commands.yaml

+          Search Attribute in `KEY=VALUE` format.
+          Keys must be identifiers, and values must be
+          JSON values.
+          Can be passed multiple times.


Suggested change

Can be passed multiple times.

Can be passed multiple times.

See https://docs.temporal.io/visibility.

🤖 Applied suggestion in c96bb91: added See https://docs.temporal.io/visibility. to search-attribute description.

dandavison · 2026-02-16T03:46:30Z

internal/temporalcli/commands.yaml

+        experimental: true
+        description: |
+          Static Activity summary for human consumption in UIs.
+          Uses Temporal Markdown formatting.


Can you find whether "Temporal Markdown" is documented somewhere? Use your temporal-docs MCP tool and/or the documentation repo.

🤖 I searched the api proto repo, sdk-go, sdk-java, documentation repo, and UI repo. "Temporal Markdown" is used as a term in Go SDK and Java SDK doc comments (e.g. in single-line Temporal Markdown format) and in the generated CLI docs, but there is no dedicated documentation page or formal specification for it. The term appears to refer to standard Markdown as rendered by the Temporal UI.

- Activity count/list/result: use Standalone Activity Execution wording and 'only supported for Standalone Activity Execution' - Activity complete/fail: restore --workflow-id YourWorkflowId in examples - Keywords: restore 'activity execution' - Activity count/list: Search Attributes and queries; filter/to be counted - Workflow execute: add backslash after execute in example - Workflow start: revert to main (Initiate, Returns Workflow- and Run-IDs) - Workflow delete: revert to main (Remove, Executions typo); remove TODO - Workflow result: remove TODO (output verb already used) - Workflow count/list: example query and remove TODOs; queries. wording - Restore trailing spaces in worker deployment and task-queue docs to avoid whitespace-only diff noise Co-authored-by: Cursor <cursoragent@cursor.com>

dandavison · 2026-02-16T04:07:58Z

🤖 Addressed all review feedback in commit 2ec455d:

Activity count/list/result: Use "Standalone Activity Execution" and "only supported for Standalone Activity Execution".
Activity complete/fail: Restored --workflow-id YourWorkflowId in examples.
Keywords: Restored "activity execution".
Activity count/list: "Search Attributes and queries"; "filter the activities to be counted".
Workflow execute: Added backslash after execute in example.
Workflow start: Reverted to main (Initiate, Returns Workflow- and Run-IDs).
Workflow delete: Reverted to main (Remove, Executions typo); removed TODO.
Workflow result: Removed TODO (output verb already used).
Workflow count/list: Example queries and "queries." wording; removed TODOs.
Trailing whitespace: Restored in worker deployment and task-queue docs to avoid diff noise.

2810472090 (server repo test coverage): The server repo is not in this workspace; suggest verifying tests/standalone_activity_test.go in the server repo separately.

This reverts commit 2ec455d.

- Activity complete/fail: restore --workflow-id in examples - Activity count/list: Standalone Activity Execution wording, filter/sentences, Search Attributes and queries - All standalone-only activity commands: summary + only supported sentence - Restore activity execution keyword - Workflow describe: revert summary to Show Workflow Execution info - Workflow delete: remove TODO - Workflow terminate: revert summary to Forcefully end a Workflow Execution - Workflow execute: add backslash after execute in example - Workflow count/list: remove TODO show an example query - Workflow result: remove TODO Co-authored-by: Cursor <cursoragent@cursor.com>

- Revert all trailing-whitespace-only changes in deployment/worker sections - Restore trailing whitespace on workflow headers line to match main - Apply workflow start description suggestion (mention workflow execute) - Apply id-reuse-policy description suggestion - Apply id-conflict-policy description suggestion - Add visibility docs link to search-attribute description Co-authored-by: Cursor <cursoragent@cursor.com>

Individual verb subcommands already have examples. Co-authored-by: Cursor <cursoragent@cursor.com>

dandavison · 2026-02-16T05:13:35Z

internal/temporalcli/commands.yaml

+    summary: List Standalone Activity Executions (Experimental)
+    description: |
+      List Standalone Activity Executions. Use `--query` to filter results.
+      Only supported for Standalone Activity Execution.


Suggested change

Only supported for Standalone Activity Execution.

🤖 Applied: removed redundant sentence from all 9 standalone activity command descriptions in ed5405a.

The summaries already say "Standalone", making this sentence redundant in the descriptions. Co-authored-by: Cursor <cursoragent@cursor.com>

dandavison · 2026-02-16T05:15:26Z

internal/temporalcli/commands.yaml

    description: |
      Update the options of a running Activity that were passed into it from
      a Workflow. Updates are incremental, only changing the specified options.
+      Not supported for standalone Activities.


Capitalization should be Standalone Activit{y,ies} throughout this file.

🤖 Applied in 69f8335: capitalized "Standalone Activities" in all 6 remaining lowercase instances.

Co-authored-by: Cursor <cursoragent@cursor.com>

dandavison and others added 7 commits February 8, 2026 05:00

Bump SDK

87301b4

Bump server

9439326

Code review

a0eebde

dandavison force-pushed the standalone-activity-client branch from be04db2 to f1d4185 Compare February 9, 2026 02:37

dandavison commented Feb 16, 2026

View reviewed changes

dandavison and others added 4 commits February 15, 2026 23:22

Revert "Address PR 942 review: docs and revert noise"

adc5329

This reverts commit 2ec455d.

Remove examples from temporal activity top-level help

c9f6af7

Individual verb subcommands already have examples. Co-authored-by: Cursor <cursoragent@cursor.com>

dandavison commented Feb 16, 2026

View reviewed changes

Remove redundant "Only supported for Standalone Activity Execution"

ed5405a

The summaries already say "Standalone", making this sentence redundant in the descriptions. Co-authored-by: Cursor <cursoragent@cursor.com>

dandavison commented Feb 16, 2026

View reviewed changes

Capitalize "Standalone Activities" consistently

69f8335

Co-authored-by: Cursor <cursoragent@cursor.com>

		Re-use policy for the Activity ID when a previous
		Execution has completed.

	Can be passed multiple times.
	Can be passed multiple times.
	See https://docs.temporal.io/visibility.

Conversation

dandavison commented Feb 8, 2026

What was changed

Why?

Checklist

Uh oh!

dandavison left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dandavison commented Feb 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment