Temporal CLI activity command reference

View Markdown

This page provides a reference for the temporal CLI activity command. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to Global Flags for flags that you can use with every subcommand.

cancel

Request cancellation of a Standalone Activity.

temporal activity cancel \
    --activity-id YourActivityId

Requesting cancellation transitions the Activity's run state to CancelRequested. If the Activity is heartbeating, a cancellation 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.

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	Yes	string Activity ID.
--reason	No	string Reason for cancellation.
--run-id, -r	No	string Activity Run ID. If not set, targets the latest run.

complete

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

temporal activity complete \
    --activity-id YourActivityId \
    --workflow-id YourWorkflowId \
    --result '{"YourResultKey": "YourResultVal"}'

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	Yes	string Activity ID. This may be the ID of an Activity invoked by a Workflow, or of a Standalone Activity.
--result	Yes	string Result JSON to return.
--run-id, -r	No	string Run ID. For workflow Activities (when --workflow-id is provided), this is the Workflow Run ID. For Standalone Activities, this is the Activity Run ID.
--workflow-id, -w	No	string Workflow ID. Required for workflow Activities. Omit for Standalone Activities.

count

Return a count of Standalone Activities. Use --query to filter the activities to be counted.

temporal activity count \
    --query 'ActivityType="YourActivity"'

Visit https://docs.temporal.io/visibility to read more about Search Attributes and queries.

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--query, -q	No	string Query to filter Activity Executions to count.

describe

Display information about a Standalone Activity.

temporal activity describe \
    --activity-id YourActivityId

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	Yes	string Activity ID.
--raw	No	bool Print properties without changing their format.
--run-id, -r	No	string Activity Run ID. If not set, targets the latest run.

execute

Start a new Standalone Activity and block until it completes. The result is output to stdout.

temporal activity execute \
    --activity-id YourActivityId \
    --type YourActivity \
    --task-queue YourTaskQueue \
    --start-to-close-timeout 30s \
    --input '{"some-key": "some-value"}'

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	Yes	string Activity ID.
--fairness-key	No	string Fairness key (max 64 bytes) for proportional task dispatch.
--fairness-weight	No	float Weight [0.001-1000] for this fairness key.
--headers	No	string[] Temporal activity headers in 'KEY=VALUE' format. Keys must be identifiers, and values must be JSON values. May be passed multiple times.
--heartbeat-timeout	No	duration Maximum time between successful Worker heartbeats. On expiry the current activity attempt fails.
--id-conflict-policy	No	string-enum Policy for handling activity start when an Activity with the same ID is currently running. Accepted values: Fail, UseExisting.
--id-reuse-policy	No	string-enum Policy for handling activity start when an Activity with the same ID exists and has completed. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate.
--input, -i	No	string[] Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.
--input-base64	No	bool Assume inputs are base64-encoded and attempt to decode them.
--input-file	No	string[] A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.
--input-meta	No	string[] Input payload metadata as a KEY=VALUE pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.
--priority-key	No	int Priority key (1-5, lower = higher priority). Default is 3 when not specified.
--retry-backoff-coefficient	No	float Coefficient for calculating the next retry interval. Must be 1 or larger.
--retry-initial-interval	No	duration Interval of the first retry. If "retry-backoff-coefficient" is 1.0, it is used for all retries.
--retry-maximum-attempts	No	int Maximum number of attempts. Setting to 1 disables retries. Setting to 0 means unlimited attempts.
--retry-maximum-interval	No	duration Maximum interval between retries.
--schedule-to-close-timeout	No	duration Maximum time for the Activity Execution, including all retries. Either this or "start-to-close-timeout" is required.
--schedule-to-start-timeout	No	duration Maximum time an Activity task can stay in a task queue before a Worker picks it up. On expiry it results in a non-retryable failure and no further attempts are scheduled.
--search-attribute	No	string[] Search Attribute in KEY=VALUE format. Keys must be identifiers, and values must be JSON values. Can be passed multiple times. See https://docs.temporal.io/visibility.
--start-to-close-timeout	No	duration Maximum time for a single Activity attempt. On expiry a new attempt may be scheduled if permitted by the retry policy and schedule-to-close timeout. Either this or "schedule-to-close-timeout" is required.
--static-details	No	string Static Activity details for human consumption in UIs. Uses standard Markdown formatting excluding images, HTML, and script tags. (Experimental)
--static-summary	No	string Static Activity summary for human consumption in UIs. Uses standard Markdown formatting excluding images, HTML, and script tags. (Experimental)
--task-queue, -t	Yes	string Activity task queue.
--type	Yes	string Activity Type name.

