Temporal CLI activity command reference
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.
| Flag | Required | Description | Default |
|---|---|---|---|
--activity-id | Yes | string Activity ID to complete. | |
--result | Yes | string Result JSON to return. | |
--run-id, -r | No | string Run ID. | |
--workflow-id, -w | Yes | string Workflow ID. |
fail
Fail an Activity, marking it as having encountered an error. Specify the Activity and Workflow IDs:
temporal activity fail \
--activity-id YourActivityId \
--workflow-id YourWorkflowId
Use the following options to change the behavior of this command.
| Flag | Required | Description | Default |
|---|---|---|---|
--activity-id | Yes | string Activity ID to fail. | |
--detail | No | string Reason for failing the Activity (JSON). | |
--reason | No | string Reason for failing the Activity. | |
--run-id, -r | No | string Run ID. | |
--workflow-id, -w | Yes | string Workflow ID. |
pause
Pause an Activity.
If the Activity is not currently running (e.g. because it previously failed), it will not be run again until it is unpaused.
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.
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.
Activities should be specified either by their Activity ID or Activity Type.
For example, specify the Activity and Workflow IDs like this:
temporal activity pause \
--activity-id YourActivityId \
--workflow-id YourWorkflowId
To later unpause the activity, see unpause. You may also want to reset the activity to unpause it while also starting it from the beginning.
Use the following options to change the behavior of this command.
| Flag | Required | Description | Default |
|---|---|---|---|
--activity-id, -a | No | string The Activity ID to pause. Either activity-id or activity-type must be provided, but not both. | |
--activity-type | No | string All activities of the Activity Type will be paused. Either activity-id or activity-type must be provided, but not both. Note: Pausing Activity by Type is an experimental feature and may change in the future. | |
--identity | No | string The identity of the user or client submitting this request. | |
--run-id, -r | No | string Run ID. | |
--workflow-id, -w | Yes | string Workflow ID. |
reset
Reset an activity. This restarts the activity as if it were first being scheduled. That is, it will reset both the number of attempts and the activity timeout, as well as, optionally, the heartbeat details.
If the activity may be executing (i.e. it has not yet timed out), the reset will take effect the next time it fails, heartbeats, or times out. If is waiting for a retry (i.e. has failed or timed out), the reset will apply immediately.
If the activity is already paused, it will be unpaused by default.
You can specify keep_paused to prevent this.
If the activity is paused and the keep_paused flag is not provided,
it will be unpaused. If the activity is paused and keep_paused flag
is provided - it will stay paused.
Activities can be specified by their Activity ID or Activity Type.
Resetting activities that heartbeat
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.
If the reset_heartbeats flag is set, the heartbeat details will also be cleared.
Specify the Activity Type of ID and Workflow IDs:
temporal activity reset \
--activity-id YourActivityId \
--workflow-id YourWorkflowId
--keep-paused
--reset-heartbeats
Either activity-id, activity-type, or --match-all must be specified.
Activities can be reset in bulk with a visibility query list filter. For example, if you want to reset activities of type Foo:
temporal activity reset \
--query 'TemporalResetInfo="property:activityType=Foo"'
Use the following options to change the behavior of this command.
| Flag | Required | Description | Default |
|---|---|---|---|
--activity-id, -a | No | string The Activity ID to reset. Mutually exclusive with --query, --match-all, and --activity-type. Requires --workflow-id to be specified. | |
--activity-type | No | string Activities of this Type will be reset. Mutually exclusive with --match-all and activity-id. | |
--jitter | No | duration The activity will reset at random a time within the specified duration. Can only be used with --query. | |
--keep-paused | No | bool If the activity was paused, it will stay paused. | |
--match-all | No | bool Every activity should be reset. Every activity should be updated. Mutually exclusive with --activity-id and --activity-type. | |
--query, -q | No | string Content for an SQL-like QUERY List Filter. You must set either --workflow-id or --query. | |
--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. Only works with --reset-attempts. | |
--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. | |
--run-id, -r | No | string Run ID. Only use with --workflow-id. Cannot use with --query. | |
--workflow-id, -w | No | string Workflow ID. You must set either --workflow-id or --query. | |
--yes, -y | No | bool Don't prompt to confirm signaling. Only allowed when --query is present. |
unpause
Re-schedule a previously-paused Activity for execution.
If the Activity is not running and is past its retry timeout, it will be scheduled immediately. Otherwise, it will be scheduled after its retry timeout expires.
Use --reset-attempts to reset the number of previous run attempts to
zero. For example, if an Activity is near the maximum number of attempts
N specified in its retry policy, --reset-attempts will allow the
Activity to be retried another N times after unpausing.
Use --reset-heartbeat to reset the Activity's heartbeats.
Activities can be specified by their Activity ID or Activity Type. One of those parameters must be provided.
Specify the Activity ID or Type and Workflow IDs:
temporal activity unpause \
--activity-id YourActivityId \
--workflow-id YourWorkflowId
--reset-attempts
--reset-heartbeats
Activities can be unpaused in bulk via a visibility Query list filter. For example, if you want to unpause activities of type Foo that you previously paused, do:
temporal activity unpause \
--query 'TemporalPauseInfo="property:activityType=Foo"'
Use the following options to change the behavior of this command.
| Flag | Required | Description | Default |
|---|---|---|---|
--activity-id, -a | No | string The Activity ID to unpause. Mutually exclusive with --query, --match-all, and --activity-type. Requires --workflow-id to be specified. | |
--activity-type | No | string 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. | |
--jitter | No | duration The activity will start at random a time within the specified duration. Can only be used with --query. | |
--match-all | No | bool Every paused activity should be unpaused. This flag is ignored if activity-type is provided. | |
--query, -q | No | string Content for an SQL-like QUERY List Filter. You must set either --workflow-id or --query. | |
--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. Only works with --reset-attempts. | |
--rps | No | float Limit batch's requests per second. Only allowed if query is present. | |
--run-id, -r | No | string Run ID. Only use with --workflow-id. Cannot use with --query. | |
--workflow-id, -w | No | string Workflow ID. You must set either --workflow-id or --query. | |
--yes, -y | No | bool Don't prompt to confirm signaling. Only allowed when --query is present. |
update-options
Update the options of a running Activity that were passed into it from a Workflow. Updates are incremental, only changing the specified options.
For example:
temporal activity update-options \
--activity-id YourActivityId \
--workflow-id YourWorkflowId \
--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
You may follow this command with temporal activity reset, and the new values will apply after the reset.
Either activity-id, activity-type, or --match-all must be specified.
Activity options can be updated in bulk with a visibility query list filter. For example, if you want to reset for activities of type Foo, do:
temporal activity update-options \
--query 'TemporalPauseInfo="property:activityType=Foo"'
...
Use the following options to change the behavior of this command.
| Flag | Required | Description | Default |
|---|---|---|---|
--activity-id, -a | No | string The Activity ID to update options. Mutually exclusive with --query, --match-all, and --activity-type. Requires --workflow-id to be specified. | |
--activity-type | No | string Activities of this Type will be updated. Mutually exclusive with --match-all and activity-id. | |
--heartbeat-timeout | No | duration Maximum permitted time between successful worker heartbeats. | |
--match-all | No | bool Every activity should be updated. Mutually exclusive with --activity-id and --activity-type. | |
--query, -q | No | string Content for an SQL-like QUERY List Filter. You must set either --workflow-id or --query. | |
--reason | No | string Reason for batch operation. Only use with --query. Defaults to user name. | |
--restore-original-options | No | bool Restore the original options of the activity. | |
--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 Run ID. Only use with --workflow-id. Cannot use 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. You must set either --workflow-id or --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/temporal/temporal.toml where $CONFIG_PATH is defined as $HOME/.config on Unix, $HOME/Library/Application Support on macOS, and %AppData% on Windows. (Experimental) | |
--disable-config-env | No | bool If set, disables loading environment config from environment variables. (Experimental) | |
--disable-config-file | No | bool If set, disables loading environment config from config file. (Experimental) | |
--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:HOST". | |
--log-format | No | string-enum Log format. Accepted values: text, json. | text |
--log-level | No | string-enum Log level. Default is "info" for most commands and "warn" for server start-dev. Accepted values: debug, info, warn, error, never. | info |
--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. (Experimental) | |
--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. |