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.
Flags:
--activity-id string
Activity ID to complete. Required.
--identity string
Identity of the user submitting this request.
--result string
Result JSON to return. Required.
Global Flags:
--address string
Temporal Service gRPC endpoint. (default "127.0.0.1:7233")
--api-key string
API key for request.
--codec-auth string
Authorization header for Codec Server requests.
--codec-endpoint string
Remote Codec Server endpoint.
--codec-header string[]
HTTP headers for requests to codec server. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers.
--color string-enum
Output coloring. Accepted values: always, never, auto. (default "auto")
--command-timeout duration
The command execution timeout. 0s means no timeout.
--config-file 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.
Option is experimental.
--disable-config-env bool
If set, disables loading environment config from environment variables.
Option is experimental.
--disable-config-file bool
If set, disables loading environment config from config file.
Option is experimental.
--env string
Active environment name (ENV). (default "default")
--env-file string
Path to environment settings file. Defaults to $HOME/.config/temporalio/temporal.yaml.
--grpc-meta 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].
--log-format string-enum
Log format. Accepted values: text, json. (default "text")
--log-level string-enum
Log level. Default is "info" for most commands and "warn" for server start-dev. Accepted values: debug, info, warn, error, never. (default "info")
--namespace, -n string
Temporal Service Namespace. (default "default")
--no-json-shorthand-payloads bool
Raw payload output, even if the JSON option was used.
--output, -o string-enum
Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")
--profile string
Profile to use for config file.
Option is experimental.
--time-format string-enum
Time format. Accepted values: relative, iso, raw. (default "relative")
--tls 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 string
Data for server CA certificate. Can't be used with --tls-ca-path.
--tls-ca-path string
Path to server CA certificate. Can't be used with --tls-ca-data.
--tls-cert-data string
Data for x509 certificate. Can't be used with --tls-cert-path.
--tls-cert-path string
Path to x509 certificate. Can't be used with --tls-cert-data.
--tls-disable-host-verification bool
Disable TLS host-name verification.
--tls-key-data string
Private certificate key data. Can't be used with --tls-key-path.
--tls-key-path string
Path to x509 private key. Can't be used with --tls-key-data.
--tls-server-name string
Override target TLS server name.
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.
Flags:
--activity-id string
Activity ID to fail. Required.
--detail string
Reason for failing the Activity (JSON).
--identity string
Identity of the user submitting this request.
--reason string
Reason for failing the Activity.
Global Flags:
--address string
Temporal Service gRPC endpoint. (default "127.0.0.1:7233")
--api-key string
API key for request.
--codec-auth string
Authorization header for Codec Server requests.
--codec-endpoint string
Remote Codec Server endpoint.
--codec-header string[]
HTTP headers for requests to codec server. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers.
--color string-enum
Output coloring. Accepted values: always, never, auto. (default "auto")
--command-timeout duration
The command execution timeout. 0s means no timeout.
--config-file 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.
Option is experimental.
--disable-config-env bool
If set, disables loading environment config from environment variables.
Option is experimental.
--disable-config-file bool
If set, disables loading environment config from config file.
Option is experimental.
--env string
Active environment name (ENV). (default "default")
--env-file string
Path to environment settings file. Defaults to $HOME/.config/temporalio/temporal.yaml.
--grpc-meta 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].
--log-format string-enum
Log format. Accepted values: text, json. (default "text")
--log-level string-enum
Log level. Default is "info" for most commands and "warn" for server start-dev. Accepted values: debug, info, warn, error, never. (default "info")
--namespace, -n string
Temporal Service Namespace. (default "default")
--no-json-shorthand-payloads bool
Raw payload output, even if the JSON option was used.
--output, -o string-enum
Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")
--profile string
Profile to use for config file.
Option is experimental.
--time-format string-enum
Time format. Accepted values: relative, iso, raw. (default "relative")
--tls 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 string
Data for server CA certificate. Can't be used with --tls-ca-path.
--tls-ca-path string
Path to server CA certificate. Can't be used with --tls-ca-data.
--tls-cert-data string
Data for x509 certificate. Can't be used with --tls-cert-path.
--tls-cert-path string
Path to x509 certificate. Can't be used with --tls-cert-data.
--tls-disable-host-verification bool
Disable TLS host-name verification.
--tls-key-data string
Private certificate key data. Can't be used with --tls-key-path.
--tls-key-path string
Path to x509 private key. Can't be used with --tls-key-data.
--tls-server-name string
Override target TLS server name.
pause
In Public Preview.
Available in Temporal Cloud.
Supported Open Source Versions:
- Temporal Server version 1.28 and higher.
- CLI version v1.4 and higher.
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.
Flags:
--activity-id, -a string
The Activity ID to pause. Either activity-id or activity-type must be provided, but not both.
--activity-type, -g string
All activities of the Activity Type will be paused. Either activity-id or activity-type must be provided, but not both.
--identity string
The identity of the user or client submitting this request.
--run-id string
Run ID.
--workflow-id string
Workflow ID to Pause. Required.
Global Flags:
--address string
Temporal Service gRPC endpoint. (default "127.0.0.1:7233")
--api-key string
API key for request.
--codec-auth string
Authorization header for Codec Server requests.
--codec-endpoint string
Remote Codec Server endpoint.
--codec-header string[]
HTTP headers for requests to codec server. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers.
--color string-enum
Output coloring. Accepted values: always, never, auto. (default "auto")
--command-timeout duration
The command execution timeout. 0s means no timeout.
--config-file 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.
Option is experimental.
--disable-config-env bool
If set, disables loading environment config from environment variables.
Option is experimental.
--disable-config-file bool
If set, disables loading environment config from config file.
Option is experimental.
--env string
Active environment name (ENV). (default "default")
--env-file string
Path to environment settings file. Defaults to $HOME/.config/temporalio/temporal.yaml.
--grpc-meta 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].
--log-format string-enum
Log format. Accepted values: text, json. (default "text")
--log-level string-enum
Log level. Default is "info" for most commands and "warn" for server start-dev. Accepted values: debug, info, warn, error, never. (default "info")
--namespace, -n string
Temporal Service Namespace. (default "default")
--no-json-shorthand-payloads bool
Raw payload output, even if the JSON option was used.
--output, -o string-enum
Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")
--profile string
Profile to use for config file.
Option is experimental.
--time-format string-enum
Time format. Accepted values: relative, iso, raw. (default "relative")
--tls 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 string
Data for server CA certificate. Can't be used with --tls-ca-path.
--tls-ca-path string
Path to server CA certificate. Can't be used with --tls-ca-data.
--tls-cert-data string
Data for x509 certificate. Can't be used with --tls-cert-path.
--tls-cert-path string
Path to x509 certificate. Can't be used with --tls-cert-data.
--tls-disable-host-verification bool
Disable TLS host-name verification.
--tls-key-data string
Private certificate key data. Can't be used with --tls-key-path.
--tls-key-path string
Path to x509 private key. Can't be used with --tls-key-data.
--tls-server-name string
Override target TLS server name.
reset
In Public Preview.
Available in Temporal Cloud.
Supported Open Source Versions:
- Temporal Server version 1.28 and higher.
- CLI version v1.4 and higher.
Resetting an activity 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
Use the following options to change the behavior of this command.
Flags:
--activity-id, -a string
The Activity ID to reset. Either activity-id or activity-type must be provided, but not both.
--activity-type, -g string
to reset. Either activity-id or activity-type must be provided, but not both.
--identity string
The identity of the user or client submitting this request.
--keep-paused bool
If the activity was paused, it will stay paused.
--reset-heartbeats bool
Clear the Activity's heartbeat details.
--run-id string
Run ID to reset.
--workflow-id string
Workflow ID to reset. Required.
Global Flags:
--address string
Temporal Service gRPC endpoint. (default "127.0.0.1:7233")
--api-key string
API key for request.
--codec-auth string
Authorization header for Codec Server requests.
--codec-endpoint string
Remote Codec Server endpoint.
--codec-header string[]
HTTP headers for requests to codec server. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers.
--color string-enum
Output coloring. Accepted values: always, never, auto. (default "auto")
--command-timeout duration
The command execution timeout. 0s means no timeout.
--config-file 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.
Option is experimental.
--disable-config-env bool
If set, disables loading environment config from environment variables.
Option is experimental.
--disable-config-file bool
If set, disables loading environment config from config file.
Option is experimental.
--env string
Active environment name (ENV). (default "default")
--env-file string
Path to environment settings file. Defaults to $HOME/.config/temporalio/temporal.yaml.
--grpc-meta 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].
--log-format string-enum
Log format. Accepted values: text, json. (default "text")
--log-level string-enum
Log level. Default is "info" for most commands and "warn" for server start-dev. Accepted values: debug, info, warn, error, never. (default "info")
--namespace, -n string
Temporal Service Namespace. (default "default")
--no-json-shorthand-payloads bool
Raw payload output, even if the JSON option was used.
--output, -o string-enum
Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")
--profile string
Profile to use for config file.
Option is experimental.
--time-format string-enum
Time format. Accepted values: relative, iso, raw. (default "relative")
--tls 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 string
Data for server CA certificate. Can't be used with --tls-ca-path.
--tls-ca-path string
Path to server CA certificate. Can't be used with --tls-ca-data.
--tls-cert-data string
Data for x509 certificate. Can't be used with --tls-cert-path.
--tls-cert-path string
Path to x509 certificate. Can't be used with --tls-cert-data.
--tls-disable-host-verification bool
Disable TLS host-name verification.
--tls-key-data string
Private certificate key data. Can't be used with --tls-key-path.
--tls-key-path string
Path to x509 private key. Can't be used with --tls-key-data.
--tls-server-name string
Override target TLS server name.
unpause
In Public Preview.
Available in Temporal Cloud.
Supported Open Source Versions:
- Temporal Server version 1.28 and higher.
- CLI version v1.4 and higher.
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.
Flags:
--activity-id, -a string
The Activity ID to unpause. Can only be used without --query or --match-all. Either activity-id or activity-type must be provided, but not both.
--activity-type, -g 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.
--identity string
The identity of the user or client submitting this request.
--jitter, -j duration
The activity will start at random a time within the specified duration. Can only be used with --query.
--match-all bool
Every paused activity should be unpaused. This flag is ignored if activity-type is provided. Can only be used with --query.
--query, -q string
Content for an SQL-like QUERY List Filter. You must set either --workflow-id or --query.
--reason string
Reason for batch operation. Only use with --query. Defaults to user name.
--reset-attempts bool
Also reset the activity attempts.
--reset-heartbeats bool
Reset the Activity's heartbeats. Only works with --reset-attempts.
--rps float
Limit batch's requests per second. Only allowed if query is present.
--run-id, -r string
Run ID. Only use with --workflow-id. Cannot use with --query.
--workflow-id, -w string
Workflow ID. You must set either --workflow-id or --query.
--yes, -y bool
Don't prompt to confirm signaling. Only allowed when --query is present.
Global Flags:
--address string
Temporal Service gRPC endpoint. (default "127.0.0.1:7233")
--api-key string
API key for request.
--codec-auth string
Authorization header for Codec Server requests.
--codec-endpoint string
Remote Codec Server endpoint.
--codec-header string[]
HTTP headers for requests to codec server. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers.
--color string-enum
Output coloring. Accepted values: always, never, auto. (default "auto")
--command-timeout duration
The command execution timeout. 0s means no timeout.
--config-file 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.
Option is experimental.
--disable-config-env bool
If set, disables loading environment config from environment variables.
Option is experimental.
--disable-config-file bool
If set, disables loading environment config from config file.
Option is experimental.
--env string
Active environment name (ENV). (default "default")
--env-file string
Path to environment settings file. Defaults to $HOME/.config/temporalio/temporal.yaml.
--grpc-meta 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].
--log-format string-enum
Log format. Accepted values: text, json. (default "text")
--log-level string-enum
Log level. Default is "info" for most commands and "warn" for server start-dev. Accepted values: debug, info, warn, error, never. (default "info")
--namespace, -n string
Temporal Service Namespace. (default "default")
--no-json-shorthand-payloads bool
Raw payload output, even if the JSON option was used.
--output, -o string-enum
Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")
--profile string
Profile to use for config file.
Option is experimental.
--time-format string-enum
Time format. Accepted values: relative, iso, raw. (default "relative")
--tls 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 string
Data for server CA certificate. Can't be used with --tls-ca-path.
--tls-ca-path string
Path to server CA certificate. Can't be used with --tls-ca-data.
--tls-cert-data string
Data for x509 certificate. Can't be used with --tls-cert-path.
--tls-cert-path string
Path to x509 certificate. Can't be used with --tls-cert-data.
--tls-disable-host-verification bool
Disable TLS host-name verification.
--tls-key-data string
Private certificate key data. Can't be used with --tls-key-path.
--tls-key-path string
Path to x509 private key. Can't be used with --tls-key-data.
--tls-server-name string
Override target TLS server name.
update-options
In Public Preview.
Available in Temporal Cloud.
Supported Open Source Versions:
- Temporal Server version 1.28 and higher.
- CLI version v1.4 and higher.
Updates 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.
Use the following options:
Flags:
--activity-id string
Activity ID. Required.
--heartbeat-timeout duration
Modifies the Activity's Heartbeat Timeout.
--identity string
The identity of the user or client submitting this request.
--retry-backoff-coefficient float
Modifies the Backoff Coefficient
--retry-initial-interval duration
Modifies the Initial Retry Interval in the activity's Retry Policy. If your activity has already retried, this is only useful in conjunction with activity reset.
--retry-maximum-attempts int
Modifies the Maximum Attempts in the activity's Retry Policy.
--retry-maximum-interval duration
Modifies the Maximum Interval in the activity's Retry Policy.
--schedule-to-close-timeout duration
Modifies the activity's Schedule-to-Close Timeout.
--schedule-to-start-timeout duration
Modifies the activity's Schedule-to-Start Timeout.
--start-to-close-timeout duration
Modifies the activity's Start-to-Close Timeout.
--task-queue string
Name of the task queue for the Activity.
Global Flags:
--address string
Temporal Service gRPC endpoint. (default "127.0.0.1:7233")
--api-key string
API key for request.
--codec-auth string
Authorization header for Codec Server requests.
--codec-endpoint string
Remote Codec Server endpoint.
--codec-header string[]
HTTP headers for requests to codec server. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers.
--color string-enum
Output coloring. Accepted values: always, never, auto. (default "auto")
--command-timeout duration
The command execution timeout. 0s means no timeout.
--config-file 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.
Option is experimental.
--disable-config-env bool
If set, disables loading environment config from environment variables.
Option is experimental.
--disable-config-file bool
If set, disables loading environment config from config file.
Option is experimental.
--env string
Active environment name (ENV). (default "default")
--env-file string
Path to environment settings file. Defaults to $HOME/.config/temporalio/temporal.yaml.
--grpc-meta 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].
--log-format string-enum
Log format. Accepted values: text, json. (default "text")
--log-level string-enum
Log level. Default is "info" for most commands and "warn" for server start-dev. Accepted values: debug, info, warn, error, never. (default "info")
--namespace, -n string
Temporal Service Namespace. (default "default")
--no-json-shorthand-payloads bool
Raw payload output, even if the JSON option was used.
--output, -o string-enum
Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")
--profile string
Profile to use for config file.
Option is experimental.
--time-format string-enum
Time format. Accepted values: relative, iso, raw. (default "relative")
--tls 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 string
Data for server CA certificate. Can't be used with --tls-ca-path.
--tls-ca-path string
Path to server CA certificate. Can't be used with --tls-ca-data.
--tls-cert-data string
Data for x509 certificate. Can't be used with --tls-cert-path.
--tls-cert-path string
Path to x509 certificate. Can't be used with --tls-cert-data.
--tls-disable-host-verification bool
Disable TLS host-name verification.
--tls-key-data string
Private certificate key data. Can't be used with --tls-key-path.
--tls-key-path string
Path to x509 private key. Can't be used with --tls-key-data.
--tls-server-name string
Override target TLS server name.