fail

Fail an Activity, marking it as having encountered an error:

temporal activity fail \
    --activity-id YourActivityId \
    --workflow-id YourWorkflowId

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	Yes	string Activity ID. This may be the ID of an Activity invoked by a Workflow, or of a Standalone Activity.
--detail	No	string Failure detail (JSON). Attached as the failure details payload.
--reason	No	string Failure reason. Attached as the failure message.
--run-id, -r	No	string Run ID. For workflow Activities (when --workflow-id is provided), this is the Workflow Run ID. For Standalone Activities, this is the Activity Run ID.
--workflow-id, -w	No	string Workflow ID. Required for workflow Activities. Omit for Standalone Activities.

list

List Standalone Activities. Use --query to filter results.

temporal activity list \
    --query 'ActivityType="YourActivity"'

Visit https://docs.temporal.io/visibility to read more about Search Attributes and queries.

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--limit	No	int Maximum number of Activity Executions to display.
--page-size	No	int Maximum number of Activity Executions to fetch at a time from the server.
--query, -q	No	string Query to filter the Activity Executions to list.

pause

Pause a Workflow Activity or Standalone Activity.

If no Worker is running the Activity, it won't be dispatched until it is Unpaused. If an attempt is running, the Pause remains pending. The next Heartbeat response reports the Pause; otherwise, the attempt continues until it completes, fails, or times out.

However, if the Activity is currently running, it will run until the next time it fails, completes, or times out, at which point the pause will kick in.

Pause does not stop or extend the Activity's Schedule-To-Close Timeout. A paused Activity can still time out. Use temporal activity update-options to extend timeout settings before a long pause.

If the Activity is on its last retry attempt and fails, the failure will be returned to the caller, just as if the Activity had not been paused.

Specify the Activity and Workflow IDs:

temporal activity pause \
    --workflow-id YourWorkflowId \
    --activity-id YourActivityId

To target the latest run of a Standalone Activity, omit --workflow-id:

temporal activity pause \
    --activity-id YourActivityId

Use --run-id to target a specific Workflow Run or Standalone Activity Run. See Activity Operations for behavior and state transitions.

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	Yes	string Activity ID.
--identity	No	string The identity of the user or client submitting this request.
--reason	No	string Reason for pausing the Activity.
--run-id, -r	No	string Workflow Run ID when --workflow-id is set; otherwise, Standalone Activity Run ID. If omitted for a Standalone Activity, targets the latest run.
--workflow-id, -w	No	string Workflow ID for a Workflow Activity. Omit for a Standalone Activity.

reset

Reset a Workflow Activity or Standalone Activity to attempt 1. Reset clears retry backoff and Heartbeat details, but it doesn't restart the Schedule-To-Close period.

Reset applies immediately when no Activity Task Execution is in flight—for example, while the Activity is waiting for its initial Start Delay or retry backoff, is dispatched but not yet picked up by a Worker, or is fully Paused. The next attempt still waits for any applicable Start Delay, jitter, or Paused state.

After a Worker picks up an Activity Task, Reset remains pending until that attempt reports an outcome or times out. A successful result wins and Reset has no effect; a failure or timeout applies Reset and schedules attempt 1 if it fits within the unchanged Schedule-To-Close deadline. The next Heartbeat response reports the pending Reset.

If the Activity is Paused, Reset Unpauses it by default. Use --keep-paused to reset its state without dispatching it.

To target a Workflow Activity, provide both IDs. To target a Standalone Activity, provide --activity-id and omit --workflow-id. Use --run-id to select a specific Workflow Run or Standalone Activity Run.

temporal activity reset \
    --activity-id YourActivityId

Heartbeat behavior when resetting

Activities that heartbeat will receive a Canceled failure the next time they heartbeat after a reset.

If, in your Activity, you need to do any cleanup when an Activity is reset, handle this error and then re-throw it when you've cleaned up.

Reset always clears the last Heartbeat time and Heartbeat details when it is applied.

Workflow Activities can be Reset in bulk with a Visibility Query List Filter. Batch mode doesn't target Standalone Activities.

temporal activity reset \
    --query 'WorkflowType="YourWorkflow"'

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	No	string Activity ID. Mutually exclusive with --query. Set --workflow-id for a Workflow Activity; omit it for a Standalone Activity.
--headers	No	string[] 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.
--jitter	No	duration Delays the new dispatch by a random duration within this window. Ignored while --keep-paused prevents dispatch.
--keep-paused	No	bool Keep a Paused Activity Paused after Reset.
--query, -q	No	string SQL-like Visibility Query List Filter for a batch of Workflow Activities. Mutually exclusive with --activity-id. This feature is experimental and may change.
--reason	No	string Reason for batch operation. Only use with --query. Defaults to user name.
--restore-original-options	No	bool Restore the Activity options captured when it was first scheduled.
--rps	No	float Limit batch's requests per second. Only allowed if query is present.
--run-id, -r	No	string Workflow Run ID when --workflow-id is set; otherwise, Standalone Activity Run ID. Can't be used with --query.
--workflow-id, -w	No	string Workflow ID for a Workflow Activity. Omit for a Standalone Activity. Can't be used with --query.
--yes, -y	No	bool Don't prompt to confirm signaling. Only allowed when --query is present.

result

Wait for a Standalone Activity to complete and output the result.

temporal activity result \
    --activity-id YourActivityId

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	Yes	string Activity ID.
--run-id, -r	No	string Activity Run ID. If not set, targets the latest run.

start

Start a new Standalone Activity. Outputs the Activity ID and Run ID.

temporal activity start \
    --activity-id YourActivityId \
    --type YourActivity \
    --task-queue YourTaskQueue \
    --start-to-close-timeout 5m \
    --input '{"some-key": "some-value"}'

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	Yes	string Activity ID.
--fairness-key	No	string Fairness key (max 64 bytes) for proportional task dispatch.
--fairness-weight	No	float Weight [0.001-1000] for this fairness key.
--headers	No	string[] Temporal activity headers in 'KEY=VALUE' format. Keys must be identifiers, and values must be JSON values. May be passed multiple times.
--heartbeat-timeout	No	duration Maximum time between successful Worker heartbeats. On expiry the current activity attempt fails.
--id-conflict-policy	No	string-enum Policy for handling activity start when an Activity with the same ID is currently running. Accepted values: Fail, UseExisting.
--id-reuse-policy	No	string-enum Policy for handling activity start when an Activity with the same ID exists and has completed. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate.
--input, -i	No	string[] Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.
--input-base64	No	bool Assume inputs are base64-encoded and attempt to decode them.
--input-file	No	string[] A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.
--input-meta	No	string[] Input payload metadata as a KEY=VALUE pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.
--priority-key	No	int Priority key (1-5, lower = higher priority). Default is 3 when not specified.
--retry-backoff-coefficient	No	float Coefficient for calculating the next retry interval. Must be 1 or larger.
--retry-initial-interval	No	duration Interval of the first retry. If "retry-backoff-coefficient" is 1.0, it is used for all retries.
--retry-maximum-attempts	No	int Maximum number of attempts. Setting to 1 disables retries. Setting to 0 means unlimited attempts.
--retry-maximum-interval	No	duration Maximum interval between retries.
--schedule-to-close-timeout	No	duration Maximum time for the Activity Execution, including all retries. Either this or "start-to-close-timeout" is required.
--schedule-to-start-timeout	No	duration Maximum time an Activity task can stay in a task queue before a Worker picks it up. On expiry it results in a non-retryable failure and no further attempts are scheduled.
--search-attribute	No	string[] Search Attribute in KEY=VALUE format. Keys must be identifiers, and values must be JSON values. Can be passed multiple times. See https://docs.temporal.io/visibility.
--start-to-close-timeout	No	duration Maximum time for a single Activity attempt. On expiry a new attempt may be scheduled if permitted by the retry policy and schedule-to-close timeout. Either this or "schedule-to-close-timeout" is required.
--static-details	No	string Static Activity details for human consumption in UIs. Uses standard Markdown formatting excluding images, HTML, and script tags. (Experimental)
--static-summary	No	string Static Activity summary for human consumption in UIs. Uses standard Markdown formatting excluding images, HTML, and script tags. (Experimental)
--task-queue, -t	Yes	string Activity task queue.
--type	Yes	string Activity Type name.

terminate

Terminate a Standalone Activity.

temporal activity terminate \
    --activity-id YourActivityId \
    --reason YourReason

Activity code cannot see or respond to terminations.

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	Yes	string Activity ID.
--reason	No	string Reason for termination. Defaults to a message with the current user's name.
--run-id, -r	No	string Activity Run ID. If not set, targets the latest run.

unpause

Resume a Paused Workflow Activity or Standalone Activity.

By default, the Activity keeps its attempt count, Heartbeat details, and any remaining retry backoff. The next attempt is dispatched after that backoff and any remaining Start Delay.

Use --reset-attempts to restart at attempt 1 or --jitter to add a random delay before dispatch.

To target a Workflow Activity, provide both IDs:

temporal activity unpause \
    --workflow-id YourWorkflowId \
    --activity-id YourActivityId

To target a Standalone Activity, provide --activity-id and omit --workflow-id. Use --run-id to select a specific Workflow Run or Standalone Activity Run.

Workflow Activities can be Unpaused in bulk with a Visibility Query List Filter. Batch mode doesn't target Standalone Activities.

temporal activity unpause \
    --query 'TemporalPauseInfo IS NOT NULL'

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	No	string Activity ID. Mutually exclusive with --query. Set --workflow-id for a Workflow Activity; omit it for a Standalone Activity.
--headers	No	string[] 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.
--jitter	No	duration Adds a random delay within this window before the next dispatch.
--query, -q	No	string SQL-like Visibility Query List Filter for a batch of Workflow Activities. Mutually exclusive with --activity-id. This feature is experimental and may change.
--reason	No	string Reason for batch operation. Only use with --query. Defaults to user name.
--reset-attempts	No	bool Reset the Activity to attempt 1 and clear its current retry interval.
--rps	No	float Limit batch's requests per second. Only allowed if query is present.
--run-id, -r	No	string Workflow Run ID when --workflow-id is set; otherwise, Standalone Activity Run ID. Can't be used with --query.
--workflow-id, -w	No	string Workflow ID for a Workflow Activity. Omit for a Standalone Activity. Can't be used with --query.
--yes, -y	No	bool Don't prompt to confirm signaling. Only allowed when --query is present.

update-options

Update the options of a Workflow Activity or Standalone Activity. Updates are incremental; options that you don't specify remain unchanged.

To target a Workflow Activity, provide the Workflow and Activity IDs. To target a Standalone Activity, provide --activity-id and omit --workflow-id:

temporal activity update-options \
    --activity-id YourActivityId \
    --task-queue NewTaskQueueName \
    --schedule-to-close-timeout DURATION \
    --schedule-to-start-timeout DURATION \
    --start-to-close-timeout DURATION \
    --heartbeat-timeout DURATION \
    --retry-initial-interval DURATION \
    --retry-maximum-interval DURATION \
    --retry-backoff-coefficient NewBackoffCoefficient \
    --retry-maximum-attempts NewMaximumAttempts

Use --run-id to select a specific Workflow Run or Standalone Activity Run. Use --restore-original-options without other option flags to restore the values captured when the Activity was first scheduled.

Workflow Activity options can be updated in bulk with a Visibility Query List Filter. Batch mode doesn't target Standalone Activities.

temporal activity update-options \
    --query 'WorkflowType="YourWorkflow"' \
    --task-queue NewTaskQueueName

Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.

Flag	Required	Description
--activity-id, -a	No	string Activity ID. Mutually exclusive with --query. Set --workflow-id for a Workflow Activity; omit it for a Standalone Activity.
--headers	No	string[] 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.
--heartbeat-timeout	No	duration Maximum permitted time between successful worker heartbeats.
--query, -q	No	string SQL-like Visibility Query List Filter for a batch of Workflow Activities. Mutually exclusive with --activity-id. This feature is experimental and may change.
--reason	No	string Reason for batch operation. Only use with --query. Defaults to user name.
--restore-original-options	No	bool Restore the Activity options captured when it was first scheduled. Can't be combined with option changes.
--retry-backoff-coefficient	No	float 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.
--retry-initial-interval	No	duration Interval of the first retry. If retryBackoffCoefficient is 1.0 then it is used for all retries.
--retry-maximum-attempts	No	int 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).
--retry-maximum-interval	No	duration Maximum interval between retries. Exponential backoff leads to interval increase. This value is the cap of the increase.
--rps	No	float Limit batch's requests per second. Only allowed if query is present.
--run-id, -r	No	string Workflow Run ID when --workflow-id is set; otherwise, Standalone Activity Run ID. Can't be used with --query.
--schedule-to-close-timeout	No	duration Indicates how long the caller is willing to wait for an activity completion. Limits how long retries will be attempted.
--schedule-to-start-timeout	No	duration 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 the schedule-to-close timeout or workflow execution timeout if not specified.
--start-to-close-timeout	No	duration Maximum time an activity is allowed to execute after being picked up by a worker. This timeout is always retryable.
--task-queue	No	string Name of the task queue for the Activity.
--workflow-id, -w	No	string Workflow ID for a Workflow Activity. Omit for a Standalone Activity. Can't be used with --query.
--yes, -y	No	bool Don't prompt to confirm signaling. Only allowed when --query is present.

Global Flags

The following options can be used with any command.

Flag	Required	Description	Default
--address	No	string Temporal Service gRPC endpoint.	localhost:7233
--api-key	No	string API key for request.
--client-authority	No	string Temporal gRPC client :authority pseudoheader.
--client-connect-timeout	No	duration The client connection timeout. 0s means no timeout.
--codec-auth	No	string Authorization header for Codec Server requests.
--codec-endpoint	No	string Remote Codec Server endpoint.
--codec-header	No	string[] HTTP headers for requests to codec server. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers.
--color	No	string-enum Output coloring. Accepted values: always, never, auto.	auto
--command-timeout	No	duration The command execution timeout. 0s means no timeout.
--config-file	No	string File path to read TOML config from, defaults to $CONFIG_PATH/temporalio/temporal.toml where $CONFIG_PATH is defined as $HOME/.config on Unix, $HOME/Library/Application Support on macOS, and %AppData% on Windows.
--disable-config-env	No	bool If set, disables loading environment config from environment variables.
--disable-config-file	No	bool If set, disables loading environment config from config file.
--env	No	string Active environment name (ENV).	default
--env-file	No	string Path to environment settings file. Defaults to $HOME/.config/temporalio/temporal.yaml.
--grpc-meta	No	string[] HTTP headers for requests. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as TEMPORAL_GRPC_META_[name].
--identity	No	string The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".
--log-format	No	string-enum Log format. Accepted values: text, json.	text
--log-level	No	string-enum Log level. Default is "never" for most commands and "warn" for "server start-dev". Accepted values: debug, info, warn, error, never.	never
--namespace, -n	No	string Temporal Service Namespace.	default
--no-json-shorthand-payloads	No	bool Raw payload output, even if the JSON option was used.
--output, -o	No	string-enum Non-logging data output format. Accepted values: text, json, jsonl, none.	text
--profile	No	string Profile to use for config file.
--time-format	No	string-enum Time format. Accepted values: relative, iso, raw.	relative
--tls	No	bool Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.
--tls-ca-data	No	string Data for server CA certificate. Can't be used with --tls-ca-path.
--tls-ca-path	No	string Path to server CA certificate. Can't be used with --tls-ca-data.
--tls-cert-data	No	string Data for x509 certificate. Can't be used with --tls-cert-path.
--tls-cert-path	No	string Path to x509 certificate. Can't be used with --tls-cert-data.
--tls-disable-host-verification	No	bool Disable TLS host-name verification.
--tls-key-data	No	string Private certificate key data. Can't be used with --tls-key-path.
--tls-key-path	No	string Path to x509 private key. Can't be used with --tls-key-data.
--tls-server-name	No	string Override target TLS server name.